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

Comparing libev/ev.pod (file contents):
Revision 1.425 by root, Tue Jan 22 03:53:01 2013 UTC vs.
Revision 1.435 by root, Tue Apr 21 10:10:57 2015 UTC

+=encoding utf-8
 =head1 NAME
 libev - a high performance full-featured event loop written in C
 =head1 SYNOPSIS
 If this flag bit is or'ed into the flag value (or the program runs setuid
 or setgid) then libev will I<not> look at the environment variable
 C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
 override the flags completely if it is found in the environment. This is
-useful to try out specific backends to test their performance, or to work
+useful to try out specific backends to test their performance, to work
-around bugs.
+around bugs, or to make libev threadsafe (accessing environment variables
+cannot be done in a threadsafe way, but usually it works if no other
+thread modifies them).
 =item C<EVFLAG_FORKCHECK>
 Instead of calling C<ev_loop_fork> manually after a fork, you can also
 make libev check for a fork in each iteration by enabling this flag.
 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)
-This function sets a flag that causes subsequent C<ev_run> iterations to
+This function sets a flag that causes subsequent C<ev_run> iterations
-reinitialise the kernel state for backends that have one. Despite the
+to reinitialise the kernel state for backends that have one. Despite
-name, you can call it anytime, but it makes most sense after forking, in
+the name, you can call it anytime you are allowed to start or stop
-the child process. You I<must> call it (or use C<EVFLAG_FORKCHECK>) in the
+watchers (except inside an C<ev_prepare> callback), but it makes most
+sense after forking, in the child process. You I<must> call it (or use
-child before resuming or calling C<ev_run>.
+C<EVFLAG_FORKCHECK>) in the child before resuming or calling C<ev_run>.
 Again, you I<have> to call it on I<any> loop that you want to re-use after
 a fork, I<even if you do not plan to use the loop in the parent>. This is
 because some kernel interfaces *cough* I<kqueue> *cough* do funny things
 during fork.
 On the other hand, you only need to call this function in the child
 The relative timeouts are calculated relative to the C<ev_now ()>
 time. This is usually the right thing as this timestamp refers to the time
 of the event triggering whatever timeout you are modifying/starting. If
 you suspect event processing to be delayed and you I<need> to base the
-timeout on the current time, use something like this to adjust for this:
+timeout on the current time, use something like the following to adjust
+for it:
-   ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
+   ev_timer_set (&timer, after + (ev_time () - ev_now ()), 0.);
 If the event loop is suspended for a long time, you can also force an
 update of the time returned by C<ev_now ()> by calling C<ev_now_update
