<meta name="description" content="Pod documentation for libev" />
<meta name="inputfile" content="<standard input>" />
<meta name="outputfile" content="<standard output>" />
- <meta name="created" content="Wed Nov 28 18:32:11 2007" />
+ <meta name="created" content="Fri Dec 7 17:49:47 2007" />
<meta name="generator" content="Pod::Xhtml 1.57" />
<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
<body>
override the flags completely if it is found in the environment. This is
useful to try out specific backends to test their performance, or to work
around bugs.</p>
+ </dd>
+ <dt><code>EVFLAG_FORKCHECK</code></dt>
+ <dd>
+ <p>Instead of calling <code>ev_default_fork</code> or <code>ev_loop_fork</code> manually after
+a fork, you can also make libev check for a fork in each iteration by
+enabling this flag.</p>
+ <p>This works by calling <code>getpid ()</code> on every iteration of the loop,
+and thus this might slow down your event loop if you do a lot of loop
+iterations and little real work, but is usually not noticeable (on my
+Linux system for example, <code>getpid</code> is actually a simple 5-insn sequence
+without a syscall and thus <i>very</i> fast, but my Linux system also has
+<code>pthread_atfork</code> which is even faster).</p>
+ <p>The big advantage of this flag is that you can forget about fork (and
+forget about forgetting to tell libev about forking) when you use this
+flag.</p>
+ <p>This flag setting cannot be overriden or specified in the <code>LIBEV_FLAGS</code>
+environment variable.</p>
</dd>
<dt><code>EVBACKEND_SELECT</code> (value 1, portable select backend)</dt>
<dd>
<p>Like <code>ev_default_fork</code>, but acts on an event loop created by
<code>ev_loop_new</code>. Yes, you have to call this on every allocated event loop
after fork, and how you do this is entirely your own problem.</p>
+ </dd>
+ <dt>unsigned int ev_loop_count (loop)</dt>
+ <dd>
+ <p>Returns the count of loop iterations for the loop, which is identical to
+the number of times libev did poll for new events. It starts at <code>0</code> and
+happily wraps around with enough iterations.</p>
+ <p>This value can sometimes be useful as a generation counter of sorts (it
+"ticks" the number of loop iterations), as it roughly corresponds with
+<code>ev_prepare</code> and <code>ev_check</code> calls.</p>
</dd>
<dt>unsigned int ev_backend (loop)</dt>
<dd>
<p>Change the callback. You can change the callback at virtually any time
(modulo threads).</p>
</dd>
+ <dt>ev_set_priority (ev_TYPE *watcher, priority)</dt>
+ <dt>int ev_priority (ev_TYPE *watcher)</dt>
+ <dd>
+ <p>Set and query the priority of the watcher. The priority is a small
+integer between <code>EV_MAXPRI</code> (default: <code>2</code>) and <code>EV_MINPRI</code>
+(default: <code>-2</code>). Pending watchers with higher priority will be invoked
+before watchers with lower priority, but priority will not keep watchers
+from being executed (except for <code>ev_idle</code> watchers).</p>
+ <p>This means that priorities are <i>only</i> used for ordering callback
+invocation after new events have been received. This is useful, for
+example, to reduce latency after idling, or more often, to bind two
+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>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>
</dl>
<dd>
<p>This will act as if the timer timed out and restart it again if it is
repeating. The exact semantics are:</p>
- <p>If the timer is started but nonrepeating, stop it.</p>
- <p>If the timer is repeating, either start it if necessary (with the repeat
-value), or reset the running timer to the repeat value.</p>
+ <p>If the timer is pending, its pending status is cleared.</p>
+ <p>If the timer is started but nonrepeating, stop it (as if it timed out).</p>
+ <p>If the timer is repeating, either start it if necessary (with the
+<code>repeat</code> value), or reset the running timer to the <code>repeat</code> value.</p>
<p>This sounds a bit complicated, but here is a useful and typical
-example: Imagine you have a tcp connection and you want a so-called
-idle timeout, that is, you want to be called when there have been,
-say, 60 seconds of inactivity on the socket. The easiest way to do
-this is to configure an <code>ev_timer</code> with <code>after</code>=<code>repeat</code>=<code>60</code> and calling
+example: Imagine you have a tcp connection and you want a so-called idle
+timeout, that is, you want to be called when there have been, say, 60
+seconds of inactivity on the socket. The easiest way to do this is to
+configure an <code>ev_timer</code> with a <code>repeat</code> value of <code>60</code> and then call
<code>ev_timer_again</code> each time you successfully read or write some data. If
you go into an idle state where you do not expect data to travel on the
-socket, you can stop the timer, and again will automatically restart it if
-need be.</p>
- <p>You can also ignore the <code>after</code> value and <code>ev_timer_start</code> altogether
-and only ever use the <code>repeat</code> value:</p>
+socket, you can <code>ev_timer_stop</code> the timer, and <code>ev_timer_again</code> will
+automatically restart it if need be.</p>
+ <p>That means you can ignore the <code>after</code> value and <code>ev_timer_start</code>
+altogether and only ever use the <code>repeat</code> value and <code>ev_timer_again</code>:</p>
<pre> ev_timer_init (timer, callback, 0., 5.);
ev_timer_again (loop, timer);
...
ev_timer_again (loop, timer);
</pre>
- <p>This is more efficient then stopping/starting the timer eahc time you want
-to modify its timeout value.</p>
+ <p>This is more slightly efficient then stopping/starting the timer each time
+you want to modify its timeout value.</p>
</dd>
<dt>ev_tstamp repeat [read-write]</dt>
<dd>
not exist" is signified by the <code>st_nlink</code> field being zero (which is
otherwise always forced to be at least one) and all the other fields of
the stat buffer having unspecified contents.</p>
+<p>The path <i>should</i> be absolute and <i>must not</i> end in a slash. If it is
+relative and your working directory changes, the behaviour is undefined.</p>
<p>Since there is no standard to do this, the portable implementation simply
calls <code>stat (2)</code> regularly on the path to see if it changed somehow. You
can specify a recommended polling interval for this case. If you specify
</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>
<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
-as your process is busy handling sockets or timeouts (or even signals,
-imagine) it will not be triggered. But when your process is idle all idle
-watchers are being called again and again, once per event loop iteration -
-until stopped, that is, or your process receives more events and becomes
-busy.</p>
+<p>Idle watchers trigger events when no other events of the same or higher
+priority are pending (prepare, check and other idle watchers do not
+count).</p>
+<p>That is, as long as your process is busy handling sockets or timeouts
+(or even signals, imagine) of the same or higher priority it will not be
+triggered. But when your process is idle (or only lower-priority watchers
+are pending), the idle watchers are being called once per event loop
+iteration - until stopped, that is, or your process receives more events
+and becomes busy again with higher priority stuff.</p>
<p>The most noteworthy effect is that as long as any idle watchers are
active, the process will not block when waiting for new events.</p>
<p>Apart from keeping your process non-blocking (which is a useful
static void
adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
{
- int timeout = 3600000;truct pollfd fds [nfd];
+ int timeout = 3600000;
+ struct pollfd fds [nfd];
// actual code will need to loop here and realloc etc.
adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
loop, if multiple loops are supported ("ev loop default").</p>
</dd>
</dl>
-<p>Example: Declare and initialise a check watcher, working regardless of
-wether multiple loops are supported or not.</p>
+<p>Example: Declare and initialise a check watcher, utilising the above
+macros so it will work regardless of wether multiple loops are supported
+or not.</p>
<pre> static void
check_cb (EV_P_ ev_timer *w, int revents)
{
ev_check_start (EV_DEFAULT_ &check);
ev_loop (EV_DEFAULT_ 0);
-
-
-
</pre>
</div>
ev_win32.c required on win32 platforms only
- ev_select.c only when select backend is enabled (which is by default)
+ ev_select.c only when select backend is enabled (which is enabled 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)
<dd>
<p>If undefined or defined to be <code>1</code>, then periodic timers are supported. If
defined to be <code>0</code>, then they are not. Disabling them saves a few kB of
+code.</p>
+ </dd>
+ <dt>EV_IDLE_ENABLE</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, then idle watchers are supported. If
+defined to be <code>0</code>, then they are not. Disabling them saves a few kB of
code.</p>
</dd>
<dt>EV_EMBED_ENABLE</dt>
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
+that everybody includes and which overrides some configure choices:</p>
+<pre> #define EV_MINIMAL 1
+ #define EV_USE_POLL 0
#define EV_MULTIPLICITY 0
- #define EV_PERIODICS 0
+ #define EV_PERIODIC_ENABLE 0
+ #define EV_STAT_ENABLE 0
+ #define EV_FORK_ENABLE 0
#define EV_CONFIG_H <config.h>
+ #define EV_MINPRI 0
+ #define EV_MAXPRI 0
#include "ev++.h"
projects / software / libev.git / blobdiff