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

Comparing libev/ev.pod (file contents):
Revision 1.335 by root, Mon Oct 25 10:32:05 2010 UTC vs.
Revision 1.342 by root, Wed Nov 10 13:16:44 2010 UTC

 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
 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.
 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.
 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
 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)
 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 when entering C<ev_run> again.
-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.
 =item ev_ref (loop)
 =item ev_unref (loop)
 =item 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.
 =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
 =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.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.335 by root, Mon Oct 25 10:32:05 2010 UTC vs. Revision 1.342 by root, Wed Nov 10 13:16:44 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.335 by root, Mon Oct 25 10:32:05 2010 UTC vs.
Revision 1.342 by root, Wed Nov 10 13:16:44 2010 UTC