<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="Sat Nov 24 10:48:32 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="#SUMMARY_OF_GENERIC_WATCHER_FUNCTIONS">SUMMARY OF 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>
<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>
+<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>
(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>
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="SUMMARY_OF_GENERIC_WATCHER_FUNCTIONS">SUMMARY OF GENERIC WATCHER FUNCTIONS</h2>
+<div id="SUMMARY_OF_GENERIC_WATCHER_FUNCTIONS-2">
+<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 callbakc 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">
<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>
</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">
<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>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.</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
+</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>
+
+
+
+
+
</div>
<h1 id="OTHER_FUNCTIONS">OTHER FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="OTHER_FUNCTIONS_CONTENT">
</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="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
projects / software / libev.git / blobdiff