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

Comparing libev/ev.pod (file contents):
Revision 1.21 by root, Mon Nov 12 09:07:10 2007 UTC vs.
Revision 1.27 by root, Wed Nov 14 05:02:07 2007 UTC

… …
56 56
57=over 4 57=over 4
58 58
59=item ev_tstamp ev_time () 59=item ev_tstamp ev_time ()
60 60
61Returns the current time as libev would use it. 61Returns the current time as libev would use it. Please note that the
62C<ev_now> function is usually faster and also often returns the timestamp
63you actually want to know.
62 64
63=item int ev_version_major () 65=item int ev_version_major ()
64 66
65=item int ev_version_minor () 67=item int ev_version_minor ()
66 68
… …
237 239
238This flags value could be used to implement alternative looping 240This flags value could be used to implement alternative looping
239constructs, but the C<prepare> and C<check> watchers provide a better and 241constructs, but the C<prepare> and C<check> watchers provide a better and
240more generic mechanism. 242more generic mechanism.
241 243
244Here are the gory details of what ev_loop does:
245
246 1. If there are no active watchers (reference count is zero), return.
247 2. Queue and immediately call all prepare watchers.
248 3. If we have been forked, recreate the kernel state.
249 4. Update the kernel state with all outstanding changes.
250 5. Update the "event loop time".
251 6. Calculate for how long to block.
252 7. Block the process, waiting for events.
253 8. Update the "event loop time" and do time jump handling.
254 9. Queue all outstanding timers.
255 10. Queue all outstanding periodics.
256 11. If no events are pending now, queue all idle watchers.
257 12. Queue all check watchers.
258 13. Call all queued watchers in reverse order (i.e. check watchers first).
259 14. If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
260 was used, return, otherwise continue with step #1.
261
242=item ev_unloop (loop, how) 262=item ev_unloop (loop, how)
243 263
244Can be used to make a call to C<ev_loop> return early (but only after it 264Can be used to make a call to C<ev_loop> return early (but only after it
245has processed all outstanding events). The C<how> argument must be either 265has processed all outstanding events). The C<how> argument must be either
246C<EVUNLOOP_ONCE>, which will make the innermost C<ev_loop> call return, or 266C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
247C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 267C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
248 268
249=item ev_ref (loop) 269=item ev_ref (loop)
250 270
251=item ev_unref (loop) 271=item ev_unref (loop)
… …
417in each iteration of the event loop (This behaviour is called 437in each iteration of the event loop (This behaviour is called
418level-triggering because you keep receiving events as long as the 438level-triggering because you keep receiving events as long as the
419condition persists. Remember you can stop the watcher if you don't want to 439condition persists. Remember you can stop the watcher if you don't want to
420act on the event and neither want to receive future events). 440act on the event and neither want to receive future events).
421 441
422In general you can register as many read and/or write event watchers oer 442In general you can register as many read and/or write event watchers per
423fd as you want (as long as you don't confuse yourself). Setting all file 443fd as you want (as long as you don't confuse yourself). Setting all file
424descriptors to non-blocking mode is also usually a good idea (but not 444descriptors to non-blocking mode is also usually a good idea (but not
425required if you know what you are doing). 445required if you know what you are doing).
426 446
427You have to be careful with dup'ed file descriptors, though. Some backends 447You have to be careful with dup'ed file descriptors, though. Some backends
428(the linux epoll backend is a notable example) cannot handle dup'ed file 448(the linux epoll backend is a notable example) cannot handle dup'ed file
429descriptors correctly if you register interest in two or more fds pointing 449descriptors correctly if you register interest in two or more fds pointing
430to the same file/socket etc. description. 450to the same underlying file/socket etc. description (that is, they share
451the same underlying "file open").
431 452
432If you must do this, then force the use of a known-to-be-good backend 453If you must do this, then force the use of a known-to-be-good backend
433(at the time of this writing, this includes only EVMETHOD_SELECT and 454(at the time of this writing, this includes only EVMETHOD_SELECT and
434EVMETHOD_POLL). 455EVMETHOD_POLL).
435 456
… …
449 470
450Timer watchers are simple relative timers that generate an event after a 471Timer watchers are simple relative timers that generate an event after a
451given time, and optionally repeating in regular intervals after that. 472given time, and optionally repeating in regular intervals after that.
452 473
453The timers are based on real time, that is, if you register an event that 474The timers are based on real time, that is, if you register an event that
454times out after an hour and youreset your system clock to last years 475times out after an hour and you reset your system clock to last years
455time, it will still time out after (roughly) and hour. "Roughly" because 476time, it will still time out after (roughly) and hour. "Roughly" because
456detecting time jumps is hard, and soem inaccuracies are unavoidable (the 477detecting time jumps is hard, and soem inaccuracies are unavoidable (the
457monotonic clock option helps a lot here). 478monotonic clock option helps a lot here).
458 479
459The relative timeouts are calculated relative to the C<ev_now ()> 480The relative timeouts are calculated relative to the C<ev_now ()>
460time. This is usually the right thing as this timestamp refers to the time 481time. This is usually the right thing as this timestamp refers to the time
461of the event triggering whatever timeout you are modifying/starting. If 482of the event triggering whatever timeout you are modifying/starting. If
462you suspect event processing to be delayed and you *need* to base the timeout 483you suspect event processing to be delayed and you *need* to base the timeout
463ion the current time, use something like this to adjust for this: 484on the current time, use something like this to adjust for this:
464 485
465 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 486 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
466 487
467=over 4 488=over 4
468 489
… …
476later, again, and again, until stopped manually. 497later, again, and again, until stopped manually.
477 498
478The timer itself will do a best-effort at avoiding drift, that is, if you 499The timer itself will do a best-effort at avoiding drift, that is, if you
479configure a timer to trigger every 10 seconds, then it will trigger at 500configure a timer to trigger every 10 seconds, then it will trigger at
480exactly 10 second intervals. If, however, your program cannot keep up with 501exactly 10 second intervals. If, however, your program cannot keep up with
481the timer (ecause it takes longer than those 10 seconds to do stuff) the 502the timer (because it takes longer than those 10 seconds to do stuff) the
482timer will not fire more than once per event loop iteration. 503timer will not fire more than once per event loop iteration.
483 504
484=item ev_timer_again (loop) 505=item ev_timer_again (loop)
485 506
486This will act as if the timer timed out and restart it again if it is 507This will act as if the timer timed out and restart it again if it is
… …
725=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 746=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
726 747
727This function combines a simple timer and an I/O watcher, calls your 748This function combines a simple timer and an I/O watcher, calls your
728callback on whichever event happens first and automatically stop both 749callback on whichever event happens first and automatically stop both
729watchers. This is useful if you want to wait for a single event on an fd 750watchers. This is useful if you want to wait for a single event on an fd
730or timeout without havign to allocate/configure/start/stop/free one or 751or timeout without having to allocate/configure/start/stop/free one or
731more watchers yourself. 752more watchers yourself.
732 753
733If C<fd> is less than 0, then no I/O watcher will be started and events 754If C<fd> is less than 0, then no I/O watcher will be started and events
734is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and 755is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
735C<events> set will be craeted and started. 756C<events> set will be craeted and started.
… …
771 792
772=back 793=back
773 794
774=head1 LIBEVENT EMULATION 795=head1 LIBEVENT EMULATION
775 796
797Libev offers a compatibility emulation layer for libevent. It cannot
798emulate the internals of libevent, so here are some usage hints:
799
800=over 4
801
802=item * Use it by including <event.h>, as usual.
803
804=item * The following members are fully supported: ev_base, ev_callback,
805ev_arg, ev_fd, ev_res, ev_events.
806
807=item * Avoid using ev_flags and the EVLIST_*-macros, while it is
808maintained by libev, it does not work exactly the same way as in libevent (consider
809it a private API).
810
811=item * Priorities are not currently supported. Initialising priorities
812will fail and all watchers will have the same priority, even though there
813is an ev_pri field.
814
815=item * Other members are not supported.
816
817=item * The libev emulation is I<not> ABI compatible to libevent, you need
818to use the libev header file and library.
819
820=back
821
822=head1 C++ SUPPORT
823
776TBD. 824TBD.
777 825
778=head1 C++ SUPPORT
779
780TBD.
781
782=head1 AUTHOR 826=head1 AUTHOR
783 827
784Marc Lehmann <libev@schmorp.de>. 828Marc Lehmann <libev@schmorp.de>.
785 829

Diff Legend

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