[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.323 by root, Sun Oct 24 18:01:26 2010 UTC vs.
Revision 1.356 by root, Tue Jan 11 01:42:47 2011 UTC

 on event-based programming, nor will it introduce event-based programming
 with libev.
 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<ANATOMY OF A WATCHER>, then the L<EXAMPLE PROGRAM> above and
+look up the missing functions in L<GLOBAL FUNCTIONS> and the C<ev_io> and
+C<ev_timer> sections in L<WATCHER TYPES>.
 =head1 ABOUT LIBEV
 Libev is an event loop: you register interest in certain events (such as a
 file descriptor being readable or a timeout occurring), and it will manage
 the current system, you would need to look at C<ev_embeddable_backends ()
 & ev_supported_backends ()>, likewise for recommended ones.
 See the description of C<ev_embed> watchers for more info.
-=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
+=item ev_set_allocator (void *(*cb)(void *ptr, long size))
 Sets the allocation function to use (the prototype is similar - the
 semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
 used to allocate and free memory (no surprises here). If it returns zero
 when memory needs to be allocated (C<size != 0>), the library might abort
    }
    ...
    ev_set_allocator (persistent_realloc);
-=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
+=item ev_set_syserr_cb (void (*cb)(const char *msg))
 Set the callback function to call on a retryable system call error (such
 as failed select, poll, epoll_wait). The message is a printable string
 indicating the system call or subsystem causing the problem. If this
 callback is set, then libev will expect it to remedy the situation, no
    }
    ...
    ev_set_syserr_cb (fatal_error);
+=item ev_feed_signal (int signum)
+This function can be used to "simulate" a signal receive. It is completely
+safe to call this function at any time, from any context, including signal
+handlers or random threads.
+Its main use is to customise signal handling in your process, especially
+in the presence of threads. For example, you could block signals
+by default in all threads (and specifying C<EVFLAG_NOSIGMASK> when
+creating any loops), and in one thread, use C<sigwait> or any other
+mechanism to wait for signals, then "deliver" them to libev by calling
+C<ev_feed_signal>.
 =back
 =head1 FUNCTIONS CONTROLLING EVENT LOOPS
 An event loop is described by a C<struct ev_loop *> (the C<struct> is
 I<not> optional in this case unless libev 3 compatibility is disabled, as
 libev 3 had an C<ev_loop> function colliding with the struct name).
 The library knows two types of such loops, the I<default> loop, which
-supports signals and child events, and dynamically created event loops
+supports child process events, and dynamically created event loops which
-which do not.
+do not.
 =over 4
 =item struct ev_loop *ev_default_loop (unsigned int flags)
 =item struct ev_loop *ev_loop_new (unsigned int flags)
 This will create and initialise a new event loop object. If the loop
 could not be initialised, returns false.
-Note that this function I<is> thread-safe, and one common way to use
+This function is thread-safe, and one common way to use libev with
-libev with threads is indeed to create one loop per thread, and using the
+threads is indeed to create one loop per thread, and using the default
-default loop in the "main" or "initial" thread.
+loop in the "main" or "initial" thread.
 The flags argument can be used to specify special behaviour or specific
 backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
 The following flags are supported:
 environment variable.
 =item C<EVFLAG_NOINOTIFY>
 When this flag is specified, then libev will not attempt to use the
-I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
+I<inotify> API for its C<ev_stat> watchers. Apart from debugging and
 testing, this flag can be useful to conserve inotify file descriptors, as
 otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
 =item C<EVFLAG_SIGNALFD>
 When this flag is specified, then libev will attempt to use the
-I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
+I<signalfd> API for its C<ev_signal> (and C<ev_child>) watchers. This API
 delivers signals synchronously, which makes it both faster and might make
 it possible to get the queued signal data. It can also simplify signal
 handling with threads, as long as you properly block signals in your
 threads that are not interested in handling them.
 Signalfd will not be used by default as this changes your signal mask, and
 there are a lot of shoddy libraries and programs (glib's threadpool for
 example) that can't properly initialise their signal masks.
