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

Comparing libev/ev.pod (file contents):
Revision 1.297 by root, Tue Jun 29 11:49:02 2010 UTC vs.
Revision 1.299 by sf-exg, Sat Aug 28 21:42:12 2010 UTC

… …
75While this document tries to be as complete as possible in documenting 75While this document tries to be as complete as possible in documenting
76libev, its usage and the rationale behind its design, it is not a tutorial 76libev, its usage and the rationale behind its design, it is not a tutorial
77on event-based programming, nor will it introduce event-based programming 77on event-based programming, nor will it introduce event-based programming
78with libev. 78with libev.
79 79
80Familarity with event based programming techniques in general is assumed 80Familiarity with event based programming techniques in general is assumed
81throughout this document. 81throughout this document.
82 82
83=head1 ABOUT LIBEV 83=head1 ABOUT LIBEV
84 84
85Libev is an event loop: you register interest in certain events (such as a 85Libev is an event loop: you register interest in certain events (such as a
… …
705C<ev_resume> directly afterwards to resume timer processing. 705C<ev_resume> directly afterwards to resume timer processing.
706 706
707Effectively, all C<ev_timer> watchers will be delayed by the time spend 707Effectively, all C<ev_timer> watchers will be delayed by the time spend
708between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers 708between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
709will be rescheduled (that is, they will lose any events that would have 709will be rescheduled (that is, they will lose any events that would have
710occured while suspended). 710occurred while suspended).
711 711
712After calling C<ev_suspend> you B<must not> call I<any> function on the 712After calling C<ev_suspend> you B<must not> call I<any> function on the
713given loop other than C<ev_resume>, and you B<must not> call C<ev_resume> 713given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
714without a previous call to C<ev_suspend>. 714without a previous call to C<ev_suspend>.
715 715
… …
792C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 792C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
793C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 793C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
794 794
795This "unloop state" will be cleared when entering C<ev_loop> again. 795This "unloop state" will be cleared when entering C<ev_loop> again.
796 796
797It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls. 797It is safe to call C<ev_unloop> from outside any C<ev_loop> calls.
798 798
799=item ev_ref (loop) 799=item ev_ref (loop)
800 800
801=item ev_unref (loop) 801=item ev_unref (loop)
802 802
… …
872usually doesn't make much sense to set it to a lower value than C<0.01>, 872usually doesn't make much sense to set it to a lower value than C<0.01>,
873as this approaches the timing granularity of most systems. Note that if 873as this approaches the timing granularity of most systems. Note that if
874you do transactions with the outside world and you can't increase the 874you do transactions with the outside world and you can't increase the
875parallelity, then this setting will limit your transaction rate (if you 875parallelity, then this setting will limit your transaction rate (if you
876need to poll once per transaction and the I/O collect interval is 0.01, 876need to poll once per transaction and the I/O collect interval is 0.01,
877then you can't do more than 100 transations per second). 877then you can't do more than 100 transactions per second).
878 878
879Setting the I<timeout collect interval> can improve the opportunity for 879Setting the I<timeout collect interval> can improve the opportunity for
880saving power, as the program will "bundle" timer callback invocations that 880saving power, as the program will "bundle" timer callback invocations that
881are "near" in time together, by delaying some, thus reducing the number of 881are "near" in time together, by delaying some, thus reducing the number of
882times the process sleeps and wakes up again. Another useful technique to 882times the process sleeps and wakes up again. Another useful technique to
… …
1380 1380
1381For example, to emulate how many other event libraries handle priorities, 1381For example, to emulate how many other event libraries handle priorities,
1382you can associate an C<ev_idle> watcher to each such watcher, and in 1382you can associate an C<ev_idle> watcher to each such watcher, and in
1383the normal watcher callback, you just start the idle watcher. The real 1383the normal watcher callback, you just start the idle watcher. The real
1384processing is done in the idle watcher callback. This causes libev to 1384processing is done in the idle watcher callback. This causes libev to
1385continously poll and process kernel event data for the watcher, but when 1385continuously poll and process kernel event data for the watcher, but when
1386the lock-out case is known to be rare (which in turn is rare :), this is 1386the lock-out case is known to be rare (which in turn is rare :), this is
1387workable. 1387workable.
1388 1388
1389Usually, however, the lock-out model implemented that way will perform 1389Usually, however, the lock-out model implemented that way will perform
1390miserably under the type of load it was designed to handle. In that case, 1390miserably under the type of load it was designed to handle. In that case,
… …
1468 1468
1469If you cannot use non-blocking mode, then force the use of a 1469If you cannot use non-blocking mode, then force the use of a
1470known-to-be-good backend (at the time of this writing, this includes only 1470known-to-be-good backend (at the time of this writing, this includes only
1471C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file 1471C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1472descriptors for which non-blocking operation makes no sense (such as 1472descriptors for which non-blocking operation makes no sense (such as
1473files) - libev doesn't guarentee any specific behaviour in that case. 1473files) - libev doesn't guarantee any specific behaviour in that case.
1474 1474
1475Another thing you have to watch out for is that it is quite easy to 1475Another thing you have to watch out for is that it is quite easy to
1476receive "spurious" readiness notifications, that is your callback might 1476receive "spurious" readiness notifications, that is your callback might
1477be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1477be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1478because there is no data. Not only are some backends known to create a 1478because there is no data. Not only are some backends known to create a
… …
1737 ev_tstamp timeout = last_activity + 60.; 1737 ev_tstamp timeout = last_activity + 60.;
1738 1738
1739 // if last_activity + 60. is older than now, we did time out 1739 // if last_activity + 60. is older than now, we did time out
1740 if (timeout < now) 1740 if (timeout < now)
1741 { 1741 {
1742 // timeout occured, take action 1742 // timeout occurred, take action
1743 } 1743 }
1744 else 1744 else
1745 { 1745 {
1746 // callback was invoked, but there was some activity, re-arm 1746 // callback was invoked, but there was some activity, re-arm
1747 // the watcher to fire in last_activity + 60, which is 1747 // the watcher to fire in last_activity + 60, which is
… …
3885EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, 3885EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3886EV_ASYNC_ENABLE, EV_CHILD_ENABLE. 3886EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3887 3887
3888If undefined or defined to be C<1> (and the platform supports it), then 3888If undefined or defined to be C<1> (and the platform supports it), then
3889the respective watcher type is supported. If defined to be C<0>, then it 3889the respective watcher type is supported. If defined to be C<0>, then it
3890is not. Disabling watcher types mainly saves codesize. 3890is not. Disabling watcher types mainly saves code size.
3891 3891
3892=item EV_FEATURES 3892=item EV_FEATURES
3893 3893
3894If you need to shave off some kilobytes of code at the expense of some 3894If you need to shave off some kilobytes of code at the expense of some
3895speed (but with the full API), you can define this symbol to request 3895speed (but with the full API), you can define this symbol to request
… …
3915 3915
3916=item C<1> - faster/larger code 3916=item C<1> - faster/larger code
3917 3917
3918Use larger code to speed up some operations. 3918Use larger code to speed up some operations.
3919 3919
3920Currently this is used to override some inlining decisions (enlarging the roughly 3920Currently this is used to override some inlining decisions (enlarging the
392130% code size on amd64. 3921code size by roughly 30% on amd64).
3922 3922
3923When optimising for size, use of compiler flags such as C<-Os> with 3923When optimising for size, use of compiler flags such as C<-Os> with
3924gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of 3924gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
3925assertions. 3925assertions.
3926 3926
3927=item C<2> - faster/larger data structures 3927=item C<2> - faster/larger data structures
3928 3928
3929Replaces the small 2-heap for timer management by a faster 4-heap, larger 3929Replaces the small 2-heap for timer management by a faster 4-heap, larger
3930hash table sizes and so on. This will usually further increase codesize 3930hash table sizes and so on. This will usually further increase code size
3931and can additionally have an effect on the size of data structures at 3931and can additionally have an effect on the size of data structures at
3932runtime. 3932runtime.
3933 3933
3934=item C<4> - full API configuration 3934=item C<4> - full API configuration
3935 3935
… …
3972I/O watcher then might come out at only 5Kb. 3972I/O watcher then might come out at only 5Kb.
3973 3973
3974=item EV_AVOID_STDIO 3974=item EV_AVOID_STDIO
3975 3975
3976If this is set to C<1> at compiletime, then libev will avoid using stdio 3976If this is set to C<1> at compiletime, then libev will avoid using stdio
3977functions (printf, scanf, perror etc.). This will increase the codesize 3977functions (printf, scanf, perror etc.). This will increase the code size
3978somewhat, but if your program doesn't otherwise depend on stdio and your 3978somewhat, but if your program doesn't otherwise depend on stdio and your
3979libc allows it, this avoids linking in the stdio library which is quite 3979libc allows it, this avoids linking in the stdio library which is quite
3980big. 3980big.
3981 3981
3982Note that error messages might become less precise when this option is 3982Note that error messages might become less precise when this option is
… …
3986 3986
3987The highest supported signal number, +1 (or, the number of 3987The highest supported signal number, +1 (or, the number of
3988signals): Normally, libev tries to deduce the maximum number of signals 3988signals): Normally, libev tries to deduce the maximum number of signals
3989automatically, but sometimes this fails, in which case it can be 3989automatically, but sometimes this fails, in which case it can be
3990specified. Also, using a lower number than detected (C<32> should be 3990specified. Also, using a lower number than detected (C<32> should be
3991good for about any system in existance) can save some memory, as libev 3991good for about any system in existence) can save some memory, as libev
3992statically allocates some 12-24 bytes per signal number. 3992statically allocates some 12-24 bytes per signal number.
3993 3993
3994=item EV_PID_HASHSIZE 3994=item EV_PID_HASHSIZE
3995 3995
3996C<ev_child> watchers use a small hash table to distribute workload by 3996C<ev_child> watchers use a small hash table to distribute workload by
… …
4651 4651
4652This is a simple rename - all other watcher types use their name 4652This is a simple rename - all other watcher types use their name
4653as revents flag, and now C<ev_timer> does, too. 4653as revents flag, and now C<ev_timer> does, too.
4654 4654
4655Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions 4655Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
4656and continue to be present for the forseeable future, so this is mostly a 4656and continue to be present for the foreseeable future, so this is mostly a
4657documentation change. 4657documentation change.
4658 4658
4659=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES> 4659=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4660 4660
4661The preprocessor symbol C<EV_MINIMAL> has been replaced by a different 4661The preprocessor symbol C<EV_MINIMAL> has been replaced by a different

Diff Legend

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