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

Comparing libev/ev.pod (file contents):
Revision 1.341 by root, Fri Nov 5 22:08:09 2010 UTC vs.
Revision 1.351 by root, Mon Jan 10 14:24:26 2011 UTC

    }
    ...
    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
 =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:
 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,
 =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>, with the event polling
+function sometimes returning events to the caller even though an error
+occured, but with no indication whether it has done so or not (yes, it's
+even documented that way) - deadly for edge-triggered interfaces, but
+fortunately libev seems to be able to work around it.
 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
 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 "break 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, too.
+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.
 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
 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.
+=over 4
+=item 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;
 =back
 =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.
 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

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.341 by root, Fri Nov 5 22:08:09 2010 UTC vs. Revision 1.351 by root, Mon Jan 10 14:24:26 2011 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.341 by root, Fri Nov 5 22:08:09 2010 UTC vs.
Revision 1.351 by root, Mon Jan 10 14:24:26 2011 UTC