--- libev/ev.pod 2010/10/21 12:32:47 1.310 +++ libev/ev.pod 2010/10/22 09:33:14 1.315 @@ -295,8 +295,8 @@ =head1 FUNCTIONS CONTROLLING THE EVENT LOOP An event loop is described by a C (the C is -I optional in case unless libev 3 compatibility is disabled, as libev -3 had an C function colliding with the struct name). +I optional in this case unless libev 3 compatibility is disabled, as +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 @@ -910,7 +910,11 @@ This call will simply invoke all pending watchers while resetting their pending state. Normally, C does this automatically when required, -but when overriding the invoke callback this call comes handy. +but when overriding the invoke callback this call comes handy. This +function can be invoked from a watcher - this can be useful for example +when you want to do some lengthy calculation and want to pass further +event handling to another thread (you still have to make sure only one +thread executes within C or C of course). =item int ev_pending_count (loop) @@ -992,9 +996,10 @@ watcher type, e.g. C can mean C for timer watchers and C for I/O watchers. -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 C watcher for that: +A watcher is an opaque structure that you allocate and register to record +your interest in some event. To make a concrete example, imagine you want +to wait for STDIN to become readable, you would create an C watcher +for that: static void my_cb (struct ev_loop *loop, ev_io *w, int revents) { @@ -1019,11 +1024,11 @@ Each watcher has an associated watcher structure (called C or simply C, as typedefs are provided for all watcher structs). -Each watcher structure must be initialised by a call to C, which expects a callback to be provided. This -callback gets invoked each time the event occurs (or, in the case of I/O -watchers, each time the event loop detects that the file descriptor given -is readable and/or writable). +Each watcher structure must be initialised by a call to C, which expects a callback to be provided. This callback is +invoked each time the event occurs (or, in the case of I/O watchers, each +time the event loop detects that the file descriptor given is readable +and/or writable). Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >> macro to configure it, with arguments specific to the watcher type. There @@ -1131,6 +1136,65 @@ =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 @@ -4469,9 +4533,10 @@ The kqueue syscall is broken in all known versions - most versions support only sockets, many support pipes. -Libev tries to work around this by not using C by default on -this rotten platform, but of course you can still ask for it when creating -a loop. +Libev tries to work around this by not using C by default on this +rotten platform, but of course you can still ask for it when creating a +loop - embedding a socket-only kqueue loop into a select-based one is +probably going to work well. =head3 C is buggy @@ -4500,19 +4565,21 @@ The default compile environment on Solaris is unfortunately so thread-unsafe that you can't even use components/libraries compiled -without C<-D_REENTRANT> (as long as they use C), which, of course, -isn't defined by default. +without C<-D_REENTRANT> in a threaded program, which, of course, isn't +defined by default. A valid, if stupid, implementation choice. If you want to use libev in threaded environments you have to make sure it's compiled with C<_REENTRANT> defined. =head3 Event port backend -The scalable event interface for Solaris is called "event ports". Unfortunately, -this mechanism is very buggy. If you run into high CPU usage, your program -freezes or you get a large number of spurious wakeups, make sure you have -all the relevant and latest kernel patches applied. No, I don't know which -ones, but there are multiple ones. +The scalable event interface for Solaris is called "event +ports". Unfortunately, this mechanism is very buggy in all major +releases. If you run into high CPU usage, your program freezes or you get +a large number of spurious wakeups, make sure you have all the relevant +and latest kernel patches applied. No, I don't know which ones, but there +are multiple ones to apply, and afterwards, event ports actually work +great. If you can't get it to work, you can try running the program by setting the environment variable C to only allow C and @@ -4523,7 +4590,7 @@ AIX unfortunately has a broken C header. Libev works around this by trying to avoid the poll backend altogether (i.e. it's not even compiled in), which normally isn't a big problem as C