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

Comparing libev/ev.pod (file contents):
Revision 1.440 by root, Tue Jan 31 09:31:43 2017 UTC vs.
Revision 1.446 by root, Mon Mar 18 19:28:15 2019 UTC

 You could override this function in high-availability programs to, say,
 free some memory if it cannot allocate memory, to use a special allocator,
 or even to sleep a while and retry until some memory is available.
+Example: The following is the C<realloc> function that libev itself uses
+which should work with C<realloc> and C<free> functions of all kinds and
+is probably a good basis for your own implementation.
+   static void *
+   ev_realloc_emul (void *ptr, long size) EV_NOEXCEPT
+   {
+     if (size)
+       return realloc (ptr, size);
+     free (ptr);
+     return 0;
+   }
 Example: Replace the libev allocator with one that waits a bit and then
-retries (example requires a standards-compliant C<realloc>).
+retries.
    static void *
    persistent_realloc (void *ptr, size_t size)
    {
+     if (!size)
+       {
+         free (ptr);
+         return 0;
+       }
      for (;;)
        {
          void *newptr = realloc (ptr, size);
          if (newptr)
 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, although you still
 have to ignore C<SIGPIPE>) when you use this flag.
 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
 =item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
-Configure the timer to trigger after C<after> seconds. If C<repeat>
+Configure the timer to trigger after C<after> seconds (fractional and
-is C<0.>, then it will automatically be stopped once the timeout is
+negative values are supported). If C<repeat> is C<0.>, then it will
-reached. If it is positive, then the timer will automatically be
+automatically be stopped once the timeout is reached. If it is positive,
-configured to trigger again C<repeat> seconds later, again, and again,
+then the timer will automatically be configured to trigger again C<repeat>
-until stopped manually.
+seconds later, again, and again, until stopped manually.
 The timer itself will do a best-effort at avoiding drift, that is, if
 you configure a timer to trigger every 10 seconds, then it will normally
 trigger at exactly 10 second intervals. If, however, your program cannot
 keep up with the timer (because it takes longer than those 10 seconds to
 C<ev_timer>, which would still trigger roughly 10 seconds after starting
 it, as it uses a relative timeout).
 C<ev_periodic> watchers can also be used to implement vastly more complex
 timers, such as triggering an event on each "midnight, local time", or
-other complicated rules. This cannot be done with C<ev_timer> watchers, as
+other complicated rules. This cannot easily be done with C<ev_timer>
-those cannot react to time jumps.
+watchers, as those cannot react to time jumps.
 As with timers, the callback is guaranteed to be invoked only when the
 point in time where it is supposed to trigger has passed. If multiple
 timers become ready during the same loop iteration then the ones with
 earlier time-out values are invoked before ones with later time-out values
 NOTE: I<< This callback must always return a time that is higher than or
 equal to the passed C<now> value >>.
 This can be used to create very complex timers, such as a timer that
-triggers on "next midnight, local time". To do this, you would calculate the
+triggers on "next midnight, local time". To do this, you would calculate
-next midnight after C<now> and return the timestamp value for this. How
+the next midnight after C<now> and return the timestamp value for
-you do this is, again, up to you (but it is not trivial, which is the main
+this. Here is a (completely untested, no error checking) example on how to
-reason I omitted it as an example).
+do this:
+   #include <time.h>
+   static ev_tstamp
+   my_rescheduler (ev_periodic *w, ev_tstamp now)
+   {
+     time_t tnow = (time_t)now;
+     struct tm tm;
+     localtime_r (&tnow, &tm);
+     tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
+     ++tm.tm_mday; // midnight next day
+     return mktime (&tm);
+   }
+Note: this code might run into trouble on days that have more then two
+midnights (beginning and end).
 =back
 =item ev_periodic_again (loop, ev_periodic *)
 There are some other functions of possible interest. Described. Here. Now.
 =over 4
-=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
+=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)
 This function combines a simple timer and an I/O watcher, calls your
 callback on whichever event happens first and automatically stops both
 watchers. This is useful if you want to wait for a single event on an fd
 or timeout without having to allocate/configure/start/stop/free one or
 The normal C API should work fine when used from C++: both ev.h and the
 libev sources can be compiled as C++. Therefore, code that uses the C API
 will work fine.
 Proper exception specifications might have to be added to callbacks passed
-to libev: exceptions may be thrown only from watcher callbacks, all
+to libev: exceptions may be thrown only from watcher callbacks, all other
-other callbacks (allocator, syserr, loop acquire/release and periodic
+callbacks (allocator, syserr, loop acquire/release and periodic reschedule
-reschedule callbacks) must not throw exceptions, and might need a C<throw
+callbacks) must not throw exceptions, and might need a C<noexcept>
-()> specification. If you have code that needs to be compiled as both C
+specification. If you have code that needs to be compiled as both C and
-and C++ you can use the C<EV_THROW> macro for this:
+C++ you can use the C<EV_NOEXCEPT> macro for this:
    static void
-   fatal_error (const char *msg) EV_THROW
+   fatal_error (const char *msg) EV_NOEXCEPT
    {
      perror (msg);
      abort ();
    }

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.440 by root, Tue Jan 31 09:31:43 2017 UTC vs. Revision 1.446 by root, Mon Mar 18 19:28:15 2019 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.440 by root, Tue Jan 31 09:31:43 2017 UTC vs.
Revision 1.446 by root, Mon Mar 18 19:28:15 2019 UTC