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

Comparing libev/ev.pod (file contents):
Revision 1.183 by root, Tue Sep 23 08:37:38 2008 UTC vs.
Revision 1.188 by root, Tue Sep 30 18:35:47 2008 UTC

 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))
+=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
 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));
+=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
 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
 =back
 =head3 Examples
-Example: Try to exit cleanly on SIGINT and SIGTERM.
+Example: Try to exit cleanly on SIGINT.
    static void
    sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
    {
      ev_unloop (loop, EVUNLOOP_ALL);
    }
    struct ev_signal signal_watcher;
    ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
-   ev_signal_start (loop, &sigint_cb);
+   ev_signal_start (loop, &signal_watcher);
 =head2 C<ev_child> - watch out for process status changes
 Child watchers trigger when your process receives a SIGCHLD in response to
 when you fork, you not only have to call C<ev_loop_fork> on both loops,
 but you will also have to stop and restart any C<ev_embed> watchers
 yourself - but you can use a fork watcher to handle this automatically,
 and future versions of libev might do just that.
-Unfortunately, not all backends are embeddable, only the ones returned by
+Unfortunately, not all backends are embeddable: only the ones returned by
 C<ev_embeddable_backends> are, which, unfortunately, does not include any
 portable one.
 So when you want to use this feature you will always have to be prepared
 that you cannot get an embeddable loop. The recommended way to get around
 this is to have a separate variables for your embeddable loop, try to
 create it, and if that fails, use the normal loop for everything.
+=head3 C<ev_embed> and fork
+While the C<ev_embed> watcher is running, forks in the embedding loop will
+automatically be applied to the embedded loop as well, so no special
+fork handling is required in that case. When the watcher is not running,
+however, it is still the task of the libev user to call C<ev_loop_fork ()>
+as applicable.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 is that the author does not know of a simple (or any) algorithm for a
 multiple-writer-single-reader queue that works in all cases and doesn't
 need elaborate support such as pthreads.
 That means that if you want to queue data, you have to provide your own
-queue. But at least I can tell you would implement locking around your
+queue. But at least I can tell you how to implement locking around your
 queue:
 =over 4
 =item queueing from a signal handler context
 =item ev_async_init (ev_async *, callback)
 Initialises and configures the async watcher - it has no parameters of any
 kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
-believe me.
+trust me.
 =item ev_async_send (loop, ev_async *)
 Sends/signals/activates the given C<ev_async> watcher, that is, feeds
 an C<EV_ASYNC> event on the watcher into the event loop. Unlike
-C<ev_feed_event>, this call is safe to do in other threads, signal or
+C<ev_feed_event>, this call is safe to do from other threads, signal or
 similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
 section below on what exactly this means).
 This call incurs the overhead of a system call only once per loop iteration,
 so while the overhead might be noticeable, it doesn't apply to repeated
 The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
 See the method-C<set> above for more details.
-Example:
+Example: Use a plain function as callback.
    static void io_cb (ev::io &w, int revents) { }
    iow.set <io_cb> ();
 =item w->set (struct ev_loop *)
 Example: Define a class with an IO and idle watcher, start one of them in
 the constructor.
    class myclass
    {
-     ev::io   io;  void io_cb   (ev::io   &w, int revents);
+     ev::io   io  ; void io_cb   (ev::io   &w, int revents);
-     ev:idle idle  void idle_cb (ev::idle &w, int revents);
+     ev::idle idle; void idle_cb (ev::idle &w, int revents);
      myclass (int fd)
      {
        io  .set <myclass, &myclass::io_cb  > (this);
        idle.set <myclass, &myclass::idle_cb> (this);
 =item Perl
 The EV module implements the full libev API and is actually used to test
 libev. EV is developed together with libev. Apart from the EV core module,
 there are additional modules that implement libev-compatible interfaces
-to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the
+to C<libadns> (C<EV::ADNS>, but C<AnyEvent::DNS> is preferred nowadays),
-C<libglib> event core (C<Glib::EV> and C<EV::Glib>).
+C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV>
+and C<EV::Glib>).
 It can be found and installed via CPAN, its homepage is at
 L<http://software.schmorp.de/pkg/EV>.
 =item Python
 =head2 PREPROCESSOR SYMBOLS/MACROS
 Libev can be configured via a variety of preprocessor symbols you have to
 define before including any of its files. The default in the absence of
-autoconf is noted for every option.
+autoconf is documented for every option.
 =over 4
 =item EV_STANDALONE
 When doing priority-based operations, libev usually has to linearly search
 all the priorities, so having many of them (hundreds) uses a lot of space
 and time, so using the defaults of five priorities (-2 .. +2) is usually
 fine.
-If your embedding application does not need any priorities, defining these both to
+If your embedding application does not need any priorities, defining these
-C<0> will save some memory and CPU.
+both to C<0> will save some memory and CPU.
 =item EV_PERIODIC_ENABLE
 If undefined or defined to be C<1>, then periodic timers are supported. If
 defined to be C<0>, then they are not. Disabling them saves a few kB of
 code.
 =item EV_EMBED_ENABLE
 If undefined or defined to be C<1>, then embed watchers are supported. If
-defined to be C<0>, then they are not.
+defined to be C<0>, then they are not. Embed watchers rely on most other
+watcher types, which therefore must not be disabled.
 =item EV_STAT_ENABLE
 If undefined or defined to be C<1>, then stat watchers are supported. If
 defined to be C<0>, then they are not.
 two).
 =item EV_USE_4HEAP
 Heaps are not very cache-efficient. To improve the cache-efficiency of the