-()>.
+()>, although that will push the event time of all outstanding events
+further into the future.
 =head3 The special problem of unsynchronised clocks
 Modern systems have a variety of clocks - libev itself uses the normal
 "wall clock" clock and, if available, the monotonic clock (to avoid time
    ev_periodic hourly_tick;
    ev_periodic_init (&hourly_tick, clock_cb,
                      fmod (ev_now (loop), 3600.), 3600., 0);
    ev_periodic_start (loop, &hourly_tick);
 =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
 only within the same loop, i.e. you can watch for C<SIGINT> in your
 default loop and for C<SIGIO> in another loop, but you cannot watch for
 C<SIGINT> in both the default loop and another loop at the same time. At
 the moment, C<SIGCHLD> is permanently tied to the default loop.
-When the first watcher gets started will libev actually register something
+Only after the first watcher for a signal is started will libev actually
-with the kernel (thus it coexists with your own signal handlers as long as
+register something with the kernel. It thus coexists with your own signal
-you don't register any with libev for the same signal).
+handlers as long as you don't register any with libev for the same signal.
 If possible and supported, libev will install its handlers with
 C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
 not be unduly interrupted. If you have a problem with system calls getting
 interrupted by signals you can block all signals in an C<ev_check> watcher
 Prepare and check watchers are often (but not always) used in pairs:
 prepare watchers get invoked before the process blocks and check watchers
 afterwards.
-You I<must not> call C<ev_run> or similar functions that enter
+You I<must not> call C<ev_run> (or similar functions that enter the
-the current event loop from either C<ev_prepare> or C<ev_check>
+current event loop) or C<ev_loop_fork> from either C<ev_prepare> or
-watchers. Other loops than the current one are fine, however. The
+C<ev_check> watchers. Other loops than the current one are fine,
-rationale behind this is that you do not need to check for recursion in
+however. The rationale behind this is that you do not need to check
-those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
+for recursion in those watchers, i.e. the sequence will always be
-C<ev_check> so if you have one watcher of each kind they will always be
+C<ev_prepare>, blocking, C<ev_check> so if you have one watcher of each
-called in pairs bracketing the blocking call.
+kind they will always be called in pairs bracketing the blocking call.
 Their main purpose is to integrate other event mechanisms into libev and
 their use is somewhat advanced. They could be used, for example, to track
 variable changes, implement your own watchers, integrate net-snmp or a
 coroutine library and lots more. They are also occasionally useful if
 used).
    struct ev_loop *loop_hi = ev_default_init (0);
    struct ev_loop *loop_lo = 0;
    ev_embed embed;
    // see if there is a chance of getting one that works
    // (remember that a flags value of 0 means autodetection)
    loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
      ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
      : 0;
 C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
    struct ev_loop *loop = ev_default_init (0);
    struct ev_loop *loop_socket = 0;
    ev_embed embed;
    if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
      if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
        {
          ev_embed_init (&embed, 0, loop_socket);
          ev_embed_start (loop, &embed);
 and calls it in the wrong process, the fork handlers will be invoked, too,
 of course.
 =head3 The special problem of life after fork - how is it possible?
-Most uses of C<fork()> consist of forking, then some simple calls to set
+Most uses of C<fork ()> consist of forking, then some simple calls to set
 up/change the process environment, followed by a call to C<exec()>. This
 sequence should be handled by libev without any problems.
 This changes when the application actually wants to do event handling
 in the child, or both parent in child, in effect "continuing" after the
 To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two
 files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
    // my_ev.h
    #define EV_CB_DECLARE(type)   struct my_coro *cb;
-   #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb);
+   #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
    #include "../libev/ev.h"
    // my_ev.c
    #define EV_H "my_ev.h"
    #include "../libev/ev.c"
 Libev comes with some simplistic wrapper classes for C++ that mainly allow
 you to use some convenience methods to start/stop watchers and also change
 the callback model to a model using method callbacks on objects.
 To use it,
    #include <ev++.h>
 This automatically includes F<ev.h> and puts all of its definitions (many
 of them macros) into the global namespace. All C++ specific things are
 put into the C<ev> namespace. It should support all the same embedding
      void operator() (ev::io &w, int revents)
      {
        ...
      }
    }
    myfunctor f;
    ev::io w;
    w.set (&f);
 different cpus (or different cpu cores). This reduces dependencies
 and makes libev faster.
 =item EV_NO_THREADS
-If defined to be C<1>, libev will assume that it will never be called
+If defined to be C<1>, libev will assume that it will never be called from
-from different threads, which is a stronger assumption than C<EV_NO_SMP>,
+different threads (that includes signal handlers), which is a stronger
-above. This reduces dependencies and makes libev faster.
+assumption than C<EV_NO_SMP>, above. This reduces dependencies and makes
+libev faster.
 =item EV_ATOMIC_T
 Libev requires an integer type (suitable for storing C<0> or C<1>) whose
 access is atomic with respect to other threads or signal contexts. No
 =over 4
 =item C<EV_COMPAT3> backwards compatibility mechanism
 The backward compatibility mechanism can be controlled by
-C<EV_COMPAT3>. See L</PREPROCESSOR SYMBOLS/MACROS> in the L</EMBEDDING>
+C<EV_COMPAT3>. See L</"PREPROCESSOR SYMBOLS/MACROS"> in the L</EMBEDDING>
 section.
 =item C<ev_default_destroy> and C<ev_default_fork> have been removed
 These calls can be replaced easily by their C<ev_loop_xxx> counterparts:

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.425 by root, Tue Jan 22 03:53:01 2013 UTC vs. Revision 1.435 by root, Tue Apr 21 10:10:57 2015 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.425 by root, Tue Jan 22 03:53:01 2013 UTC vs.
Revision 1.435 by root, Tue Apr 21 10:10:57 2015 UTC