X-Git-Url: https://git.llucax.com/software/libev.git/blobdiff_plain/09c28a9820828432b5ced0a8f2b05c56213690fc..3360a3869a421bc12a57dcd0a9450ef5ee8a11ec:/ev.pod

diff --git a/ev.pod b/ev.pod
index 538b9f8..ee162ca 100644
--- a/ev.pod
+++ b/ev.pod
@@ -119,14 +119,17 @@ you actually want to know.
 
 =item int ev_version_minor ()
 
-You can find out the major and minor version numbers of the library
+You can find out the major and minor ABI version numbers of the library
 you linked against by calling the functions C<ev_version_major> and
 C<ev_version_minor>. If you want, you can compare against the global
 symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
 version of the library your program was compiled against.
 
+These version numbers refer to the ABI version of the library, not the
+release version.
+
 Usually, it's a good idea to terminate if the major versions mismatch,
-as this indicates an incompatible change.  Minor versions are usually
+as this indicates an incompatible change. Minor versions are usually
 compatible to older versions, so a larger minor version alone is usually
 not a problem.
 
@@ -488,8 +491,9 @@ usually a better approach for this kind of thing.
 
 Here are the gory details of what C<ev_loop> does:
 
+   - Before the first iteration, call any pending watchers.
    * If there are no active watchers (reference count is zero), return.
-   - Queue prepare watchers and then call all outstanding watchers.
+   - Queue all prepare watchers and then call all outstanding watchers.
    - If we have been forked, recreate the kernel state.
    - Update the kernel state with all outstanding changes.
    - Update the "event loop time".
@@ -909,6 +913,30 @@ whether a file descriptor is really ready with a known-to-be good interface
 such as poll (fortunately in our Xlib example, Xlib already does this on
 its own, so its quite safe to use).
 
+=head3 The special problem of disappearing file descriptors
+
+Some backends (e.g kqueue, epoll) need to be told about closing a file
+descriptor (either by calling C<close> explicitly or by any other means,
+such as C<dup>). The reason is that you register interest in some file
+descriptor, but when it goes away, the operating system will silently drop
+this interest. If another file descriptor with the same number then is
+registered with libev, there is no efficient way to see that this is, in
+fact, a different file descriptor.
+
+To avoid having to explicitly tell libev about such cases, libev follows
+the following policy:  Each time C<ev_io_set> is being called, libev
+will assume that this is potentially a new file descriptor, otherwise
+it is assumed that the file descriptor stays the same. That means that
+you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the
+descriptor even if the file descriptor number itself did not change.
+
+This is how one would do it normally anyway, the important point is that
+the libev application should not optimise around libev but should leave
+optimisations to libev.
+
+
+=head3 Watcher-Specific Functions
+
 =over 4
 
 =item ev_io_init (ev_io *, callback, int fd, int events)
@@ -971,6 +999,8 @@ The callback is guarenteed to be invoked only when its timeout has passed,
 but if multiple timers become ready during the same loop iteration then
 order of execution is undefined.
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
@@ -1075,16 +1105,18 @@ to trigger "at" some specific point in time. For example, if you tell a
 periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
 + 10.>) and then reset your system clock to the last year, then it will
 take a year to trigger the event (unlike an C<ev_timer>, which would trigger
-roughly 10 seconds later and of course not if you reset your system time
-again).
+roughly 10 seconds later).
 
 They can also be used to implement vastly more complex timers, such as
-triggering an event on eahc midnight, local time.
+triggering an event on each midnight, local time or other, complicated,
+rules.
 
 As with timers, the callback is guarenteed to be invoked only when the
 time (C<at>) has been passed, but if multiple periodic timers become ready
 during the same loop iteration then order of execution is undefined.
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
@@ -1096,18 +1128,18 @@ operation, and we will explain them from simplest to complex:
 
 =over 4
 
