--- libev/ev.pod 2009/04/25 14:12:48 1.240 +++ libev/ev.pod 2009/07/09 09:11:20 1.250 @@ -623,6 +623,18 @@ "ticks" the number of loop iterations), as it roughly corresponds with C and C calls. +=item unsigned int ev_loop_depth (loop) + +Returns the number of times C was entered minus the number of +times C was exited, in other words, the recursion depth. + +Outside C, this number is zero. In a callback, this number is +C<1>, unless C was invoked recursively (or from another thread), +in which case it is higher. + +Leaving C abnormally (setjmp/longjmp, cancelling the thread +etc.), doesn't count as exit. + =item unsigned int ev_backend (loop) Returns one of the C flags indicating the event backend in @@ -813,7 +825,9 @@ time collecting I/O events, so you can handle more events per iteration, at the cost of increasing latency. Timeouts (both C and C) will be not affected. Setting this to a non-null value will -introduce an additional C call into most loop iterations. +introduce an additional C call into most loop iterations. The +sleep time ensures that libev will not poll for I/O events more often then +once per this interval, on average. Likewise, by setting a higher I you allow libev to spend more time collecting timeouts, at the expense of increased @@ -825,7 +839,11 @@ interval to a value near C<0.1> or so, which is often enough for interactive servers (of course not for games), likewise for timeouts. It usually doesn't make much sense to set it to a lower value than C<0.01>, -as this approaches the timing granularity of most systems. +as this approaches the timing granularity of most systems. Note that if +you do transactions with the outside world and you can't increase the +parallelity, then this setting will limit your transaction rate (if you +need to poll once per transaction and the I/O collect interval is 0.01, +then you can't do more than 100 transations per second). Setting the I can improve the opportunity for saving power, as the program will "bundle" timer callback invocations that @@ -834,6 +852,12 @@ reduce iterations/wake-ups is to use C watchers and make sure they fire on, say, one-second boundaries only. +Example: we only need 0.1s timeout granularity, and we wish not to poll +more often than 100 times per second: + + ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1); + ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01); + =item ev_loop_verify (loop) This function only does something when C support has been @@ -1186,14 +1210,14 @@ static void t1_cb (EV_P_ ev_timer *w, int revents) { - struct my_biggy big = (struct my_biggy * + struct my_biggy big = (struct my_biggy *) (((char *)w) - offsetof (struct my_biggy, t1)); } static void t2_cb (EV_P_ ev_timer *w, int revents) { - struct my_biggy big = (struct my_biggy * + struct my_biggy big = (struct my_biggy *) (((char *)w) - offsetof (struct my_biggy, t2)); } @@ -1279,7 +1303,7 @@ } static void - idle-cb (EV_P_ ev_idle *w, int revents) + idle_cb (EV_P_ ev_idle *w, int revents) { // actual processing read (STDIN_FILENO, ...); @@ -1470,8 +1494,8 @@ passed (not I, so on systems with very low-resolution clocks this might introduce a small delay). If multiple timers become ready during the same loop iteration then the ones with earlier time-out values are invoked -before ones with later time-out values (but this is no longer true when a -callback calls C recursively). +before ones of the same priority with later time-out values (but this is +no longer true when a callback calls C recursively). =head3 Be smart about timeouts @@ -1525,7 +1549,7 @@ At start: - ev_timer_init (timer, callback); + ev_init (timer, callback); timer->repeat = 60.; ev_timer_again (loop, timer); @@ -1597,7 +1621,7 @@ to the current time (meaning we just have some activity :), then call the callback, which will "do the right thing" and start the timer: - ev_timer_init (timer, callback); + ev_init (timer, callback); last_activity = ev_now (loop); callback (loop, timer, EV_TIMEOUT); @@ -2004,12 +2028,16 @@ has been forked (which implies it might have already exited), as long as the event loop isn't entered (or is continued from a watcher), i.e., forking and then immediately registering a watcher for the child is fine, -but forking and registering a watcher a few event loop iterations later is -not. +but forking and registering a watcher a few event loop iterations later or +in the next callback invocation is not. Only the default event loop is capable of handling signals, and therefore you can only register child watchers in the default event loop. +Due to some design glitches inside libev, child watchers will always be +handled at maximum priority (their priority is set to C by +libev) + =head3 Process Interaction Libev grabs C as soon as the default event loop is @@ -2370,7 +2398,7 @@ ev_idle *idle_watcher = malloc (sizeof (ev_idle)); ev_idle_init (idle_watcher, idle_cb); - ev_idle_start (loop, idle_cb); + ev_idle_start (loop, idle_watcher); =head2 C and C - customise your event loop! @@ -2473,7 +2501,7 @@ adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); /* the callback is illegal, but won't be called as we stop during check */ - ev_timer_init (&tw, 0, timeout * 1e-3); + ev_timer_init (&tw, 0, timeout * 1e-3, 0.); ev_timer_start (loop, &tw); // create one ev_io per pollfd @@ -3645,9 +3673,13 @@ =item EV_MINIMAL If you need to shave off some kilobytes of code at the expense of some -speed, define this symbol to C<1>. Currently this is used to override some -inlining decisions, saves roughly 30% code size on amd64. It also selects a -much smaller 2-heap for timer management over the default 4-heap. +speed (but with the full API), define this symbol to C<1>. Currently this +is used to override some inlining decisions, saves roughly 30% code size +on amd64. It also selects a much smaller 2-heap for timer management over +the default 4-heap. + +You can save even more by disabling watcher types you do not need and +setting C == C. =item EV_PID_HASHSIZE @@ -3937,6 +3969,9 @@ There is no supported compilation method available on windows except embedding it into other applications. +Sensible signal handling is officially unsupported by Microsoft - libev +tries its best, but under most conditions, signals will simply not work. + Not a libev limitation but worth mentioning: windows apparently doesn't accept large writes: instead of resulting in a partial write, windows will either accept everything or return C if the buffer is too large, @@ -3950,7 +3985,7 @@ more than a hundred or so sockets, then likely it needs to use a totally different implementation for windows, as libev offers the POSIX readiness notification model, which cannot be implemented efficiently on windows -(Microsoft monopoly games). +(due to Microsoft monopoly games). A typical way to use libev under windows is to embed it (see the embedding section for details) and use the following F header file instead @@ -3996,24 +4031,22 @@ of C<64> handles (probably owning to the fact that all windows kernels can only wait for C<64> things at the same time internally; Microsoft recommends spawning a chain of threads and wait for 63 handles and the -previous thread in each. Great). +previous thread in each. Sounds great!). Newer versions support more handles, but you need to define C to some high number (e.g. C<2048>) before compiling the winsocket select -call (which might be in libev or elsewhere, for example, perl does its own -select emulation on windows). +call (which might be in libev or elsewhere, for example, perl and many +other interpreters do their own select emulation on windows). Another limit is the number of file descriptors in the Microsoft runtime -libraries, which by default is C<64> (there must be a hidden I<64> fetish -or something like this inside Microsoft). You can increase this by calling -C<_setmaxstdio>, which can increase this limit to C<2048> (another -arbitrary limit), but is broken in many versions of the Microsoft runtime -libraries. - -This might get you to about C<512> or C<2048> sockets (depending on -windows version and/or the phase of the moon). To get more, you need to -wrap all I/O functions and provide your own fd management, but the cost of -calling select (O(n²)) will likely make this unworkable. +libraries, which by default is C<64> (there must be a hidden I<64> +fetish or something like this inside Microsoft). You can increase this +by calling C<_setmaxstdio>, which can increase this limit to C<2048> +(another arbitrary limit), but is broken in many versions of the Microsoft +runtime libraries. This might get you to about C<512> or C<2048> sockets +(depending on windows version and/or the phase of the moon). To get more, +you need to wrap all I/O functions and provide your own fd management, but +the cost of calling select (O(n²)) will likely make this unworkable. =back @@ -4066,7 +4099,9 @@ The type C is used to represent timestamps. It is required to have at least 51 bits of mantissa (and 9 bits of exponent), which is good enough for at least into the year 4000. This requirement is fulfilled by -implementations implementing IEEE 754 (basically all existing ones). +implementations implementing IEEE 754, which is basically all existing +ones. With IEEE 754 doubles, you get microsecond accuracy until at least +2200. =back