<meta name="description" content="Pod documentation for libev" />
<meta name="inputfile" content="<standard input>" />
<meta name="outputfile" content="<standard output>" />
- <meta name="created" content="Mon Nov 26 10:52:13 2007" />
+ <meta name="created" content="Tue Nov 27 11:59:06 2007" />
<meta name="generator" content="Pod::Xhtml 1.57" />
<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
<body>
<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_stat_code_did_the_file_attri"><code>ev_stat</code> - did the file attributes just change?</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>
+<li><a href="#code_ev_fork_code_the_audacity_to_re"><code>ev_fork</code> - the audacity to resume the event loop after a fork</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="#MACRO_MAGIC">MACRO MAGIC</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="#EXAMPLES">EXAMPLES</a></li>
</ul>
</li>
+<li><a href="#COMPLEXITIES">COMPLEXITIES</a></li>
<li><a href="#AUTHOR">AUTHOR</a>
</li>
</ul><hr />
to the <code>double</code> type in C, and when you need to do any calculations on
it, you should treat it as such.</p>
-
-
-
-
</div>
<h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="GLOBAL_FUNCTIONS_CONTENT">
<dd>
<p>The pid specified in the <code>ev_child</code> watcher has received a status change.</p>
</dd>
+ <dt><code>EV_STAT</code></dt>
+ <dd>
+ <p>The path specified in the <code>ev_stat</code> watcher changed its attributes somehow.</p>
+ </dd>
<dt><code>EV_IDLE</code></dt>
<dd>
<p>The <code>ev_idle</code> watcher has determined that you have nothing better to do.</p>
many watchers as they want, and all of them will be taken into account
(for example, a <code>ev_prepare</code> watcher might start an idle watcher to keep
<code>ev_loop</code> from blocking).</p>
+ </dd>
+ <dt><code>EV_EMBED</code></dt>
+ <dd>
+ <p>The embedded event loop specified in the <code>ev_embed</code> watcher needs attention.</p>
+ </dd>
+ <dt><code>EV_FORK</code></dt>
+ <dd>
+ <p>The event loop has been resumed in the child process after fork (see
+<code>ev_fork</code>).</p>
</dd>
<dt><code>EV_ERROR</code></dt>
<dd>
<h1 id="WATCHER_TYPES">WATCHER TYPES</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="WATCHER_TYPES_CONTENT">
<p>This section describes each watcher in detail, but will not repeat
-information given in the last section.</p>
+information given in the last section. Any initialisation/set macros,
+functions and members specific to the watcher type are explained.</p>
+<p>Members are additionally marked with either <i>[read-only]</i>, meaning that,
+while the watcher is active, you can look at the member and expect some
+sensible content, but you must not modify it (you can modify it while the
+watcher is stopped to your hearts content), or <i>[read-write]</i>, which
+means you can expect it to have some sensible content while the watcher
+is active, but you can also modify it. Modifying it may not do something
+sensible or take immediate effect (or do anything at all), but libev will
+not crash or malfunction in any way.</p>
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>
+ <dt>int fd [read-only]</dt>
+ <dd>
+ <p>The file descriptor being watched.</p>
+ </dd>
+ <dt>int events [read-only]</dt>
+ <dd>
+ <p>The events being watched.</p>
+ </dd>
</dl>
<p>Example: call <code>stdin_readable_cb</code> when STDIN_FILENO has become, well
readable, but only once. Since it is likely line-buffered, you could
<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>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 after=repeat=60 and calling ev_timer_again 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>
+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
+<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>
+<pre> ev_timer_init (timer, callback, 0., 5.);
+ ev_timer_again (loop, timer);
+ ...
+ timer->again = 17.;
+ ev_timer_again (loop, timer);
+ ...
+ timer->again = 10.;
+ 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>
+ </dd>
+ <dt>ev_tstamp repeat [read-write]</dt>
+ <dd>
+ <p>The current <code>repeat</code> value. Will be used each time the watcher times out
+or <code>ev_timer_again</code> is called and determines the next timeout (if any),
+which is also when any modifications are taken into account.</p>
</dd>
</dl>
<p>Example: create a timer that fires after 60 seconds.</p>
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 interval [read-write]</dt>
+ <dd>
+ <p>The current interval value. 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 (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]</dt>
+ <dd>
+ <p>The current reschedule callback, or <code>0</code>, if this functionality is
+switched off. Can be changed any time, but changes only take effect when
+the periodic timer fires or <code>ev_periodic_again</code> is being called.</p>
+ </dd>
</dl>
<p>Example: call a callback every hour, or, more precisely, whenever the
system clock is divisible by 3600. The callback invocation times have
<p>Configures the watcher to trigger on the given signal number (usually one
of the <code>SIGxxx</code> constants).</p>
</dd>
+ <dt>int signum [read-only]</dt>
+ <dd>
+ <p>The signal the watcher watches out for.</p>
+ </dd>
</dl>
<code>waitpid</code> documentation). The <code>rpid</code> member contains the pid of the
process causing the status change.</p>
</dd>
+ <dt>int pid [read-only]</dt>
+ <dd>
+ <p>The process id this watcher watches out for, or <code>0</code>, meaning any process id.</p>
+ </dd>
+ <dt>int rpid [read-write]</dt>
+ <dd>
+ <p>The process id that detected a status change.</p>
+ </dd>
+ <dt>int rstatus [read-write]</dt>
+ <dd>
+ <p>The process exit/trace status caused by <code>rpid</code> (see your systems
+<code>waitpid</code> and <code>sys/wait.h</code> documentation for details).</p>
+ </dd>
</dl>
<p>Example: try to exit cleanly on SIGINT and SIGTERM.</p>
<pre> static void
+</pre>
+
+</div>
+<h2 id="code_ev_stat_code_did_the_file_attri"><code>ev_stat</code> - did the file attributes just change?</h2>
+<div id="code_ev_stat_code_did_the_file_attri-2">
+<p>This watches a filesystem path for attribute changes. That is, it calls
+<code>stat</code> regularly (or when the OS says it changed) and sees if it changed
+compared to the last time, invoking the callback if it did.</p>
+<p>The path does not need to exist: changing from "path exists" to "path does
+not exist" is a status change like any other. The condition "path does
+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>Since there is no standard to do this, the portable implementation simply
+calls <code>stat (2)</code> regulalry on the path to see if it changed somehow. You
+can specify a recommended polling interval for this case. If you specify
+a polling interval of <code>0</code> (highly recommended!) then a <i>suitable,
+unspecified default</i> value will be used (which you can expect to be around
+five seconds, although this might change dynamically). Libev will also
+impose a minimum interval which is currently around <code>0.1</code>, but thats
+usually overkill.</p>
+<p>This watcher type is not meant for massive numbers of stat watchers,
+as even with OS-supported change notifications, this can be
+resource-intensive.</p>
+<p>At the time of this writing, no specific OS backends are implemented, but
+if demand increases, at least a kqueue and inotify backend will be added.</p>
+<dl>
+ <dt>ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)</dt>
+ <dt>ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)</dt>
+ <dd>
+ <p>Configures the watcher to wait for status changes of the given
+<code>path</code>. The <code>interval</code> is a hint on how quickly a change is expected to
+be detected and should normally be specified as <code>0</code> to let libev choose
+a suitable value. The memory pointed to by <code>path</code> must point to the same
+path for as long as the watcher is active.</p>
+ <p>The callback will be receive <code>EV_STAT</code> when a change was detected,
+relative to the attributes at the time the watcher was started (or the
+last change was detected).</p>
+ </dd>
+ <dt>ev_stat_stat (ev_stat *)</dt>
+ <dd>
+ <p>Updates the stat buffer immediately with new values. If you change the
+watched path in your callback, you could call this fucntion to avoid
+detecting this change (while introducing a race condition). Can also be
+useful simply to find out the new values.</p>
+ </dd>
+ <dt>ev_statdata attr [read-only]</dt>
+ <dd>
+ <p>The most-recently detected attributes of the file. Although the type is of
+<code>ev_statdata</code>, this is usually the (or one of the) <code>struct stat</code> types
+suitable for your system. If the <code>st_nlink</code> member is <code>0</code>, then there
+was some error while <code>stat</code>ing the file.</p>
+ </dd>
+ <dt>ev_statdata prev [read-only]</dt>
+ <dd>
+ <p>The previous attributes of the file. The callback gets invoked whenever
+<code>prev</code> != <code>attr</code>.</p>
+ </dd>
+ <dt>ev_tstamp interval [read-only]</dt>
+ <dd>
+ <p>The specified interval.</p>
+ </dd>
+ <dt>const char *path [read-only]</dt>
+ <dd>
+ <p>The filesystem path that is being watched.</p>
+ </dd>
+</dl>
+<p>Example: Watch <code>/etc/passwd</code> for attribute changes.</p>
+<pre> static void
+ passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
+ {
+ /* /etc/passwd changed in some way */
+ if (w->attr.st_nlink)
+ {
+ printf ("passwd current size %ld\n", (long)w->attr.st_size);
+ printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
+ printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
+ }
+ else
+ /* you shalt not abuse printf for puts */
+ puts ("wow, /etc/passwd is not there, expect problems. "
+ "if this is windows, they already arrived\n");
+ }
+
+ ...
+ ev_stat passwd;
+
+ ev_stat_init (&passwd, passwd_cb, "/etc/passwd");
+ ev_stat_start (loop, &passwd);
+
+
+
+
</pre>
</div>
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;
similarly to <code>ev_loop (embedded_loop, EVLOOP_NONBLOCK)</code>, but in the most
apropriate way for embedded loops.</p>
</dd>
+ <dt>struct ev_loop *loop [read-only]</dt>
+ <dd>
+ <p>The embedded event loop.</p>
+ </dd>
+</dl>
+
+
+
+
+
+</div>
+<h2 id="code_ev_fork_code_the_audacity_to_re"><code>ev_fork</code> - the audacity to resume the event loop after a fork</h2>
+<div id="code_ev_fork_code_the_audacity_to_re-2">
+<p>Fork watchers are called when a <code>fork ()</code> was detected (usually because
+whoever is a good citizen cared to tell libev about it by calling
+<code>ev_default_fork</code> or <code>ev_loop_fork</code>). The invocation is done before the
+event loop blocks next and before <code>ev_check</code> watchers are being called,
+and only in the child after the fork. If whoever good citizen calling
+<code>ev_default_fork</code> cheats and calls it in the wrong process, the fork
+handlers will be invoked, too, of course.</p>
+<dl>
+ <dt>ev_fork_init (ev_signal *, callback)</dt>
+ <dd>
+ <p>Initialises and configures the fork watcher - it has no parameters of any
+kind. There is a <code>ev_fork_set</code> macro, but using it is utterly pointless,
+believe me.</p>
+ </dd>
</dl>
<dd>
<p>Invokes <code>ev_embed_sweep</code>.</p>
</dd>
+ <dt>w->update () <code>ev::stat</code> only</dt>
+ <dd>
+ <p>Invokes <code>ev_stat_stat</code>.</p>
+ </dd>
</dl>
</p>
</dd>
io.start (fd, ev::READ);
}
+
+
+
+</pre>
+
+</div>
+<h1 id="MACRO_MAGIC">MACRO MAGIC</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="MACRO_MAGIC_CONTENT">
+<p>Libev can be compiled with a variety of options, the most fundemantal is
+<code>EV_MULTIPLICITY</code>. This option determines wether (most) functions and
+callbacks have an initial <code>struct ev_loop *</code> argument.</p>
+<p>To make it easier to write programs that cope with either variant, the
+following macros are defined:</p>
+<dl>
+ <dt><code>EV_A</code>, <code>EV_A_</code></dt>
+ <dd>
+ <p>This provides the loop <i>argument</i> for functions, if one is required ("ev
+loop argument"). The <code>EV_A</code> form is used when this is the sole argument,
+<code>EV_A_</code> is used when other arguments are following. Example:</p>
+<pre> ev_unref (EV_A);
+ ev_timer_add (EV_A_ watcher);
+ ev_loop (EV_A_ 0);
+
+</pre>
+ <p>It assumes the variable <code>loop</code> of type <code>struct ev_loop *</code> is in scope,
+which is often provided by the following macro.</p>
+ </dd>
+ <dt><code>EV_P</code>, <code>EV_P_</code></dt>
+ <dd>
+ <p>This provides the loop <i>parameter</i> for functions, if one is required ("ev
+loop parameter"). The <code>EV_P</code> form is used when this is the sole parameter,
+<code>EV_P_</code> is used when other parameters are following. Example:</p>
+<pre> // this is how ev_unref is being declared
+ static void ev_unref (EV_P);
+
+ // this is how you can declare your typical callback
+ static void cb (EV_P_ ev_timer *w, int revents)
+
+</pre>
+ <p>It declares a parameter <code>loop</code> of type <code>struct ev_loop *</code>, quite
+suitable for use with <code>EV_A</code>.</p>
+ </dd>
+ <dt><code>EV_DEFAULT</code>, <code>EV_DEFAULT_</code></dt>
+ <dd>
+ <p>Similar to the other two macros, this gives you the value of the default
+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>
+<pre> static void
+ check_cb (EV_P_ ev_timer *w, int revents)
+ {
+ ev_check_stop (EV_A_ w);
+ }
+
+ ev_check check;
+ ev_check_init (&check, check_cb);
+ ev_check_start (EV_DEFAULT_ &check);
+ ev_loop (EV_DEFAULT_ 0);
+
+
+
+
</pre>
</div>
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>
+ <dt>EV_PERIODIC_ENABLE</dt>
+ <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_EMBED_ENABLE</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, then embed watchers are supported. If
+defined to be <code>0</code>, then they are not.</p>
+ </dd>
+ <dt>EV_STAT_ENABLE</dt>
+ <dd>
+ <p>If undefined or defined to be <code>1</code>, then stat watchers are supported. If
+defined to be <code>0</code>, then they are not.</p>
+ </dd>
+ <dt>EV_FORK_ENABLE</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>
+ <p>If undefined or defined to be <code>1</code>, then fork watchers are supported. If
+defined to be <code>0</code>, then they are not.</p>
+ </dd>
+ <dt>EV_MINIMAL</dt>
+ <dd>
+ <p>If you need to shave off some kilobytes of code at the expense of some
+speed, define this symbol to <code>1</code>. Currently only used for gcc to override
+some inlining decisions, saves roughly 30% codesize of amd64.</p>
</dd>
<dt>EV_COMMON</dt>
<dd>
<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">
projects / software / libev.git / blobdiff