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

Comparing libev/ev.pod (file contents):
Revision 1.422 by root, Thu Nov 15 01:39:45 2012 UTC vs.
Revision 1.432 by root, Sat Apr 26 14:28:48 2014 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.
 reinitialise the kernel state for backends that have one. Despite the
 name, you can call it anytime, but it makes most sense after forking, in
 the child process. You I<must> call it (or use 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
    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
 =head2 C<ev_stat> - did the file attributes just change?
 This watches a file system path for attribute changes. That is, it calls
 C<stat> on that path in regular intervals (or when the OS says it changed)
-and sees if it changed compared to the last time, invoking the callback if
+and sees if it changed compared to the last time, invoking the callback
-it did.
+if it did. Starting the watcher C<stat>'s the file, so only changes that
+happen after the watcher has been started will be reported.
 The path does not need to exist: changing from "path exists" to "path does
 not exist" is a status change like any other. The condition "path does not
 exist" (or more correctly "path cannot be stat'ed") is signified by the
 C<st_nlink> field being zero (which is otherwise always forced to be at
 =over 4
 =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
-=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
+=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)
 Configures the watcher to embed the given loop, which must be
 embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
 invoked automatically, otherwise it is the responsibility of the callback
 to invoke it (it will continue to be called until the sweep has been done,
 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);
 already been invoked.
 A common way around all these issues is to make sure that
 C<start_new_request> I<always> returns before the callback is invoked. If
 C<start_new_request> immediately knows the result, it can artificially
-delay invoking the callback by e.g. using a C<prepare> or C<idle> watcher
+delay invoking the callback by using a C<prepare> or C<idle> watcher for
-for example, or more sneakily, by reusing an existing (stopped) watcher
+example, or more sneakily, by reusing an existing (stopped) watcher and
-and pushing it into the pending queue:
+pushing it into the pending queue:
    ev_set_cb (watcher, callback);
    ev_feed_event (EV_A_ watcher, 0);
 This way, C<start_new_request> can safely return before the callback is
 This brings the problem of exiting - a callback might want to finish the
 main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but
 a modal "Are you sure?" dialog is still waiting), or just the nested one
 and not the main one (e.g. user clocked "Ok" in a modal dialog), or some
-other combination: In these cases, C<ev_break> will not work alone.
+other combination: In these cases, a simple C<ev_break> will not work.
 The solution is to maintain "break this loop" variable for each C<ev_run>
 invocation, and use a loop around C<ev_run> until the condition is
 triggered, using C<EVRUN_ONCE>:
 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.422 by root, Thu Nov 15 01:39:45 2012 UTC vs. Revision 1.432 by root, Sat Apr 26 14:28:48 2014 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.422 by root, Thu Nov 15 01:39:45 2012 UTC vs.
Revision 1.432 by root, Sat Apr 26 14:28:48 2014 UTC