@ -1,5 +1,6 @@
Revision history for libev, a high-performance and full-featured event loop.
4.00 Mon Oct 25 12:32:12 CEST 2010
- "PORTING FROM LIBEV 3.X TO 4.X" (in ev.pod) is recommended reading.
- ev_embed_stop did not correctly stop the watcher (very good
testcase by Vladimir Timofeev).
@ -1156,65 +1156,6 @@ thing, so beware.
=head2 WATCHER STATES
There are various watcher states mentioned throughout this manual -
active, pending and so on. In this section these states and the rules to
transition between them will be described in more detail - and while these
rules might look complicated, they usually do "the right thing".
Before a watcher can be registered with the event looop it has to be
initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
In this state it is simply some block of memory that is suitable for use
in an event loop. It can be moved around, freed, reused etc. at will.
Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
property of the event loop, and is actively waiting for events. While in
this state it cannot be accessed (except in a few documented ways), moved,
freed or anything else - the only legal thing is to keep a pointer to it,
and call libev functions on it that are documented to work on active watchers.
If a watcher is active and libev determines that an event it is interested
in has occurred (such as a timer expiring), it will become pending. It will
stay in this pending state until either it is stopped or its callback is
about to be invoked, so it is not normally pending inside the watcher
The watcher might or might not be active while it is pending (for example,
an expired non-repeating timer can be pending but no longer active). If it
is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
but it is still property of the event loop at this time, so cannot be
moved, freed or reused. And if it is active the rules described in the
previous item still apply.
It is also possible to feed an event on a watcher that is not active (e.g.
via C<ev_feed_event>), in which case it becomes pending without being
A watcher can be stopped implicitly by libev (in which case it might still
be pending), or explicitly by calling its C<ev_TYPE_stop> function. The
latter will clear any pending state the watcher might be in, regardless
of whether it was active or not, so stopping a watcher explicitly before
freeing it is often a good idea.
While stopped (and not pending) the watcher is essentially in the
initialised state, that is it can be reused, moved, modified in any way
=head2 GENERIC WATCHER FUNCTIONS
@ -1366,7 +1307,6 @@ functions that do not need a watcher.
=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
Each watcher has, by default, a member C<void *data> that you can change
@ -1432,6 +1372,65 @@ programmers):
(((char *)w) - offsetof (struct my_biggy, t2));
=head2 WATCHER PRIORITY MODELS
Many event loops support I<watcher priorities>, which are usually small