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.24 by root, Mon Nov 12 19:20:05 2007 UTC

… …
417in each iteration of the event loop (This behaviour is called 417in each iteration of the event loop (This behaviour is called
418level-triggering because you keep receiving events as long as the 418level-triggering because you keep receiving events as long as the
419condition persists. Remember you can stop the watcher if you don't want to 419condition persists. Remember you can stop the watcher if you don't want to
420act on the event and neither want to receive future events). 420act on the event and neither want to receive future events).
421 421
422In general you can register as many read and/or write event watchers oer 422In 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 423fd 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 424descriptors to non-blocking mode is also usually a good idea (but not
425required if you know what you are doing). 425required if you know what you are doing).
426 426
427You have to be careful with dup'ed file descriptors, though. Some backends 427You 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 428(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 429descriptors correctly if you register interest in two or more fds pointing
430to the same file/socket etc. description. 430to the same underlying file/socket etc. description (that is, they share
431the same underlying "file open").
431 432
432If you must do this, then force the use of a known-to-be-good backend 433If 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 434(at the time of this writing, this includes only EVMETHOD_SELECT and
434EVMETHOD_POLL). 435EVMETHOD_POLL).
435 436
… …
449 450
450Timer watchers are simple relative timers that generate an event after a 451Timer watchers are simple relative timers that generate an event after a
451given time, and optionally repeating in regular intervals after that. 452given time, and optionally repeating in regular intervals after that.
452 453
453The timers are based on real time, that is, if you register an event that 454The 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 455times 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 456time, it will still time out after (roughly) and hour. "Roughly" because
456detecting time jumps is hard, and soem inaccuracies are unavoidable (the 457detecting time jumps is hard, and soem inaccuracies are unavoidable (the
457monotonic clock option helps a lot here). 458monotonic clock option helps a lot here).
458 459
459The relative timeouts are calculated relative to the C<ev_now ()> 460The relative timeouts are calculated relative to the C<ev_now ()>
460time. This is usually the right thing as this timestamp refers to the time 461time. This is usually the right thing as this timestamp refers to the time
461of the event triggering whatever timeout you are modifying/starting. If 462of the event triggering whatever timeout you are modifying/starting. If
462you suspect event processing to be delayed and you *need* to base the timeout 463you 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: 464on the current time, use something like this to adjust for this:
464 465
465 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 466 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
466 467
467=over 4 468=over 4
468 469
… …
476later, again, and again, until stopped manually. 477later, again, and again, until stopped manually.
477 478
478The timer itself will do a best-effort at avoiding drift, that is, if you 479The 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 480configure a timer to trigger every 10 seconds, then it will trigger at
480exactly 10 second intervals. If, however, your program cannot keep up with 481exactly 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 482the timer (because it takes longer than those 10 seconds to do stuff) the
482timer will not fire more than once per event loop iteration. 483timer will not fire more than once per event loop iteration.
483 484
484=item ev_timer_again (loop) 485=item ev_timer_again (loop)
485 486
486This will act as if the timer timed out and restart it again if it is 487This 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) 726=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
726 727
727This function combines a simple timer and an I/O watcher, calls your 728This function combines a simple timer and an I/O watcher, calls your
728callback on whichever event happens first and automatically stop both 729callback 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 730watchers. 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 731or timeout without having to allocate/configure/start/stop/free one or
731more watchers yourself. 732more watchers yourself.
732 733
733If C<fd> is less than 0, then no I/O watcher will be started and events 734If 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 735is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
735C<events> set will be craeted and started. 736C<events> set will be craeted and started.
… …
771 772
772=back 773=back
773 774
774=head1 LIBEVENT EMULATION 775=head1 LIBEVENT EMULATION
775 776
777Libev offers a compatibility emulation layer for libevent. It cannot
778emulate the internals of libevent, so here are some usage hints:
779
780=over 4
781
782=item * Use it by including <event.h>, as usual.
783
784=item * The following members are fully supported: ev_base, ev_callback,
785ev_arg, ev_fd, ev_res, ev_events.
786
787=item * Avoid using ev_flags and the EVLIST_*-macros, while it is
788maintained by libev, it does not work exactly the same way as in libevent (consider
789it a private API).
790
791=item * Priorities are not currently supported. Initialising priorities
792will fail and all watchers will have the same priority, even though there
793is an ev_pri field.
794
795=item * Other members are not supported.
796
797=item * The libev emulation is I<not> ABI compatible to libevent, you need
798to use the libev header file and library.
799
800=back
801
802=head1 C++ SUPPORT
803
776TBD. 804TBD.
777 805
778=head1 C++ SUPPORT
779
780TBD.
781
782=head1 AUTHOR 806=head1 AUTHOR
783 807
784Marc Lehmann <libev@schmorp.de>. 808Marc Lehmann <libev@schmorp.de>.
785 809

Diff Legend

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