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

Comparing libev/ev.pod (file contents):
Revision 1.332 by root, Sun Oct 24 23:30:23 2010 UTC vs.
Revision 1.339 by root, Sun Oct 31 22:19:38 2010 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
 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
 on SMP systems). Libev tries to counter these spurious notifications by
 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
 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)
 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
 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 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.332 by root, Sun Oct 24 23:30:23 2010 UTC vs. Revision 1.339 by root, Sun Oct 31 22:19:38 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.332 by root, Sun Oct 24 23:30:23 2010 UTC vs.
Revision 1.339 by root, Sun Oct 31 22:19:38 2010 UTC