<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 Nov 23 17:17:04 2007" />
+ <meta name="created" content="Mon Nov 26 11:20:35 2007" />
<meta name="generator" content="Pod::Xhtml 1.57" />
<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
<body>
<li><a href="#GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</a></li>
<li><a href="#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP">FUNCTIONS CONTROLLING THE EVENT LOOP</a></li>
<li><a href="#ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</a>
-<ul><li><a href="#ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</a></li>
+<ul><li><a href="#GENERIC_WATCHER_FUNCTIONS">GENERIC WATCHER FUNCTIONS</a></li>
+<li><a href="#ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</a></li>
</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>
-<li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring 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>
-<li><a href="#code_ev_child_code_wait_for_pid_stat"><code>ev_child</code> - wait for pid status changes</a></li>
-<li><a href="#code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do</a></li>
-<li><a href="#code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop</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></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>
+<li><a href="#code_ev_child_code_watch_out_for_pro"><code>ev_child</code> - watch out for process status changes</a></li>
+<li><a href="#code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do...</a></li>
+<li><a href="#code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop!</a></li>
+<li><a href="#code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough...</a></li>
</ul>
</li>
<li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li>
<li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li>
<li><a href="#C_SUPPORT">C++ SUPPORT</a></li>
+<li><a href="#EMBEDDING">EMBEDDING</a>
+<ul><li><a href="#FILESETS">FILESETS</a>
+<ul><li><a href="#CORE_EVENT_LOOP">CORE EVENT LOOP</a></li>
+<li><a href="#LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</a></li>
+<li><a href="#AUTOCONF_SUPPORT">AUTOCONF SUPPORT</a></li>
+</ul>
+</li>
+<li><a href="#PREPROCESSOR_SYMBOLS_MACROS">PREPROCESSOR SYMBOLS/MACROS</a></li>
+<li><a href="#EXAMPLES">EXAMPLES</a></li>
+</ul>
+</li>
+<li><a href="#COMPLEXITIES">COMPLEXITIES</a></li>
<li><a href="#AUTHOR">AUTHOR</a>
</li>
</ul><hr />
(assuming you know what you are doing). This is the set of backends that
libev will probe for if you specify no backends explicitly.</p>
</dd>
+ <dt>unsigned int ev_embeddable_backends ()</dt>
+ <dd>
+ <p>Returns the set of backends that are embeddable in other event loops. This
+is the theoretical, all-platform, value. To find which backends
+might be supported on the current system, you would need to look at
+<code>ev_embeddable_backends () & ev_supported_backends ()</code>, likewise for
+recommended ones.</p>
+ <p>See the description of <code>ev_embed</code> watchers for more info.</p>
+ </dd>
<dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt>
<dd>
<p>Sets the allocation function to use (the prototype is similar to the
<dt>ev_default_destroy ()</dt>
<dd>
<p>Destroys the default loop again (frees all memory and kernel state
-etc.). This stops all registered event watchers (by not touching them in
-any way whatsoever, although you cannot rely on this :).</p>
+etc.). None of the active event watchers will be stopped in the normal
+sense, so e.g. <code>ev_is_active</code> might still return true. It is your
+responsibility to either stop all watchers cleanly yoursef <i>before</i>
+calling this function, or cope with the fact afterwards (which is usually
+the easiest thing, youc na just ignore the watchers and/or <code>free ()</code> them
+for example).</p>
</dd>
<dt>ev_loop_destroy (loop)</dt>
<dd>
</dd>
</dl>
+
+
+
+
</div>
<h1 id="ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="ANATOMY_OF_A_WATCHER_CONTENT">
corresponding stop function (<code>ev_<type>_stop (loop, watcher *)</code>.</p>
<p>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
-reinitialise it or call its set macro.</p>
-<p>You can check whether an event is active by calling the <code>ev_is_active
-(watcher *)</code> macro. To see whether an event is outstanding (but the
-callback for it has not been called yet) you can use the <code>ev_is_pending
-(watcher *)</code> macro.</p>
+reinitialise it or call its <code>set</code> macro.</p>
<p>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.</p>
</dd>
</dl>
+</div>
+<h2 id="GENERIC_WATCHER_FUNCTIONS">GENERIC WATCHER FUNCTIONS</h2>
+<div id="GENERIC_WATCHER_FUNCTIONS_CONTENT">
+<p>In the following description, <code>TYPE</code> stands for the watcher type,
+e.g. <code>timer</code> for <code>ev_timer</code> watchers and <code>io</code> for <code>ev_io</code> watchers.</p>
+<dl>
+ <dt><code>ev_init</code> (ev_TYPE *watcher, callback)</dt>
+ <dd>
+ <p>This macro initialises the generic portion of a watcher. The contents
+of the watcher object can be arbitrary (so <code>malloc</code> will do). Only
+the generic parts of the watcher are initialised, you <i>need</i> to call
+the type-specific <code>ev_TYPE_set</code> macro afterwards to initialise the
+type-specific parts. For each type there is also a <code>ev_TYPE_init</code> macro
+which rolls both calls into one.</p>
+ <p>You can reinitialise a watcher at any time as long as it has been stopped
+(or never started) and there are no pending events outstanding.</p>
+ <p>The callback is always of type <code>void (*)(ev_loop *loop, ev_TYPE *watcher,
+int revents)</code>.</p>
+ </dd>
+ <dt><code>ev_TYPE_set</code> (ev_TYPE *, [args])</dt>
+ <dd>
+ <p>This macro initialises the type-specific parts of a watcher. You need to
+call <code>ev_init</code> at least once before you call this macro, but you can
+call <code>ev_TYPE_set</code> any number of times. You must not, however, call this
+macro on a watcher that is active (it can be pending, however, which is a
+difference to the <code>ev_init</code> macro).</p>
+ <p>Although some watcher types do not have type-specific arguments
+(e.g. <code>ev_prepare</code>) you still need to call its <code>set</code> macro.</p>
+ </dd>
+ <dt><code>ev_TYPE_init</code> (ev_TYPE *watcher, callback, [args])</dt>
+ <dd>
+ <p>This convinience macro rolls both <code>ev_init</code> and <code>ev_TYPE_set</code> macro
+calls into a single call. This is the most convinient method to initialise
+a watcher. The same limitations apply, of course.</p>
+ </dd>
+ <dt><code>ev_TYPE_start</code> (loop *, ev_TYPE *watcher)</dt>
+ <dd>
+ <p>Starts (activates) the given watcher. Only active watchers will receive
+events. If the watcher is already active nothing will happen.</p>
+ </dd>
+ <dt><code>ev_TYPE_stop</code> (loop *, ev_TYPE *watcher)</dt>
+ <dd>
+ <p>Stops the given watcher again (if active) and clears the pending
+status. It is possible that stopped watchers are pending (for example,
+non-repeating timers are being stopped when they become pending), but
+<code>ev_TYPE_stop</code> ensures that the watcher is neither active nor pending. If
+you want to free or reuse the memory used by the watcher it is therefore a
+good idea to always call its <code>ev_TYPE_stop</code> function.</p>
+ </dd>
+ <dt>bool ev_is_active (ev_TYPE *watcher)</dt>
+ <dd>
+ <p>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.</p>
+ </dd>
+ <dt>bool ev_is_pending (ev_TYPE *watcher)</dt>
+ <dd>
+ <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>
+ </dd>
+ <dt>callback = ev_cb (ev_TYPE *watcher)</dt>
+ <dd>
+ <p>Returns the callback currently set on the watcher.</p>
+ </dd>
+ <dt>ev_cb_set (ev_TYPE *watcher, callback)</dt>
+ <dd>
+ <p>Change the callback. You can change the callback at virtually any time
+(modulo threads).</p>
+ </dd>
+</dl>
+
+
+
+
+
</div>
<h2 id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</h2>
<div id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH-2">
</div>
-<h2 id="code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable</h2>
+<h2 id="code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable?</h2>
<div id="code_ev_io_code_is_this_file_descrip-2">
<p>I/O watchers check whether a file descriptor is readable or writable
-in each iteration of the event loop (This behaviour is called
-level-triggering because you keep receiving events as long as the
-condition persists. Remember you can stop the watcher if you don't want to
-act on the event and neither want to receive future events).</p>
+in each iteration of the event loop, or, more precisely, when reading
+would not block the process and writing would at least be able to write
+some data. This behaviour is called level-triggering because you keep
+receiving events as long as the condition persists. Remember you can stop
+the watcher if you don't want to act on the event and neither want to
+receive future events.</p>
<p>In general you can register as many read and/or write event watchers per
fd as you want (as long as you don't confuse yourself). Setting all file
descriptors to non-blocking mode is also usually a good idea (but not
<p>You have to be careful with dup'ed file descriptors, though. Some backends
(the linux epoll backend is a notable example) cannot handle dup'ed file
descriptors correctly if you register interest in two or more fds pointing
-to the same underlying file/socket etc. description (that is, they share
+to the same underlying file/socket/etc. description (that is, they share
the same underlying "file open").</p>
<p>If you must do this, then force the use of a known-to-be-good backend
(at the time of this writing, this includes only <code>EVBACKEND_SELECT</code> and
<code>EVBACKEND_POLL</code>).</p>
+<p>Another thing you have to watch out for is that it is quite easy to
+receive "spurious" readyness notifications, that is your callback might
+be called with <code>EV_READ</code> but a subsequent <code>read</code>(2) will actually block
+because there is no data. Not only are some backends known to create a
+lot of those (for example solaris ports), it is very easy to get into
+this situation even with a relatively standard program structure. Thus
+it is best to always use non-blocking I/O: An extra <code>read</code>(2) returning
+<code>EAGAIN</code> is far preferable to a program hanging until some data arrives.</p>
+<p>If you cannot run the fd in non-blocking mode (for example you should not
+play around with an Xlib connection), then you have to seperately re-test
+wether 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>
<dl>
<dt>ev_io_init (ev_io *, callback, int fd, int events)</dt>
<dt>ev_io_set (ev_io *, int fd, int events)</dt>
<dd>
- <p>Configures an <code>ev_io</code> watcher. The fd is the file descriptor to rceeive
-events for and events is either <code>EV_READ</code>, <code>EV_WRITE</code> or <code>EV_READ |
-EV_WRITE</code> to receive the given events.</p>
- <p>Please note that most of the more scalable backend mechanisms (for example
-epoll and solaris ports) can result in spurious readyness notifications
-for file descriptors, so you practically need to use non-blocking I/O (and
-treat callback invocation as hint only), or retest separately with a safe
-interface before doing I/O (XLib can do this), or force the use of either
-<code>EVBACKEND_SELECT</code> or <code>EVBACKEND_POLL</code>, which don't suffer from this
-problem. Also note that it is quite easy to have your callback invoked
-when the readyness condition is no longer valid even when employing
-typical ways of handling events, so its a good idea to use non-blocking
-I/O unconditionally.</p>
+ <p>Configures an <code>ev_io</code> watcher. The <code>fd</code> is the file descriptor to
+rceeive events for and events is either <code>EV_READ</code>, <code>EV_WRITE</code> or
+<code>EV_READ | EV_WRITE</code> to receive the given events.</p>
</dd>
</dl>
<p>Example: call <code>stdin_readable_cb</code> when STDIN_FILENO has become, well
</pre>
</div>
-<h2 id="code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring timeouts</h2>
+<h2 id="code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally repeating timeouts</h2>
<div id="code_ev_timer_code_relative_and_opti-2">
<p>Timer watchers are simple relative timers that generate an event after a
given time, and optionally repeating in regular intervals after that.</p>
</pre>
</div>
-<h2 id="code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron</h2>
+<h2 id="code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron?</h2>
<div id="code_ev_periodic_code_to_cron_or_not-2">
<p>Periodic watchers are also timers of a kind, but they are very versatile
(and unfortunately a bit complex).</p>
<p>Unlike <code>ev_timer</code>'s, they are not based on real time (or relative time)
but on wallclock time (absolute time). You can tell a periodic watcher
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
+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>
</pre>
</div>
-<h2 id="code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled</h2>
+<h2 id="code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled!</h2>
<div id="code_ev_signal_code_signal_me_when_a-2">
<p>Signal watchers will trigger an event when the process receives a specific
signal one or more times. Even though signals are very asynchronous, libev
</dd>
</dl>
+
+
+
+
</div>
-<h2 id="code_ev_child_code_wait_for_pid_stat"><code>ev_child</code> - wait for pid status changes</h2>
-<div id="code_ev_child_code_wait_for_pid_stat-2">
+<h2 id="code_ev_child_code_watch_out_for_pro"><code>ev_child</code> - watch out for process status changes</h2>
+<div id="code_ev_child_code_watch_out_for_pro-2">
<p>Child watchers trigger when your process receives a SIGCHLD in response to
some child status changes (most typically when a child of yours dies).</p>
<dl>
</pre>
</div>
-<h2 id="code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do</h2>
+<h2 id="code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do...</h2>
<div id="code_ev_idle_code_when_you_ve_got_no-2">
<p>Idle watchers trigger events when there are no other events are pending
(prepare, check and other idle watchers do not count). That is, as long
</pre>
</div>
-<h2 id="code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop</h2>
+<h2 id="code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop!</h2>
<div id="code_ev_prepare_code_and_code_ev_che-2">
<p>Prepare and check watchers are usually (but not always) used in tandem:
prepare watchers get invoked before the process blocks and check watchers
afterwards.</p>
-<p>Their main purpose is to integrate other event mechanisms into libev. This
-could be used, for example, to track variable changes, implement your own
-watchers, integrate net-snmp or a coroutine library and lots more.</p>
+<p>You <i>must not</i> call <code>ev_loop</code> or similar functions that enter
+the current event loop from either <code>ev_prepare</code> or <code>ev_check</code>
+watchers. Other loops than the current one are fine, however. The
+rationale behind this is that you do not need to check for recursion in
+those watchers, i.e. the sequence will always be <code>ev_prepare</code>, blocking,
+<code>ev_check</code> so if you have one watcher of each kind they will always be
+called in pairs bracketing the blocking call.</p>
+<p>Their main purpose is to integrate other event mechanisms into libev and
+their use is somewhat advanced. This could be used, for example, to track
+variable changes, implement your own watchers, integrate net-snmp or a
+coroutine library and lots more. They are also occasionally useful if
+you cache some data and want to flush it before blocking (for example,
+in X programs you might want to do an <code>XFlush ()</code> in an <code>ev_prepare</code>
+watcher).</p>
<p>This is done by examining in each prepare call which file descriptors need
to be watched by the other library, registering <code>ev_io</code> watchers for
them and starting an <code>ev_timer</code> watcher for any timeouts (many libraries
macros, but using them is utterly, utterly and completely pointless.</p>
</dd>
</dl>
-<p>Example: *TODO*.</p>
+<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>
+<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
+ static void
+ adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
+ {
+ int timeout = 3600000;truct pollfd fds [nfd];
+ // actual code will need to loop here and realloc etc.
+ adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
+
+ /* the callback is illegal, but won't be called as we stop during check */
+ ev_timer_init (&tw, 0, timeout * 1e-3);
+ ev_timer_start (loop, &tw);
+
+ // create on ev_io per pollfd
+ for (int i = 0; i < nfd; ++i)
+ {
+ ev_io_init (iow + i, io_cb, fds [i].fd,
+ ((fds [i].events & POLLIN ? EV_READ : 0)
+ | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
+
+ fds [i].revents = 0;
+ iow [i].data = fds + i;
+ ev_io_start (loop, iow + i);
+ }
+ }
+
+ // stop all watchers after blocking
+ static void
+ adns_check_cb (ev_loop *loop, ev_check *w, int revents)
+ {
+ ev_timer_stop (loop, &tw);
+
+ for (int i = 0; i < nfd; ++i)
+ ev_io_stop (loop, iow + i);
+
+ adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
+ }
+
+
+
+
+</pre>
+
+</div>
+<h2 id="code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough...</h2>
+<div id="code_ev_embed_code_when_one_backend_-2">
+<p>This is a rather advanced watcher type that lets you embed one event loop
+into another (currently only <code>ev_io</code> 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).</p>
+<p>There are primarily two reasons you would want that: work around bugs and
+prioritise I/O.</p>
+<p>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 poll and then call kevent, but
+at least you can use both at what they are best.</p>
+<p>As for prioritising I/O: rarely 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.</p>
+<p>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 <code>ev_embed_sweep (mainloop, watcher)</code> to make a single sweep and invoke
+their callbacks (you could also start an idle watcher to give the embedded
+loop strictly lower priority for example). You can also set the callback
+to <code>0</code>, in which case the embed watcher will automatically execute the
+embedded loop sweep.</p>
+<p>As long as the watcher is started it will automatically handle events. The
+callback will be invoked whenever some events have been handled. You can
+set the callback to <code>0</code> to avoid having to specify one if you are not
+interested in that.</p>
+<p>Also, there have not currently been made special provisions for forking:
+when you fork, you not only have to call <code>ev_loop_fork</code> on both loops,
+but you will also have to stop and restart any <code>ev_embed</code> watchers
+yourself.</p>
+<p>Unfortunately, not all backends are embeddable, only the ones returned by
+<code>ev_embeddable_backends</code> are, which, unfortunately, does not include any
+portable one.</p>
+<p>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:</p>
+<pre> struct ev_loop *loop_hi = ev_default_init (0);
+ struct ev_loop *loop_lo = 0;
+ struct ev_embed embed;
+
+ // see if there is a chance of getting one that works
+ // (remember that a flags value of 0 means autodetection)
+ loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
+ ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
+ : 0;
+
+ // if we got one, then embed it, otherwise default to loop_hi
+ if (loop_lo)
+ {
+ ev_embed_init (&embed, 0, loop_lo);
+ ev_embed_start (loop_hi, &embed);
+ }
+ else
+ loop_lo = loop_hi;
+
+</pre>
+<dl>
+ <dt>ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)</dt>
+ <dt>ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)</dt>
+ <dd>
+ <p>Configures the watcher to embed the given loop, which must be
+embeddable. If the callback is <code>0</code>, then <code>ev_embed_sweep</code> 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 thta, you need to temporarily stop the embed watcher).</p>
+ </dd>
+ <dt>ev_embed_sweep (loop, ev_embed *)</dt>
+ <dd>
+ <p>Make a single, non-blocking sweep over the embedded loop. This works
+similarly to <code>ev_loop (embedded_loop, EVLOOP_NONBLOCK)</code>, but in the most
+apropriate way for embedded loops.</p>
+ </dd>
+</dl>
</pre>
</dd>
- <dt>ev_feed_event (loop, watcher, int events)</dt>
+ <dt>ev_feed_event (ev_loop *, watcher *, int revents)</dt>
<dd>
<p>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).</p>
</dd>
- <dt>ev_feed_fd_event (loop, int fd, int revents)</dt>
+ <dt>ev_feed_fd_event (ev_loop *, int fd, int revents)</dt>
<dd>
<p>Feed an event on the given fd, as if a file descriptor backend detected
the given events it.</p>
</dd>
- <dt>ev_feed_signal_event (loop, int signum)</dt>
+ <dt>ev_feed_signal_event (ev_loop *loop, int signum)</dt>
<dd>
- <p>Feed an event as if the given signal occured (loop must be the default loop!).</p>
+ <p>Feed an event as if the given signal occured (<code>loop</code> must be the default
+loop!).</p>
</dd>
</dl>
</div>
<h1 id="C_SUPPORT">C++ SUPPORT</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="C_SUPPORT_CONTENT">
-<p>TBD.</p>
+<p>Libev comes with some simplistic wrapper classes for C++ that mainly allow
+you to use some convinience methods to start/stop watchers and also change
+the callback model to a model using method callbacks on objects.</p>
+<p>To use it,</p>
+<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>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>
+ <dd>
+ <p>These are just enum values with the same values as the <code>EV_READ</code> etc.
+macros from <cite>ev.h</cite>.</p>
+ </dd>
+ <dt><code>ev::tstamp</code>, <code>ev::now</code></dt>
+ <dd>
+ <p>Aliases to the same types/functions as with the <code>ev_</code> prefix.</p>
+ </dd>
+ <dt><code>ev::io</code>, <code>ev::timer</code>, <code>ev::periodic</code>, <code>ev::idle</code>, <code>ev::sig</code> etc.</dt>
+ <dd>
+ <p>For each <code>ev_TYPE</code> watcher in <cite>ev.h</cite> there is a corresponding class of
+the same name in the <code>ev</code> namespace, with the exception of <code>ev_signal</code>
+which is called <code>ev::sig</code> to avoid clashes with the <code>signal</code> macro
+defines by many implementations.</p>
+ <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>
+ <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 destructor automatically stops the watcher if it is active.</p>
+ </dd>
+ <dt>w->set (struct ev_loop *)</dt>
+ <dd>
+ <p>Associates a different <code>struct ev_loop</code> with this watcher. You can only
+do this when the watcher is inactive (and not pending either).</p>
+ </dd>
+ <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>
+ </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>
+ </dd>
+ <dt>w->stop ()</dt>
+ <dd>
+ <p>Stops the watcher if it is active. Again, no <code>loop</code> argument.</p>
+ </dd>
+ <dt>w->again () <code>ev::timer</code>, <code>ev::periodic</code> only</dt>
+ <dd>
+ <p>For <code>ev::timer</code> and <code>ev::periodic</code>, this invokes the corresponding
+<code>ev_TYPE_again</code> function.</p>
+ </dd>
+ <dt>w->sweep () <code>ev::embed</code> only</dt>
+ <dd>
+ <p>Invokes <code>ev_embed_sweep</code>.</p>
+ </dd>
+ </dl>
+ </p>
+ </dd>
+</dl>
+<p>Example: Define a class with an IO and idle watcher, start one of them in
+the constructor.</p>
+<pre> class myclass
+ {
+ ev_io io; void io_cb (ev::io &w, int revents);
+ ev_idle idle void idle_cb (ev::idle &w, int revents);
+
+ myclass ();
+ }
+
+ myclass::myclass (int fd)
+ : io (this, &myclass::io_cb),
+ idle (this, &myclass::idle_cb)
+ {
+ io.start (fd, ev::READ);
+ }
+
+</pre>
+
+</div>
+<h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="EMBEDDING_CONTENT">
+<p>Libev can (and often is) directly embedded into host
+applications. Examples of applications that embed it include the Deliantra
+Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
+and rxvt-unicode.</p>
+<p>The goal is to enable you to just copy the neecssary files into your
+source directory without having to change even a single line in them, so
+you can easily upgrade by simply copying (or having a checked-out copy of
+libev somewhere in your source tree).</p>
+
+</div>
+<h2 id="FILESETS">FILESETS</h2>
+<div id="FILESETS_CONTENT">
+<p>Depending on what features you need you need to include one or more sets of files
+in your app.</p>
+
+</div>
+<h3 id="CORE_EVENT_LOOP">CORE EVENT LOOP</h3>
+<div id="CORE_EVENT_LOOP_CONTENT">
+<p>To include only the libev core (all the <code>ev_*</code> functions), with manual
+configuration (no autoconf):</p>
+<pre> #define EV_STANDALONE 1
+ #include "ev.c"
+
+</pre>
+<p>This will automatically include <cite>ev.h</cite>, too, and should be done in a
+single C source file only to provide the function implementations. To use
+it, do the same for <cite>ev.h</cite> in all files wishing to use this API (best
+done by writing a wrapper around <cite>ev.h</cite> that you can include instead and
+where you can put other configuration options):</p>
+<pre> #define EV_STANDALONE 1
+ #include "ev.h"
+
+</pre>
+<p>Both header files and implementation files can be compiled with a C++
+compiler (at least, thats a stated goal, and breakage will be treated
+as a bug).</p>
+<p>You need the following files in your source tree, or in a directory
+in your include path (e.g. in libev/ when using -Ilibev):</p>
+<pre> ev.h
+ ev.c
+ ev_vars.h
+ ev_wrap.h
+
+ ev_win32.c required on win32 platforms only
+
+ ev_select.c only when select backend is enabled (which is by default)
+ ev_poll.c only when poll backend is enabled (disabled by default)
+ ev_epoll.c only when the epoll backend is enabled (disabled by default)
+ ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
+ ev_port.c only when the solaris port backend is enabled (disabled by default)
+
+</pre>
+<p><cite>ev.c</cite> includes the backend files directly when enabled, so you only need
+to compile this single file.</p>
+
+</div>
+<h3 id="LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</h3>
+<div id="LIBEVENT_COMPATIBILITY_API_CONTENT">
+<p>To include the libevent compatibility API, also include:</p>
+<pre> #include "event.c"
+
+</pre>
+<p>in the file including <cite>ev.c</cite>, and:</p>
+<pre> #include "event.h"
+
+</pre>
+<p>in the files that want to use the libevent API. This also includes <cite>ev.h</cite>.</p>
+<p>You need the following additional files for this:</p>
+<pre> event.h
+ event.c
+
+</pre>
+
+</div>
+<h3 id="AUTOCONF_SUPPORT">AUTOCONF SUPPORT</h3>
+<div id="AUTOCONF_SUPPORT_CONTENT">
+<p>Instead of using <code>EV_STANDALONE=1</code> and providing your config in
+whatever way you want, you can also <code>m4_include([libev.m4])</code> in your
+<cite>configure.ac</cite> and leave <code>EV_STANDALONE</code> undefined. <cite>ev.c</cite> will then
+include <cite>config.h</cite> and configure itself accordingly.</p>
+<p>For this of course you need the m4 file:</p>
+<pre> libev.m4
+
+</pre>
+
+</div>
+<h2 id="PREPROCESSOR_SYMBOLS_MACROS">PREPROCESSOR SYMBOLS/MACROS</h2>
+<div id="PREPROCESSOR_SYMBOLS_MACROS_CONTENT">
+<p>Libev can be configured via a variety of preprocessor symbols you have to define
+before including any of its files. The default is not to build for multiplicity
+and only include the select backend.</p>
+<dl>
+ <dt>EV_STANDALONE</dt>
+ <dd>
+ <p>Must always be <code>1</code> if you do not use autoconf configuration, which
+keeps libev from including <cite>config.h</cite>, and it also defines dummy
+implementations for some libevent functions (such as logging, which is not
+supported). It will also not define any of the structs usually found in
+<cite>event.h</cite> that are not directly supported by the libev core alone.</p>
+ </dd>
+ <dt>EV_USE_MONOTONIC</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will try to detect the availability of the
+monotonic clock option at both compiletime and runtime. Otherwise no use
+of the monotonic clock option will be attempted. If you enable this, you
+usually have to link against librt or something similar. Enabling it when
+the functionality isn't available is safe, though, althoguh you have
+to make sure you link against any libraries where the <code>clock_gettime</code>
+function is hiding in (often <cite>-lrt</cite>).</p>
+ </dd>
+ <dt>EV_USE_REALTIME</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will try to detect the availability of the
+realtime clock option at compiletime (and assume its availability at
+runtime if successful). Otherwise no use of the realtime clock option will
+be attempted. This effectively replaces <code>gettimeofday</code> by <code>clock_get
+(CLOCK_REALTIME, ...)</code> and will not normally affect correctness. See tzhe note about libraries
+in the description of <code>EV_USE_MONOTONIC</code>, though.</p>
+ </dd>
+ <dt>EV_USE_SELECT</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, libev will compile in support for the
+<code>select</code>(2) backend. No attempt at autodetection will be done: if no
+other method takes over, select will be it. Otherwise the select backend
+will not be compiled in.</p>
+ </dd>
+ <dt>EV_SELECT_USE_FD_SET</dt>
+ <dd>
+ <p>If defined to <code>1</code>, then the select backend will use the system <code>fd_set</code>
+structure. This is useful if libev doesn't compile due to a missing
+<code>NFDBITS</code> or <code>fd_mask</code> definition or it misguesses the bitset layout on
+exotic systems. This usually limits the range of file descriptors to some
+low limit such as 1024 or might have other limitations (winsocket only
+allows 64 sockets). The <code>FD_SETSIZE</code> macro, set before compilation, might
+influence the size of the <code>fd_set</code> used.</p>
+ </dd>
+ <dt>EV_SELECT_IS_WINSOCKET</dt>
+ <dd>
+ <p>When defined to <code>1</code>, the select backend will assume that
+select/socket/connect etc. don't understand file descriptors but
+wants osf handles on win32 (this is the case when the select to
+be used is the winsock select). This means that it will call
+<code>_get_osfhandle</code> on the fd to convert it to an OS handle. Otherwise,
+it is assumed that all these functions actually work on fds, even
+on win32. Should not be defined on non-win32 platforms.</p>
+ </dd>
+ <dt>EV_USE_POLL</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will compile in support for the <code>poll</code>(2)
+backend. Otherwise it will be enabled on non-win32 platforms. It
+takes precedence over select.</p>
+ </dd>
+ <dt>EV_USE_EPOLL</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will compile in support for the Linux
+<code>epoll</code>(7) backend. Its availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the
+preferred backend for GNU/Linux systems.</p>
+ </dd>
+ <dt>EV_USE_KQUEUE</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will compile in support for the BSD style
+<code>kqueue</code>(2) backend. Its actual availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the preferred
+backend for BSD and BSD-like systems, although on most BSDs kqueue only
+supports some types of fds correctly (the only platform we found that
+supports ptys for example was NetBSD), so kqueue might be compiled in, but
+not be used unless explicitly requested. The best way to use it is to find
+out whether kqueue supports your type of fd properly and use an embedded
+kqueue loop.</p>
+ </dd>
+ <dt>EV_USE_PORT</dt>
+ <dd>
+ <p>If defined to be <code>1</code>, libev will compile in support for the Solaris
+10 port style backend. Its availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the preferred
+backend for Solaris 10 systems.</p>
+ </dd>
+ <dt>EV_USE_DEVPOLL</dt>
+ <dd>
+ <p>reserved for future expansion, works like the USE symbols above.</p>
+ </dd>
+ <dt>EV_H</dt>
+ <dd>
+ <p>The name of the <cite>ev.h</cite> header file used to include it. The default if
+undefined is <code><ev.h></code> in <cite>event.h</cite> and <code>"ev.h"</code> in <cite>ev.c</cite>. This
+can be used to virtually rename the <cite>ev.h</cite> header file in case of conflicts.</p>
+ </dd>
+ <dt>EV_CONFIG_H</dt>
+ <dd>
+ <p>If <code>EV_STANDALONE</code> isn't <code>1</code>, this variable can be used to override
+<cite>ev.c</cite>'s idea of where to find the <cite>config.h</cite> file, similarly to
+<code>EV_H</code>, above.</p>
+ </dd>
+ <dt>EV_EVENT_H</dt>
+ <dd>
+ <p>Similarly to <code>EV_H</code>, this macro can be used to override <cite>event.c</cite>'s idea
+of how the <cite>event.h</cite> header can be found.</p>
+ </dd>
+ <dt>EV_PROTOTYPES</dt>
+ <dd>
+ <p>If defined to be <code>0</code>, then <cite>ev.h</cite> will not define any function
+prototypes, but still define all the structs and other symbols. This is
+occasionally useful if you want to provide your own wrapper functions
+around libev functions.</p>
+ </dd>
+ <dt>EV_MULTIPLICITY</dt>
+ <dd>
+ <p>If undefined or defined to <code>1</code>, then all event-loop-specific functions
+will have the <code>struct ev_loop *</code> as first argument, and you can create
+additional independent event loops. Otherwise there will be no support
+for multiple event loops and there is no first event loop pointer
+argument. Instead, all functions act on the single default loop.</p>
+ </dd>
+ <dt>EV_PERIODICS</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, then periodic timers are supported,
+otherwise not. This saves a few kb of code.</p>
+ </dd>
+ <dt>EV_COMMON</dt>
+ <dd>
+ <p>By default, all watchers have a <code>void *data</code> member. By redefining
+this macro to a something else you can include more and other types of
+members. You have to define it each time you include one of the files,
+though, and it must be identical each time.</p>
+ <p>For example, the perl EV module uses something like this:</p>
+<pre> #define EV_COMMON \
+ SV *self; /* contains this struct */ \
+ SV *cb_sv, *fh /* note no trailing ";" */
+
+</pre>
+ </dd>
+ <dt>EV_CB_DECLARE (type)</dt>
+ <dt>EV_CB_INVOKE (watcher, revents)</dt>
+ <dt>ev_set_cb (ev, cb)</dt>
+ <dd>
+ <p>Can be used to change the callback member declaration in each watcher,
+and the way callbacks are invoked and set. Must expand to a struct member
+definition and a statement, respectively. See the <cite>ev.v</cite> header file for
+their default definitions. One possible use for overriding these is to
+avoid the <code>struct ev_loop *</code> as first argument in all cases, or to use
+method calls instead of plain function calls in C++.</p>
+
+</div>
+<h2 id="EXAMPLES">EXAMPLES</h2>
+<div id="EXAMPLES_CONTENT">
+ <p>For a real-world example of a program the includes libev
+verbatim, you can have a look at the EV perl module
+(<a href="http://software.schmorp.de/pkg/EV.html">http://software.schmorp.de/pkg/EV.html</a>). It has the libev files in
+the <cite>libev/</cite> subdirectory and includes them in the <cite>EV/EVAPI.h</cite> (public
+interface) and <cite>EV.xs</cite> (implementation) files. Only the <cite>EV.xs</cite> file
+will be compiled. It is pretty complex because it provides its own header
+file.</p>
+ <p>The usage in rxvt-unicode is simpler. It has a <cite>ev_cpp.h</cite> header file
+that everybody includes and which overrides some autoconf choices:</p>
+<pre> #define EV_USE_POLL 0
+ #define EV_MULTIPLICITY 0
+ #define EV_PERIODICS 0
+ #define EV_CONFIG_H <config.h>
+
+ #include "ev++.h"
+
+</pre>
+ <p>And a <cite>ev_cpp.C</cite> implementation file that contains libev proper and is compiled:</p>
+<pre> #include "ev_cpp.h"
+ #include "ev.c"
+
+
+
+
+</pre>
+
+</div>
+<h1 id="COMPLEXITIES">COMPLEXITIES</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="COMPLEXITIES_CONTENT">
+ <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>
+ <dl>
+ <dt>Starting and stopping timer/periodic watchers: O(log skipped_other_timers)</dt>
+ <dt>Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)</dt>
+ <dt>Starting io/check/prepare/idle/signal/child watchers: O(1)</dt>
+ <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 % 16))</dt>
+ <dt>Finding the next timer per loop iteration: O(1)</dt>
+ <dt>Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)</dt>
+ <dt>Activating one watcher: O(1)</dt>
+ </dl>
+ </p>
+
+
+
+
</div>
<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="AUTHOR_CONTENT">
-<p>Marc Lehmann <libev@schmorp.de>.</p>
+
<p>Marc Lehmann <libev@schmorp.de>.</p>
</div>
</div></body>
projects / software / libev.git / blobdiff