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

Comparing libev/ev.pod (file contents):
Revision 1.227 by root, Wed Mar 4 14:33:10 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
… …
3033L<http://software.schmorp.de/pkg/EV>. 3043L<http://software.schmorp.de/pkg/EV>.
3034 3044
3035=item Python 3045=item Python
3036 3046
3037Python bindings can be found at L<http://code.google.com/p/pyev/>. It 3047Python bindings can be found at L<http://code.google.com/p/pyev/>. It
3038seems to be quite complete and well-documented. Note, however, that the 3048seems to be quite complete and well-documented.
3039patch they require for libev is outright dangerous as it breaks the ABI
3040for everybody else, and therefore, should never be applied in an installed
3041libev (if python requires an incompatible ABI then it needs to embed
3042libev).
3043 3049
3044=item Ruby 3050=item Ruby
3045 3051
3046Tony Arcieri has written a ruby extension that offers access to a subset 3052Tony Arcieri has written a ruby extension that offers access to a subset
3047of the libev API and adds file handle abstractions, asynchronous DNS and 3053of the libev API and adds file handle abstractions, asynchronous DNS and
3048more on top of it. It can be found via gem servers. Its homepage is at 3054more on top of it. It can be found via gem servers. Its homepage is at
3049L<http://rev.rubyforge.org/>. 3055L<http://rev.rubyforge.org/>.
3050 3056
3051Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190> 3057Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3052makes rev work even on mingw. 3058makes rev work even on mingw.
3059
3060=item Haskell
3061
3062A haskell binding to libev is available at
3063L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3053 3064
3054=item D 3065=item D
3055 3066
3056Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 3067Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
3057be found at L<http://proj.llucax.com.ar/wiki/evd>. 3068be found at L<http://proj.llucax.com.ar/wiki/evd>.

Diff Legend

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