+=item C<EVFLAG_NOSIGMASK>
+When this flag is specified, then libev will avoid to modify the signal
+mask. Specifically, this means you ahve to make sure signals are unblocked
+when you want to receive them.
+This behaviour is useful when you want to do your own signal handling, or
+want to handle signals only in specific threads and want to avoid libev
+unblocking the signals.
+This flag's behaviour will become the default in future versions of libev.
 =item C<EVBACKEND_SELECT>  (value 1, portable select backend)
 This is your standard select(2) backend. Not I<completely> standard, as
 libev tries to roll its own fd_set with no limits on the number of fds,
 epoll scales either O(1) or O(active_fds).
 The epoll mechanism deserves honorable mention as the most misdesigned
 of the more advanced event mechanisms: mere annoyances include silently
 dropping file descriptors, requiring a system call per change per file
-descriptor (and unnecessary guessing of parameters), problems with dup and
+descriptor (and unnecessary guessing of parameters), problems with dup,
+returning before the timeout value, resulting in additional iterations
+(and only giving 5ms accuracy while select on the same platform gives
-so on. The biggest issue is fork races, however - if a program forks then
+0.1ms) and so on. The biggest issue is fork races, however - if a program
-I<both> parent and child process have to recreate the epoll set, which can
+forks then I<both> parent and child process have to recreate the epoll
-take considerable time (one syscall per file descriptor) and is of course
+set, which can take considerable time (one syscall per file descriptor)
-hard to detect.
+and is of course hard to detect.
 Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
 of course I<doesn't>, and epoll just loves to report events for totally
 I<different> file descriptors (even already closed ones, so one cannot
 even remove them from the set) than registered in the set (especially
 employing an additional generation counter and comparing that against the
 events to filter out spurious ones, recreating the set when required. Last
 not least, it also refuses to work with some file descriptors which work
 perfectly fine with C<select> (files, many character devices...).
+Epoll is truly the train wreck analog among event poll mechanisms,
+a frankenpoll, cobbled together in a hurry, no thought to design or
+interaction with others.
 While stopping, setting and starting an I/O watcher in the same iteration
 will result in some caching, there is still a system call per such
 incident (because the same I<file descriptor> could point to a different
 I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
 file descriptors might not work very well if you register events for both
 =item C<EVBACKEND_PORT>    (value 32, Solaris 10)
 This uses the Solaris 10 event port mechanism. As with everything on Solaris,
 it's really slow, but it still scales very well (O(active_fds)).
-Please note that Solaris event ports can deliver a lot of spurious
-notifications, so you need to use non-blocking I/O or other means to avoid
-blocking when no data (or space) is available.
 While this backend scales well, it requires one system call per active
 file descriptor per loop iteration. For small and medium numbers of file
 descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
 might perform better.
-On the positive side, with the exception of the spurious readiness
+On the positive side, this backend actually performed fully to
-notifications, this backend actually performed fully to specification
-in all tests and is fully embeddable, which is a rare feat among the
+specification in all tests and is fully embeddable, which is a rare feat
-OS-specific backends (I vastly prefer correctness over speed hacks).
+among the OS-specific backends (I vastly prefer correctness over speed
+hacks).
+On the negative side, the interface is I<bizarre> - so bizarre that
+even sun itself gets it wrong in their code examples: The event polling
+function sometimes returning events to the caller even though an error
+occurred, but with no indication whether it has done so or not (yes, it's
+even documented that way) - deadly for edge-triggered interfaces where
+you absolutely have to know whether an event occurred or not because you
+have to re-arm the watcher.
+Fortunately libev seems to be able to work around these idiocies.
 This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
 C<EVBACKEND_POLL>.
 =item C<EVBACKEND_ALL>
 Try all backends (even potentially broken ones that wouldn't be tried
 with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
 C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
-It is definitely not recommended to use this flag.
+It is definitely not recommended to use this flag, use whatever
+C<ev_recommended_backends ()> returns, or simply do not specify a backend
+at all.
+=item C<EVBACKEND_MASK>
+Not a backend at all, but a mask to select all backend bits from a
+C<flags> value, in case you want to mask out any backends from a flags
+value (e.g. when modifying the C<LIBEV_FLAGS> environment variable).
 =back
 If one or more of the backend flags are or'ed into the flags value,
 then only these backends will be tried (in the reverse order as listed
 This function is normally used on loop objects allocated by
 C<ev_loop_new>, but it can also be used on the default loop returned by
 C<ev_default_loop>, in which case it is not thread-safe.
 Note that it is not advisable to call this function on the default loop
-except in the rare occasion where you really need to free it's resources.
+except in the rare occasion where you really need to free its resources.
 If you need dynamically allocated loops it is better to use C<ev_loop_new>
 and C<ev_loop_destroy>.
 =item ev_loop_fork (loop)
 prepare and check phases.
 =item unsigned int ev_depth (loop)
 Returns the number of times C<ev_run> was entered minus the number of
-times C<ev_run> was exited, in other words, the recursion depth.
+times C<ev_run> was exited normally, in other words, the recursion depth.
 Outside C<ev_run>, this number is zero. In a callback, this number is
 C<1>, unless C<ev_run> was invoked recursively (or from another thread),
 in which case it is higher.
-Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread
+Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread,
-etc.), doesn't count as "exit" - consider this as a hint to avoid such
+throwing an exception etc.), doesn't count as "exit" - consider this
-ungentleman-like behaviour unless it's really convenient.
+as a hint to avoid such ungentleman-like behaviour unless it's really
+convenient, in which case it is fully supported.
 =item unsigned int ev_backend (loop)
 Returns one of the C<EVBACKEND_*> flags indicating the event backend in
 use.
 relying on all watchers to be stopped when deciding when a program has
 finished (especially in interactive programs), but having a program
 that automatically loops as long as it has to and no longer by virtue
 of relying on its watchers stopping correctly, that is truly a thing of
 beauty.
+This function is also I<mostly> exception-safe - you can break out of
+a C<ev_run> call by calling C<longjmp> in a callback, throwing a C++
+exception and so on. This does not decrement the C<ev_depth> value, nor
+will it clear any outstanding C<EVBREAK_ONE> breaks.
 A flags value of C<EVRUN_NOWAIT> will look for new events, will handle
 those events and any already outstanding ones, but will not wait and
 block your process in case there are no events and will return after one
 iteration of the loop. This is sometimes useful to poll and handle new
 Can be used to make a call to C<ev_run> return early (but only after it
 has processed all outstanding events). The C<how> argument must be either
 C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or
 C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return.
-This "unloop state" will be cleared when entering C<ev_run> again.
+This "break state" will be cleared on the next call to C<ev_run>.
-It is safe to call C<ev_break> from outside any C<ev_run> calls. ##TODO##
+It is safe to call C<ev_break> from outside any C<ev_run> calls, too, in
+which case it will have no effect.
 =item ev_ref (loop)
 =item ev_unref (loop)
 running when nothing else is active.
    ev_signal exitsig;
    ev_signal_init (&exitsig, sig_cb, SIGINT);
    ev_signal_start (loop, &exitsig);
-   evf_unref (loop);
+   ev_unref (loop);
 Example: For some weird reason, unregister the above signal handler again.
    ev_ref (loop);
    ev_signal_stop (loop, &exitsig);
 See also the locking example in the C<THREADS> section later in this
 document.
 =item ev_set_userdata (loop, void *data)
-=item ev_userdata (loop)
+=item void *ev_userdata (loop)
 Set and retrieve a single C<void *> associated with a loop. When
 C<ev_set_userdata> has never been called, then C<ev_userdata> returns
-C<0.>
+C<0>.
 These two functions can be used to associate arbitrary data with a loop,
 and are intended solely for the C<invoke_pending_cb>, C<release> and
 C<acquire> callbacks described above, but of course can be (ab-)used for
 any other purpose as well.
 =item C<EV_FORK>
 The event loop has been resumed in the child process after fork (see
 C<ev_fork>).
+=item C<EV_CLEANUP>
+The event loop is about to be destroyed (see C<ev_cleanup>).
 =item C<EV_ASYNC>
 The given async watcher has been asynchronously notified (see C<ev_async>).
 =item C<EV_CUSTOM>
 programs, though, as the fd could already be closed and reused for another
 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
 =item C<ev_init> (ev_TYPE *watcher, callback)
 See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
 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
 and read at any time: libev will completely ignore it. This can be used
    t2_cb (EV_P_ ev_timer *w, int revents)
    {
      struct my_biggy big = (struct my_biggy *)
        (((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
 integers that influence the ordering of event callback invocation
 In general you can register as many read and/or write event watchers per
 fd as you want (as long as you don't confuse yourself). Setting all file
 descriptors to non-blocking mode is also usually a good idea (but not
 required if you know what you are doing).
-If you cannot use non-blocking mode, then force the use of a
-known-to-be-good backend (at the time of this writing, this includes only
-C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
-descriptors for which non-blocking operation makes no sense (such as
-files) - libev doesn't guarantee any specific behaviour in that case.
 Another thing you have to watch out for is that it is quite easy to
-receive "spurious" readiness notifications, that is your callback might
+receive "spurious" readiness notifications, that is, your callback might
 be called with C<EV_READ> but a subsequent C<read>(2) will actually block
-because there is no data. Not only are some backends known to create a
+because there is no data. It is very easy to get into this situation even
-lot of those (for example Solaris ports), it is very easy to get into
+with a relatively standard program structure. Thus it is best to always
-this situation even with a relatively standard program structure. Thus
+use non-blocking I/O: An extra C<read>(2) returning C<EAGAIN> is far
-it is best to always use non-blocking I/O: An extra C<read>(2) returning
-C<EAGAIN> is far preferable to a program hanging until some data arrives.
+preferable to a program hanging until some data arrives.
 If you cannot run the fd in non-blocking mode (for example you should
 not play around with an Xlib connection), then you have to separately
 re-test whether a file descriptor is really ready with a known-to-be good
-interface such as poll (fortunately in our Xlib example, Xlib already
+interface such as poll (fortunately in the case of Xlib, it already does
-does this on its own, so its quite safe to use). Some people additionally
+this on its own, so its quite safe to use). Some people additionally
 use C<SIGALRM> and an interval timer, just to be sure you won't block
 indefinitely.
 But really, best use non-blocking mode.
 There is no workaround possible except not registering events
 for potentially C<dup ()>'ed file descriptors, or to resort to
 C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
+=head3 The special problem of files
+Many people try to use C<select> (or libev) on file descriptors
+representing files, and expect it to become ready when their program
+doesn't block on disk accesses (which can take a long time on their own).
+However, this cannot ever work in the "expected" way - you get a readiness
+notification as soon as the kernel knows whether and how much data is
+there, and in the case of open files, that's always the case, so you
+always get a readiness notification instantly, and your read (or possibly
+write) will still block on the disk I/O.
+Another way to view it is that in the case of sockets, pipes, character
+devices and so on, there is another party (the sender) that delivers data
+on it's own, but in the case of files, there is no such thing: the disk
+will not send data on it's own, simply because it doesn't know what you
+wish to read - you would first have to request some data.
+Since files are typically not-so-well supported by advanced notification
+mechanism, libev tries hard to emulate POSIX behaviour with respect
+to files, even though you should not use it. The reason for this is
+convenience: sometimes you want to watch STDIN or STDOUT, which is
+usually a tty, often a pipe, but also sometimes files or special devices
+(for example, C<epoll> on Linux works with F</dev/random> but not with
+F</dev/urandom>), and even though the file might better be served with
+asynchronous I/O instead of with non-blocking I/O, it is still useful when
+it "just works" instead of freezing.
+So avoid file descriptors pointing to files when you know it (e.g. use
+libeio), but use them when it is convenient, e.g. for STDIN/STDOUT, or
+when you rarely read from a file instead of from a socket, and want to
+reuse the same code path.
 =head3 The special problem of fork
 Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
 useless behaviour. Libev fully supports fork, but needs to be told about
-it in the child.
+it in the child if you want to continue to use it in the child.
-To support fork in your programs, you either have to call
+To support fork in your child processes, you have to call C<ev_loop_fork
-C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
+()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to
-enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
+C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
-C<EVBACKEND_POLL>.
 =head3 The special problem of SIGPIPE
 While not really specific to libev, it is easy to forget about C<SIGPIPE>:
 when writing to a pipe whose other end has been closed, your program gets
 =head2 C<ev_signal> - signal me when a signal gets signalled!
 Signal watchers will trigger an event when the process receives a specific
 signal one or more times. Even though signals are very asynchronous, libev
-will try it's best to deliver signals synchronously, i.e. as part of the
+will try its best to deliver signals synchronously, i.e. as part of the
 normal event processing, like any other event.
 If you want signals to be delivered truly asynchronously, just use
 C<sigaction> as you would do without libev and forget about sharing
 the signal. You can even use C<ev_async> from a signal handler to
 I<has> to modify the signal mask, at least temporarily.
 So I can't stress this enough: I<If you do not reset your signal mask when
 you expect it to be empty, you have a race condition in your code>. This
 is not a libev-specific thing, this is true for most event libraries.
+=head3 The special problem of threads signal handling
+POSIX threads has problematic signal handling semantics, specifically,
+a lot of functionality (sigfd, sigwait etc.) only really works if all
+threads in a process block signals, which is hard to achieve.
+When you want to use sigwait (or mix libev signal handling with your own
+for the same signals), you can tackle this problem by globally blocking
+all signals before creating any threads (or creating them with a fully set
+sigprocmask) and also specifying the C<EVFLAG_NOSIGMASK> when creating
+loops. Then designate one thread as "signal receiver thread" which handles
+these signals. You can pass on any signals that libev might be interested
+in by calling C<ev_feed_signal>.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 =head3 Watcher-Specific Functions and Data Members
 =over 4
-=item ev_fork_init (ev_signal *, callback)
+=item ev_fork_init (ev_fork *, callback)
 Initialises and configures the fork watcher - it has no parameters of any
 kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
-believe me.
+really.
 =back
+=head2 C<ev_cleanup> - even the best things end
+Cleanup watchers are called just before the event loop is being destroyed
+by a call to C<ev_loop_destroy>.
+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<ev_cleanup_start>.
+=head3 Watcher-Specific Functions and Data Members
+=over 4
+=item ev_cleanup_init (ev_cleanup *, callback)
+Initialises and configures the cleanup watcher - it has no parameters of
+any kind. There is a C<ev_cleanup_set> macro, but using it is utterly
+pointless, I assure you.
+=back
+Example: Register an atexit handler to destroy the default loop, so any
+cleanup functions are called.
+   static void
+   program_exits (void)
+   {
+     ev_loop_destroy (EV_DEFAULT_UC);
+   }
+   ...
+   atexit (program_exits);
 =head2 C<ev_async> - how to wake up an event loop
 In general, you cannot use an C<ev_run> from multiple threads or other
 it by calling C<ev_async_send>, which is thread- and signal safe.
 This functionality is very similar to C<ev_signal> watchers, as signals,
 too, are asynchronous in nature, and signals, too, will be compressed
 (i.e. the number of callback invocations may be less than the number of
-C<ev_async_sent> calls).
+C<ev_async_sent> calls). In fact, you could use signal watchers as a kind
+of "global async watchers" by using a watcher on an otherwise unused
+signal, and C<ev_feed_signal> to signal this watcher from another thread,
+even without knowing which loop owns the signal.
 Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
 just the default loop.
 =head3 Queueing
 Feed an event on the given fd, as if a file descriptor backend detected
 the given events it.
 =item ev_feed_signal_event (loop, int signum)
-Feed an event as if the given signal occurred (C<loop> must be the default
+Feed an event as if the given signal occurred. See also C<ev_feed_signal>,
-loop!).
+which is async-safe.
 =back
+=head1 COMMON OR USEFUL IDIOMS (OR BOTH)
+This section explains some common idioms that are not immediately
+obvious. Note that examples are sprinkled over the whole manual, and this
+section only contains stuff that wouldn't fit anywhere else.
+=head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS
+Often (especially in GUI toolkits) there are places where you have
+I<modal> interaction, which is most easily implemented by recursively
+invoking C<ev_run>.
+This brings the problem of exiting - a callback might want to finish the
+main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but
+a modal "Are you sure?" dialog is still waiting), or just the nested one
+and not the main one (e.g. user clocked "Ok" in a modal dialog), or some
+other combination: In these cases, C<ev_break> will not work alone.
+The solution is to maintain "break this loop" variable for each C<ev_run>
+invocation, and use a loop around C<ev_run> until the condition is
+triggered, using C<EVRUN_ONCE>:
+   // main loop
+   int exit_main_loop = 0;
+   while (!exit_main_loop)
+     ev_run (EV_DEFAULT_ EVRUN_ONCE);
+   // in a model watcher
+   int exit_nested_loop = 0;
+   while (!exit_nested_loop)
+     ev_run (EV_A_ EVRUN_ONCE);
+To exit from any of these loops, just set the corresponding exit variable:
+   // exit modal loop
+   exit_nested_loop = 1;
+   // exit main program, after modal loop is finished
+   exit_main_loop = 1;
+   // exit both
+   exit_main_loop = exit_nested_loop = 1;
+=head2 THREAD LOCKING EXAMPLE
+Here is a fictitious example of how to run an event loop in a different
+thread than where callbacks are being invoked and watchers are
+created/added/removed.
+For a real-world example, see the C<EV::Loop::Async> perl module,
+which uses exactly this technique (which is suited for many high-level
+languages).
+The example uses a pthread mutex to protect the loop data, a condition
+variable to wait for callback invocations, an async watcher to notify the
+event loop thread and an unspecified mechanism to wake up the main thread.
+First, you need to associate some data with the event loop:
+   typedef struct {
+     mutex_t lock; /* global loop lock */
+     ev_async async_w;
+     thread_t tid;
+     cond_t invoke_cv;
+   } userdata;
+   void prepare_loop (EV_P)
+   {
+      // for simplicity, we use a static userdata struct.
+      static userdata u;
+      ev_async_init (&u->async_w, async_cb);
+      ev_async_start (EV_A_ &u->async_w);
+      pthread_mutex_init (&u->lock, 0);
+      pthread_cond_init (&u->invoke_cv, 0);
+      // now associate this with the loop
+      ev_set_userdata (EV_A_ u);
+      ev_set_invoke_pending_cb (EV_A_ l_invoke);
+      ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
+      // then create the thread running ev_loop
+      pthread_create (&u->tid, 0, l_run, EV_A);
+   }
+The callback for the C<ev_async> watcher does nothing: the watcher is used
+solely to wake up the event loop so it takes notice of any new watchers
+that might have been added:
+   static void
+   async_cb (EV_P_ ev_async *w, int revents)
+   {
+      // just used for the side effects
+   }
+The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
+protecting the loop data, respectively.
+   static void
+   l_release (EV_P)
+   {
+     userdata *u = ev_userdata (EV_A);
+     pthread_mutex_unlock (&u->lock);
+   }
+   static void
+   l_acquire (EV_P)
+   {
+     userdata *u = ev_userdata (EV_A);
+     pthread_mutex_lock (&u->lock);
+   }
+The event loop thread first acquires the mutex, and then jumps straight
+into C<ev_run>:
+   void *
+   l_run (void *thr_arg)
+   {
+     struct ev_loop *loop = (struct ev_loop *)thr_arg;
+     l_acquire (EV_A);
+     pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
+     ev_run (EV_A_ 0);
+     l_release (EV_A);
+     return 0;
+   }
+Instead of invoking all pending watchers, the C<l_invoke> callback will
+signal the main thread via some unspecified mechanism (signals? pipe
+writes? C<Async::Interrupt>?) and then waits until all pending watchers
+have been called (in a while loop because a) spurious wakeups are possible
+and b) skipping inter-thread-communication when there are no pending
+watchers is very beneficial):
+   static void
+   l_invoke (EV_P)
+   {
+     userdata *u = ev_userdata (EV_A);
+     while (ev_pending_count (EV_A))
+       {
+         wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
+         pthread_cond_wait (&u->invoke_cv, &u->lock);
+       }
+   }
+Now, whenever the main thread gets told to invoke pending watchers, it
+will grab the lock, call C<ev_invoke_pending> and then signal the loop
+thread to continue:
+   static void
+   real_invoke_pending (EV_P)
+   {
+     userdata *u = ev_userdata (EV_A);
+     pthread_mutex_lock (&u->lock);
+     ev_invoke_pending (EV_A);
+     pthread_cond_signal (&u->invoke_cv);
+     pthread_mutex_unlock (&u->lock);
+   }
+Whenever you want to start/stop a watcher or do other modifications to an
+event loop, you will now have to lock:
+   ev_timer timeout_watcher;
+   userdata *u = ev_userdata (EV_A);
+   ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
+   pthread_mutex_lock (&u->lock);
+   ev_timer_start (EV_A_ &timeout_watcher);
+   ev_async_send (EV_A_ &u->async_w);
+   pthread_mutex_unlock (&u->lock);
+Note that sending the C<ev_async> watcher is required because otherwise
+an event loop currently blocking in the kernel will have no knowledge
+about the newly added timer. By waking up the loop it will pick up any new
+watchers in the next event loop iteration.
 =head1 LIBEVENT EMULATION
 Libev offers a compatibility emulation layer for libevent. It cannot
 emulate the internals of libevent, so here are some usage hints:
 =over 4
+=item * Only the libevent-1.4.1-beta API is being emulated.
+This was the newest libevent version available when libev was implemented,
+and is still mostly unchanged in 2010.
 =item * Use it by including <event.h>, as usual.
 =item * The following members are fully supported: ev_base, ev_callback,
 ev_arg, ev_fd, ev_res, ev_events.
 =item * Priorities are not currently supported. Initialising priorities
 will fail and all watchers will have the same priority, even though there
 is an ev_pri field.
 =item * In libevent, the last base created gets the signals, in libev, the
-first base created (== the default loop) gets the signals.
+base that registered the signal gets the signals.
 =item * Other members are not supported.
 =item * The libev emulation is I<not> ABI compatible to libevent, you need
 to use the libev header file and library.
 Care has been taken to keep the overhead low. The only data member the C++
 classes add (compared to plain C-style watchers) is the event loop pointer
 that the watcher is associated with (or no additional members at all if
 you disable C<EV_MULTIPLICITY> when embedding libev).
-Currently, functions, and static and non-static member functions can be
+Currently, functions, static and non-static member functions and classes
-used as callbacks. Other types should be easy to add as long as they only
+with C<operator ()> can be used as callbacks. Other types should be easy
-need one additional pointer for context. If you need support for other
+to add as long as they only need one additional pointer for context. If
-types of functors please contact the author (preferably after implementing
+you need support for other types of functors please contact the author
-it).
+(preferably after implementing it).
 Here is a list of things available in the C<ev> namespace:
 =over 4
 And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
    #include "ev_cpp.h"
    #include "ev.c"
-=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
+=head1 INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT
 =head2 THREADS AND COROUTINES
 =head3 THREADS
 default loop and triggering an C<ev_async> watcher from the default loop
 watcher callback into the event loop interested in the signal.
 =back
-=head4 THREAD LOCKING EXAMPLE
+See also L<THREAD LOCKING EXAMPLE>.
-Here is a fictitious example of how to run an event loop in a different
-thread than where callbacks are being invoked and watchers are
-created/added/removed.
-For a real-world example, see the C<EV::Loop::Async> perl module,
-which uses exactly this technique (which is suited for many high-level
-languages).
-The example uses a pthread mutex to protect the loop data, a condition
-variable to wait for callback invocations, an async watcher to notify the
-event loop thread and an unspecified mechanism to wake up the main thread.
-First, you need to associate some data with the event loop:
-   typedef struct {
-     mutex_t lock; /* global loop lock */
-     ev_async async_w;
-     thread_t tid;
-     cond_t invoke_cv;
-   } userdata;
-   void prepare_loop (EV_P)
-   {
-      // for simplicity, we use a static userdata struct.
-      static userdata u;
-      ev_async_init (&u->async_w, async_cb);
-      ev_async_start (EV_A_ &u->async_w);
-      pthread_mutex_init (&u->lock, 0);
-      pthread_cond_init (&u->invoke_cv, 0);
-      // now associate this with the loop
-      ev_set_userdata (EV_A_ u);
-      ev_set_invoke_pending_cb (EV_A_ l_invoke);
-      ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
-      // then create the thread running ev_loop
-      pthread_create (&u->tid, 0, l_run, EV_A);
-   }
-The callback for the C<ev_async> watcher does nothing: the watcher is used
-solely to wake up the event loop so it takes notice of any new watchers
-that might have been added:
-   static void
-   async_cb (EV_P_ ev_async *w, int revents)
-   {
-      // just used for the side effects
-   }
-The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
-protecting the loop data, respectively.
-   static void
-   l_release (EV_P)
-   {
-     userdata *u = ev_userdata (EV_A);
-     pthread_mutex_unlock (&u->lock);
-   }
-   static void
-   l_acquire (EV_P)
-   {
-     userdata *u = ev_userdata (EV_A);
-     pthread_mutex_lock (&u->lock);
-   }
-The event loop thread first acquires the mutex, and then jumps straight
-into C<ev_run>:
-   void *
-   l_run (void *thr_arg)
-   {
-     struct ev_loop *loop = (struct ev_loop *)thr_arg;
-     l_acquire (EV_A);
-     pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
-     ev_run (EV_A_ 0);
-     l_release (EV_A);
-     return 0;
-   }
-Instead of invoking all pending watchers, the C<l_invoke> callback will
-signal the main thread via some unspecified mechanism (signals? pipe
-writes? C<Async::Interrupt>?) and then waits until all pending watchers
-have been called (in a while loop because a) spurious wakeups are possible
-and b) skipping inter-thread-communication when there are no pending
-watchers is very beneficial):
-   static void
-   l_invoke (EV_P)
-   {
-     userdata *u = ev_userdata (EV_A);
-     while (ev_pending_count (EV_A))
-       {
-         wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
-         pthread_cond_wait (&u->invoke_cv, &u->lock);
-       }
-   }
-Now, whenever the main thread gets told to invoke pending watchers, it
-will grab the lock, call C<ev_invoke_pending> and then signal the loop
-thread to continue:
-   static void
-   real_invoke_pending (EV_P)
-   {
-     userdata *u = ev_userdata (EV_A);
-     pthread_mutex_lock (&u->lock);
-     ev_invoke_pending (EV_A);
-     pthread_cond_signal (&u->invoke_cv);
-     pthread_mutex_unlock (&u->lock);
-   }
-Whenever you want to start/stop a watcher or do other modifications to an
-event loop, you will now have to lock:
-   ev_timer timeout_watcher;
-   userdata *u = ev_userdata (EV_A);
-   ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
-   pthread_mutex_lock (&u->lock);
-   ev_timer_start (EV_A_ &timeout_watcher);
-   ev_async_send (EV_A_ &u->async_w);
-   pthread_mutex_unlock (&u->lock);
-Note that sending the C<ev_async> watcher is required because otherwise
-an event loop currently blocking in the kernel will have no knowledge
-about the newly added timer. By waking up the loop it will pick up any new
-watchers in the next event loop iteration.
 =head3 COROUTINES
 Libev is very accommodating to coroutines ("cooperative threads"):
 libev fully supports nesting calls to its functions from different
 structure (guaranteed by POSIX but not by ISO C for example), but it also
 assumes that the same (machine) code can be used to call any watcher
 callback: The watcher callbacks have different type signatures, but libev
 calls them using an C<ev_watcher *> 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<sig_atomic_t volatile> must be thread-atomic as well
 The type C<sig_atomic_t volatile> (or whatever is defined as
 C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
 threads. This is not part of the specification for C<sig_atomic_t>, but is
 =back
 =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<ev.h> header file tries to implement superficial
+At the moment, the C<ev.h> header file provides compatibility definitions
-compatibility, so most programs should still compile. Those might be
+for all changes, so most programs should still compile. The compatibility
-removed in later versions of libev, so better update early than late.
+layer might be removed in later versions of libev, so better update to the
+new API early than late.
 =over 4
+=item C<EV_COMPAT3> backwards compatibility mechanism
+The backward compatibility mechanism can be controlled by
+C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
+section.
 =item C<ev_default_destroy> and C<ev_default_fork> have been removed
 These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
-   ev_loop_destroy (EV_DEFAULT);
+   ev_loop_destroy (EV_DEFAULT_UC);
    ev_loop_fork (EV_DEFAULT);
 =item function/symbol renames
 A number of functions and symbols have been renamed:
 ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme
 as all other watcher types. Note that C<ev_loop_fork> is still called
 C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
 typedef.
-=item C<EV_COMPAT3> backwards compatibility mechanism
-The backward compatibility mechanism can be controlled by
-C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
-section.
 =item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
 The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
 mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
 and work, but the library code will of course be larger.
 =back
 =head1 AUTHOR
-Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
+Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
+Magnusson and Emanuele Giaquinta.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing libev/ev.pod (file contents): Revision 1.323 by root, Sun Oct 24 18:01:26 2010 UTC vs. Revision 1.356 by root, Tue Jan 11 01:42:47 2011 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.323 by root, Sun Oct 24 18:01:26 2010 UTC vs.
Revision 1.356 by root, Tue Jan 11 01:42:47 2011 UTC