[libcamera-devel] [PATCH v2 3/3] Documentation: Update the "Start an event loop" section

[Laurent Pinchart]

Hi Daniel,

Thank you for the patch.

On Fri, Jun 17, 2022 at 04:35:49PM +0200, Daniel Semkowicz via libcamera-devel wrote:
> Event loop was moved to be a part of CameraManager, so it is no longer
> a user responsibility to control the event dispatching.
> 
> Signed-off-by: Daniel Semkowicz <dse at thaumatec.com>
> ---
>  .../guides/application-developer.rst          | 38 ++++++++-----------
>  1 file changed, 16 insertions(+), 22 deletions(-)
> 
> diff --git a/Documentation/guides/application-developer.rst b/Documentation/guides/application-developer.rst
> index a5f363cf..f4551f58 100644
> --- a/Documentation/guides/application-developer.rst
> +++ b/Documentation/guides/application-developer.rst
> @@ -27,10 +27,12 @@ defined names and types without the need of prefixing them.
>     #include <iomanip>
>     #include <iostream>
>     #include <memory>
> +   #include <thread>
>  
>     #include <libcamera/libcamera.h>
>  
>     using namespace libcamera;
> +   using namespace std::chrono_literals;
>  
>     int main()
>     {
> @@ -506,35 +508,27 @@ and queue all the previously created requests.
>     for (std::unique_ptr<Request> &request : requests)
>         camera->queueRequest(request.get());
>  
> -Start an event loop
> +Event processing
>  ~~~~~~~~~~~~~~~~~~~

You can shorten the underline. With this,

Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

I can fix this when applying, there's no need to resubmit.

>  
> -The libcamera library needs an event loop to monitor and dispatch events
> -generated by the video devices part of the capture pipeline. libcamera provides
> -its own ``EventDispatcher`` class (inspired by the `Qt event system`_) to
> -process and deliver events generated by ``EventNotifiers``.
> +libcamera creates an internal execution thread at `CameraManager::start()`_
> +time to decouple its own event processing from the application's main thread.
> +Applications are thus free to manage their own execution opportunely, and only
> +need to respond to events generated by libcamera emitted through signals.
>  
> -.. _Qt event system: https://doc.qt.io/qt-5/eventsandfilters.html
> +.. _CameraManager::start(): https://libcamera.org/api-html/classlibcamera_1_1CameraManager.html#a49e322880a2a26013bb0076788b298c5
>  
> -The libcamera library implements this by creating instances of the
> -``EventNotifier`` class, which models a file descriptor event source registered
> -to an ``EventDispatcher``. Whenever the ``EventDispatcher`` detects an event on
> -a notifier it is monitoring, it emits the notifier's
> -``EventNotifier::activated`` signal. The libcamera components connect to the
> -notifiers' signals and emit application visible events, such as the
> -``Camera::bufferReady`` and ``Camera::requestCompleted`` signals.
> -
> -The code below retrieves a reference to the system-wide event dispatcher and for
> -the a fixed duration of 3 seconds, processes all the events detected in the
> -system.
> +Real-world applications will likely either integrate with the event loop of the
> +framework they use, or create their own event loop to respond to user events.
> +For the simple application presented in this example, it is enough to prevent
> +immediate termination by pausing for 3 seconds. During that time, the libcamera
> +thread will generate request completion events that the application will handle
> +in the ``requestComplete()`` slot connected to the ``Camera::requestCompleted``
> +signal.
>  
>  .. code:: cpp
>  
> -   EventDispatcher *dispatcher = cm->eventDispatcher();
> -   Timer timer;
> -   timer.start(3000);
> -   while (timer.isRunning())
> -       dispatcher->processEvents();
> +   std::this_thread::sleep_for(3000ms);
>  
>  Clean up and stop the application
>  ---------------------------------

-- 
Regards,

Laurent Pinchart