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

[Daniel Semkowicz]

Hi Jacopo,

On Thu, Jun 16, 2022 at 1:06 PM Jacopo Mondi <jacopo at jmondi.org> wrote:
>
> Hi Daniel,
>
>    I wonder if we shouldn't just drop the whole
>
> Start an event loop
> ~~~~~~~~~~~~~~~~~~~
>
> paragraph
>

I was also thinking about that when I was editing the current text.
It is always the decision on how many details about the internal
architecture We want to present to the developer in this guide.
As it is the introduction guide then maybe indeed it will be better to
keep it simple and do not talk too much about the internals.

There will still be this one "sleep_for(3000ms)" line needed and I think
it would be good to leave some short explanation why it is here. Do you
think that adding it at the end of "Request queueing" section is a good
idea or should I create a separate section about it?

Best regards
Daniel


> On Wed, Jun 15, 2022 at 06:26:01PM +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.
> > ---
> >  .../guides/application-developer.rst          | 20 ++++++++++---------
> >  1 file changed, 11 insertions(+), 9 deletions(-)
> >
> > diff --git a/Documentation/guides/application-developer.rst b/Documentation/guides/application-developer.rst
> > index 00bafb10..97c032a5 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,7 +508,7 @@ and queue all the previously created requests.
> >     for (std::unique_ptr<Request> &request : requests)
> >         camera->queueRequest(request.get());
> >
> > -Start an event loop
> > +Event loop
> >  ~~~~~~~~~~~~~~~~~~~
> >
> >  The libcamera library needs an event loop to monitor and dispatch events
> > @@ -524,17 +526,17 @@ a notifier it is monitoring, it emits the notifier's
> >  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.
> > +Event loop is handled internally by ``CameraManager`` instance in a separate
> > +thread. ``CameraManager::start()`` creates a new thread and starts the event
> > +loop processing.
> > +
> > +As the ``CameraManager`` was already started in our example, we need to prevent
> > +the immediate termination of the application. The code below pauses the main
> > +thread for 3 seconds, so that the event loop thread can process the requests.
> >
> >  .. 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
> >  ---------------------------------
> > --
> > 2.34.1
> >