view release on metacpan or  search on metacpan

libev/ev.pod  view on Meta::CPAN

   event_poll_func (GPollFD *fds, guint nfds, gint timeout)
   {
     int got_events = 0;

     for (n = 0; n < nfds; ++n)
       // create/start io watcher that sets the relevant bits in fds[n] and increment got_events

     if (timeout >= 0)
       // create/start timer

     // poll
     ev_run (EV_A_ 0);

     // stop timer again
     if (timeout >= 0)
       ev_timer_stop (EV_A_ &to);

     // stop io watchers again - their callbacks should have set
     for (n = 0; n < nfds; ++n)
       ev_io_stop (EV_A_ iow [n]);

     return got_events;
   }


=head2 C<ev_embed> - when one backend isn't enough...

This is a rather advanced watcher type that lets you embed one event loop
into another (currently only C<ev_io> events are supported in the embedded
loop, other types of watchers might be handled in a delayed or incorrect
fashion and must not be used).

There are primarily two reasons you would want that: work around bugs and
prioritise I/O.

As an example for a bug workaround, the kqueue backend might only support
sockets on some platform, so it is unusable as generic backend, but you
still want to make use of it because you have many sockets and it scales
so nicely. In this case, you would create a kqueue-based loop and embed
it into your default loop (which might use e.g. poll). Overall operation
will be a bit slower because first libev has to call C<poll> and then
C<kevent>, but at least you can use both mechanisms for what they are
best: C<kqueue> for scalable sockets and C<poll> if you want it to work :)

As for prioritising I/O: under rare circumstances you have the case where
some fds have to be watched and handled very quickly (with low latency),
and even priorities and idle watchers might have too much overhead. In
this case you would put all the high priority stuff in one loop and all
the rest in a second one, and embed the second one in the first.

As long as the watcher is active, the callback will be invoked every
time there might be events pending in the embedded loop. The callback
must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
sweep and invoke their callbacks (the callback doesn't need to invoke the
C<ev_embed_sweep> function directly, it could also start an idle watcher
to give the embedded loop strictly lower priority for example).

You can also set the callback to C<0>, in which case the embed watcher
will automatically execute the embedded loop sweep whenever necessary.

Fork detection will be handled transparently while the C<ev_embed> watcher
is active, i.e., the embedded loop will automatically be forked when the
embedding loop forks. In other cases, the user is responsible for calling
C<ev_loop_fork> on the embedded loop.

Unfortunately, not all backends are embeddable: only the ones returned by
C<ev_embeddable_backends> are, which, unfortunately, does not include any
portable one.

So when you want to use this feature you will always have to be prepared
that you cannot get an embeddable loop. The recommended way to get around
this is to have a separate variables for your embeddable loop, try to
create it, and if that fails, use the normal loop for everything.

=head3 C<ev_embed> and fork

While the C<ev_embed> watcher is running, forks in the embedding loop will
automatically be applied to the embedded loop as well, so no special
fork handling is required in that case. When the watcher is not running,
however, it is still the task of the libev user to call C<ev_loop_fork ()>
as applicable.

=head3 Watcher-Specific Functions and Data Members

=over 4

=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)

=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)

Configures the watcher to embed the given loop, which must be
embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
invoked automatically, otherwise it is the responsibility of the callback
to invoke it (it will continue to be called until the sweep has been done,
if you do not want that, you need to temporarily stop the embed watcher).

=item ev_embed_sweep (loop, ev_embed *)

Make a single, non-blocking sweep over the embedded loop. This works
similarly to C<ev_run (embedded_loop, EVRUN_NOWAIT)>, but in the most
appropriate way for embedded loops.

=item struct ev_loop *other [read-only]

The embedded event loop.

=back

=head3 Examples

Example: Try to get an embeddable event loop and embed it into the default
event loop. If that is not possible, use the default loop. The default
loop is stored in C<loop_hi>, while the embeddable loop is stored in
C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be
used).

   struct ev_loop *loop_hi = ev_default_init (0);
   struct ev_loop *loop_lo = 0;
   ev_embed embed;

   // see if there is a chance of getting one that works