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

Comparing libev/ev.pod (file contents):
Revision 1.228 by root, Sat Mar 28 08:22:30 2009 UTC vs.
Revision 1.230 by root, Wed Apr 15 18:47:07 2009 UTC

… …
726 726
727If you have a watcher you never unregister that should not keep C<ev_loop> 727If you have a watcher you never unregister that should not keep C<ev_loop>
728from returning, call ev_unref() after starting, and ev_ref() before 728from returning, call ev_unref() after starting, and ev_ref() before
729stopping it. 729stopping it.
730 730
731As an example, libev itself uses this for its internal signal pipe: It is 731As an example, libev itself uses this for its internal signal pipe: It
732not visible to the libev user and should not keep C<ev_loop> from exiting 732is not visible to the libev user and should not keep C<ev_loop> from
733if no event watchers registered by it are active. It is also an excellent 733exiting if no event watchers registered by it are active. It is also an
734way to do this for generic recurring timers or from within third-party 734excellent way to do this for generic recurring timers or from within
735libraries. Just remember to I<unref after start> and I<ref before stop> 735third-party libraries. Just remember to I<unref after start> and I<ref
736(but only if the watcher wasn't active before, or was active before, 736before stop> (but only if the watcher wasn't active before, or was active
737respectively). 737before, respectively. Note also that libev might stop watchers itself
738(e.g. non-repeating timers) in which case you have to C<ev_ref>
739in the callback).
738 740
739Example: Create a signal watcher, but keep it from keeping C<ev_loop> 741Example: Create a signal watcher, but keep it from keeping C<ev_loop>
740running when nothing else is active. 742running when nothing else is active.
741 743
742 ev_signal exitsig; 744 ev_signal exitsig;
… …
925C<ev_fork>). 927C<ev_fork>).
926 928
927=item C<EV_ASYNC> 929=item C<EV_ASYNC>
928 930
929The given async watcher has been asynchronously notified (see C<ev_async>). 931The given async watcher has been asynchronously notified (see C<ev_async>).
932
933=item C<EV_CUSTOM>
934
935Not ever sent (or otherwise used) by libev itself, but can be freely used
936by libev users to signal watchers (e.g. via C<ev_feed_event>).
930 937
931=item C<EV_ERROR> 938=item C<EV_ERROR>
932 939
933An unspecified error has occurred, the watcher has been stopped. This might 940An unspecified error has occurred, the watcher has been stopped. This might
934happen because the watcher could not be properly started because libev 941happen because the watcher could not be properly started because libev
… …
1317year, it will still time out after (roughly) one hour. "Roughly" because 1324year, it will still time out after (roughly) one hour. "Roughly" because
1318detecting time jumps is hard, and some inaccuracies are unavoidable (the 1325detecting time jumps is hard, and some inaccuracies are unavoidable (the
1319monotonic clock option helps a lot here). 1326monotonic clock option helps a lot here).
1320 1327
1321The callback is guaranteed to be invoked only I<after> its timeout has 1328The callback is guaranteed to be invoked only I<after> its timeout has
1322passed, but if multiple timers become ready during the same loop iteration 1329passed. If multiple timers become ready during the same loop iteration
1323then order of execution is undefined. 1330then the ones with earlier time-out values are invoked before ones with
1331later time-out values (but this is no longer true when a callback calls
1332C<ev_loop> recursively).
1324 1333
1325=head3 Be smart about timeouts 1334=head3 Be smart about timeouts
1326 1335
1327Many real-world problems involve some kind of timeout, usually for error 1336Many real-world problems involve some kind of timeout, usually for error
1328recovery. A typical example is an HTTP request - if the other side hangs, 1337recovery. A typical example is an HTTP request - if the other side hangs,
… …
1617timers, such as triggering an event on each "midnight, local time", or 1626timers, such as triggering an event on each "midnight, local time", or
1618other complicated rules. This cannot be done with C<ev_timer> watchers, as 1627other complicated rules. This cannot be done with C<ev_timer> watchers, as
1619those cannot react to time jumps. 1628those cannot react to time jumps.
1620 1629
1621As with timers, the callback is guaranteed to be invoked only when the 1630As with timers, the callback is guaranteed to be invoked only when the
1622point in time where it is supposed to trigger has passed, but if multiple 1631point in time where it is supposed to trigger has passed. If multiple
1623periodic timers become ready during the same loop iteration, then order of 1632timers become ready during the same loop iteration then the ones with
1624execution is undefined. 1633earlier time-out values are invoked before ones with later time-out values
1634(but this is no longer true when a callback calls C<ev_loop> recursively).
1625 1635
1626=head3 Watcher-Specific Functions and Data Members 1636=head3 Watcher-Specific Functions and Data Members
1627 1637
1628=over 4 1638=over 4
1629 1639

Diff Legend

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