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

Comparing libev/ev.pod (file contents):
Revision 1.245 by root, Tue Jun 30 06:24:38 2009 UTC vs.
Revision 1.253 by root, Tue Jul 14 18:33:48 2009 UTC

… …
620happily wraps around with enough iterations. 620happily wraps around with enough iterations.
621 621
622This value can sometimes be useful as a generation counter of sorts (it 622This value can sometimes be useful as a generation counter of sorts (it
623"ticks" the number of loop iterations), as it roughly corresponds with 623"ticks" the number of loop iterations), as it roughly corresponds with
624C<ev_prepare> and C<ev_check> calls. 624C<ev_prepare> and C<ev_check> calls.
625
626=item unsigned int ev_loop_depth (loop)
627
628Returns the number of times C<ev_loop> was entered minus the number of
629times C<ev_loop> was exited, in other words, the recursion depth.
630
631Outside C<ev_loop>, this number is zero. In a callback, this number is
632C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
633in which case it is higher.
634
635Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
636etc.), doesn't count as exit.
625 637
626=item unsigned int ev_backend (loop) 638=item unsigned int ev_backend (loop)
627 639
628Returns one of the C<EVBACKEND_*> flags indicating the event backend in 640Returns one of the C<EVBACKEND_*> flags indicating the event backend in
629use. 641use.
… …
844more often than 100 times per second: 856more often than 100 times per second:
845 857
846 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1); 858 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
847 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01); 859 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
848 860
861=item ev_invoke_pending (loop)
862
863This call will simply invoke all pending watchers while resetting their
864pending state. Normally, C<ev_loop> does this automatically when required,
865but when overriding the invoke callback this call comes handy.
866
867=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
868
869This overrides the invoke pending functionality of the loop: Instead of
870invoking all pending watchers when there are any, C<ev_loop> will call
871this callback instead. This is useful, for example, when you want to
872invoke the actual watchers inside another context (another thread etc.).
873
874If you want to reset the callback, use C<ev_invoke_pending> as new
875callback.
876
877=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
878
879Sometimes you want to share the same loop between multiple threads. This
880can be done relatively simply by putting mutex_lock/unlock calls around
881each call to a libev function.
882
883However, C<ev_loop> can run an indefinite time, so it is not feasible to
884wait for it to return. One way around this is to wake up the loop via
885C<ev_unloop> and C<av_async_send>, another way is to set these I<release>
886and I<acquire> callbacks on the loop.
887
888When set, then C<release> will be called just before the thread is
889suspended waiting for new events, and C<acquire> is called just
890afterwards.
891
892Ideally, C<release> will just call your mutex_unlock function, and
893C<acquire> will just call the mutex_lock function again.
894
895=item ev_set_userdata (loop, void *data)
896
897=item ev_userdata (loop)
898
899Set and retrieve a single C<void *> associated with a loop. When
900C<ev_set_userdata> has never been called, then C<ev_userdata> returns
901C<0.>
902
903These two functions can be used to associate arbitrary data with a loop,
904and are intended solely for the C<invoke_pending_cb>, C<release> and
905C<acquire> callbacks described above, but of course can be (ab-)used for
906any other purpose as well.
907
849=item ev_loop_verify (loop) 908=item ev_loop_verify (loop)
850 909
851This function only does something when C<EV_VERIFY> support has been 910This function only does something when C<EV_VERIFY> support has been
852compiled in, which is the default for non-minimal builds. It tries to go 911compiled in, which is the default for non-minimal builds. It tries to go
853through all internal structures and checks them for validity. If anything 912through all internal structures and checks them for validity. If anything
… …
1480 1539
1481The callback is guaranteed to be invoked only I<after> its timeout has 1540The callback is guaranteed to be invoked only I<after> its timeout has
1482passed (not I<at>, so on systems with very low-resolution clocks this 1541passed (not I<at>, so on systems with very low-resolution clocks this
1483might introduce a small delay). If multiple timers become ready during the 1542might introduce a small delay). If multiple timers become ready during the
1484same loop iteration then the ones with earlier time-out values are invoked 1543same loop iteration then the ones with earlier time-out values are invoked
1485before ones with later time-out values (but this is no longer true when a 1544before ones of the same priority with later time-out values (but this is
1486callback calls C<ev_loop> recursively). 1545no longer true when a callback calls C<ev_loop> recursively).
1487 1546
1488=head3 Be smart about timeouts 1547=head3 Be smart about timeouts
1489 1548
1490Many real-world problems involve some kind of timeout, usually for error 1549Many real-world problems involve some kind of timeout, usually for error
1491recovery. A typical example is an HTTP request - if the other side hangs, 1550recovery. A typical example is an HTTP request - if the other side hangs,
… …
2019but forking and registering a watcher a few event loop iterations later or 2078but forking and registering a watcher a few event loop iterations later or
2020in the next callback invocation is not. 2079in the next callback invocation is not.
2021 2080
2022Only the default event loop is capable of handling signals, and therefore 2081Only the default event loop is capable of handling signals, and therefore
2023you can only register child watchers in the default event loop. 2082you can only register child watchers in the default event loop.
2083
2084Due to some design glitches inside libev, child watchers will always be
2085handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2086libev)
2024 2087
2025=head3 Process Interaction 2088=head3 Process Interaction
2026 2089
2027Libev grabs C<SIGCHLD> as soon as the default event loop is 2090Libev grabs C<SIGCHLD> as soon as the default event loop is
2028initialised. This is necessary to guarantee proper behaviour even if 2091initialised. This is necessary to guarantee proper behaviour even if
… …
3655defined to be C<0>, then they are not. 3718defined to be C<0>, then they are not.
3656 3719
3657=item EV_MINIMAL 3720=item EV_MINIMAL
3658 3721
3659If you need to shave off some kilobytes of code at the expense of some 3722If you need to shave off some kilobytes of code at the expense of some
3660speed, define this symbol to C<1>. Currently this is used to override some 3723speed (but with the full API), define this symbol to C<1>. Currently this
3661inlining decisions, saves roughly 30% code size on amd64. It also selects a 3724is used to override some inlining decisions, saves roughly 30% code size
3662much smaller 2-heap for timer management over the default 4-heap. 3725on amd64. It also selects a much smaller 2-heap for timer management over
3726the default 4-heap.
3727
3728You can save even more by disabling watcher types you do not need
3729and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>
3730(C<-DNDEBUG>) will usually reduce code size a lot.
3731
3732Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
3733provide a bare-bones event library. See C<ev.h> for details on what parts
3734of the API are still available, and do not complain if this subset changes
3735over time.
3663 3736
3664=item EV_PID_HASHSIZE 3737=item EV_PID_HASHSIZE
3665 3738
3666C<ev_child> watchers use a small hash table to distribute workload by 3739C<ev_child> watchers use a small hash table to distribute workload by
3667pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3740pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
… …
3853default loop and triggering an C<ev_async> watcher from the default loop 3926default loop and triggering an C<ev_async> watcher from the default loop
3854watcher callback into the event loop interested in the signal. 3927watcher callback into the event loop interested in the signal.
3855 3928
3856=back 3929=back
3857 3930
3931=head4 THREAD LOCKING EXAMPLE
3932
3858=head3 COROUTINES 3933=head3 COROUTINES
3859 3934
3860Libev is very accommodating to coroutines ("cooperative threads"): 3935Libev is very accommodating to coroutines ("cooperative threads"):
3861libev fully supports nesting calls to its functions from different 3936libev fully supports nesting calls to its functions from different
3862coroutines (e.g. you can call C<ev_loop> on the same loop from two 3937coroutines (e.g. you can call C<ev_loop> on the same loop from two
… …
4077=item C<double> must hold a time value in seconds with enough accuracy 4152=item C<double> must hold a time value in seconds with enough accuracy
4078 4153
4079The type C<double> is used to represent timestamps. It is required to 4154The type C<double> is used to represent timestamps. It is required to
4080have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4155have at least 51 bits of mantissa (and 9 bits of exponent), which is good
4081enough for at least into the year 4000. This requirement is fulfilled by 4156enough for at least into the year 4000. This requirement is fulfilled by
4082implementations implementing IEEE 754 (basically all existing ones). 4157implementations implementing IEEE 754, which is basically all existing
4158ones. With IEEE 754 doubles, you get microsecond accuracy until at least
41592200.
4083 4160
4084=back 4161=back
4085 4162
4086If you know of other additional requirements drop me a note. 4163If you know of other additional requirements drop me a note.
4087 4164

Diff Legend

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