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

Comparing libev/ev.pod (file contents):
Revision 1.433 by root, Fri May 2 07:05:42 2014 UTC vs.
Revision 1.441 by root, Thu Jul 13 10:46:52 2017 UTC

 make libev check for a fork in each iteration by enabling this flag.
 This works by calling C<getpid ()> on every iteration of the loop,
 and thus this might slow down your event loop if you do a lot of loop
 iterations and little real work, but is usually not noticeable (on my
-GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
+GNU/Linux system for example, C<getpid> is actually a simple 5-insn
-without a system call and thus I<very> fast, but my GNU/Linux system also has
+sequence without a system call and thus I<very> fast, but my GNU/Linux
-C<pthread_atfork> which is even faster).
+system also has C<pthread_atfork> which is even faster). (Update: glibc
+versions 2.25 apparently removed the C<getpid> optimisation again).
 The big advantage of this flag is that you can forget about fork (and
-forget about forgetting to tell libev about forking) when you use this
+forget about forgetting to tell libev about forking, although you still
-flag.
+have to ignore C<SIGPIPE>) when you use this flag.
 This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
 environment variable.
 =item C<EVFLAG_NOINOTIFY>
 to reinitialise the kernel state for backends that have one. Despite
 the name, you can call it anytime you are allowed to start or stop
 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
 C<EVFLAG_FORKCHECK>) in the child before resuming or calling C<ev_run>.
+In addition, if you want to reuse a loop (via this function or
+C<EVFLAG_FORKCHECK>), you I<also> have to ignore C<SIGPIPE>.
 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.
 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
 Periodic watchers are also timers of a kind, but they are very versatile
 (and unfortunately a bit complex).
 Unlike C<ev_timer>, periodic watchers are not based on real time (or
 relative time, the physical time that passes) but on wall clock time
-(absolute time, the thing you can read on your calender or clock). The
+(absolute time, the thing you can read on your calendar or clock). The
 difference is that wall clock time can run faster or slower than real
 time, and time jumps are not uncommon (e.g. when you adjust your
 wrist-watch).
 You can tell a periodic watcher to trigger after some specific point
 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"
    ev_vars.h
    ev_wrap.h
    ev_win32.c      required on win32 platforms only
-   ev_select.c     only when select backend is enabled (which is enabled by default)
+   ev_select.c     only when select backend is enabled
-   ev_poll.c       only when poll backend is enabled (disabled by default)
+   ev_poll.c       only when poll backend is enabled
-   ev_epoll.c      only when the epoll backend is enabled (disabled by default)
+   ev_epoll.c      only when the epoll backend is enabled
-   ev_kqueue.c     only when the kqueue backend is enabled (disabled by default)
+   ev_kqueue.c     only when the kqueue backend is enabled
-   ev_port.c       only when the solaris port backend is enabled (disabled by default)
+   ev_port.c       only when the solaris port backend is enabled
 F<ev.c> includes the backend files directly when enabled, so you only need
 to compile this single file.
 =head3 LIBEVENT COMPATIBILITY API
 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 null pointers and integer zero are represented by 0 bytes
+Libev uses C<memset> to initialise structs and arrays to C<0> bytes, and
+relies on this setting pointers and integers to null.
 =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.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.433 by root, Fri May 2 07:05:42 2014 UTC vs. Revision 1.441 by root, Thu Jul 13 10:46:52 2017 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.433 by root, Fri May 2 07:05:42 2014 UTC vs.
Revision 1.441 by root, Thu Jul 13 10:46:52 2017 UTC