=item int ev_version_minor ()
-You can find out the major and minor version numbers of the library
+You can find out the major and minor ABI version numbers of the library
you linked against by calling the functions C<ev_version_major> and
C<ev_version_minor>. If you want, you can compare against the global
symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
version of the library your program was compiled against.
+These version numbers refer to the ABI version of the library, not the
+release version.
+
Usually, it's a good idea to terminate if the major versions mismatch,
-as this indicates an incompatible change. Minor versions are usually
+as this indicates an incompatible change. Minor versions are usually
compatible to older versions, so a larger minor version alone is usually
not a problem.
periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
+ 10.>) and then reset your system clock to the last year, then it will
take a year to trigger the event (unlike an C<ev_timer>, which would trigger
-roughly 10 seconds later and of course not if you reset your system time
-again).
+roughly 10 seconds later).
They can also be used to implement vastly more complex timers, such as
-triggering an event on eahc midnight, local time.
+triggering an event on each midnight, local time or other, complicated,
+rules.
As with timers, the callback is guarenteed to be invoked only when the
time (C<at>) has been passed, but if multiple periodic timers become ready
=over 4
-=item * absolute timer (interval = reschedule_cb = 0)
+=item * absolute timer (at = time, interval = reschedule_cb = 0)
In this configuration the watcher triggers an event at the wallclock time
C<at> and doesn't repeat. It will not adjust when a time jump occurs,
that is, if it is to be run at January 1st 2011 then it will run when the
system time reaches or surpasses this time.
-=item * non-repeating interval timer (interval > 0, reschedule_cb = 0)
+=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
In this mode the watcher will always be scheduled to time out at the next
-C<at + N * interval> time (for some integer N) and then repeat, regardless
-of any time jumps.
+C<at + N * interval> time (for some integer N, which can also be negative)
+and then repeat, regardless of any time jumps.
This can be used to create timers that do not drift with respect to system
time:
C<ev_periodic> will try to run the callback in this mode at the next possible
time where C<time = at (mod interval)>, regardless of any time jumps.
-=item * manual reschedule mode (reschedule_cb = callback)
+For numerical stability it is preferable that the C<at> value is near
+C<ev_now ()> (the current time), but there is no range requirement for
+this value.
+
+=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
In this mode the values for C<interval> and C<at> are both being
ignored. Instead, each time the periodic watcher gets scheduled, the
NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
ever, or make any event loop modifications>. If you need to stop it,
return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
-starting a prepare watcher).
+starting an C<ev_prepare> watcher, which is legal).
Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
ev_tstamp now)>, e.g.:
a different time than the last time it was called (e.g. in a crond like
program when the crontabs have changed).
+=item ev_tstamp offset [read-write]
+
+When repeating, this contains the offset value, otherwise this is the
+absolute point in time (the C<at> value passed to C<ev_periodic_set>).
+
+Can be modified any time, but changes only take effect when the periodic
+timer fires or C<ev_periodic_again> is being called.
+
=item ev_tstamp interval [read-write]
The current interval value. Can be modified any time, but changes only
projects / software / libev.git / blobdiff