mirror of /home/gitosis/repositories/libev.git
*** empty log message ***
This commit is contained in:
parent
f6718ae94b
commit
d199f05aa7
68
ev.html
68
ev.html
|
@ -6,7 +6,7 @@
|
|||
<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 12 09:20:02 2007" />
|
||||
<meta name="created" content="Mon Nov 12 09:29:10 2007" />
|
||||
<meta name="generator" content="Pod::Xhtml 1.57" />
|
||||
<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
|
||||
<body>
|
||||
|
@ -109,7 +109,7 @@ 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>Usually, its a good idea to terminate if the major versions mismatch,
|
||||
<p>Usually, it's a good idea to terminate if the major versions mismatch,
|
||||
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>
|
||||
|
@ -148,7 +148,7 @@ in your main thread (or in a separate thrad) and for each thread you
|
|||
create, you also create another event loop. Libev itself does no locking
|
||||
whatsoever, so if you mix calls to the same event loop in different
|
||||
threads, make sure you lock (this is usually a bad idea, though, even if
|
||||
done correctly, because its hideous and inefficient).</p>
|
||||
done correctly, because it's hideous and inefficient).</p>
|
||||
<dl>
|
||||
<dt>struct ev_loop *ev_default_loop (unsigned int flags)</dt>
|
||||
<dd>
|
||||
|
@ -165,7 +165,7 @@ backends to use, and is usually specified as 0 (or EVFLAG_AUTO).</p>
|
|||
<dl>
|
||||
<dt>EVFLAG_AUTO</dt>
|
||||
<dd>
|
||||
<p>The default flags value. Use this if you have no clue (its the right
|
||||
<p>The default flags value. Use this if you have no clue (it's the right
|
||||
thing, believe me).</p>
|
||||
</dd>
|
||||
<dt>EVFLAG_NOENV</dt>
|
||||
|
@ -177,12 +177,12 @@ 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>EVMETHOD_SELECT portable select backend</dt>
|
||||
<dt>EVMETHOD_POLL poll backend (everywhere except windows)</dt>
|
||||
<dt>EVMETHOD_EPOLL linux only</dt>
|
||||
<dt>EVMETHOD_KQUEUE some bsds only</dt>
|
||||
<dt>EVMETHOD_DEVPOLL solaris 8 only</dt>
|
||||
<dt>EVMETHOD_PORT solaris 10 only</dt>
|
||||
<dt>EVMETHOD_SELECT (portable select backend)</dt>
|
||||
<dt>EVMETHOD_POLL (poll backend, available everywhere except on windows)</dt>
|
||||
<dt>EVMETHOD_EPOLL (linux only)</dt>
|
||||
<dt>EVMETHOD_KQUEUE (some bsds only)</dt>
|
||||
<dt>EVMETHOD_DEVPOLL (solaris 8 only)</dt>
|
||||
<dt>EVMETHOD_PORT (solaris 10 only)</dt>
|
||||
<dd>
|
||||
<p>If one or more of these are ored into the flags value, then only these
|
||||
backends will be tried (in the reverse order as given here). If one are
|
||||
|
@ -202,7 +202,7 @@ undefined behaviour (or a failed assertion if assertions are enabled).</p>
|
|||
<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 cnanot rely on this :).</p>
|
||||
any way whatsoever, although you cannot rely on this :).</p>
|
||||
</dd>
|
||||
<dt>ev_loop_destroy (loop)</dt>
|
||||
<dd>
|
||||
|
@ -218,7 +218,7 @@ again makes little sense).</p>
|
|||
<p>You <i>must</i> call this function after forking if and only if you want to
|
||||
use the event library in both processes. If you just fork+exec, you don't
|
||||
have to call it.</p>
|
||||
<p>The function itself is quite fast and its usually not a problem to call
|
||||
<p>The function itself is quite fast and it's usually not a problem to call
|
||||
it just in case after a fork. To make this easy, the function will fit in
|
||||
quite nicely into a call to <code>pthread_atfork</code>:</p>
|
||||
<pre> pthread_atfork (0, 0, ev_default_fork);
|
||||
|
@ -236,7 +236,7 @@ after fork, and how you do this is entirely your own problem.</p>
|
|||
<p>Returns one of the <code>EVMETHOD_*</code> flags indicating the event backend in
|
||||
use.</p>
|
||||
</dd>
|
||||
<dt>ev_tstamp = ev_now (loop)</dt>
|
||||
<dt>ev_tstamp ev_now (loop)</dt>
|
||||
<dd>
|
||||
<p>Returns the current "event loop time", which is the time the event loop
|
||||
got events and started processing them. This timestamp does not change
|
||||
|
@ -253,33 +253,35 @@ events.</p>
|
|||
no event watchers are active anymore or <code>ev_unloop</code> was called.</p>
|
||||
<p>A flags value of <code>EVLOOP_NONBLOCK</code> will look for new events, will handle
|
||||
those events and any outstanding ones, but will not block your process in
|
||||
case there are no events.</p>
|
||||
case there are no events and will return after one iteration of the loop.</p>
|
||||
<p>A flags value of <code>EVLOOP_ONESHOT</code> will look for new events (waiting if
|
||||
neccessary) and will handle those and any outstanding ones. It will block
|
||||
your process until at least one new event arrives.</p>
|
||||
your process until at least one new event arrives, and will return after
|
||||
one iteration of the loop.</p>
|
||||
<p>This flags value could be used to implement alternative looping
|
||||
constructs, but the <code>prepare</code> and <code>check</code> watchers provide a better and
|
||||
more generic mechanism.</p>
|
||||
</dd>
|
||||
<dt>ev_unloop (loop, how)</dt>
|
||||
<dd>
|
||||
<p>Can be used to make a call to <code>ev_loop</code> return early. The <code>how</code> argument
|
||||
must be either <code>EVUNLOOP_ONCE</code>, which will make the innermost <code>ev_loop</code>
|
||||
call return, or <code>EVUNLOOP_ALL</code>, which will make all nested <code>ev_loop</code>
|
||||
calls return.</p>
|
||||
<p>Can be used to make a call to <code>ev_loop</code> return early (but only after it
|
||||
has processed all outstanding events). The <code>how</code> argument must be either
|
||||
<code>EVUNLOOP_ONCE</code>, which will make the innermost <code>ev_loop</code> call return, or
|
||||
<code>EVUNLOOP_ALL</code>, which will make all nested <code>ev_loop</code> calls return.</p>
|
||||
</dd>
|
||||
<dt>ev_ref (loop)</dt>
|
||||
<dt>ev_unref (loop)</dt>
|
||||
<dd>
|
||||
<p>Ref/unref can be used to add or remove a refcount on the event loop: Every
|
||||
watcher keeps one reference. If you have a long-runing watcher you never
|
||||
unregister that should not keep ev_loop from running, ev_unref() after
|
||||
starting, and ev_ref() before stopping it. Libev itself uses this for
|
||||
example for its internal signal pipe: It is not visible to you as a user
|
||||
and should not keep <code>ev_loop</code> from exiting if the work is done. It is
|
||||
also an excellent way to do this for generic recurring timers or from
|
||||
within third-party libraries. Just remember to unref after start and ref
|
||||
before stop.</p>
|
||||
<p>Ref/unref can be used to add or remove a reference count on the event
|
||||
loop: Every watcher keeps one reference, and as long as the reference
|
||||
count is nonzero, <code>ev_loop</code> will not return on its own. If you have
|
||||
a watcher you never unregister that should not keep <code>ev_loop</code> from
|
||||
returning, ev_unref() after starting, and ev_ref() before stopping it. For
|
||||
example, libev itself uses this for its internal signal pipe: It is not
|
||||
visible to the libev user and should not keep <code>ev_loop</code> from exiting if
|
||||
no event watchers registered by it are active. It is also an excellent
|
||||
way to do this for generic recurring timers or from within third-party
|
||||
libraries. Just remember to <i>unref after start</i> and <i>ref before stop</i>.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
@ -464,6 +466,14 @@ times out after an hour and youreset your system clock to last years
|
|||
time, it will still time out after (roughly) and hour. "Roughly" because
|
||||
detecting time jumps is hard, and soem inaccuracies are unavoidable (the
|
||||
monotonic clock option helps a lot here).</p>
|
||||
<p>The relative timeouts are calculated relative to the <code>ev_now ()</code>
|
||||
time. This is usually the right thing as this timestamp refers to the time
|
||||
of the event triggering whatever timeout you are modifying/starting. If
|
||||
you suspect event processing to be delayed and you *need* to base the timeout
|
||||
ion the current time, use something like this to adjust for this:</p>
|
||||
<pre> ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
|
||||
|
||||
</pre>
|
||||
<dl>
|
||||
<dt>ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)</dt>
|
||||
<dt>ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)</dt>
|
||||
|
@ -591,7 +601,7 @@ program when the crontabs have changed).</p>
|
|||
<div id="ev_signal_signal_me_when_a_signal_ge-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
|
||||
will try its best to deliver signals synchronously, i.e. as part of the
|
||||
will try it's best to deliver signals synchronously, i.e. as part of the
|
||||
normal event processing, like any other event.</p>
|
||||
<p>You cna configure as many watchers as you like per signal. Only when the
|
||||
first watcher gets started will libev actually register a signal watcher
|
||||
|
|
90
ev.pod
90
ev.pod
|
@ -126,12 +126,12 @@ It supports the following flags:
|
|||
|
||||
=over 4
|
||||
|
||||
=item EVFLAG_AUTO
|
||||
=item C<EVFLAG_AUTO>
|
||||
|
||||
The default flags value. Use this if you have no clue (it's the right
|
||||
thing, believe me).
|
||||
|
||||
=item EVFLAG_NOENV
|
||||
=item C<EVFLAG_NOENV>
|
||||
|
||||
If this flag bit is ored into the flag value (or the program runs setuid
|
||||
or setgid) then libev will I<not> look at the environment variable
|
||||
|
@ -140,17 +140,17 @@ 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.
|
||||
|
||||
=item EVMETHOD_SELECT (portable select backend)
|
||||
=item C<EVMETHOD_SELECT> (portable select backend)
|
||||
|
||||
=item EVMETHOD_POLL (poll backend, available everywhere except on windows)
|
||||
=item C<EVMETHOD_POLL> (poll backend, available everywhere except on windows)
|
||||
|
||||
=item EVMETHOD_EPOLL (linux only)
|
||||
=item C<EVMETHOD_EPOLL> (linux only)
|
||||
|
||||
=item EVMETHOD_KQUEUE (some bsds only)
|
||||
=item C<EVMETHOD_KQUEUE> (some bsds only)
|
||||
|
||||
=item EVMETHOD_DEVPOLL (solaris 8 only)
|
||||
=item C<EVMETHOD_DEVPOLL> (solaris 8 only)
|
||||
|
||||
=item EVMETHOD_PORT (solaris 10 only)
|
||||
=item C<EVMETHOD_PORT> (solaris 10 only)
|
||||
|
||||
If one or more of these are ored into the flags value, then only these
|
||||
backends will be tried (in the reverse order as given here). If one are
|
||||
|
@ -262,7 +262,7 @@ libraries. Just remember to I<unref after start> and I<ref before stop>.
|
|||
|
||||
A watcher is a structure that you create and register to record your
|
||||
interest in some event. For instance, if you want to wait for STDIN to
|
||||
become readable, you would create an ev_io watcher for that:
|
||||
become readable, you would create an C<ev_io> watcher for that:
|
||||
|
||||
static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
|
||||
{
|
||||
|
@ -316,46 +316,46 @@ are:
|
|||
|
||||
=over 4
|
||||
|
||||
=item EV_READ
|
||||
=item C<EV_READ>
|
||||
|
||||
=item EV_WRITE
|
||||
=item C<EV_WRITE>
|
||||
|
||||
The file descriptor in the ev_io watcher has become readable and/or
|
||||
The file descriptor in the C<ev_io> watcher has become readable and/or
|
||||
writable.
|
||||
|
||||
=item EV_TIMEOUT
|
||||
=item C<EV_TIMEOUT>
|
||||
|
||||
The ev_timer watcher has timed out.
|
||||
The C<ev_timer> watcher has timed out.
|
||||
|
||||
=item EV_PERIODIC
|
||||
=item C<EV_PERIODIC>
|
||||
|
||||
The ev_periodic watcher has timed out.
|
||||
The C<ev_periodic> watcher has timed out.
|
||||
|
||||
=item EV_SIGNAL
|
||||
=item C<EV_SIGNAL>
|
||||
|
||||
The signal specified in the ev_signal watcher has been received by a thread.
|
||||
The signal specified in the C<ev_signal> watcher has been received by a thread.
|
||||
|
||||
=item EV_CHILD
|
||||
=item C<EV_CHILD>
|
||||
|
||||
The pid specified in the ev_child watcher has received a status change.
|
||||
The pid specified in the C<ev_child> watcher has received a status change.
|
||||
|
||||
=item EV_IDLE
|
||||
=item C<EV_IDLE>
|
||||
|
||||
The ev_idle watcher has determined that you have nothing better to do.
|
||||
The C<ev_idle> watcher has determined that you have nothing better to do.
|
||||
|
||||
=item EV_PREPARE
|
||||
=item C<EV_PREPARE>
|
||||
|
||||
=item EV_CHECK
|
||||
=item C<EV_CHECK>
|
||||
|
||||
All ev_prepare watchers are invoked just I<before> C<ev_loop> starts
|
||||
to gather new events, and all ev_check watchers are invoked just after
|
||||
All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts
|
||||
to gather new events, and all C<ev_check> watchers are invoked just after
|
||||
C<ev_loop> has gathered them, but before it invokes any callbacks for any
|
||||
received events. Callbacks of both watcher types can start and stop as
|
||||
many watchers as they want, and all of them will be taken into account
|
||||
(for example, a ev_prepare watcher might start an idle watcher to keep
|
||||
(for example, a C<ev_prepare> watcher might start an idle watcher to keep
|
||||
C<ev_loop> from blocking).
|
||||
|
||||
=item EV_ERROR
|
||||
=item C<EV_ERROR>
|
||||
|
||||
An unspecified error has occured, the watcher has been stopped. This might
|
||||
happen because the watcher could not be properly started because libev
|
||||
|
@ -406,7 +406,7 @@ have been omitted....
|
|||
This section describes each watcher in detail, but will not repeat
|
||||
information given in the last section.
|
||||
|
||||
=head2 struct ev_io - is my file descriptor readable or writable
|
||||
=head2 C<ev_io> - is this file descriptor readable or writable
|
||||
|
||||
I/O watchers check whether a file descriptor is readable or writable
|
||||
in each iteration of the event loop (This behaviour is called
|
||||
|
@ -434,13 +434,13 @@ EVMETHOD_POLL).
|
|||
|
||||
=item ev_io_set (ev_io *, int fd, int events)
|
||||
|
||||
Configures an ev_io watcher. The fd is the file descriptor to rceeive
|
||||
Configures an C<ev_io> watcher. The fd is the file descriptor to rceeive
|
||||
events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ |
|
||||
EV_WRITE> to receive the given events.
|
||||
|
||||
=back
|
||||
|
||||
=head2 struct ev_timer - relative and optionally recurring timeouts
|
||||
=head2 C<ev_timer> - relative and optionally recurring timeouts
|
||||
|
||||
Timer watchers are simple relative timers that generate an event after a
|
||||
given time, and optionally repeating in regular intervals after that.
|
||||
|
@ -490,24 +490,24 @@ 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 ev_timer with after=repeat=60 and calling ev_timer_again each
|
||||
configure an C<ev_timer> 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.
|
||||
|
||||
=back
|
||||
|
||||
=head2 ev_periodic - to cron or not to cron it
|
||||
=head2 C<ev_periodic> - to cron or not to cron it
|
||||
|
||||
Periodic watchers are also timers of a kind, but they are very versatile
|
||||
(and unfortunately a bit complex).
|
||||
|
||||
Unlike ev_timer's, they are not based on real time (or relative time)
|
||||
Unlike C<ev_timer>'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
|
||||
take a year to trigger the event (unlike an ev_timer, which would trigger
|
||||
take a year to trigger the event (unlike an C<ev_timer>, which would trigger
|
||||
roughly 10 seconds later and of course not if you reset your system time
|
||||
again).
|
||||
|
||||
|
@ -550,7 +550,7 @@ full hour (UTC), or more correct, when the system time is evenly divisible
|
|||
by 3600.
|
||||
|
||||
Another way to think about it (for the mathematically inclined) is that
|
||||
ev_periodic will try to run the callback in this mode at the next possible
|
||||
C<ev_periodic> will try to run the callback in this mode at the next possible
|
||||
time where C<time = at (mod interval)>, regardless of any time jumps.
|
||||
|
||||
=item * manual reschedule mode (reschedule_cb = callback)
|
||||
|
@ -593,7 +593,7 @@ program when the crontabs have changed).
|
|||
|
||||
=back
|
||||
|
||||
=head2 ev_signal - signal me when a signal gets signalled
|
||||
=head2 C<ev_signal> - signal me when a signal gets signalled
|
||||
|
||||
Signal watchers will trigger an event when the process receives a specific
|
||||
signal one or more times. Even though signals are very asynchronous, libev
|
||||
|
@ -618,7 +618,7 @@ of the C<SIGxxx> constants).
|
|||
|
||||
=back
|
||||
|
||||
=head2 ev_child - wait for pid status changes
|
||||
=head2 C<ev_child> - wait for pid status changes
|
||||
|
||||
Child watchers trigger when your process receives a SIGCHLD in response to
|
||||
some child status changes (most typically when a child of yours dies).
|
||||
|
@ -637,7 +637,7 @@ contains the pid of the process causing the status change.
|
|||
|
||||
=back
|
||||
|
||||
=head2 ev_idle - when you've got nothing better to do
|
||||
=head2 C<ev_idle> - when you've got nothing better to do
|
||||
|
||||
Idle watchers trigger events when there are no other I/O or timer (or
|
||||
periodic) events pending. That is, as long as your process is busy
|
||||
|
@ -674,8 +674,8 @@ could be used, for example, to track variable changes, implement your own
|
|||
watchers, integrate net-snmp or a coroutine library and lots more.
|
||||
|
||||
This is done by examining in each prepare call which file descriptors need
|
||||
to be watched by the other library, registering ev_io watchers for them
|
||||
and starting an ev_timer watcher for any timeouts (many libraries provide
|
||||
to be watched by the other library, registering C<ev_io> watchers for them
|
||||
and starting an C<ev_timer> watcher for any timeouts (many libraries provide
|
||||
just this functionality). Then, in the check watcher you check for any
|
||||
events that occured (by making your callbacks set soem flags for example)
|
||||
and call back into the library.
|
||||
|
@ -712,16 +712,16 @@ or timeout without havign to allocate/configure/start/stop/free one or
|
|||
more watchers yourself.
|
||||
|
||||
If C<fd> is less than 0, then no I/O watcher will be started and events is
|
||||
ignored. Otherwise, an ev_io watcher for the given C<fd> and C<events> set
|
||||
ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and C<events> set
|
||||
will be craeted and started.
|
||||
|
||||
If C<timeout> is less than 0, then no timeout watcher will be
|
||||
started. Otherwise an ev_timer watcher with after = C<timeout> (and repeat
|
||||
started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and repeat
|
||||
= 0) will be started.
|
||||
|
||||
The callback has the type C<void (*cb)(int revents, void *arg)> and
|
||||
gets passed an events set (normally a combination of EV_ERROR, EV_READ,
|
||||
EV_WRITE or EV_TIMEOUT) and the C<arg> value passed to C<ev_once>:
|
||||
gets passed an events set (normally a combination of C<EV_ERROR>, C<EV_READ>,
|
||||
C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> value passed to C<ev_once>:
|
||||
|
||||
static void stdin_ready (int revents, void *arg)
|
||||
{
|
||||
|
|
Loading…
Reference in New Issue