--- libev/ev.pod 2010/10/24 19:44:27 1.326 +++ libev/ev.pod 2010/10/25 11:10:10 1.336 @@ -80,6 +80,14 @@ Familiarity with event based programming techniques in general is assumed throughout this document. +=head1 WHAT TO READ WHEN IN A HURRY + +This manual tries to be very detailed, but unfortunately, this also makes +it very long. If you just want to know the basics of libev, I suggest +reading L, then the L above and +look up the missing functions in L and the C and +C sections in L. + =head1 ABOUT LIBEV Libev is an event loop: you register interest in certain events (such as a @@ -302,8 +310,8 @@ libev 3 had an C function colliding with the struct name). The library knows two types of such loops, the I loop, which -supports signals and child events, and dynamically created event loops -which do not. +supports child process events, and dynamically created event loops which +do not. =over 4 @@ -817,9 +825,9 @@ C, which will make the innermost C call return, or C, which will make all nested C calls return. -This "unloop state" will be cleared when entering C again. +This "break state" will be cleared when entering C again. -It is safe to call C from outside any C calls. ##TODO## +It is safe to call C from outside any C calls, too. =item ev_ref (loop) @@ -1116,7 +1124,7 @@ =item C -The event loop is abotu to be destroyed (see C). +The event loop is about to be destroyed (see C). =item C @@ -1148,65 +1156,6 @@ =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 @@ -1358,7 +1307,6 @@ =back - =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER Each watcher has, by default, a member C that you can change @@ -1424,6 +1372,65 @@ (((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 @@ -3100,21 +3107,26 @@ Initialises and configures the fork watcher - it has no parameters of any kind. There is a C macro, but using it is utterly pointless, -believe me. +really. =back =head2 C - even the best things end -Cleanup watchers are called just before the event loop they are registered -with is being destroyed. +Cleanup watchers are called just before the event loop is being destroyed +by a call to C. While there is no guarantee that the event loop gets destroyed, cleanup watchers provide a convenient method to install cleanup hooks for your program, worker threads and so on - you just to make sure to destroy the loop when you want them to be invoked. +Cleanup watchers are invoked in the same way as any other watcher. Unlike +all other watchers, they do not keep a reference to the event loop (which +makes a lot of sense if you think about it). Like all other watchers, you +can call libev functions in the callback, except C. + =head3 Watcher-Specific Functions and Data Members =over 4 @@ -3123,7 +3135,7 @@ Initialises and configures the cleanup watcher - it has no parameters of any kind. There is a C macro, but using it is utterly -pointless, believe me. +pointless, I assure you. =back @@ -4754,6 +4766,11 @@ callback: The watcher callbacks have different type signatures, but libev calls them using an C internally. +=item pointer accesses must be thread-atomic + +Accessing a pointer value must be atomic, it must both be readable and +writable in one piece - this is the case on all current architectures. + =item C must be thread-atomic as well The type C (or whatever is defined as @@ -4869,14 +4886,21 @@ =head1 PORTING FROM LIBEV 3.X TO 4.X -The major version 4 introduced some minor incompatible changes to the API. +The major version 4 introduced some incompatible changes to the API. -At the moment, the C header file tries to implement superficial -compatibility, so most programs should still compile. Those might be -removed in later versions of libev, so better update early than late. +At the moment, the C header file provides compatibility definitions +for all changes, so most programs should still compile. The compatibility +layer might be removed in later versions of libev, so better update to the +new API early than late. =over 4 +=item C backwards compatibility mechanism + +The backward compatibility mechanism can be controlled by +C. See L in the L +section. + =item C and C have been removed These calls can be replaced easily by their C counterparts: @@ -4911,12 +4935,6 @@ C because it would otherwise clash with the C typedef. -=item C backwards compatibility mechanism - -The backward compatibility mechanism can be controlled by -C. See L in the L -section. - =item C mechanism replaced by C The preprocessor symbol C has been replaced by a different @@ -5000,5 +5018,6 @@ =head1 AUTHOR -Marc Lehmann , with repeated corrections by Mikael Magnusson. +Marc Lehmann , with repeated corrections by Mikael +Magnusson and Emanuele Giaquinta.