|
|
@ -1156,65 +1156,6 @@ thing, so beware. |
|
|
|
|
|
|
|
=back |
|
|
|
|
|
|
|
=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". |
|
|
|
|
|
|
|
=over 4 |
|
|
|
|
|
|
|
=item initialiased |
|
|
|
|
|
|
|
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. |
|
|
|
|
|
|
|
=item started/running/active |
|
|
|
|
|
|
|
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. |
|
|
|
|
|
|
|
=item pending |
|
|
|
|
|
|
|
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 |
|
|
|
callback. |
|
|
|
|
|
|
|
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 |
|
|
|
active. |
|
|
|
|
|
|
|
=item stopped |
|
|
|
|
|
|
|
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 |
|
|
|
you wish. |
|
|
|
|
|
|
|
=back |
|
|
|
|
|
|
|
=head2 GENERIC WATCHER FUNCTIONS |
|
|
|
|
|
|
|
=over 4 |
|
|
@ -1366,7 +1307,6 @@ functions that do not need a watcher. |
|
|
|
|
|
|
|
=back |
|
|
|
|
|
|
|
|
|
|
|
=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 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". |
|
|
|
|
|
|
|
=over 4 |
|
|
|
|
|
|
|
=item initialiased |
|
|
|
|
|
|
|
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. |
|
|
|
|
|
|
|
=item started/running/active |
|
|
|
|
|
|
|
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. |
|
|
|
|
|
|
|
=item pending |
|
|
|
|
|
|
|
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 |
|
|
|
callback. |
|
|
|
|
|
|
|
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 |
|
|
|
active. |
|
|
|
|
|
|
|
=item stopped |
|
|
|
|
|
|
|
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 |
|
|
|
you wish. |
|
|
|
|
|
|
|
=back |
|
|
|
|
|
|
|
=head2 WATCHER PRIORITY MODELS |
|
|
|
|
|
|
|
Many event loops support I<watcher priorities>, which are usually small |
|
|
|