<meta name="description" content="Pod documentation for libev" />
<meta name="inputfile" content="<standard input>" />
<meta name="outputfile" content="<standard output>" />
- <meta name="created" content="Fri Dec 7 20:07:44 2007" />
+ <meta name="created" content="Wed Dec 12 05:53:55 2007" />
<meta name="generator" content="Pod::Xhtml 1.57" />
<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
<body>
</ul>
</li>
<li><a href="#WATCHER_TYPES">WATCHER TYPES</a>
-<ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable?</a></li>
+<ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable?</a>
+<ul><li><a href="#The_special_problem_of_disappearing_">The special problem of disappearing file descriptors</a></li>
+</ul>
+</li>
<li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally repeating timeouts</a></li>
<li><a href="#code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron?</a></li>
<li><a href="#code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled!</a></li>
<dt>int ev_version_major ()</dt>
<dt>int ev_version_minor ()</dt>
<dd>
- <p>You can find out the major and minor version numbers of the library
+ <p>You can find out the major and minor ABI version numbers of the library
you linked against by calling the functions <code>ev_version_major</code> and
<code>ev_version_minor</code>. If you want, you can compare against the global
symbols <code>EV_VERSION_MAJOR</code> and <code>EV_VERSION_MINOR</code>, which specify the
version of the library your program was compiled against.</p>
+ <p>These version numbers refer to the ABI version of the library, not the
+release version.</p>
<p>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.</p>
<p>Example: Make sure we haven't accidentally been linked against the wrong
libev watchers. However, a pair of <code>ev_prepare</code>/<code>ev_check</code> watchers is
usually a better approach for this kind of thing.</p>
<p>Here are the gory details of what <code>ev_loop</code> does:</p>
-<pre> * If there are no active watchers (reference count is zero), return.
- - Queue prepare watchers and then call all outstanding watchers.
+<pre> - Before the first iteration, call any pending watchers.
+ * If there are no active watchers (reference count is zero), return.
+ - 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".
<p>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
-<code>ev_TYPE_set</code> is safe) and you must make sure the watcher is available to
-libev (e.g. you cnanot <code>free ()</code> it).</p>
+<code>ev_TYPE_set</code> is safe), you must not change its priority, and you must
+make sure the watcher is available to libev (e.g. you cannot <code>free ()</code>
+it).</p>
</dd>
<dt>callback ev_cb (ev_TYPE *watcher)</dt>
<dd>
watchers on the same event and make sure one is called first.</p>
<p>If you need to suppress invocation when higher priority events are pending
you need to look at <code>ev_idle</code> watchers, which provide this functionality.</p>
+ <p>You <i>must not</i> change the priority of a watcher as long as it is active or
+pending.</p>
<p>The default priority used by watchers when no priority has been set is
always <code>0</code>, which is supposed to not be too high and not be too low :).</p>
<p>Setting a priority outside the range of <code>EV_MINPRI</code> to <code>EV_MAXPRI</code> is
fine, as long as you do not mind that the priority value you query might
or might not have been adjusted to be within valid range.</p>
</dd>
+ <dt>ev_invoke (loop, ev_TYPE *watcher, int revents)</dt>
+ <dd>
+ <p>Invoke the <code>watcher</code> with the given <code>loop</code> and <code>revents</code>. Neither
+<code>loop</code> nor <code>revents</code> need to be valid as long as the watcher callback
+can deal with that fact.</p>
+ </dd>
+ <dt>int ev_clear_pending (loop, ev_TYPE *watcher)</dt>
+ <dd>
+ <p>If the watcher is pending, this function returns clears its pending status
+and returns its <code>revents</code> bitset (as if its callback was invoked). If the
+watcher isn't pending it does nothing and returns <code>0</code>.</p>
+ </dd>
</dl>
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).</p>
+
+</div>
+<h3 id="The_special_problem_of_disappearing_">The special problem of disappearing file descriptors</h3>
+<div id="The_special_problem_of_disappearing_-2">
+<p>Some backends (e.g kqueue, epoll) need to be told about closing a file
+descriptor (either by calling <code>close</code> explicitly or by any other means,
+such as <code>dup</code>). 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.</p>
+<p>To avoid having to explicitly tell libev about such cases, libev follows
+the following policy: Each time <code>ev_io_set</code> 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</i> to call <code>ev_io_set</code> (or <code>ev_io_init</code>) when you change the
+descriptor even if the file descriptor number itself did not change.</p>
+<p>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.</p>
+
+
+
+
<dl>
<dt>ev_io_init (ev_io *, callback, int fd, int events)</dt>
<dt>ev_io_set (ev_io *, int fd, int events)</dt>
periodic watcher to trigger in 10 seconds (by specifiying e.g. <code>ev_now ()
+ 10.</code>) and then reset your system clock to the last year, then it will
take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger
-roughly 10 seconds later and of course not if you reset your system time
-again).</p>
+roughly 10 seconds later).</p>
<p>They can also be used to implement vastly more complex timers, such as
-triggering an event on eahc midnight, local time.</p>
+triggering an event on each midnight, local time or other, complicated,
+rules.</p>
<p>As with timers, the callback is guarenteed to be invoked only when the
time (<code>at</code>) has been passed, but if multiple periodic timers become ready
during the same loop iteration then order of execution is undefined.</p>
operation, and we will explain them from simplest to complex:</p>
<p>
<dl>
- <dt>* absolute timer (interval = reschedule_cb = 0)</dt>
+ <dt>* absolute timer (at = time, interval = reschedule_cb = 0)</dt>
<dd>
<p>In this configuration the watcher triggers an event at the wallclock time
<code>at</code> 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.</p>
</dd>
- <dt>* non-repeating interval timer (interval > 0, reschedule_cb = 0)</dt>
+ <dt>* non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)</dt>
<dd>
<p>In this mode the watcher will always be scheduled to time out at the next
-<code>at + N * interval</code> time (for some integer N) and then repeat, regardless
-of any time jumps.</p>
+<code>at + N * interval</code> time (for some integer N, which can also be negative)
+and then repeat, regardless of any time jumps.</p>
<p>This can be used to create timers that do not drift with respect to system
time:</p>
<pre> ev_periodic_set (&periodic, 0., 3600., 0);
<p>Another way to think about it (for the mathematically inclined) is that
<code>ev_periodic</code> will try to run the callback in this mode at the next possible
time where <code>time = at (mod interval)</code>, regardless of any time jumps.</p>
+ <p>For numerical stability it is preferable that the <code>at</code> value is near
+<code>ev_now ()</code> (the current time), but there is no range requirement for
+this value.</p>
</dd>
- <dt>* manual reschedule mode (reschedule_cb = callback)</dt>
+ <dt>* manual reschedule mode (at and interval ignored, reschedule_cb = callback)</dt>
<dd>
<p>In this mode the values for <code>interval</code> and <code>at</code> are both being
ignored. Instead, each time the periodic watcher gets scheduled, the
<p>NOTE: <i>This callback MUST NOT stop or destroy any periodic watcher,
ever, or make any event loop modifications</i>. If you need to stop it,
return <code>now + 1e30</code> (or so, fudge fudge) and stop it afterwards (e.g. by
-starting a prepare watcher).</p>
+starting an <code>ev_prepare</code> watcher, which is legal).</p>
<p>Its prototype is <code>ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
ev_tstamp now)</code>, e.g.:</p>
<pre> static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
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).</p>
+ </dd>
+ <dt>ev_tstamp offset [read-write]</dt>
+ <dd>
+ <p>When repeating, this contains the offset value, otherwise this is the
+absolute point in time (the <code>at</code> value passed to <code>ev_periodic_set</code>).</p>
+ <p>Can be modified any time, but changes only take effect when the periodic
+timer fires or <code>ev_periodic_again</code> is being called.</p>
</dd>
<dt>ev_tstamp interval [read-write]</dt>
<dd>
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).</p>
+<p>It is recommended to give <code>ev_check</code> watchers highest (<code>EV_MAXPRI</code>)
+priority, to ensure that they are being run before any other watchers
+after the poll. Also, <code>ev_check</code> watchers (and <code>ev_prepare</code> watchers,
+too) should not activate ("feed") events into libev. While libev fully
+supports this, they will be called before other <code>ev_check</code> watchers did
+their job. As <code>ev_check</code> watchers are often used to embed other event
+loops those other event loops might be in an unusable state until their
+<code>ev_check</code> watcher ran (always remind yourself to coexist peacefully with
+others).</p>
<dl>
<dt>ev_prepare_init (ev_prepare *, callback)</dt>
<dt>ev_check_init (ev_check *, callback)</dt>
macros, but using them is utterly, utterly and completely pointless.</p>
</dd>
</dl>
-<p>Example: To include a library such as adns, you would add IO watchers
-and a timeout watcher in a prepare handler, as required by libadns, and
-in a check watcher, destroy them and call into libadns. What follows is
-pseudo-code only of course:</p>
+<p>There are a number of principal ways to embed other event loops or modules
+into libev. Here are some ideas on how to include libadns into libev
+(there is a Perl module named <code>EV::ADNS</code> that does this, which you could
+use for an actually working example. Another Perl module named <code>EV::Glib</code>
+embeds a Glib main context into libev, and finally, <code>Glib::EV</code> embeds EV
+into the Glib event loop).</p>
+<p>Method 1: Add IO watchers and a timeout watcher in a prepare handler,
+and in a check watcher, destroy them and call into libadns. What follows
+is pseudo-code only of course. This requires you to either use a low
+priority for the check watcher or use <code>ev_clear_pending</code> explicitly, as
+the callbacks for the IO/timeout watchers might not have been called yet.</p>
<pre> static ev_io iow [nfd];
static ev_timer tw;
static void
io_cb (ev_loop *loop, ev_io *w, int revents)
{
- // set the relevant poll flags
- // could also call adns_processreadable etc. here
- struct pollfd *fd = (struct pollfd *)w->data;
- if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
- if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
}
// create io watchers for each fd and a timer before blocking
ev_timer_init (&tw, 0, timeout * 1e-3);
ev_timer_start (loop, &tw);
- // create on ev_io per pollfd
+ // create one ev_io per pollfd
for (int i = 0; i < nfd; ++i)
{
ev_io_init (iow + i, io_cb, fds [i].fd,
| (fds [i].events & POLLOUT ? EV_WRITE : 0)));
fds [i].revents = 0;
- iow [i].data = fds + i;
ev_io_start (loop, iow + i);
}
}
ev_timer_stop (loop, &tw);
for (int i = 0; i < nfd; ++i)
- ev_io_stop (loop, iow + i);
+ {
+ // set the relevant poll flags
+ // could also call adns_processreadable etc. here
+ struct pollfd *fd = fds + i;
+ int revents = ev_clear_pending (iow + i);
+ if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
+ if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
+
+ // now stop the watcher
+ ev_io_stop (loop, iow + i);
+ }
adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
}
+</pre>
+<p>Method 2: This would be just like method 1, but you run <code>adns_afterpoll</code>
+in the prepare watcher and would dispose of the check watcher.</p>
+<p>Method 3: If the module to be embedded supports explicit event
+notification (adns does), you can also make use of the actual watcher
+callbacks, and only destroy/create the watchers in the prepare watcher.</p>
+<pre> static void
+ timer_cb (EV_P_ ev_timer *w, int revents)
+ {
+ adns_state ads = (adns_state)w->data;
+ update_now (EV_A);
+
+ adns_processtimeouts (ads, &tv_now);
+ }
+
+ static void
+ io_cb (EV_P_ ev_io *w, int revents)
+ {
+ adns_state ads = (adns_state)w->data;
+ update_now (EV_A);
+
+ if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now);
+ if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
+ }
+
+ // do not ever call adns_afterpoll
+
+</pre>
+<p>Method 4: Do not use a prepare or check watcher because the module you
+want to embed is too inflexible to support it. Instead, youc na override
+their poll function. The drawback with this solution is that the main
+loop is now no longer controllable by EV. The <code>Glib::EV</code> module does
+this.</p>
+<pre> static gint
+ 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_loop (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;
+ }
+
<pre> #include <ev++.h>
</pre>
-<p>(it is not installed by default). This automatically includes <cite>ev.h</cite>
-and puts all of its definitions (many of them macros) into the global
-namespace. All C++ specific things are put into the <code>ev</code> namespace.</p>
-<p>It should support all the same embedding options as <cite>ev.h</cite>, most notably
-<code>EV_MULTIPLICITY</code>.</p>
+<p>This automatically includes <cite>ev.h</cite> and puts all of its definitions (many
+of them macros) into the global namespace. All C++ specific things are
+put into the <code>ev</code> namespace. It should support all the same embedding
+options as <cite>ev.h</cite>, most notably <code>EV_MULTIPLICITY</code>.</p>
+<p>Care has been taken to keep the overhead low. The only data member the C++
+classes add (compared to plain C-style watchers) is the event loop pointer
+that the watcher is associated with (or no additional members at all if
+you disable <code>EV_MULTIPLICITY</code> when embedding libev).</p>
+<p>Currently, functions, and static and non-static member functions can be
+used as callbacks. Other types should be easy to add as long as they only
+need one additional pointer for context. If you need support for other
+types of functors please contact the author (preferably after implementing
+it).</p>
<p>Here is a list of things available in the <code>ev</code> namespace:</p>
<dl>
<dt><code>ev::READ</code>, <code>ev::WRITE</code> etc.</dt>
<p>All of those classes have these methods:</p>
<p>
<dl>
- <dt>ev::TYPE::TYPE (object *, object::method *)</dt>
- <dt>ev::TYPE::TYPE (object *, object::method *, struct ev_loop *)</dt>
+ <dt>ev::TYPE::TYPE ()</dt>
+ <dt>ev::TYPE::TYPE (struct ev_loop *)</dt>
<dt>ev::TYPE::~TYPE</dt>
<dd>
- <p>The constructor takes a pointer to an object and a method pointer to
-the event handler callback to call in this class. The constructor calls
-<code>ev_init</code> for you, which means you have to call the <code>set</code> method
-before starting it. If you do not specify a loop then the constructor
-automatically associates the default loop with this watcher.</p>
+ <p>The constructor (optionally) takes an event loop to associate the watcher
+with. If it is omitted, it will use <code>EV_DEFAULT</code>.</p>
+ <p>The constructor calls <code>ev_init</code> for you, which means you have to call the
+<code>set</code> method before starting it.</p>
+ <p>It will not set a callback, however: You have to call the templated <code>set</code>
+method to set a callback before you can start the watcher.</p>
+ <p>(The reason why you have to use a method is a limitation in C++ which does
+not allow explicit template arguments for constructors).</p>
<p>The destructor automatically stops the watcher if it is active.</p>
</dd>
+ <dt>w->set<class, &class::method> (object *)</dt>
+ <dd>
+ <p>This method sets the callback method to call. The method has to have a
+signature of <code>void (*)(ev_TYPE &, int)</code>, it receives the watcher as
+first argument and the <code>revents</code> as second. The object must be given as
+parameter and is stored in the <code>data</code> member of the watcher.</p>
+ <p>This method synthesizes efficient thunking code to call your method from
+the C callback that libev requires. If your compiler can inline your
+callback (i.e. it is visible to it at the place of the <code>set</code> call and
+your compiler is good :), then the method will be fully inlined into the
+thunking function, making it as fast as a direct C callback.</p>
+ <p>Example: simple class declaration and watcher initialisation</p>
+<pre> struct myclass
+ {
+ void io_cb (ev::io &w, int revents) { }
+ }
+
+ myclass obj;
+ ev::io iow;
+ iow.set <myclass, &myclass::io_cb> (&obj);
+
+</pre>
+ </dd>
+ <dt>w->set<function> (void *data = 0)</dt>
+ <dd>
+ <p>Also sets a callback, but uses a static method or plain function as
+callback. The optional <code>data</code> argument will be stored in the watcher's
+<code>data</code> member and is free for you to use.</p>
+ <p>The prototype of the <code>function</code> must be <code>void (*)(ev::TYPE &w, int)</code>.</p>
+ <p>See the method-<code>set</code> above for more details.</p>
+ <p>Example:</p>
+<pre> static void io_cb (ev::io &w, int revents) { }
+ iow.set <io_cb> ();
+
+</pre>
+ </dd>
<dt>w->set (struct ev_loop *)</dt>
<dd>
<p>Associates a different <code>struct ev_loop</code> with this watcher. You can only
<dt>w->set ([args])</dt>
<dd>
<p>Basically the same as <code>ev_TYPE_set</code>, with the same args. Must be
-called at least once. Unlike the C counterpart, an active watcher gets
-automatically stopped and restarted.</p>
+called at least once. Unlike the C counterpart, an active watcher gets
+automatically stopped and restarted when reconfiguring it with this
+method.</p>
</dd>
<dt>w->start ()</dt>
<dd>
- <p>Starts the watcher. Note that there is no <code>loop</code> argument as the
-constructor already takes the loop.</p>
+ <p>Starts the watcher. Note that there is no <code>loop</code> argument, as the
+constructor already stores the event loop.</p>
</dd>
<dt>w->stop ()</dt>
<dd>
}
myclass::myclass (int fd)
- : io (this, &myclass::io_cb),
- idle (this, &myclass::idle_cb)
{
+ io .set <myclass, &myclass::io_cb > (this);
+ idle.set <myclass, &myclass::idle_cb> (this);
+
io.start (fd, ev::READ);
}
<p>In this section the complexities of (many of) the algorithms used inside
libev will be explained. For complexity discussions about backends see the
documentation for <code>ev_default_init</code>.</p>
+ <p>All of the following are about amortised time: If an array needs to be
+extended, libev needs to realloc and move the whole array, but this
+happens asymptotically never with higher number of elements, so O(1) might
+mean it might do a lengthy realloc operation in rare cases, but on average
+it is much faster and asymptotically approaches constant time.</p>
<p>
<dl>
<dt>Starting and stopping timer/periodic watchers: O(log skipped_other_timers)</dt>
</dd>
<dt>Starting io/check/prepare/idle/signal/child watchers: O(1)</dt>
<dd>
- <p>These just add the watcher into an array or at the head of a list. If
-the array needs to be extended libev needs to realloc and move the whole
-array, but this happen asymptotically less and less with more watchers,
-thus amortised O(1).</p>
+ <p>These just add the watcher into an array or at the head of a list.
+=item Stopping check/prepare/idle watchers: O(1)</p>
</dd>
- <dt>Stopping check/prepare/idle watchers: O(1)</dt>
<dt>Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))</dt>
<dd>
<p>These watchers are stored in lists then need to be walked to find the
projects / software / libev.git / blobdiff