[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.456 by root, Tue Jul 2 06:07:54 2019 UTC vs.
Revision 1.469 by root, Sat Jun 3 08:53:03 2023 UTC

 unblocking the signals.
 It's also required by POSIX in a threaded program, as libev calls
 C<sigprocmask>, whose behaviour is officially unspecified.
-This flag's behaviour will become the default in future versions of libev.
+=item C<EVFLAG_NOTIMERFD>
+When this flag is specified, the libev will avoid using a C<timerfd> to
+detect time jumps. It will still be able to detect time jumps, but takes
+longer and has a lower accuracy in doing so, but saves a file descriptor
+per loop.
+The current implementation only tries to use a C<timerfd> when the first
+C<ev_periodic> watcher is started and falls back on other methods if it
+cannot be created, but this behaviour might change in the future.
 =item C<EVBACKEND_SELECT>  (value 1, portable select backend)
 This is your standard select(2) backend. Not I<completely> standard, as
 libev tries to roll its own fd_set with no limits on the number of fds,
 and is not embeddable, which would limit the usefulness of this backend
 immensely.
 =item C<EVBACKEND_PORT>    (value 32, Solaris 10)
-This uses the Solaris 10 event port mechanism. As with everything on Solaris,
+This uses the Solaris 10 event port mechanism. As with everything on
-it's really slow, but it still scales very well (O(active_fds)).
+Solaris, it's really slow, but it still scales very well (O(active_fds)).
 While this backend scales well, it requires one system call per active
 file descriptor per loop iteration. For small and medium numbers of file
 descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
 might perform better.
    - Queue all expired timers.
    - Queue all expired periodics.
    - Queue all idle watchers with priority higher than that of pending events.
    - Queue all check watchers.
    - Call all queued watchers in reverse order (i.e. check watchers first).
-     Signals and child watchers are implemented as I/O watchers, and will
+     Signals, async and child watchers are implemented as I/O watchers, and
-     be handled here by queueing them when their watcher gets executed.
+     will be handled here by queueing them when their watcher gets executed.
    - If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT
      were used, or there are no active watchers, goto FINISH, otherwise
      continue with step LOOP.
    FINISH:
    - Reset the ev_break status iff it was EVBREAK_ONE.
 with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
 *) >>), and you can stop watching for events at any time by calling the
 corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
 As long as your watcher is active (has been started but not stopped) you
-must not touch the values stored in it. Most specifically you must never
+must not touch the values stored in it except when explicitly documented
-reinitialise it or call its C<ev_TYPE_set> macro.
+otherwise. Most specifically you must never reinitialise it or call its
+C<ev_TYPE_set> macro.
 Each and every callback receives the event loop pointer as first, the
 registered watcher structure as second, and a bitset of received events as
 third argument.
 =item bool ev_is_active (ev_TYPE *watcher)
 Returns a true value iff the watcher is active (i.e. it has been started
 and not yet been stopped). As long as a watcher is active you must not modify
-it.
+it unless documented otherwise.
+Obviously, it is safe to call this on an active watcher, or actually any
+watcher that is initialised.
 =item bool ev_is_pending (ev_TYPE *watcher)
 Returns a true value iff the watcher is pending, (i.e. it has outstanding
 events but its callback has not yet been invoked). As long as a watcher
 is pending (but not active) you must not call an init function on it (but
 C<ev_TYPE_set> is safe), you must not change its priority, and you must
 make sure the watcher is available to libev (e.g. you cannot C<free ()>
 it).
+It is safe to call this on any watcher in any state as long as it is
+initialised.
 =item callback ev_cb (ev_TYPE *watcher)
 Returns the callback currently set on the watcher.
 =item ev_set_cb (ev_TYPE *watcher, callback)
 from being executed (except for C<ev_idle> watchers).
 If you need to suppress invocation when higher priority events are pending
 you need to look at C<ev_idle> watchers, which provide this functionality.
-You I<must not> change the priority of a watcher as long as it is active or
+You I<must not> change the priority of a watcher as long as it is active
-pending.
+or pending. Reading the priority with C<ev_priority> is fine in any state.
 Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
 fine, as long as you do not mind that the priority value you query might
 or might not have been clamped to the valid range.
 =item ev_feed_event (loop, ev_TYPE *watcher, int revents)
 Feeds the given event set into the event loop, as if the specified event
 had happened for the specified watcher (which must be a pointer to an
-initialised but not necessarily started event watcher). Obviously you must
+initialised but not necessarily started event watcher, though it can be
-not free the watcher as long as it has pending events.
+active). Obviously you must not free the watcher as long as it has pending
+events.
 Stopping the watcher, letting libev invoke it, or calling
 C<ev_clear_pending> will clear the pending event, even if the watcher was
 not started in the first place.
 =item started/running/active
 Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
 property of the event loop, and is actively waiting for events. While in