-=item * absolute timer (interval = reschedule_cb = 0)
+=item * absolute timer (at = time, interval = reschedule_cb = 0)
 
 In this configuration the watcher triggers an event at the wallclock time
 C<at> and doesn't repeat. It will not adjust when a time jump occurs,
 that is, if it is to be run at January 1st 2011 then it will run when the
 system time reaches or surpasses this time.
 
-=item * non-repeating interval timer (interval > 0, reschedule_cb = 0)
+=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
 
 In this mode the watcher will always be scheduled to time out at the next
-C<at + N * interval> time (for some integer N) and then repeat, regardless
-of any time jumps.
+C<at + N * interval> time (for some integer N, which can also be negative)
+and then repeat, regardless of any time jumps.
 
 This can be used to create timers that do not drift with respect to system
 time:
@@ -1123,7 +1155,11 @@ Another way to think about it (for the mathematically inclined) is that
 C<ev_periodic> will try to run the callback in this mode at the next possible
 time where C<time = at (mod interval)>, regardless of any time jumps.
 
-=item * manual reschedule mode (reschedule_cb = callback)
+For numerical stability it is preferable that the C<at> value is near
+C<ev_now ()> (the current time), but there is no range requirement for
+this value.
+
+=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
 
 In this mode the values for C<interval> and C<at> are both being
 ignored. Instead, each time the periodic watcher gets scheduled, the
@@ -1133,7 +1169,7 @@ current time as second argument.
 NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
 ever, or make any event loop modifications>. If you need to stop it,
 return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
-starting a prepare watcher).
+starting an C<ev_prepare> watcher, which is legal).
 
 Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
 ev_tstamp now)>, e.g.:
@@ -1166,6 +1202,14 @@ when you changed some parameters or the reschedule callback would return
 a different time than the last time it was called (e.g. in a crond like
 program when the crontabs have changed).
 
+=item ev_tstamp offset [read-write]
+
+When repeating, this contains the offset value, otherwise this is the
+absolute point in time (the C<at> value passed to C<ev_periodic_set>).
+
+Can be modified any time, but changes only take effect when the periodic
+timer fires or C<ev_periodic_again> is being called.
+
 =item ev_tstamp interval [read-write]
 
 The current interval value. Can be modified any time, but changes only
@@ -1228,6 +1272,8 @@ as you don't register any with libev). Similarly, when the last signal
 watcher for a signal is stopped libev will reset the signal handler to
 SIG_DFL (regardless of what it was set to before).
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_signal_init (ev_signal *, callback, int signum)
@@ -1249,6 +1295,8 @@ The signal the watcher watches out for.
 Child watchers trigger when your process receives a SIGCHLD in response to
 some child status changes (most typically when a child of yours dies).
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_child_init (ev_child *, callback, int pid)
@@ -1326,6 +1374,8 @@ to fall back to regular polling again even with inotify, but changes are
 usually detected immediately, and if the file exists there will be no
 polling.
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
@@ -1417,6 +1467,8 @@ effect on its own sometimes), idle watchers are a good place to do
 "pseudo-background processing", or delay processing stuff to after the
 event loop has handled all outstanding events.
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_idle_init (ev_signal *, callback)
@@ -1483,6 +1535,18 @@ of lower priority, but only once, using idle watchers to keep the event
 loop from blocking if lower-priority coroutines are active, thus mapping
 low-priority coroutines to idle/background tasks).
 
+It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
+priority, to ensure that they are being run before any other watchers
+after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
+too) should not activate ("feed") events into libev. While libev fully
+supports this, they will be called before other C<ev_check> watchers did
+their job. As C<ev_check> watchers are often used to embed other event
+loops those other event loops might be in an unusable state until their
+C<ev_check> watcher ran (always remind yourself to coexist peacefully with
+others).
+
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_prepare_init (ev_prepare *, callback)
@@ -1693,6 +1757,8 @@ create it, and if that fails, use the normal loop for everything:
   else
     loop_lo = loop_hi;
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)