--- libev/ev.pod 2007/11/12 09:06:09 1.20 +++ libev/ev.pod 2007/11/22 12:28:28 1.29 @@ -58,7 +58,9 @@ =item ev_tstamp ev_time () -Returns the current time as libev would use it. +Returns the current time as libev would use it. Please note that the +C function is usually faster and also often returns the timestamp +you actually want to know. =item int ev_version_major () @@ -145,24 +147,70 @@ useful to try out specific backends to test their performance, or to work around bugs. -=item C (portable select backend) +=item C (value 1, portable select backend) -=item C (poll backend, available everywhere except on windows) +This is your standard select(2) backend. Not I standard, as +libev tries to roll its own fd_set with no limits on the number of fds, +but if that fails, expect a fairly low limit on the number of fds when +using this backend. It doesn't scale too well (O(highest_fd)), but its usually +the fastest backend for a low number of fds. -=item C (linux only) +=item C (value 2, poll backend, available everywhere except on windows) -=item C (some bsds only) +And this is your standard poll(2) backend. It's more complicated than +select, but handles sparse fds better and has no artificial limit on the +number of fds you can use (except it will slow down considerably with a +lot of inactive fds). It scales similarly to select, i.e. O(total_fds). -=item C (solaris 8 only) +=item C (value 4, Linux) -=item C (solaris 10 only) +For few fds, this backend is a bit little slower than poll and select, +but it scales phenomenally better. While poll and select usually scale like +O(total_fds) where n is the total number of fds (or the highest fd), epoll scales +either O(1) or O(active_fds). -If one or more of these are ored into the flags value, then only these -backends will be tried (in the reverse order as given here). If one are -specified, any backend will do. +While stopping and starting an I/O watcher in the same iteration will +result in some caching, there is still a syscall per such incident +(because the fd could point to a different file description now), so its +best to avoid that. Also, dup()ed file descriptors might not work very +well if you register events for both fds. + +=item C (value 8, most BSD clones) + +Kqueue deserves special mention, as at the time of this writing, it +was broken on all BSDs except NetBSD (usually it doesn't work with +anything but sockets and pipes, except on Darwin, where of course its +completely useless). For this reason its not being "autodetected" unless +you explicitly specify the flags (i.e. you don't use EVFLAG_AUTO). + +It scales in the same way as the epoll backend, but the interface to the +kernel is more efficient (which says nothing about its actual speed, of +course). While starting and stopping an I/O watcher does not cause an +extra syscall as with epoll, it still adds up to four event changes per +incident, so its best to avoid that. + +=item C (value 16, Solaris 8) + +This is not implemented yet (and might never be). + +=item C (value 32, Solaris 10) + +This uses the Solaris 10 port mechanism. As with everything on Solaris, +it's really slow, but it still scales very well (O(active_fds)). + +=item C + +Try all backends (even potentially broken ones that wouldn't be tried +with C). Since this is a mask, you can do stuff such as +C. =back +If one or more of these are ored into the flags value, then only these +backends will be tried (in the reverse order as given here). If none are +specified, most compiled-in backend will be tried, usually in reverse +order of their flag values :) + =item struct ev_loop *ev_loop_new (unsigned int flags) Similar to C, but always creates a new event loop that is @@ -239,11 +287,29 @@ constructs, but the C and C watchers provide a better and more generic mechanism. +Here are the gory details of what ev_loop does: + + 1. If there are no active watchers (reference count is zero), return. + 2. Queue and immediately call all prepare watchers. + 3. If we have been forked, recreate the kernel state. + 4. Update the kernel state with all outstanding changes. + 5. Update the "event loop time". + 6. Calculate for how long to block. + 7. Block the process, waiting for events. + 8. Update the "event loop time" and do time jump handling. + 9. Queue all outstanding timers. + 10. Queue all outstanding periodics. + 11. If no events are pending now, queue all idle watchers. + 12. Queue all check watchers. + 13. Call all queued watchers in reverse order (i.e. check watchers first). + 14. If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK + was used, return, otherwise continue with step #1. + =item ev_unloop (loop, how) Can be used to make a call to C return early (but only after it has processed all outstanding events). The C argument must be either -C, which will make the innermost C call return, or +C, which will make the innermost C call return, or C, which will make all nested C calls return. =item ev_ref (loop) @@ -419,7 +485,7 @@ condition persists. Remember you can stop the watcher if you don't want to act on the event and neither want to receive future events). -In general you can register as many read and/or write event watchers oer +In general you can register as many read and/or write event watchers per fd as you want (as long as you don't confuse yourself). Setting all file descriptors to non-blocking mode is also usually a good idea (but not required if you know what you are doing). @@ -427,7 +493,8 @@ You have to be careful with dup'ed file descriptors, though. Some backends (the linux epoll backend is a notable example) cannot handle dup'ed file descriptors correctly if you register interest in two or more fds pointing -to the same file/socket etc. description. +to the same underlying file/socket etc. description (that is, they share +the same underlying "file open"). If you must do this, then force the use of a known-to-be-good backend (at the time of this writing, this includes only EVMETHOD_SELECT and @@ -451,19 +518,23 @@ given time, and optionally repeating in regular intervals after that. The timers are based on real time, that is, if you register an event that -times out after an hour and youreset your system clock to last years +times out after an hour and you reset your system clock to last years time, it will still time out after (roughly) and hour. "Roughly" because -detecting time jumps is hard, and soem inaccuracies are unavoidable (the +detecting time jumps is hard, and some inaccuracies are unavoidable (the monotonic clock option helps a lot here). The relative timeouts are calculated relative to the C time. This is usually the right thing as this timestamp refers to the time -of the event triggering whatever timeout you are modifying/starting. If -you suspect event processing to be delayed and you *need* to base the timeout -ion the current time, use something like this to adjust for this: +of the event triggering whatever timeout you are modifying/starting. If +you suspect event processing to be delayed and you I to base the timeout +on the current time, use something like this to adjust for this: ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); +The callback is guarenteed to be invoked only when its timeout has passed, +but if multiple timers become ready during the same loop iteration then +order of execution is undefined. + =over 4 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) @@ -478,7 +549,7 @@ The timer itself will do a best-effort at avoiding drift, that is, if you configure a timer to trigger every 10 seconds, then it will trigger at exactly 10 second intervals. If, however, your program cannot keep up with -the timer (ecause it takes longer than those 10 seconds to do stuff) the +the timer (because it takes longer than those 10 seconds to do stuff) the timer will not fire more than once per event loop iteration. =item ev_timer_again (loop) @@ -519,6 +590,10 @@ They can also be used to implement vastly more complex timers, such as triggering an event on eahc midnight, local time. +As with timers, the callback is guarenteed to be invoked only when the +time (C) has been passed, but if multiple periodic timers become ready +during the same loop iteration then order of execution is undefined. + =over 4 =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) @@ -528,7 +603,6 @@ Lots of arguments, lets sort it out... There are basically three modes of operation, and we will explain them from simplest to complex: - =over 4 =item * absolute timer (interval = reschedule_cb = 0) @@ -727,7 +801,7 @@ This function combines a simple timer and an I/O watcher, calls your callback on whichever event happens first and automatically stop both watchers. This is useful if you want to wait for a single event on an fd -or timeout without havign to allocate/configure/start/stop/free one or +or timeout without having to allocate/configure/start/stop/free one or more watchers yourself. If C is less than 0, then no I/O watcher will be started and events @@ -740,7 +814,7 @@ dubious value. The callback has the type C and gets -passed an events set like normal event callbacks (with a combination of +passed an C set like normal event callbacks (a combination of C, C, C or C) and the C value passed to C: @@ -773,7 +847,30 @@ =head1 LIBEVENT EMULATION -TBD. +Libev offers a compatibility emulation layer for libevent. It cannot +emulate the internals of libevent, so here are some usage hints: + +=over 4 + +=item * Use it by including , as usual. + +=item * The following members are fully supported: ev_base, ev_callback, +ev_arg, ev_fd, ev_res, ev_events. + +=item * Avoid using ev_flags and the EVLIST_*-macros, while it is +maintained by libev, it does not work exactly the same way as in libevent (consider +it a private API). + +=item * Priorities are not currently supported. Initialising priorities +will fail and all watchers will have the same priority, even though there +is an ev_pri field. + +=item * Other members are not supported. + +=item * The libev emulation is I ABI compatible to libevent, you need +to use the libev header file and library. + +=back =head1 C++ SUPPORT