ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.226 by root, Wed Mar 4 12:51:37 2009 UTC vs.
Revision 1.227 by root, Wed Mar 4 14:33:10 2009 UTC

… …
1596=head2 C<ev_periodic> - to cron or not to cron? 1596=head2 C<ev_periodic> - to cron or not to cron?
1597 1597
1598Periodic watchers are also timers of a kind, but they are very versatile 1598Periodic watchers are also timers of a kind, but they are very versatile
1599(and unfortunately a bit complex). 1599(and unfortunately a bit complex).
1600 1600
1601Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1601Unlike C<ev_timer>, periodic watchers are not based on real time (or
1602but on wall clock time (absolute time). You can tell a periodic watcher 1602relative time, the physical time that passes) but on wall clock time
1603to trigger after some specific point in time. For example, if you tell a 1603(absolute time, the thing you can read on your calender or clock). The
1604periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now () 1604difference is that wall clock time can run faster or slower than real
1605+ 10.>, that is, an absolute time not a delay) and then reset your system 1605time, and time jumps are not uncommon (e.g. when you adjust your
1606clock to January of the previous year, then it will take more than year 1606wrist-watch).
1607to trigger the event (unlike an C<ev_timer>, which would still trigger
1608roughly 10 seconds later as it uses a relative timeout).
1609 1607
1608You can tell a periodic watcher to trigger after some specific point
1609in time: for example, if you tell a periodic watcher to trigger "in 10
1610seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
1611not a delay) and then reset your system clock to January of the previous
1612year, then it will take a year or more to trigger the event (unlike an
1613C<ev_timer>, which would still trigger roughly 10 seconds after starting
1614it, as it uses a relative timeout).
1615
1610C<ev_periodic>s can also be used to implement vastly more complex timers, 1616C<ev_periodic> watchers can also be used to implement vastly more complex
1611such as triggering an event on each "midnight, local time", or other 1617timers, such as triggering an event on each "midnight, local time", or
1612complicated rules. 1618other complicated rules. This cannot be done with C<ev_timer> watchers, as
1619those cannot react to time jumps.
1613 1620
1614As with timers, the callback is guaranteed to be invoked only when the 1621As with timers, the callback is guaranteed to be invoked only when the
1615time (C<at>) has passed, but if multiple periodic timers become ready 1622point in time where it is supposed to trigger has passed, but if multiple
1616during the same loop iteration, then order of execution is undefined. 1623periodic timers become ready during the same loop iteration, then order of
1624execution is undefined.
1617 1625
1618=head3 Watcher-Specific Functions and Data Members 1626=head3 Watcher-Specific Functions and Data Members
1619 1627
1620=over 4 1628=over 4
1621 1629
1622=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1630=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1623 1631
1624=item ev_periodic_set (ev_periodic *, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1632=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1625 1633
1626Lots of arguments, lets sort it out... There are basically three modes of 1634Lots of arguments, let's sort it out... There are basically three modes of
1627operation, and we will explain them from simplest to most complex: 1635operation, and we will explain them from simplest to most complex:
1628 1636
1629=over 4 1637=over 4
1630 1638
1631=item * absolute timer (at = time, interval = reschedule_cb = 0) 1639=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1632 1640
1633In this configuration the watcher triggers an event after the wall clock 1641In this configuration the watcher triggers an event after the wall clock
1634time C<at> has passed. It will not repeat and will not adjust when a time 1642time C<offset> has passed. It will not repeat and will not adjust when a
1635jump occurs, that is, if it is to be run at January 1st 2011 then it will 1643time jump occurs, that is, if it is to be run at January 1st 2011 then it
1636only run when the system clock reaches or surpasses this time. 1644will be stopped and invoked when the system clock reaches or surpasses
1645this point in time.
1637 1646
1638=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1647=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1639 1648
1640In this mode the watcher will always be scheduled to time out at the next 1649In this mode the watcher will always be scheduled to time out at the next
1641C<at + N * interval> time (for some integer N, which can also be negative) 1650C<offset + N * interval> time (for some integer N, which can also be
1642and then repeat, regardless of any time jumps. 1651negative) and then repeat, regardless of any time jumps. The C<offset>
1652argument is merely an offset into the C<interval> periods.
1643 1653
1644This can be used to create timers that do not drift with respect to the 1654This can be used to create timers that do not drift with respect to the
1645system clock, for example, here is a C<ev_periodic> that triggers each 1655system clock, for example, here is an C<ev_periodic> that triggers each
1646hour, on the hour: 1656hour, on the hour (with respect to UTC):
1647 1657
1648 ev_periodic_set (&periodic, 0., 3600., 0); 1658 ev_periodic_set (&periodic, 0., 3600., 0);
1649 1659
1650This doesn't mean there will always be 3600 seconds in between triggers, 1660This doesn't mean there will always be 3600 seconds in between triggers,
1651but only that the callback will be called when the system time shows a 1661but only that the callback will be called when the system time shows a
1652full hour (UTC), or more correctly, when the system time is evenly divisible 1662full hour (UTC), or more correctly, when the system time is evenly divisible
1653by 3600. 1663by 3600.
1654 1664
1655Another way to think about it (for the mathematically inclined) is that 1665Another way to think about it (for the mathematically inclined) is that
1656C<ev_periodic> will try to run the callback in this mode at the next possible 1666C<ev_periodic> will try to run the callback in this mode at the next possible
1657time where C<time = at (mod interval)>, regardless of any time jumps. 1667time where C<time = offset (mod interval)>, regardless of any time jumps.
1658 1668
1659For numerical stability it is preferable that the C<at> value is near 1669For numerical stability it is preferable that the C<offset> value is near
1660C<ev_now ()> (the current time), but there is no range requirement for 1670C<ev_now ()> (the current time), but there is no range requirement for
1661this value, and in fact is often specified as zero. 1671this value, and in fact is often specified as zero.
1662 1672
1663Note also that there is an upper limit to how often a timer can fire (CPU 1673Note also that there is an upper limit to how often a timer can fire (CPU
1664speed for example), so if C<interval> is very small then timing stability 1674speed for example), so if C<interval> is very small then timing stability
1665will of course deteriorate. Libev itself tries to be exact to be about one 1675will of course deteriorate. Libev itself tries to be exact to be about one
1666millisecond (if the OS supports it and the machine is fast enough). 1676millisecond (if the OS supports it and the machine is fast enough).
1667 1677
1668=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1678=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1669 1679
1670In this mode the values for C<interval> and C<at> are both being 1680In this mode the values for C<interval> and C<offset> are both being
1671ignored. Instead, each time the periodic watcher gets scheduled, the 1681ignored. Instead, each time the periodic watcher gets scheduled, the
1672reschedule callback will be called with the watcher as first, and the 1682reschedule callback will be called with the watcher as first, and the
1673current time as second argument. 1683current time as second argument.
1674 1684
1675NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1685NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1676ever, or make ANY other event loop modifications whatsoever>. 1686or make ANY other event loop modifications whatsoever, unless explicitly
1687allowed by documentation here>.
1677 1688
1678If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 1689If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1679it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 1690it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1680only event loop modification you are allowed to do). 1691only event loop modification you are allowed to do).
1681 1692
… …
1711a different time than the last time it was called (e.g. in a crond like 1722a different time than the last time it was called (e.g. in a crond like
1712program when the crontabs have changed). 1723program when the crontabs have changed).
1713 1724
1714=item ev_tstamp ev_periodic_at (ev_periodic *) 1725=item ev_tstamp ev_periodic_at (ev_periodic *)
1715 1726
1716When active, returns the absolute time that the watcher is supposed to 1727When active, returns the absolute time that the watcher is supposed
1717trigger next. 1728to trigger next. This is not the same as the C<offset> argument to
1729C<ev_periodic_set>, but indeed works even in interval and manual
1730rescheduling modes.
1718 1731
1719=item ev_tstamp offset [read-write] 1732=item ev_tstamp offset [read-write]
1720 1733
1721When repeating, this contains the offset value, otherwise this is the 1734When repeating, this contains the offset value, otherwise this is the
1722absolute point in time (the C<at> value passed to C<ev_periodic_set>). 1735absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
1736although libev might modify this value for better numerical stability).
1723 1737
1724Can be modified any time, but changes only take effect when the periodic 1738Can be modified any time, but changes only take effect when the periodic
1725timer fires or C<ev_periodic_again> is being called. 1739timer fires or C<ev_periodic_again> is being called.
1726 1740
1727=item ev_tstamp interval [read-write] 1741=item ev_tstamp interval [read-write]
… …
2682an C<EV_ASYNC> event on the watcher into the event loop. Unlike 2696an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2683C<ev_feed_event>, this call is safe to do from other threads, signal or 2697C<ev_feed_event>, this call is safe to do from other threads, signal or
2684similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 2698similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2685section below on what exactly this means). 2699section below on what exactly this means).
2686 2700
2701Note that, as with other watchers in libev, multiple events might get
2702compressed into a single callback invocation (another way to look at this
2703is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
2704reset when the event loop detects that).
2705
2687This call incurs the overhead of a system call only once per loop iteration, 2706This call incurs the overhead of a system call only once per event loop
2688so while the overhead might be noticeable, it doesn't apply to repeated 2707iteration, so while the overhead might be noticeable, it doesn't apply to
2689calls to C<ev_async_send>. 2708repeated calls to C<ev_async_send> for the same event loop.
2690 2709
2691=item bool = ev_async_pending (ev_async *) 2710=item bool = ev_async_pending (ev_async *)
2692 2711
2693Returns a non-zero value when C<ev_async_send> has been called on the 2712Returns a non-zero value when C<ev_async_send> has been called on the
2694watcher but the event has not yet been processed (or even noted) by the 2713watcher but the event has not yet been processed (or even noted) by the
… …
2697C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 2716C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2698the loop iterates next and checks for the watcher to have become active, 2717the loop iterates next and checks for the watcher to have become active,
2699it will reset the flag again. C<ev_async_pending> can be used to very 2718it will reset the flag again. C<ev_async_pending> can be used to very
2700quickly check whether invoking the loop might be a good idea. 2719quickly check whether invoking the loop might be a good idea.
2701 2720
2702Not that this does I<not> check whether the watcher itself is pending, only 2721Not that this does I<not> check whether the watcher itself is pending,
2703whether it has been requested to make this watcher pending. 2722only whether it has been requested to make this watcher pending: there
2723is a time window between the event loop checking and resetting the async
2724notification, and the callback being invoked.
2704 2725
2705=back 2726=back
2706 2727
2707 2728
2708=head1 OTHER FUNCTIONS 2729=head1 OTHER FUNCTIONS

Diff Legend

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