From 727a154750f2ed6e554ea21dd533f8496a3a157b Mon Sep 17 00:00:00 2001 From: root Date: Mon, 25 Oct 2010 10:30:23 +0000 Subject: *** empty log message *** --- ev.pod | 119 ++++++++++++++++++++++++++++++++--------------------------------- 1 file changed, 59 insertions(+), 60 deletions(-) (limited to 'ev.pod') diff --git a/ev.pod b/ev.pod index dc8f23b..4dca16d 100644 --- a/ev.pod +++ b/ev.pod @@ -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, or calls to -C followed by the watcher-specific C 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 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), -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), 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 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 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, or calls to +C followed by the watcher-specific C 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 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), +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), 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 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, which are usually small -- cgit v1.2.3