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

Comparing libev/ev.pod (file contents):
Revision 1.185 by root, Tue Sep 23 09:13:59 2008 UTC vs.
Revision 1.189 by root, Tue Sep 30 19:33:33 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
 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
 =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
 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 THREADS AND COROUTINES
+=head2 THREADS AND COROUTINES
-=head2 THREADS
+=head3 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 guarantees 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.
 default loop and triggering an C<ev_async> watcher from the default loop
 watcher callback into the event loop interested in the signal.
 =back
-=head2 COROUTINES
+=head3 COROUTINES
 Libev is much more accommodating to coroutines ("cooperative threads"):
 libev fully supports nesting calls to it's functions from different
 coroutines (e.g. you can call C<ev_loop> on the same loop from two
 different coroutines and switch freely between both coroutines running the
 you must not do this from C<ev_periodic> reschedule callbacks.
 Care has been taken to ensure that libev does not keep local state inside
 C<ev_loop>, and other calls do not usually allow coroutine switches.
+=head2 COMPILER WARNINGS
+Depending on your compiler and compiler settings, you might get no or a
+lot of warnings when compiling libev code. Some people are apparently
+scared by this.
+However, these are unavoidable for many reasons. For one, each compiler
+has different warnings, and each user has different tastes regarding
+warning options. "Warn-free" code therefore cannot be a goal except when
+targeting a specific compiler and compiler-version.
+Another reason is that some compiler warnings require elaborate
+workarounds, or other changes to the code that make it less clear and less
+maintainable.
+And of course, some compiler warnings are just plain stupid, or simply
+wrong (because they don't actually warn about the condition their message
+seems to warn about). For example, certain older gcc versions had some
+warnings that resulted an extreme number of false positives. These have
+been fixed, but some people still insist on making code warn-free with
+such buggy versions.
+While libev is written to generate as few warnings as possible,
+"warn-free" code is not a goal, and it is recommended not to build libev
+with any compiler warnings enabled unless you are prepared to cope with
+them (e.g. by ignoring them). Remember that warnings are just that:
+warnings, not errors, or proof of bugs.
+=head1 VALGRIND
+Valgrind has a special section here because it is a popular tool that is
+highly useful. Unfortunately, valgrind reports are very hard to interpret.
+If you think you found a bug (memory leak, uninitialised data access etc.)
+in libev, then check twice: If valgrind reports something like:
+   ==2274==    definitely lost: 0 bytes in 0 blocks.
+   ==2274==      possibly lost: 0 bytes in 0 blocks.
+   ==2274==    still reachable: 256 bytes in 1 blocks.
+Then there is no memory leak, just as memory accounted to global variables
+is not a memleak - the memory is still being refernced, and didn't leak.
+Similarly, under some circumstances, valgrind might report kernel bugs
+as if it were a bug in libev (e.g. in realloc or in the poll backend,
+although an acceptable workaround has been found here), or it might be
+confused.
+Keep in mind that valgrind is a very good tool, but only a tool. Don't
+make it into some kind of religion.
+If you are unsure about something, feel free to contact the mailing list
+with the full valgrind report and an explanation on why you think this
+is a bug in libev (best check the archives, too :). However, don't be
+annoyed when you get a brisk "this is no bug" answer and take the chance
+of learning how to interpret valgrind properly.
+If you need, for some reason, empty reports from valgrind for your project
+I suggest using suppression lists.
 =head1 COMPLEXITIES
 In this section the complexities of (many of) the algorithms used inside
 libev will be explained. For complexity discussions about backends see the
 involves iterating over all running async watchers or all signal numbers.
 =back
+=head1 PORTABILITY
-=head1 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
+=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
 Win32 doesn't support any of the standards (e.g. POSIX) that libev
 requires, and its I/O model is fundamentally incompatible with the POSIX
 model. Libev still offers limited functionality on this platform in
 the form of the C<EVBACKEND_SELECT> backend, and only supports socket
 wrap all I/O functions and provide your own fd management, but the cost of
 calling select (O(n²)) will likely make this unworkable.
 =back
-=head1 PORTABILITY REQUIREMENTS
+=head2 PORTABILITY REQUIREMENTS
-In addition to a working ISO-C implementation, libev relies on a few
+In addition to a working ISO-C implementation and of course the
-additional extensions:
+backend-specific APIs, libev relies on a few additional extensions:
 =over 4
 =item C<void (*)(ev_watcher_type *, int revents)> must have compatible
 calling conventions regardless of C<ev_watcher_type *>.
 except the initial one, and run the default loop in the initial thread as
 well.
 =item C<long> must be large enough for common memory allocation sizes
-To improve portability and simplify using libev, libev uses C<long>
+To improve portability and simplify its API, libev uses C<long> internally
-internally instead of C<size_t> when allocating its data structures. On
+instead of C<size_t> when allocating its data structures. On non-POSIX
-non-POSIX systems (Microsoft...) this might be unexpectedly low, but
+systems (Microsoft...) this might be unexpectedly low, but is still at
-is still at least 31 bits everywhere, which is enough for hundreds of
+least 31 bits everywhere, which is enough for hundreds of millions of
-millions of watchers.
+watchers.
 =item C<double> must hold a time value in seconds with enough accuracy
 The type C<double> is used to represent timestamps. It is required to
 have at least 51 bits of mantissa (and 9 bits of exponent), which is good
 =back
 If you know of other additional requirements drop me a note.
-=head1 COMPILER WARNINGS
-Depending on your compiler and compiler settings, you might get no or a
-lot of warnings when compiling libev code. Some people are apparently
-scared by this.
-However, these are unavoidable for many reasons. For one, each compiler
-has different warnings, and each user has different tastes regarding
-warning options. "Warn-free" code therefore cannot be a goal except when
-targeting a specific compiler and compiler-version.
-Another reason is that some compiler warnings require elaborate
-workarounds, or other changes to the code that make it less clear and less
-maintainable.
-And of course, some compiler warnings are just plain stupid, or simply
-wrong (because they don't actually warn about the condition their message
-seems to warn about).
-While libev is written to generate as few warnings as possible,
-"warn-free" code is not a goal, and it is recommended not to build libev
-with any compiler warnings enabled unless you are prepared to cope with
-them (e.g. by ignoring them). Remember that warnings are just that:
-warnings, not errors, or proof of bugs.
-=head1 VALGRIND
-Valgrind has a special section here because it is a popular tool that is
-highly useful, but valgrind reports are very hard to interpret.
-If you think you found a bug (memory leak, uninitialised data access etc.)
-in libev, then check twice: If valgrind reports something like:
-   ==2274==    definitely lost: 0 bytes in 0 blocks.
-   ==2274==      possibly lost: 0 bytes in 0 blocks.
-   ==2274==    still reachable: 256 bytes in 1 blocks.
-Then there is no memory leak. Similarly, under some circumstances,
-valgrind might report kernel bugs as if it were a bug in libev, or it
-might be confused (it is a very good tool, but only a tool).
-If you are unsure about something, feel free to contact the mailing list
-with the full valgrind report and an explanation on why you think this is
-a bug in libev. However, don't be annoyed when you get a brisk "this is
-no bug" answer and take the chance of learning how to interpret valgrind
-properly.
-If you need, for some reason, empty reports from valgrind for your project
-I suggest using suppression lists.
 =head1 AUTHOR
 Marc Lehmann <libev@schmorp.de>.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.185 by root, Tue Sep 23 09:13:59 2008 UTC vs. Revision 1.189 by root, Tue Sep 30 19:33:33 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.185 by root, Tue Sep 23 09:13:59 2008 UTC vs.
Revision 1.189 by root, Tue Sep 30 19:33:33 2008 UTC