-this state it cannot be accessed (except in a few documented ways), moved,
+this state it cannot be accessed (except in a few documented ways, such as
-freed or anything else - the only legal thing is to keep a pointer to it,
+stoping it), moved, freed or anything else - the only legal thing is to
-and call libev functions on it that are documented to work on active watchers.
+keep a pointer to it, and call libev functions on it that are documented
+to work on active watchers.
+As a rule of thumb, before accessing a member or calling any function on
+a watcher, it should be stopped (or freshly initialised). If that is not
+convenient, you can check the documentation for that function or member to
+see if it is safe to use on an active watcher.
 =item pending
 If a watcher is active and libev determines that an event it is interested
-in has occurred (such as a timer expiring), it will become pending. It will
+in has occurred (such as a timer expiring), it will become pending. It
-stay in this pending state until either it is stopped or its callback is
+will stay in this pending state until either it is explicitly stopped or
-about to be invoked, so it is not normally pending inside the watcher
+its callback is about to be invoked, so it is not normally pending inside
-callback.
+the watcher callback.
-The watcher might or might not be active while it is pending (for example,
+Generally, the watcher might or might not be active while it is pending
-an expired non-repeating timer can be pending but no longer active). If it
+(for example, an expired non-repeating timer can be pending but no longer
-is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
+active). If it is pending but not active, it can be freely accessed (e.g.
-but it is still property of the event loop at this time, so cannot be
+by calling C<ev_TYPE_set>), but it is still property of the event loop at
-moved, freed or reused. And if it is active the rules described in the
+this time, so cannot be moved, freed or reused. And if it is active the
-previous item still apply.
+rules described in the previous item still apply.
+Explicitly stopping a watcher will also clear the pending state
+unconditionally, so it is safe to stop a watcher and then free it.
 It is also possible to feed an event on a watcher that is not active (e.g.
 via C<ev_feed_event>), in which case it becomes pending without being
 active.
 Many event loops support I<watcher priorities>, which are usually small
 integers that influence the ordering of event callback invocation
 between watchers in some way, all else being equal.
-In libev, Watcher priorities can be set using C<ev_set_priority>. See its
+In libev, watcher priorities can be set using C<ev_set_priority>. See its
 description for the more technical details such as the actual priority
 range.
 There are two common ways how these these priorities are being interpreted
 by event loops:
 This section describes each watcher in detail, but will not repeat
 information given in the last section. Any initialisation/set macros,
 functions and members specific to the watcher type are explained.
-Members are additionally marked with either I<[read-only]>, meaning that,
+Most members are additionally marked with either I<[read-only]>, meaning
-while the watcher is active, you can look at the member and expect some
+that, while the watcher is active, you can look at the member and expect
-sensible content, but you must not modify it (you can modify it while the
+some sensible content, but you must not modify it (you can modify it while
-watcher is stopped to your hearts content), or I<[read-write]>, which
+the watcher is stopped to your hearts content), or I<[read-write]>, which
-means you can expect it to have some sensible content while the watcher
+means you can expect it to have some sensible content while the watcher is
-is active, but you can also modify it. Modifying it may not do something
+active, but you can also modify it (within the same thread as the event
+loop, i.e. without creating data races). Modifying it may not do something
 sensible or take immediate effect (or do anything at all), but libev will
 not crash or malfunction in any way.
+In any case, the documentation for each member will explain what the
+effects are, and if there are any additional access restrictions.
 =head2 C<ev_io> - is this file descriptor readable or writable?
 I/O watchers check whether a file descriptor is readable or writable
 in each iteration of the event loop, or, more precisely, when reading
 =item ev_io_init (ev_io *, callback, int fd, int events)
 =item ev_io_set (ev_io *, int fd, int events)
 Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
-receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or
+receive events for and C<events> is either C<EV_READ>, C<EV_WRITE>, both
-C<EV_READ | EV_WRITE>, to express the desire to receive the given events.
+C<EV_READ | EV_WRITE> or C<0>, to express the desire to receive the given
+events.
-=item int fd [read-only]
+Note that setting the C<events> to C<0> and starting the watcher is
+supported, but not specially optimized - if your program sometimes happens
+to generate this combination this is fine, but if it is easy to avoid
+starting an io watcher watching for no events you should do so.
-The file descriptor being watched.
+=item ev_io_modify (ev_io *, int events)
+Similar to C<ev_io_set>, but only changes the requested events. Using this
+might be faster with some backends, as libev can assume that the C<fd>
+still refers to the same underlying file description, something it cannot
+do when using C<ev_io_set>.
+=item int fd [no-modify]
+The file descriptor being watched. While it can be read at any time, you
+must not modify this member even when the watcher is stopped - always use
+C<ev_io_set> for that.
-=item int events [read-only]
+=item int events [no-modify]
-The events being watched.
+The set of events the fd is being watched for, among other flags. Remember
+that this is a bit set - to test for C<EV_READ>, use C<< w->events &
+EV_READ >>, and similarly for C<EV_WRITE>.
+As with C<fd>, you must not modify this member even when the watcher is
+stopped, always use C<ev_io_set> or C<ev_io_modify> for that.
 =back
 =head3 Examples
 event loop thread and an unspecified mechanism to wake up the main thread.
 First, you need to associate some data with the event loop:
    typedef struct {
-     mutex_t lock; /* global loop lock */
+     pthread_mutex_t lock; /* global loop lock */
+     pthread_t tid;
+     pthread_cond_t invoke_cv;
      ev_async async_w;
-     thread_t tid;
-     cond_t invoke_cv;
    } userdata;
    void prepare_loop (EV_P)
    {
       // for simplicity, we use a static userdata struct.
       static userdata u;
-      ev_async_init (&u->async_w, async_cb);
+      ev_async_init (&u.async_w, async_cb);
-      ev_async_start (EV_A_ &u->async_w);
+      ev_async_start (EV_A_ &u.async_w);
-      pthread_mutex_init (&u->lock, 0);
+      pthread_mutex_init (&u.lock, 0);
-      pthread_cond_init (&u->invoke_cv, 0);
+      pthread_cond_init (&u.invoke_cv, 0);
       // now associate this with the loop
-      ev_set_userdata (EV_A_ u);
+      ev_set_userdata (EV_A_ &u);
       ev_set_invoke_pending_cb (EV_A_ l_invoke);
       ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
       // then create the thread running ev_run
-      pthread_create (&u->tid, 0, l_run, EV_A);
+      pthread_create (&u.tid, 0, l_run, EV_A);
    }
 The callback for the C<ev_async> watcher does nothing: the watcher is used
 solely to wake up the event loop so it takes notice of any new watchers
 that might have been added:
 gets automatically stopped and restarted when reconfiguring it with this
 method.
 For C<ev::embed> watchers this method is called C<set_embed>, to avoid
 clashing with the C<set (loop)> method.
+For C<ev::io> watchers there is an additional C<set> method that acepts a
+new event mask only, and internally calls C<ev_io_modify>.
 =item w->start ()
 Starts the watcher. Note that there is no C<loop> argument, as the
 constructor already stores the event loop.
 =item EV_USE_NANOSLEEP
 If defined to be C<1>, libev will assume that C<nanosleep ()> is available
 and will use it for delays. Otherwise it will use C<select ()>.
+=item EV_USE_EVENTFD
+If defined to be C<1>, then libev will assume that C<eventfd ()> is
+available and will probe for kernel support at runtime. This will improve
+C<ev_signal> and C<ev_async> performance and reduce resource consumption.
+If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
+2.7 or newer, otherwise disabled.
+=item EV_USE_SIGNALFD
+If defined to be C<1>, then libev will assume that C<signalfd ()> is
+available and will probe for kernel support at runtime. This enables
+the use of EVFLAG_SIGNALFD for faster and simpler signal handling. If
+undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
+2.7 or newer, otherwise disabled.
+=item EV_USE_TIMERFD
+If defined to be C<1>, then libev will assume that C<timerfd ()> is
+available and will probe for kernel support at runtime. This allows
+libev to detect time jumps accurately. If undefined, it will be enabled
+if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
+C<TFD_TIMER_CANCEL_ON_SET>, otherwise disabled.
 =item EV_USE_EVENTFD
 If defined to be C<1>, then libev will assume that C<eventfd ()> is
 available and will probe for kernel support at runtime. This will improve

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing libev/ev.pod (file contents): Revision 1.456 by root, Tue Jul 2 06:07:54 2019 UTC vs. Revision 1.469 by root, Sat Jun 3 08:53:03 2023 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.456 by root, Tue Jul 2 06:07:54 2019 UTC vs.
Revision 1.469 by root, Sat Jun 3 08:53:03 2023 UTC