-timer and periodics heap, libev uses a 4-heap when this symbol is defined
+timer and periodics heaps, libev uses a 4-heap when this symbol is defined
-to C<1>. The 4-heap uses more complicated (longer) code but has
+to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
-noticeably faster performance with many (thousands) of watchers.
+faster performance with many (thousands) of watchers.
 The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
 (disabled).
 =item EV_HEAP_CACHE_AT
 Heaps are not very cache-efficient. To improve the cache-efficiency of the
-timer and periodics heap, libev can cache the timestamp (I<at>) within
+timer and periodics heaps, libev can cache the timestamp (I<at>) within
 the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
 which uses 8-12 bytes more per watcher and a few hundred bytes more code,
 but avoids random read accesses on heap changes. This improves performance
-noticeably with with many (hundreds) of watchers.
+noticeably with many (hundreds) of watchers.
 The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
 (disabled).
 =item EV_VERIFY
 called once per loop, which can slow down libev. If set to C<3>, then the
 verification code will be called very frequently, which will slow down
 libev considerably.
 The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be
-C<0.>
+C<0>.
 =item EV_COMMON
 By default, all watchers have a C<void *data> member. By redefining
 this macro to a something else you can include more and other types of
 and the way callbacks are invoked and set. Must expand to a struct member
 definition and a statement, respectively. See the F<ev.h> header file for
 their default definitions. One possible use for overriding these is to
 avoid the C<struct ev_loop *> as first argument in all cases, or to use
 method calls instead of plain function calls in C++.
+=back
 =head2 EXPORTED API SYMBOLS
 If you need to re-export the API (e.g. via a DLL) and you need a list of
 exported symbols, you can use the provided F<Symbol.*> files which list
 =head1 THREADS AND COROUTINES
 =head2 THREADS
-Libev itself is thread-safe (unless the opposite is specifically
+All libev functions are reentrant and thread-safe unless explicitly
-documented for a function), but it uses no locking itself. This means that
+documented otherwise, but it uses no locking itself. This means that you
-you can use as many loops as you want in parallel, as long as only one
+can use as many loops as you want in parallel, as long as there are no
-thread ever calls into one libev function with the same loop parameter:
+concurrent calls into any libev function with the same loop parameter
+(C<ev_default_*> calls have an implicit default loop parameter, of
-libev guarentees that different event loops share no data structures that
+course): libev guarantees that different event loops share no data
-need locking.
+structures that need any locking.
 Or to put it differently: calls with different loop parameters can be done
 concurrently from multiple threads, calls with the same loop parameter
 must be done serially (but can be done from different threads, as long as
 only one thread ever is inside a call at any point in time, e.g. by using
 a mutex per loop).
 Specifically to support threads (and signal handlers), libev implements
 so-called C<ev_async> watchers, which allow some limited form of
-concurrency on the same event loop.
+concurrency on the same event loop, namely waking it up "from the
+outside".
 If you want to know which design (one loop, locking, or multiple loops
 without or something else still) is best for your problem, then I cannot
-help you. I can give some generic advice however:
+help you, but here is some generic advice:
 =over 4
 =item * most applications have a main thread: use the default libev loop
 in that thread, or create a separate thread running only the default loop.
 =item Priority handling: O(number_of_priorities)
 Priorities are implemented by allocating some space for each
 priority. When doing priority-based operations, libev usually has to
 linearly search all the priorities, but starting/stopping and activating
-watchers becomes O(1) w.r.t. priority handling.
+watchers becomes O(1) with respect to priority handling.
 =item Sending an ev_async: O(1)
 =item Processing ev_async_send: O(number_of_async_watchers)
 Not a libev limitation but worth mentioning: windows apparently doesn't
 accept large writes: instead of resulting in a partial write, windows will
 either accept everything or return C<ENOBUFS> if the buffer is too large,
 so make sure you only write small amounts into your sockets (less than a
-megabyte seems safe, but thsi apparently depends on the amount of memory
+megabyte seems safe, but this apparently depends on the amount of memory
 available).
 Due to the many, low, and arbitrary limits on the win32 platform and
 the abysmal performance of winsockets, using a large number of sockets
 is not recommended (and not reasonable). If your program needs to use
    #define EV_SELECT_IS_WINSOCKET 1   /* configure libev for windows select */
    #include "ev.h"
 And compile the following F<evwrap.c> file into your project (make sure
-you do I<not> compile the F<ev.c> or any other embedded soruce files!):
+you do I<not> compile the F<ev.c> or any other embedded source files!):
    #include "evwrap.h"
    #include "ev.c"
 =over 4
 calls them using an C<ev_watcher *> internally.
 =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 w.r.t. accesses from different
+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
 believed to be sufficiently portable.
 =item C<sigprocmask> must work in a threaded environment

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.183 by root, Tue Sep 23 08:37:38 2008 UTC vs. Revision 1.188 by root, Tue Sep 30 18:35:47 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.183 by root, Tue Sep 23 08:37:38 2008 UTC vs.
Revision 1.188 by root, Tue Sep 30 18:35:47 2008 UTC