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

Comparing libev/ev.pod (file contents):
Revision 1.176 by root, Mon Sep 8 17:24:39 2008 UTC vs.
Revision 1.255 by root, Tue Jul 14 19:11:31 2009 UTC

9=head2 EXAMPLE PROGRAM 9=head2 EXAMPLE PROGRAM
10 10
11 // a single header file is required 11 // a single header file is required
12 #include <ev.h> 12 #include <ev.h>
13 13
14 #include <stdio.h> // for puts
15
14 // every watcher type has its own typedef'd struct 16 // every watcher type has its own typedef'd struct
15 // with the name ev_<type> 17 // with the name ev_TYPE
16 ev_io stdin_watcher; 18 ev_io stdin_watcher;
17 ev_timer timeout_watcher; 19 ev_timer timeout_watcher;
18 20
19 // all watcher callbacks have a similar signature 21 // all watcher callbacks have a similar signature
20 // this callback is called when data is readable on stdin 22 // this callback is called when data is readable on stdin
21 static void 23 static void
22 stdin_cb (EV_P_ struct ev_io *w, int revents) 24 stdin_cb (EV_P_ ev_io *w, int revents)
23 { 25 {
24 puts ("stdin ready"); 26 puts ("stdin ready");
25 // for one-shot events, one must manually stop the watcher 27 // for one-shot events, one must manually stop the watcher
26 // with its corresponding stop function. 28 // with its corresponding stop function.
27 ev_io_stop (EV_A_ w); 29 ev_io_stop (EV_A_ w);
30 ev_unloop (EV_A_ EVUNLOOP_ALL); 32 ev_unloop (EV_A_ EVUNLOOP_ALL);
31 } 33 }
32 34
33 // another callback, this time for a time-out 35 // another callback, this time for a time-out
34 static void 36 static void
35 timeout_cb (EV_P_ struct ev_timer *w, int revents) 37 timeout_cb (EV_P_ ev_timer *w, int revents)
36 { 38 {
37 puts ("timeout"); 39 puts ("timeout");
38 // this causes the innermost ev_loop to stop iterating 40 // this causes the innermost ev_loop to stop iterating
39 ev_unloop (EV_A_ EVUNLOOP_ONE); 41 ev_unloop (EV_A_ EVUNLOOP_ONE);
40 } 42 }
60 62
61 // unloop was called, so exit 63 // unloop was called, so exit
62 return 0; 64 return 0;
63 } 65 }
64 66
65=head1 DESCRIPTION 67=head1 ABOUT THIS DOCUMENT
68
69This document documents the libev software package.
66 70
67The newest version of this document is also available as an html-formatted 71The newest version of this document is also available as an html-formatted
68web page you might find easier to navigate when reading it for the first 72web page you might find easier to navigate when reading it for the first
69time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. 73time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
74
75While this document tries to be as complete as possible in documenting
76libev, its usage and the rationale behind its design, it is not a tutorial
77on event-based programming, nor will it introduce event-based programming
78with libev.
79
80Familarity with event based programming techniques in general is assumed
81throughout this document.
82
83=head1 ABOUT LIBEV
70 84
71Libev is an event loop: you register interest in certain events (such as a 85Libev is an event loop: you register interest in certain events (such as a
72file descriptor being readable or a timeout occurring), and it will manage 86file descriptor being readable or a timeout occurring), and it will manage
73these event sources and provide your program with events. 87these event sources and provide your program with events.
74 88
103Libev is very configurable. In this manual the default (and most common) 117Libev is very configurable. In this manual the default (and most common)
104configuration will be described, which supports multiple event loops. For 118configuration will be described, which supports multiple event loops. For
105more info about various configuration options please have a look at 119more info about various configuration options please have a look at
106B<EMBED> section in this manual. If libev was configured without support 120B<EMBED> section in this manual. If libev was configured without support
107for multiple event loops, then all functions taking an initial argument of 121for multiple event loops, then all functions taking an initial argument of
108name C<loop> (which is always of type C<struct ev_loop *>) will not have 122name C<loop> (which is always of type C<ev_loop *>) will not have
109this argument. 123this argument.
110 124
111=head2 TIME REPRESENTATION 125=head2 TIME REPRESENTATION
112 126
113Libev represents time as a single floating point number, representing the 127Libev represents time as a single floating point number, representing
114(fractional) number of seconds since the (POSIX) epoch (somewhere near 128the (fractional) number of seconds since the (POSIX) epoch (somewhere
115the beginning of 1970, details are complicated, don't ask). This type is 129near the beginning of 1970, details are complicated, don't ask). This
116called C<ev_tstamp>, which is what you should use too. It usually aliases 130type is called C<ev_tstamp>, which is what you should use too. It usually
117to the C<double> type in C, and when you need to do any calculations on 131aliases to the C<double> type in C. When you need to do any calculations
118it, you should treat it as some floating point value. Unlike the name 132on it, you should treat it as some floating point value. Unlike the name
119component C<stamp> might indicate, it is also used for time differences 133component C<stamp> might indicate, it is also used for time differences
120throughout libev. 134throughout libev.
121 135
122=head1 ERROR HANDLING 136=head1 ERROR HANDLING
123 137
214C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 228C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
215recommended ones. 229recommended ones.
216 230
217See the description of C<ev_embed> watchers for more info. 231See the description of C<ev_embed> watchers for more info.
218 232
219=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 233=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
220 234
221Sets the allocation function to use (the prototype is similar - the 235Sets the allocation function to use (the prototype is similar - the
222semantics are identical to the C<realloc> C89/SuS/POSIX function). It is 236semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
223used to allocate and free memory (no surprises here). If it returns zero 237used to allocate and free memory (no surprises here). If it returns zero
224when memory needs to be allocated (C<size != 0>), the library might abort 238when memory needs to be allocated (C<size != 0>), the library might abort
250 } 264 }
251 265
252 ... 266 ...
253 ev_set_allocator (persistent_realloc); 267 ev_set_allocator (persistent_realloc);
254 268
255=item ev_set_syserr_cb (void (*cb)(const char *msg)); 269=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
256 270
257Set the callback function to call on a retryable system call error (such 271Set the callback function to call on a retryable system call error (such
258as failed select, poll, epoll_wait). The message is a printable string 272as failed select, poll, epoll_wait). The message is a printable string
259indicating the system call or subsystem causing the problem. If this 273indicating the system call or subsystem causing the problem. If this
260callback is set, then libev will expect it to remedy the situation, no 274callback is set, then libev will expect it to remedy the situation, no
276 290
277=back 291=back
278 292
279=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 293=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
280 294
281An event loop is described by a C<struct ev_loop *>. The library knows two 295An event loop is described by a C<struct ev_loop *> (the C<struct>
282types of such loops, the I<default> loop, which supports signals and child 296is I<not> optional in this case, as there is also an C<ev_loop>
283events, and dynamically created loops which do not. 297I<function>).
298
299The library knows two types of such loops, the I<default> loop, which
300supports signals and child events, and dynamically created loops which do
301not.
284 302
285=over 4 303=over 4
286 304
287=item struct ev_loop *ev_default_loop (unsigned int flags) 305=item struct ev_loop *ev_default_loop (unsigned int flags)
288 306
294If you don't know what event loop to use, use the one returned from this 312If you don't know what event loop to use, use the one returned from this
295function. 313function.
296 314
297Note that this function is I<not> thread-safe, so if you want to use it 315Note that this function is I<not> thread-safe, so if you want to use it
298from multiple threads, you have to lock (note also that this is unlikely, 316from multiple threads, you have to lock (note also that this is unlikely,
299as loops cannot bes hared easily between threads anyway). 317as loops cannot be shared easily between threads anyway).
300 318
301The default loop is the only loop that can handle C<ev_signal> and 319The default loop is the only loop that can handle C<ev_signal> and
302C<ev_child> watchers, and to do this, it always registers a handler 320C<ev_child> watchers, and to do this, it always registers a handler
303for C<SIGCHLD>. If this is a problem for your application you can either 321for C<SIGCHLD>. If this is a problem for your application you can either
304create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 322create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
359writing a server, you should C<accept ()> in a loop to accept as many 377writing a server, you should C<accept ()> in a loop to accept as many
360connections as possible during one iteration. You might also want to have 378connections as possible during one iteration. You might also want to have
361a look at C<ev_set_io_collect_interval ()> to increase the amount of 379a look at C<ev_set_io_collect_interval ()> to increase the amount of
362readiness notifications you get per iteration. 380readiness notifications you get per iteration.
363 381
382This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the
383C<writefds> set (and to work around Microsoft Windows bugs, also onto the
384C<exceptfds> set on that platform).
385
364=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) 386=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
365 387
366And this is your standard poll(2) backend. It's more complicated 388And this is your standard poll(2) backend. It's more complicated
367than select, but handles sparse fds better and has no artificial 389than select, but handles sparse fds better and has no artificial
368limit on the number of fds you can use (except it will slow down 390limit on the number of fds you can use (except it will slow down
369considerably with a lot of inactive fds). It scales similarly to select, 391considerably with a lot of inactive fds). It scales similarly to select,
370i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for 392i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
371performance tips. 393performance tips.
372 394
395This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
396C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
397
373=item C<EVBACKEND_EPOLL> (value 4, Linux) 398=item C<EVBACKEND_EPOLL> (value 4, Linux)
374 399
375For few fds, this backend is a bit little slower than poll and select, 400For few fds, this backend is a bit little slower than poll and select,
376but it scales phenomenally better. While poll and select usually scale 401but it scales phenomenally better. While poll and select usually scale
377like O(total_fds) where n is the total number of fds (or the highest fd), 402like O(total_fds) where n is the total number of fds (or the highest fd),
378epoll scales either O(1) or O(active_fds). The epoll design has a number 403epoll scales either O(1) or O(active_fds).
379of shortcomings, such as silently dropping events in some hard-to-detect 404
380cases and requiring a system call per fd change, no fork support and bad 405The epoll mechanism deserves honorable mention as the most misdesigned
381support for dup. 406of the more advanced event mechanisms: mere annoyances include silently
407dropping file descriptors, requiring a system call per change per file
408descriptor (and unnecessary guessing of parameters), problems with dup and
409so on. The biggest issue is fork races, however - if a program forks then
410I<both> parent and child process have to recreate the epoll set, which can
411take considerable time (one syscall per file descriptor) and is of course
412hard to detect.
413
414Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
415of course I<doesn't>, and epoll just loves to report events for totally
416I<different> file descriptors (even already closed ones, so one cannot
417even remove them from the set) than registered in the set (especially
418on SMP systems). Libev tries to counter these spurious notifications by
419employing an additional generation counter and comparing that against the
420events to filter out spurious ones, recreating the set when required.
382 421
383While stopping, setting and starting an I/O watcher in the same iteration 422While stopping, setting and starting an I/O watcher in the same iteration
384will result in some caching, there is still a system call per such incident 423will result in some caching, there is still a system call per such
385(because the fd could point to a different file description now), so its 424incident (because the same I<file descriptor> could point to a different
386best to avoid that. Also, C<dup ()>'ed file descriptors might not work 425I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
387very well if you register events for both fds. 426file descriptors might not work very well if you register events for both
388 427file descriptors.
389Please note that epoll sometimes generates spurious notifications, so you
390need to use non-blocking I/O or other means to avoid blocking when no data
391(or space) is available.
392 428
393Best performance from this backend is achieved by not unregistering all 429Best performance from this backend is achieved by not unregistering all
394watchers for a file descriptor until it has been closed, if possible, i.e. 430watchers for a file descriptor until it has been closed, if possible,
395keep at least one watcher active per fd at all times. 431i.e. keep at least one watcher active per fd at all times. Stopping and
432starting a watcher (without re-setting it) also usually doesn't cause
433extra overhead. A fork can both result in spurious notifications as well
434as in libev having to destroy and recreate the epoll object, which can
435take considerable time and thus should be avoided.
436
437All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
438faster than epoll for maybe up to a hundred file descriptors, depending on
439the usage. So sad.
396 440
397While nominally embeddable in other event loops, this feature is broken in 441While nominally embeddable in other event loops, this feature is broken in
398all kernel versions tested so far. 442all kernel versions tested so far.
443
444This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
445C<EVBACKEND_POLL>.
399 446
400=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 447=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
401 448
402Kqueue deserves special mention, as at the time of this writing, it 449Kqueue deserves special mention, as at the time of this writing, it
403was broken on all BSDs except NetBSD (usually it doesn't work reliably 450was broken on all BSDs except NetBSD (usually it doesn't work reliably
404with anything but sockets and pipes, except on Darwin, where of course 451with anything but sockets and pipes, except on Darwin, where of course
405it's completely useless). For this reason it's not being "auto-detected" 452it's completely useless). Unlike epoll, however, whose brokenness
453is by design, these kqueue bugs can (and eventually will) be fixed
454without API changes to existing programs. For this reason it's not being
406unless you explicitly specify it explicitly in the flags (i.e. using 455"auto-detected" unless you explicitly specify it in the flags (i.e. using
407C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 456C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
408system like NetBSD. 457system like NetBSD.
409 458
410You still can embed kqueue into a normal poll or select backend and use it 459You still can embed kqueue into a normal poll or select backend and use it
411only for sockets (after having made sure that sockets work with kqueue on 460only for sockets (after having made sure that sockets work with kqueue on
413 462
414It scales in the same way as the epoll backend, but the interface to the 463It scales in the same way as the epoll backend, but the interface to the
415kernel is more efficient (which says nothing about its actual speed, of 464kernel is more efficient (which says nothing about its actual speed, of
416course). While stopping, setting and starting an I/O watcher does never 465course). While stopping, setting and starting an I/O watcher does never
417cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 466cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
418two event changes per incident, support for C<fork ()> is very bad and it 467two event changes per incident. Support for C<fork ()> is very bad (but
419drops fds silently in similarly hard-to-detect cases. 468sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
469cases
420 470
421This backend usually performs well under most conditions. 471This backend usually performs well under most conditions.
422 472
423While nominally embeddable in other event loops, this doesn't work 473While nominally embeddable in other event loops, this doesn't work
424everywhere, so you might need to test for this. And since it is broken 474everywhere, so you might need to test for this. And since it is broken
425almost everywhere, you should only use it when you have a lot of sockets 475almost everywhere, you should only use it when you have a lot of sockets
426(for which it usually works), by embedding it into another event loop 476(for which it usually works), by embedding it into another event loop
427(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for 477(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
428sockets. 478also broken on OS X)) and, did I mention it, using it only for sockets.
479
480This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
481C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
482C<NOTE_EOF>.
429 483
430=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 484=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
431 485
432This is not implemented yet (and might never be, unless you send me an 486This is not implemented yet (and might never be, unless you send me an
433implementation). According to reports, C</dev/poll> only supports sockets 487implementation). According to reports, C</dev/poll> only supports sockets
446While this backend scales well, it requires one system call per active 500While this backend scales well, it requires one system call per active
447file descriptor per loop iteration. For small and medium numbers of file 501file descriptor per loop iteration. For small and medium numbers of file
448descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 502descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
449might perform better. 503might perform better.
450 504
451On the positive side, ignoring the spurious readiness notifications, this 505On the positive side, with the exception of the spurious readiness
452backend actually performed to specification in all tests and is fully 506notifications, this backend actually performed fully to specification
453embeddable, which is a rare feat among the OS-specific backends. 507in all tests and is fully embeddable, which is a rare feat among the
508OS-specific backends (I vastly prefer correctness over speed hacks).
509
510This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
511C<EVBACKEND_POLL>.
454 512
455=item C<EVBACKEND_ALL> 513=item C<EVBACKEND_ALL>
456 514
457Try all backends (even potentially broken ones that wouldn't be tried 515Try all backends (even potentially broken ones that wouldn't be tried
458with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 516with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
464 522
465If one or more of these are or'ed into the flags value, then only these 523If one or more of these are or'ed into the flags value, then only these
466backends will be tried (in the reverse order as listed here). If none are 524backends will be tried (in the reverse order as listed here). If none are
467specified, all backends in C<ev_recommended_backends ()> will be tried. 525specified, all backends in C<ev_recommended_backends ()> will be tried.
468 526
469The most typical usage is like this: 527Example: This is the most typical usage.
470 528
471 if (!ev_default_loop (0)) 529 if (!ev_default_loop (0))
472 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 530 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
473 531
474Restrict libev to the select and poll backends, and do not allow 532Example: Restrict libev to the select and poll backends, and do not allow
475environment settings to be taken into account: 533environment settings to be taken into account:
476 534
477 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); 535 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
478 536
479Use whatever libev has to offer, but make sure that kqueue is used if 537Example: Use whatever libev has to offer, but make sure that kqueue is
480available (warning, breaks stuff, best use only with your own private 538used if available (warning, breaks stuff, best use only with your own
481event loop and only if you know the OS supports your types of fds): 539private event loop and only if you know the OS supports your types of
540fds):
482 541
483 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 542 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
484 543
485=item struct ev_loop *ev_loop_new (unsigned int flags) 544=item struct ev_loop *ev_loop_new (unsigned int flags)
486 545
507responsibility to either stop all watchers cleanly yourself I<before> 566responsibility to either stop all watchers cleanly yourself I<before>
508calling this function, or cope with the fact afterwards (which is usually 567calling this function, or cope with the fact afterwards (which is usually
509the easiest thing, you can just ignore the watchers and/or C<free ()> them 568the easiest thing, you can just ignore the watchers and/or C<free ()> them
510for example). 569for example).
511 570
512Note that certain global state, such as signal state, will not be freed by 571Note that certain global state, such as signal state (and installed signal
513this function, and related watchers (such as signal and child watchers) 572handlers), will not be freed by this function, and related watchers (such
514would need to be stopped manually. 573as signal and child watchers) would need to be stopped manually.
515 574
516In general it is not advisable to call this function except in the 575In general it is not advisable to call this function except in the
517rare occasion where you really need to free e.g. the signal handling 576rare occasion where you really need to free e.g. the signal handling
518pipe fds. If you need dynamically allocated loops it is better to use 577pipe fds. If you need dynamically allocated loops it is better to use
519C<ev_loop_new> and C<ev_loop_destroy>). 578C<ev_loop_new> and C<ev_loop_destroy>).
544 603
545=item ev_loop_fork (loop) 604=item ev_loop_fork (loop)
546 605
547Like C<ev_default_fork>, but acts on an event loop created by 606Like C<ev_default_fork>, but acts on an event loop created by
548C<ev_loop_new>. Yes, you have to call this on every allocated event loop 607C<ev_loop_new>. Yes, you have to call this on every allocated event loop
549after fork, and how you do this is entirely your own problem. 608after fork that you want to re-use in the child, and how you do this is
609entirely your own problem.
550 610
551=item int ev_is_default_loop (loop) 611=item int ev_is_default_loop (loop)
552 612
553Returns true when the given loop actually is the default loop, false otherwise. 613Returns true when the given loop is, in fact, the default loop, and false
614otherwise.
554 615
555=item unsigned int ev_loop_count (loop) 616=item unsigned int ev_loop_count (loop)
556 617
557Returns the count of loop iterations for the loop, which is identical to 618Returns the count of loop iterations for the loop, which is identical to
558the number of times libev did poll for new events. It starts at C<0> and 619the number of times libev did poll for new events. It starts at C<0> and
559happily wraps around with enough iterations. 620happily wraps around with enough iterations.
560 621
561This 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
562"ticks" the number of loop iterations), as it roughly corresponds with 623"ticks" the number of loop iterations), as it roughly corresponds with
563C<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.
564 637
565=item unsigned int ev_backend (loop) 638=item unsigned int ev_backend (loop)
566 639
567Returns one of the C<EVBACKEND_*> flags indicating the event backend in 640Returns one of the C<EVBACKEND_*> flags indicating the event backend in
568use. 641use.
583 656
584This function is rarely useful, but when some event callback runs for a 657This function is rarely useful, but when some event callback runs for a
585very long time without entering the event loop, updating libev's idea of 658very long time without entering the event loop, updating libev's idea of
586the current time is a good idea. 659the current time is a good idea.
587 660
588See also "The special problem of time updates" in the C<ev_timer> section. 661See also L<The special problem of time updates> in the C<ev_timer> section.
662
663=item ev_suspend (loop)
664
665=item ev_resume (loop)
666
667These two functions suspend and resume a loop, for use when the loop is
668not used for a while and timeouts should not be processed.
669
670A typical use case would be an interactive program such as a game: When
671the user presses C<^Z> to suspend the game and resumes it an hour later it
672would be best to handle timeouts as if no time had actually passed while
673the program was suspended. This can be achieved by calling C<ev_suspend>
674in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
675C<ev_resume> directly afterwards to resume timer processing.
676
677Effectively, all C<ev_timer> watchers will be delayed by the time spend
678between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
679will be rescheduled (that is, they will lose any events that would have
680occured while suspended).
681
682After calling C<ev_suspend> you B<must not> call I<any> function on the
683given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
684without a previous call to C<ev_suspend>.
685
686Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
687event loop time (see C<ev_now_update>).
589 688
590=item ev_loop (loop, int flags) 689=item ev_loop (loop, int flags)
591 690
592Finally, this is it, the event handler. This function usually is called 691Finally, this is it, the event handler. This function usually is called
593after you initialised all your watchers and you want to start handling 692after you initialised all your watchers and you want to start handling
596If the flags argument is specified as C<0>, it will not return until 695If the flags argument is specified as C<0>, it will not return until
597either no event watchers are active anymore or C<ev_unloop> was called. 696either no event watchers are active anymore or C<ev_unloop> was called.
598 697
599Please note that an explicit C<ev_unloop> is usually better than 698Please note that an explicit C<ev_unloop> is usually better than
600relying on all watchers to be stopped when deciding when a program has 699relying on all watchers to be stopped when deciding when a program has
601finished (especially in interactive programs), but having a program that 700finished (especially in interactive programs), but having a program
602automatically loops as long as it has to and no longer by virtue of 701that automatically loops as long as it has to and no longer by virtue
603relying on its watchers stopping correctly is a thing of beauty. 702of relying on its watchers stopping correctly, that is truly a thing of
703beauty.
604 704
605A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 705A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
606those events and any outstanding ones, but will not block your process in 706those events and any already outstanding ones, but will not block your
607case there are no events and will return after one iteration of the loop. 707process in case there are no events and will return after one iteration of
708the loop.
608 709
609A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 710A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
610necessary) and will handle those and any outstanding ones. It will block 711necessary) and will handle those and any already outstanding ones. It
611your process until at least one new event arrives, and will return after 712will block your process until at least one new event arrives (which could
612one iteration of the loop. This is useful if you are waiting for some 713be an event internal to libev itself, so there is no guarantee that a
613external event in conjunction with something not expressible using other 714user-registered callback will be called), and will return after one
715iteration of the loop.
716
717This is useful if you are waiting for some external event in conjunction
718with something not expressible using other libev watchers (i.e. "roll your
614libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is 719own C<ev_loop>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
615usually a better approach for this kind of thing. 720usually a better approach for this kind of thing.
616 721
617Here are the gory details of what C<ev_loop> does: 722Here are the gory details of what C<ev_loop> does:
618 723
619 - Before the first iteration, call any pending watchers. 724 - Before the first iteration, call any pending watchers.
629 any active watchers at all will result in not sleeping). 734 any active watchers at all will result in not sleeping).
630 - Sleep if the I/O and timer collect interval say so. 735 - Sleep if the I/O and timer collect interval say so.
631 - Block the process, waiting for any events. 736 - Block the process, waiting for any events.
632 - Queue all outstanding I/O (fd) events. 737 - Queue all outstanding I/O (fd) events.
633 - Update the "event loop time" (ev_now ()), and do time jump adjustments. 738 - Update the "event loop time" (ev_now ()), and do time jump adjustments.
634 - Queue all outstanding timers. 739 - Queue all expired timers.
635 - Queue all outstanding periodics. 740 - Queue all expired periodics.
636 - Unless any events are pending now, queue all idle watchers. 741 - Unless any events are pending now, queue all idle watchers.
637 - Queue all check watchers. 742 - Queue all check watchers.
638 - Call all queued watchers in reverse order (i.e. check watchers first). 743 - Call all queued watchers in reverse order (i.e. check watchers first).
639 Signals and child watchers are implemented as I/O watchers, and will 744 Signals and child watchers are implemented as I/O watchers, and will
640 be handled here by queueing them when their watcher gets executed. 745 be handled here by queueing them when their watcher gets executed.
657C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 762C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
658C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 763C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
659 764
660This "unloop state" will be cleared when entering C<ev_loop> again. 765This "unloop state" will be cleared when entering C<ev_loop> again.
661 766
767It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls.
768
662=item ev_ref (loop) 769=item ev_ref (loop)
663 770
664=item ev_unref (loop) 771=item ev_unref (loop)
665 772
666Ref/unref can be used to add or remove a reference count on the event 773Ref/unref can be used to add or remove a reference count on the event
667loop: Every watcher keeps one reference, and as long as the reference 774loop: Every watcher keeps one reference, and as long as the reference
668count is nonzero, C<ev_loop> will not return on its own. If you have 775count is nonzero, C<ev_loop> will not return on its own.
776
669a watcher you never unregister that should not keep C<ev_loop> from 777If you have a watcher you never unregister that should not keep C<ev_loop>
670returning, ev_unref() after starting, and ev_ref() before stopping it. For 778from returning, call ev_unref() after starting, and ev_ref() before
779stopping it.
780
671example, libev itself uses this for its internal signal pipe: It is not 781As an example, libev itself uses this for its internal signal pipe: It
672visible to the libev user and should not keep C<ev_loop> from exiting if 782is not visible to the libev user and should not keep C<ev_loop> from
673no event watchers registered by it are active. It is also an excellent 783exiting if no event watchers registered by it are active. It is also an
674way to do this for generic recurring timers or from within third-party 784excellent way to do this for generic recurring timers or from within
675libraries. Just remember to I<unref after start> and I<ref before stop> 785third-party libraries. Just remember to I<unref after start> and I<ref
676(but only if the watcher wasn't active before, or was active before, 786before stop> (but only if the watcher wasn't active before, or was active
677respectively). 787before, respectively. Note also that libev might stop watchers itself
788(e.g. non-repeating timers) in which case you have to C<ev_ref>
789in the callback).
678 790
679Example: Create a signal watcher, but keep it from keeping C<ev_loop> 791Example: Create a signal watcher, but keep it from keeping C<ev_loop>
680running when nothing else is active. 792running when nothing else is active.
681 793
682 struct ev_signal exitsig; 794 ev_signal exitsig;
683 ev_signal_init (&exitsig, sig_cb, SIGINT); 795 ev_signal_init (&exitsig, sig_cb, SIGINT);
684 ev_signal_start (loop, &exitsig); 796 ev_signal_start (loop, &exitsig);
685 evf_unref (loop); 797 evf_unref (loop);
686 798
687Example: For some weird reason, unregister the above signal handler again. 799Example: For some weird reason, unregister the above signal handler again.
701Setting these to a higher value (the C<interval> I<must> be >= C<0>) 813Setting these to a higher value (the C<interval> I<must> be >= C<0>)
702allows libev to delay invocation of I/O and timer/periodic callbacks 814allows libev to delay invocation of I/O and timer/periodic callbacks
703to increase efficiency of loop iterations (or to increase power-saving 815to increase efficiency of loop iterations (or to increase power-saving
704opportunities). 816opportunities).
705 817
706The background is that sometimes your program runs just fast enough to 818The idea is that sometimes your program runs just fast enough to handle
707handle one (or very few) event(s) per loop iteration. While this makes 819one (or very few) event(s) per loop iteration. While this makes the
708the program responsive, it also wastes a lot of CPU time to poll for new 820program responsive, it also wastes a lot of CPU time to poll for new
709events, especially with backends like C<select ()> which have a high 821events, especially with backends like C<select ()> which have a high
710overhead for the actual polling but can deliver many events at once. 822overhead for the actual polling but can deliver many events at once.
711 823
712By setting a higher I<io collect interval> you allow libev to spend more 824By setting a higher I<io collect interval> you allow libev to spend more
713time collecting I/O events, so you can handle more events per iteration, 825time collecting I/O events, so you can handle more events per iteration,
714at the cost of increasing latency. Timeouts (both C<ev_periodic> and 826at the cost of increasing latency. Timeouts (both C<ev_periodic> and
715C<ev_timer>) will be not affected. Setting this to a non-null value will 827C<ev_timer>) will be not affected. Setting this to a non-null value will
716introduce an additional C<ev_sleep ()> call into most loop iterations. 828introduce an additional C<ev_sleep ()> call into most loop iterations. The
829sleep time ensures that libev will not poll for I/O events more often then
830once per this interval, on average.
717 831
718Likewise, by setting a higher I<timeout collect interval> you allow libev 832Likewise, by setting a higher I<timeout collect interval> you allow libev
719to spend more time collecting timeouts, at the expense of increased 833to spend more time collecting timeouts, at the expense of increased
720latency (the watcher callback will be called later). C<ev_io> watchers 834latency/jitter/inexactness (the watcher callback will be called
721will not be affected. Setting this to a non-null value will not introduce 835later). C<ev_io> watchers will not be affected. Setting this to a non-null
722any overhead in libev. 836value will not introduce any overhead in libev.
723 837
724Many (busy) programs can usually benefit by setting the I/O collect 838Many (busy) programs can usually benefit by setting the I/O collect
725interval to a value near C<0.1> or so, which is often enough for 839interval to a value near C<0.1> or so, which is often enough for
726interactive servers (of course not for games), likewise for timeouts. It 840interactive servers (of course not for games), likewise for timeouts. It
727usually doesn't make much sense to set it to a lower value than C<0.01>, 841usually doesn't make much sense to set it to a lower value than C<0.01>,
728as this approaches the timing granularity of most systems. 842as this approaches the timing granularity of most systems. Note that if
843you do transactions with the outside world and you can't increase the
844parallelity, then this setting will limit your transaction rate (if you
845need to poll once per transaction and the I/O collect interval is 0.01,
846then you can't do more than 100 transations per second).
729 847
730Setting the I<timeout collect interval> can improve the opportunity for 848Setting the I<timeout collect interval> can improve the opportunity for
731saving power, as the program will "bundle" timer callback invocations that 849saving power, as the program will "bundle" timer callback invocations that
732are "near" in time together, by delaying some, thus reducing the number of 850are "near" in time together, by delaying some, thus reducing the number of
733times the process sleeps and wakes up again. Another useful technique to 851times the process sleeps and wakes up again. Another useful technique to
734reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure 852reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
735they fire on, say, one-second boundaries only. 853they fire on, say, one-second boundaries only.
736 854
855Example: we only need 0.1s timeout granularity, and we wish not to poll
856more often than 100 times per second:
857
858 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
859 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
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
895While event loop modifications are allowed between invocations of
896C<release> and C<acquire> (that's their only purpose after all), no
897modifications done will affect the event loop, i.e. adding watchers will
898have no effect on the set of file descriptors being watched, or the time
899waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it
900to take note of any changes you made.
901
902In theory, threads executing C<ev_loop> will be async-cancel safe between
903invocations of C<release> and C<acquire>.
904
905See also the locking example in the C<THREADS> section later in this
906document.
907
908=item ev_set_userdata (loop, void *data)
909
910=item ev_userdata (loop)
911
912Set and retrieve a single C<void *> associated with a loop. When
913C<ev_set_userdata> has never been called, then C<ev_userdata> returns
914C<0.>
915
916These two functions can be used to associate arbitrary data with a loop,
917and are intended solely for the C<invoke_pending_cb>, C<release> and
918C<acquire> callbacks described above, but of course can be (ab-)used for
919any other purpose as well.
920
737=item ev_loop_verify (loop) 921=item ev_loop_verify (loop)
738 922
739This function only does something when C<EV_VERIFY> support has been 923This function only does something when C<EV_VERIFY> support has been
740compiled in. It tries to go through all internal structures and checks 924compiled in, which is the default for non-minimal builds. It tries to go
741them for validity. If anything is found to be inconsistent, it will print 925through all internal structures and checks them for validity. If anything
742an error message to standard error and call C<abort ()>. 926is found to be inconsistent, it will print an error message to standard
927error and call C<abort ()>.
743 928
744This can be used to catch bugs inside libev itself: under normal 929This can be used to catch bugs inside libev itself: under normal
745circumstances, this function will never abort as of course libev keeps its 930circumstances, this function will never abort as of course libev keeps its
746data structures consistent. 931data structures consistent.
747 932
748=back 933=back
749 934
750 935
751=head1 ANATOMY OF A WATCHER 936=head1 ANATOMY OF A WATCHER
752 937
938In the following description, uppercase C<TYPE> in names stands for the
939watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
940watchers and C<ev_io_start> for I/O watchers.
941
753A watcher is a structure that you create and register to record your 942A watcher is a structure that you create and register to record your
754interest in some event. For instance, if you want to wait for STDIN to 943interest in some event. For instance, if you want to wait for STDIN to
755become readable, you would create an C<ev_io> watcher for that: 944become readable, you would create an C<ev_io> watcher for that:
756 945
757 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 946 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
758 { 947 {
759 ev_io_stop (w); 948 ev_io_stop (w);
760 ev_unloop (loop, EVUNLOOP_ALL); 949 ev_unloop (loop, EVUNLOOP_ALL);
761 } 950 }
762 951
763 struct ev_loop *loop = ev_default_loop (0); 952 struct ev_loop *loop = ev_default_loop (0);
953
764 struct ev_io stdin_watcher; 954 ev_io stdin_watcher;
955
765 ev_init (&stdin_watcher, my_cb); 956 ev_init (&stdin_watcher, my_cb);
766 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 957 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
767 ev_io_start (loop, &stdin_watcher); 958 ev_io_start (loop, &stdin_watcher);
959
768 ev_loop (loop, 0); 960 ev_loop (loop, 0);
769 961
770As you can see, you are responsible for allocating the memory for your 962As you can see, you are responsible for allocating the memory for your
771watcher structures (and it is usually a bad idea to do this on the stack, 963watcher structures (and it is I<usually> a bad idea to do this on the
772although this can sometimes be quite valid). 964stack).
965
966Each watcher has an associated watcher structure (called C<struct ev_TYPE>
967or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
773 968
774Each watcher structure must be initialised by a call to C<ev_init 969Each watcher structure must be initialised by a call to C<ev_init
775(watcher *, callback)>, which expects a callback to be provided. This 970(watcher *, callback)>, which expects a callback to be provided. This
776callback gets invoked each time the event occurs (or, in the case of I/O 971callback gets invoked each time the event occurs (or, in the case of I/O
777watchers, each time the event loop detects that the file descriptor given 972watchers, each time the event loop detects that the file descriptor given
778is readable and/or writable). 973is readable and/or writable).
779 974
780Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 975Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
781with arguments specific to this watcher type. There is also a macro 976macro to configure it, with arguments specific to the watcher type. There
782to combine initialisation and setting in one call: C<< ev_<type>_init 977is also a macro to combine initialisation and setting in one call: C<<
783(watcher *, callback, ...) >>. 978ev_TYPE_init (watcher *, callback, ...) >>.
784 979
785To make the watcher actually watch out for events, you have to start it 980To make the watcher actually watch out for events, you have to start it
786with a watcher-specific start function (C<< ev_<type>_start (loop, watcher 981with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
787*) >>), and you can stop watching for events at any time by calling the 982*) >>), and you can stop watching for events at any time by calling the
788corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>. 983corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
789 984
790As long as your watcher is active (has been started but not stopped) you 985As long as your watcher is active (has been started but not stopped) you
791must not touch the values stored in it. Most specifically you must never 986must not touch the values stored in it. Most specifically you must never
792reinitialise it or call its C<set> macro. 987reinitialise it or call its C<ev_TYPE_set> macro.
793 988
794Each and every callback receives the event loop pointer as first, the 989Each and every callback receives the event loop pointer as first, the
795registered watcher structure as second, and a bitset of received events as 990registered watcher structure as second, and a bitset of received events as
796third argument. 991third argument.
797 992
855 1050
856=item C<EV_ASYNC> 1051=item C<EV_ASYNC>
857 1052
858The given async watcher has been asynchronously notified (see C<ev_async>). 1053The given async watcher has been asynchronously notified (see C<ev_async>).
859 1054
1055=item C<EV_CUSTOM>
1056
1057Not ever sent (or otherwise used) by libev itself, but can be freely used
1058by libev users to signal watchers (e.g. via C<ev_feed_event>).
1059
860=item C<EV_ERROR> 1060=item C<EV_ERROR>
861 1061
862An unspecified error has occurred, the watcher has been stopped. This might 1062An unspecified error has occurred, the watcher has been stopped. This might
863happen because the watcher could not be properly started because libev 1063happen because the watcher could not be properly started because libev
864ran out of memory, a file descriptor was found to be closed or any other 1064ran out of memory, a file descriptor was found to be closed or any other
1065problem. Libev considers these application bugs.
1066
865problem. You best act on it by reporting the problem and somehow coping 1067You best act on it by reporting the problem and somehow coping with the
866with the watcher being stopped. 1068watcher being stopped. Note that well-written programs should not receive
1069an error ever, so when your watcher receives it, this usually indicates a
1070bug in your program.
867 1071
868Libev will usually signal a few "dummy" events together with an error, 1072Libev will usually signal a few "dummy" events together with an error, for
869for example it might indicate that a fd is readable or writable, and if 1073example it might indicate that a fd is readable or writable, and if your
870your callbacks is well-written it can just attempt the operation and cope 1074callbacks is well-written it can just attempt the operation and cope with
871with the error from read() or write(). This will not work in multi-threaded 1075the error from read() or write(). This will not work in multi-threaded
872programs, though, so beware. 1076programs, though, as the fd could already be closed and reused for another
1077thing, so beware.
873 1078
874=back 1079=back
875 1080
876=head2 GENERIC WATCHER FUNCTIONS 1081=head2 GENERIC WATCHER FUNCTIONS
877
878In the following description, C<TYPE> stands for the watcher type,
879e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
880 1082
881=over 4 1083=over 4
882 1084
883=item C<ev_init> (ev_TYPE *watcher, callback) 1085=item C<ev_init> (ev_TYPE *watcher, callback)
884 1086
890which rolls both calls into one. 1092which rolls both calls into one.
891 1093
892You can reinitialise a watcher at any time as long as it has been stopped 1094You can reinitialise a watcher at any time as long as it has been stopped
893(or never started) and there are no pending events outstanding. 1095(or never started) and there are no pending events outstanding.
894 1096
895The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher, 1097The callback is always of type C<void (*)(struct ev_loop *loop, ev_TYPE *watcher,
896int revents)>. 1098int revents)>.
1099
1100Example: Initialise an C<ev_io> watcher in two steps.
1101
1102 ev_io w;
1103 ev_init (&w, my_cb);
1104 ev_io_set (&w, STDIN_FILENO, EV_READ);
897 1105
898=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1106=item C<ev_TYPE_set> (ev_TYPE *, [args])
899 1107
900This macro initialises the type-specific parts of a watcher. You need to 1108This macro initialises the type-specific parts of a watcher. You need to
901call C<ev_init> at least once before you call this macro, but you can 1109call C<ev_init> at least once before you call this macro, but you can
904difference to the C<ev_init> macro). 1112difference to the C<ev_init> macro).
905 1113
906Although some watcher types do not have type-specific arguments 1114Although some watcher types do not have type-specific arguments
907(e.g. C<ev_prepare>) you still need to call its C<set> macro. 1115(e.g. C<ev_prepare>) you still need to call its C<set> macro.
908 1116
1117See C<ev_init>, above, for an example.
1118
909=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args]) 1119=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
910 1120
911This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro 1121This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
912calls into a single call. This is the most convenient method to initialise 1122calls into a single call. This is the most convenient method to initialise
913a watcher. The same limitations apply, of course. 1123a watcher. The same limitations apply, of course.
914 1124
1125Example: Initialise and set an C<ev_io> watcher in one step.
1126
1127 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1128
915=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1129=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
916 1130
917Starts (activates) the given watcher. Only active watchers will receive 1131Starts (activates) the given watcher. Only active watchers will receive
918events. If the watcher is already active nothing will happen. 1132events. If the watcher is already active nothing will happen.
919 1133
1134Example: Start the C<ev_io> watcher that is being abused as example in this
1135whole section.
1136
1137 ev_io_start (EV_DEFAULT_UC, &w);
1138
920=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1139=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
921 1140
922Stops the given watcher again (if active) and clears the pending 1141Stops the given watcher if active, and clears the pending status (whether
1142the watcher was active or not).
1143
923status. It is possible that stopped watchers are pending (for example, 1144It is possible that stopped watchers are pending - for example,
924non-repeating timers are being stopped when they become pending), but 1145non-repeating timers are being stopped when they become pending - but
925C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If 1146calling C<ev_TYPE_stop> ensures that the watcher is neither active nor
926you want to free or reuse the memory used by the watcher it is therefore a 1147pending. If you want to free or reuse the memory used by the watcher it is
927good idea to always call its C<ev_TYPE_stop> function. 1148therefore a good idea to always call its C<ev_TYPE_stop> function.
928 1149
929=item bool ev_is_active (ev_TYPE *watcher) 1150=item bool ev_is_active (ev_TYPE *watcher)
930 1151
931Returns a true value iff the watcher is active (i.e. it has been started 1152Returns a true value iff the watcher is active (i.e. it has been started
932and not yet been stopped). As long as a watcher is active you must not modify 1153and not yet been stopped). As long as a watcher is active you must not modify
958integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1179integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
959(default: C<-2>). Pending watchers with higher priority will be invoked 1180(default: C<-2>). Pending watchers with higher priority will be invoked
960before watchers with lower priority, but priority will not keep watchers 1181before watchers with lower priority, but priority will not keep watchers
961from being executed (except for C<ev_idle> watchers). 1182from being executed (except for C<ev_idle> watchers).
962 1183
963This means that priorities are I<only> used for ordering callback
964invocation after new events have been received. This is useful, for
965example, to reduce latency after idling, or more often, to bind two
966watchers on the same event and make sure one is called first.
967
968If you need to suppress invocation when higher priority events are pending 1184If you need to suppress invocation when higher priority events are pending
969you need to look at C<ev_idle> watchers, which provide this functionality. 1185you need to look at C<ev_idle> watchers, which provide this functionality.
970 1186
971You I<must not> change the priority of a watcher as long as it is active or 1187You I<must not> change the priority of a watcher as long as it is active or
972pending. 1188pending.
973 1189
1190Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1191fine, as long as you do not mind that the priority value you query might
1192or might not have been clamped to the valid range.
1193
974The default priority used by watchers when no priority has been set is 1194The default priority used by watchers when no priority has been set is
975always C<0>, which is supposed to not be too high and not be too low :). 1195always C<0>, which is supposed to not be too high and not be too low :).
976 1196
977Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1197See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
978fine, as long as you do not mind that the priority value you query might 1198priorities.
979or might not have been adjusted to be within valid range.
980 1199
981=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1200=item ev_invoke (loop, ev_TYPE *watcher, int revents)
982 1201
983Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1202Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
984C<loop> nor C<revents> need to be valid as long as the watcher callback 1203C<loop> nor C<revents> need to be valid as long as the watcher callback
985can deal with that fact. 1204can deal with that fact, as both are simply passed through to the
1205callback.
986 1206
987=item int ev_clear_pending (loop, ev_TYPE *watcher) 1207=item int ev_clear_pending (loop, ev_TYPE *watcher)
988 1208
989If the watcher is pending, this function returns clears its pending status 1209If the watcher is pending, this function clears its pending status and
990and returns its C<revents> bitset (as if its callback was invoked). If the 1210returns its C<revents> bitset (as if its callback was invoked). If the
991watcher isn't pending it does nothing and returns C<0>. 1211watcher isn't pending it does nothing and returns C<0>.
992 1212
1213Sometimes it can be useful to "poll" a watcher instead of waiting for its
1214callback to be invoked, which can be accomplished with this function.
1215
993=back 1216=back
994 1217
995 1218
996=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1219=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
997 1220
998Each watcher has, by default, a member C<void *data> that you can change 1221Each watcher has, by default, a member C<void *data> that you can change
999and read at any time, libev will completely ignore it. This can be used 1222and read at any time: libev will completely ignore it. This can be used
1000to associate arbitrary data with your watcher. If you need more data and 1223to associate arbitrary data with your watcher. If you need more data and
1001don't want to allocate memory and store a pointer to it in that data 1224don't want to allocate memory and store a pointer to it in that data
1002member, you can also "subclass" the watcher type and provide your own 1225member, you can also "subclass" the watcher type and provide your own
1003data: 1226data:
1004 1227
1005 struct my_io 1228 struct my_io
1006 { 1229 {
1007 struct ev_io io; 1230 ev_io io;
1008 int otherfd; 1231 int otherfd;
1009 void *somedata; 1232 void *somedata;
1010 struct whatever *mostinteresting; 1233 struct whatever *mostinteresting;
1011 } 1234 };
1235
1236 ...
1237 struct my_io w;
1238 ev_io_init (&w.io, my_cb, fd, EV_READ);
1012 1239
1013And since your callback will be called with a pointer to the watcher, you 1240And since your callback will be called with a pointer to the watcher, you
1014can cast it back to your own type: 1241can cast it back to your own type:
1015 1242
1016 static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) 1243 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
1017 { 1244 {
1018 struct my_io *w = (struct my_io *)w_; 1245 struct my_io *w = (struct my_io *)w_;
1019 ... 1246 ...
1020 } 1247 }
1021 1248
1022More interesting and less C-conformant ways of casting your callback type 1249More interesting and less C-conformant ways of casting your callback type
1023instead have been omitted. 1250instead have been omitted.
1024 1251
1025Another common scenario is having some data structure with multiple 1252Another common scenario is to use some data structure with multiple
1026watchers: 1253embedded watchers:
1027 1254
1028 struct my_biggy 1255 struct my_biggy
1029 { 1256 {
1030 int some_data; 1257 int some_data;
1031 ev_timer t1; 1258 ev_timer t1;
1032 ev_timer t2; 1259 ev_timer t2;
1033 } 1260 }
1034 1261
1035In this case getting the pointer to C<my_biggy> is a bit more complicated, 1262In this case getting the pointer to C<my_biggy> is a bit more
1036you need to use C<offsetof>: 1263complicated: Either you store the address of your C<my_biggy> struct
1264in the C<data> member of the watcher (for woozies), or you need to use
1265some pointer arithmetic using C<offsetof> inside your watchers (for real
1266programmers):
1037 1267
1038 #include <stddef.h> 1268 #include <stddef.h>
1039 1269
1040 static void 1270 static void
1041 t1_cb (EV_P_ struct ev_timer *w, int revents) 1271 t1_cb (EV_P_ ev_timer *w, int revents)
1042 { 1272 {
1043 struct my_biggy big = (struct my_biggy * 1273 struct my_biggy big = (struct my_biggy *)
1044 (((char *)w) - offsetof (struct my_biggy, t1)); 1274 (((char *)w) - offsetof (struct my_biggy, t1));
1045 } 1275 }
1046 1276
1047 static void 1277 static void
1048 t2_cb (EV_P_ struct ev_timer *w, int revents) 1278 t2_cb (EV_P_ ev_timer *w, int revents)
1049 { 1279 {
1050 struct my_biggy big = (struct my_biggy * 1280 struct my_biggy big = (struct my_biggy *)
1051 (((char *)w) - offsetof (struct my_biggy, t2)); 1281 (((char *)w) - offsetof (struct my_biggy, t2));
1052 } 1282 }
1283
1284=head2 WATCHER PRIORITY MODELS
1285
1286Many event loops support I<watcher priorities>, which are usually small
1287integers that influence the ordering of event callback invocation
1288between watchers in some way, all else being equal.
1289
1290In libev, Watcher priorities can be set using C<ev_set_priority>. See its
1291description for the more technical details such as the actual priority
1292range.
1293
1294There are two common ways how these these priorities are being interpreted
1295by event loops:
1296
1297In the more common lock-out model, higher priorities "lock out" invocation
1298of lower priority watchers, which means as long as higher priority
1299watchers receive events, lower priority watchers are not being invoked.
1300
1301The less common only-for-ordering model uses priorities solely to order
1302callback invocation within a single event loop iteration: Higher priority
1303watchers are invoked before lower priority ones, but they all get invoked
1304before polling for new events.
1305
1306Libev uses the second (only-for-ordering) model for all its watchers
1307except for idle watchers (which use the lock-out model).
1308
1309The rationale behind this is that implementing the lock-out model for
1310watchers is not well supported by most kernel interfaces, and most event
1311libraries will just poll for the same events again and again as long as
1312their callbacks have not been executed, which is very inefficient in the
1313common case of one high-priority watcher locking out a mass of lower
1314priority ones.
1315
1316Static (ordering) priorities are most useful when you have two or more
1317watchers handling the same resource: a typical usage example is having an
1318C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
1319timeouts. Under load, data might be received while the program handles
1320other jobs, but since timers normally get invoked first, the timeout
1321handler will be executed before checking for data. In that case, giving
1322the timer a lower priority than the I/O watcher ensures that I/O will be
1323handled first even under adverse conditions (which is usually, but not
1324always, what you want).
1325
1326Since idle watchers use the "lock-out" model, meaning that idle watchers
1327will only be executed when no same or higher priority watchers have
1328received events, they can be used to implement the "lock-out" model when
1329required.
1330
1331For example, to emulate how many other event libraries handle priorities,
1332you can associate an C<ev_idle> watcher to each such watcher, and in
1333the normal watcher callback, you just start the idle watcher. The real
1334processing is done in the idle watcher callback. This causes libev to
1335continously poll and process kernel event data for the watcher, but when
1336the lock-out case is known to be rare (which in turn is rare :), this is
1337workable.
1338
1339Usually, however, the lock-out model implemented that way will perform
1340miserably under the type of load it was designed to handle. In that case,
1341it might be preferable to stop the real watcher before starting the
1342idle watcher, so the kernel will not have to process the event in case
1343the actual processing will be delayed for considerable time.
1344
1345Here is an example of an I/O watcher that should run at a strictly lower
1346priority than the default, and which should only process data when no
1347other events are pending:
1348
1349 ev_idle idle; // actual processing watcher
1350 ev_io io; // actual event watcher
1351
1352 static void
1353 io_cb (EV_P_ ev_io *w, int revents)
1354 {
1355 // stop the I/O watcher, we received the event, but
1356 // are not yet ready to handle it.
1357 ev_io_stop (EV_A_ w);
1358
1359 // start the idle watcher to ahndle the actual event.
1360 // it will not be executed as long as other watchers
1361 // with the default priority are receiving events.
1362 ev_idle_start (EV_A_ &idle);
1363 }
1364
1365 static void
1366 idle_cb (EV_P_ ev_idle *w, int revents)
1367 {
1368 // actual processing
1369 read (STDIN_FILENO, ...);
1370
1371 // have to start the I/O watcher again, as
1372 // we have handled the event
1373 ev_io_start (EV_P_ &io);
1374 }
1375
1376 // initialisation
1377 ev_idle_init (&idle, idle_cb);
1378 ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
1379 ev_io_start (EV_DEFAULT_ &io);
1380
1381In the "real" world, it might also be beneficial to start a timer, so that
1382low-priority connections can not be locked out forever under load. This
1383enables your program to keep a lower latency for important connections
1384during short periods of high load, while not completely locking out less
1385important ones.
1053 1386
1054 1387
1055=head1 WATCHER TYPES 1388=head1 WATCHER TYPES
1056 1389
1057This section describes each watcher in detail, but will not repeat 1390This section describes each watcher in detail, but will not repeat
1081In general you can register as many read and/or write event watchers per 1414In general you can register as many read and/or write event watchers per
1082fd as you want (as long as you don't confuse yourself). Setting all file 1415fd as you want (as long as you don't confuse yourself). Setting all file
1083descriptors to non-blocking mode is also usually a good idea (but not 1416descriptors to non-blocking mode is also usually a good idea (but not
1084required if you know what you are doing). 1417required if you know what you are doing).
1085 1418
1086If you must do this, then force the use of a known-to-be-good backend 1419If you cannot use non-blocking mode, then force the use of a
1087(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 1420known-to-be-good backend (at the time of this writing, this includes only
1088C<EVBACKEND_POLL>). 1421C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1422descriptors for which non-blocking operation makes no sense (such as
1423files) - libev doesn't guarentee any specific behaviour in that case.
1089 1424
1090Another thing you have to watch out for is that it is quite easy to 1425Another thing you have to watch out for is that it is quite easy to
1091receive "spurious" readiness notifications, that is your callback might 1426receive "spurious" readiness notifications, that is your callback might
1092be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1427be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1093because there is no data. Not only are some backends known to create a 1428because there is no data. Not only are some backends known to create a
1094lot of those (for example Solaris ports), it is very easy to get into 1429lot of those (for example Solaris ports), it is very easy to get into
1095this situation even with a relatively standard program structure. Thus 1430this situation even with a relatively standard program structure. Thus
1096it is best to always use non-blocking I/O: An extra C<read>(2) returning 1431it is best to always use non-blocking I/O: An extra C<read>(2) returning
1097C<EAGAIN> is far preferable to a program hanging until some data arrives. 1432C<EAGAIN> is far preferable to a program hanging until some data arrives.
1098 1433
1099If you cannot run the fd in non-blocking mode (for example you should not 1434If you cannot run the fd in non-blocking mode (for example you should
1100play around with an Xlib connection), then you have to separately re-test 1435not play around with an Xlib connection), then you have to separately
1101whether a file descriptor is really ready with a known-to-be good interface 1436re-test whether a file descriptor is really ready with a known-to-be good
1102such as poll (fortunately in our Xlib example, Xlib already does this on 1437interface such as poll (fortunately in our Xlib example, Xlib already
1103its own, so its quite safe to use). 1438does this on its own, so its quite safe to use). Some people additionally
1439use C<SIGALRM> and an interval timer, just to be sure you won't block
1440indefinitely.
1441
1442But really, best use non-blocking mode.
1104 1443
1105=head3 The special problem of disappearing file descriptors 1444=head3 The special problem of disappearing file descriptors
1106 1445
1107Some backends (e.g. kqueue, epoll) need to be told about closing a file 1446Some backends (e.g. kqueue, epoll) need to be told about closing a file
1108descriptor (either by calling C<close> explicitly or by any other means, 1447descriptor (either due to calling C<close> explicitly or any other means,
1109such as C<dup>). The reason is that you register interest in some file 1448such as C<dup2>). The reason is that you register interest in some file
1110descriptor, but when it goes away, the operating system will silently drop 1449descriptor, but when it goes away, the operating system will silently drop
1111this interest. If another file descriptor with the same number then is 1450this interest. If another file descriptor with the same number then is
1112registered with libev, there is no efficient way to see that this is, in 1451registered with libev, there is no efficient way to see that this is, in
1113fact, a different file descriptor. 1452fact, a different file descriptor.
1114 1453
1145enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or 1484enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1146C<EVBACKEND_POLL>. 1485C<EVBACKEND_POLL>.
1147 1486
1148=head3 The special problem of SIGPIPE 1487=head3 The special problem of SIGPIPE
1149 1488
1150While not really specific to libev, it is easy to forget about SIGPIPE: 1489While not really specific to libev, it is easy to forget about C<SIGPIPE>:
1151when writing to a pipe whose other end has been closed, your program gets 1490when writing to a pipe whose other end has been closed, your program gets
1152send a SIGPIPE, which, by default, aborts your program. For most programs 1491sent a SIGPIPE, which, by default, aborts your program. For most programs
1153this is sensible behaviour, for daemons, this is usually undesirable. 1492this is sensible behaviour, for daemons, this is usually undesirable.
1154 1493
1155So when you encounter spurious, unexplained daemon exits, make sure you 1494So when you encounter spurious, unexplained daemon exits, make sure you
1156ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1495ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1157somewhere, as that would have given you a big clue). 1496somewhere, as that would have given you a big clue).
1164=item ev_io_init (ev_io *, callback, int fd, int events) 1503=item ev_io_init (ev_io *, callback, int fd, int events)
1165 1504
1166=item ev_io_set (ev_io *, int fd, int events) 1505=item ev_io_set (ev_io *, int fd, int events)
1167 1506
1168Configures an C<ev_io> watcher. The C<fd> is the file descriptor to 1507Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1169receive events for and events is either C<EV_READ>, C<EV_WRITE> or 1508receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or
1170C<EV_READ | EV_WRITE> to receive the given events. 1509C<EV_READ | EV_WRITE>, to express the desire to receive the given events.
1171 1510
1172=item int fd [read-only] 1511=item int fd [read-only]
1173 1512
1174The file descriptor being watched. 1513The file descriptor being watched.
1175 1514
1184Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well 1523Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
1185readable, but only once. Since it is likely line-buffered, you could 1524readable, but only once. Since it is likely line-buffered, you could
1186attempt to read a whole line in the callback. 1525attempt to read a whole line in the callback.
1187 1526
1188 static void 1527 static void
1189 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1528 stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents)
1190 { 1529 {
1191 ev_io_stop (loop, w); 1530 ev_io_stop (loop, w);
1192 .. read from stdin here (or from w->fd) and haqndle any I/O errors 1531 .. read from stdin here (or from w->fd) and handle any I/O errors
1193 } 1532 }
1194 1533
1195 ... 1534 ...
1196 struct ev_loop *loop = ev_default_init (0); 1535 struct ev_loop *loop = ev_default_init (0);
1197 struct ev_io stdin_readable; 1536 ev_io stdin_readable;
1198 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1537 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1199 ev_io_start (loop, &stdin_readable); 1538 ev_io_start (loop, &stdin_readable);
1200 ev_loop (loop, 0); 1539 ev_loop (loop, 0);
1201 1540
1202 1541
1205Timer watchers are simple relative timers that generate an event after a 1544Timer watchers are simple relative timers that generate an event after a
1206given time, and optionally repeating in regular intervals after that. 1545given time, and optionally repeating in regular intervals after that.
1207 1546
1208The timers are based on real time, that is, if you register an event that 1547The timers are based on real time, that is, if you register an event that
1209times out after an hour and you reset your system clock to January last 1548times out after an hour and you reset your system clock to January last
1210year, it will still time out after (roughly) and hour. "Roughly" because 1549year, it will still time out after (roughly) one hour. "Roughly" because
1211detecting time jumps is hard, and some inaccuracies are unavoidable (the 1550detecting time jumps is hard, and some inaccuracies are unavoidable (the
1212monotonic clock option helps a lot here). 1551monotonic clock option helps a lot here).
1213 1552
1214The callback is guaranteed to be invoked only after its timeout has passed, 1553The callback is guaranteed to be invoked only I<after> its timeout has
1215but if multiple timers become ready during the same loop iteration then 1554passed (not I<at>, so on systems with very low-resolution clocks this
1216order of execution is undefined. 1555might introduce a small delay). If multiple timers become ready during the
1556same loop iteration then the ones with earlier time-out values are invoked
1557before ones of the same priority with later time-out values (but this is
1558no longer true when a callback calls C<ev_loop> recursively).
1559
1560=head3 Be smart about timeouts
1561
1562Many real-world problems involve some kind of timeout, usually for error
1563recovery. A typical example is an HTTP request - if the other side hangs,
1564you want to raise some error after a while.
1565
1566What follows are some ways to handle this problem, from obvious and
1567inefficient to smart and efficient.
1568
1569In the following, a 60 second activity timeout is assumed - a timeout that
1570gets reset to 60 seconds each time there is activity (e.g. each time some
1571data or other life sign was received).
1572
1573=over 4
1574
1575=item 1. Use a timer and stop, reinitialise and start it on activity.
1576
1577This is the most obvious, but not the most simple way: In the beginning,
1578start the watcher:
1579
1580 ev_timer_init (timer, callback, 60., 0.);
1581 ev_timer_start (loop, timer);
1582
1583Then, each time there is some activity, C<ev_timer_stop> it, initialise it
1584and start it again:
1585
1586 ev_timer_stop (loop, timer);
1587 ev_timer_set (timer, 60., 0.);
1588 ev_timer_start (loop, timer);
1589
1590This is relatively simple to implement, but means that each time there is
1591some activity, libev will first have to remove the timer from its internal
1592data structure and then add it again. Libev tries to be fast, but it's
1593still not a constant-time operation.
1594
1595=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity.
1596
1597This is the easiest way, and involves using C<ev_timer_again> instead of
1598C<ev_timer_start>.
1599
1600To implement this, configure an C<ev_timer> with a C<repeat> value
1601of C<60> and then call C<ev_timer_again> at start and each time you
1602successfully read or write some data. If you go into an idle state where
1603you do not expect data to travel on the socket, you can C<ev_timer_stop>
1604the timer, and C<ev_timer_again> will automatically restart it if need be.
1605
1606That means you can ignore both the C<ev_timer_start> function and the
1607C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1608member and C<ev_timer_again>.
1609
1610At start:
1611
1612 ev_init (timer, callback);
1613 timer->repeat = 60.;
1614 ev_timer_again (loop, timer);
1615
1616Each time there is some activity:
1617
1618 ev_timer_again (loop, timer);
1619
1620It is even possible to change the time-out on the fly, regardless of
1621whether the watcher is active or not:
1622
1623 timer->repeat = 30.;
1624 ev_timer_again (loop, timer);
1625
1626This is slightly more efficient then stopping/starting the timer each time
1627you want to modify its timeout value, as libev does not have to completely
1628remove and re-insert the timer from/into its internal data structure.
1629
1630It is, however, even simpler than the "obvious" way to do it.
1631
1632=item 3. Let the timer time out, but then re-arm it as required.
1633
1634This method is more tricky, but usually most efficient: Most timeouts are
1635relatively long compared to the intervals between other activity - in
1636our example, within 60 seconds, there are usually many I/O events with
1637associated activity resets.
1638
1639In this case, it would be more efficient to leave the C<ev_timer> alone,
1640but remember the time of last activity, and check for a real timeout only
1641within the callback:
1642
1643 ev_tstamp last_activity; // time of last activity
1644
1645 static void
1646 callback (EV_P_ ev_timer *w, int revents)
1647 {
1648 ev_tstamp now = ev_now (EV_A);
1649 ev_tstamp timeout = last_activity + 60.;
1650
1651 // if last_activity + 60. is older than now, we did time out
1652 if (timeout < now)
1653 {
1654 // timeout occured, take action
1655 }
1656 else
1657 {
1658 // callback was invoked, but there was some activity, re-arm
1659 // the watcher to fire in last_activity + 60, which is
1660 // guaranteed to be in the future, so "again" is positive:
1661 w->repeat = timeout - now;
1662 ev_timer_again (EV_A_ w);
1663 }
1664 }
1665
1666To summarise the callback: first calculate the real timeout (defined
1667as "60 seconds after the last activity"), then check if that time has
1668been reached, which means something I<did>, in fact, time out. Otherwise
1669the callback was invoked too early (C<timeout> is in the future), so
1670re-schedule the timer to fire at that future time, to see if maybe we have
1671a timeout then.
1672
1673Note how C<ev_timer_again> is used, taking advantage of the
1674C<ev_timer_again> optimisation when the timer is already running.
1675
1676This scheme causes more callback invocations (about one every 60 seconds
1677minus half the average time between activity), but virtually no calls to
1678libev to change the timeout.
1679
1680To start the timer, simply initialise the watcher and set C<last_activity>
1681to the current time (meaning we just have some activity :), then call the
1682callback, which will "do the right thing" and start the timer:
1683
1684 ev_init (timer, callback);
1685 last_activity = ev_now (loop);
1686 callback (loop, timer, EV_TIMEOUT);
1687
1688And when there is some activity, simply store the current time in
1689C<last_activity>, no libev calls at all:
1690
1691 last_actiivty = ev_now (loop);
1692
1693This technique is slightly more complex, but in most cases where the
1694time-out is unlikely to be triggered, much more efficient.
1695
1696Changing the timeout is trivial as well (if it isn't hard-coded in the
1697callback :) - just change the timeout and invoke the callback, which will
1698fix things for you.
1699
1700=item 4. Wee, just use a double-linked list for your timeouts.
1701
1702If there is not one request, but many thousands (millions...), all
1703employing some kind of timeout with the same timeout value, then one can
1704do even better:
1705
1706When starting the timeout, calculate the timeout value and put the timeout
1707at the I<end> of the list.
1708
1709Then use an C<ev_timer> to fire when the timeout at the I<beginning> of
1710the list is expected to fire (for example, using the technique #3).
1711
1712When there is some activity, remove the timer from the list, recalculate
1713the timeout, append it to the end of the list again, and make sure to
1714update the C<ev_timer> if it was taken from the beginning of the list.
1715
1716This way, one can manage an unlimited number of timeouts in O(1) time for
1717starting, stopping and updating the timers, at the expense of a major
1718complication, and having to use a constant timeout. The constant timeout
1719ensures that the list stays sorted.
1720
1721=back
1722
1723So which method the best?
1724
1725Method #2 is a simple no-brain-required solution that is adequate in most
1726situations. Method #3 requires a bit more thinking, but handles many cases
1727better, and isn't very complicated either. In most case, choosing either
1728one is fine, with #3 being better in typical situations.
1729
1730Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1731rather complicated, but extremely efficient, something that really pays
1732off after the first million or so of active timers, i.e. it's usually
1733overkill :)
1217 1734
1218=head3 The special problem of time updates 1735=head3 The special problem of time updates
1219 1736
1220Establishing the current time is a costly operation (it usually takes at 1737Establishing the current time is a costly operation (it usually takes at
1221least two system calls): EV therefore updates its idea of the current 1738least two system calls): EV therefore updates its idea of the current
1222time only before and after C<ev_loop> polls for new events, which causes 1739time only before and after C<ev_loop> collects new events, which causes a
1223a growing difference between C<ev_now ()> and C<ev_time ()> when handling 1740growing difference between C<ev_now ()> and C<ev_time ()> when handling
1224lots of events. 1741lots of events in one iteration.
1225 1742
1226The relative timeouts are calculated relative to the C<ev_now ()> 1743The relative timeouts are calculated relative to the C<ev_now ()>
1227time. This is usually the right thing as this timestamp refers to the time 1744time. This is usually the right thing as this timestamp refers to the time
1228of the event triggering whatever timeout you are modifying/starting. If 1745of the event triggering whatever timeout you are modifying/starting. If
1229you suspect event processing to be delayed and you I<need> to base the 1746you suspect event processing to be delayed and you I<need> to base the
1230timeout on the current time, use something like this to adjust for this: 1747timeout on the current time, use something like this to adjust for this:
1231 1748
1232 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1749 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1233 1750
1234If the event loop is suspended for a long time, one can also force an 1751If the event loop is suspended for a long time, you can also force an
1235update of the time returned by C<ev_now ()> by calling C<ev_now_update 1752update of the time returned by C<ev_now ()> by calling C<ev_now_update
1236()>. 1753()>.
1237 1754
1238=head3 Watcher-Specific Functions and Data Members 1755=head3 Watcher-Specific Functions and Data Members
1239 1756
1265If the timer is started but non-repeating, stop it (as if it timed out). 1782If the timer is started but non-repeating, stop it (as if it timed out).
1266 1783
1267If the timer is repeating, either start it if necessary (with the 1784If the timer is repeating, either start it if necessary (with the
1268C<repeat> value), or reset the running timer to the C<repeat> value. 1785C<repeat> value), or reset the running timer to the C<repeat> value.
1269 1786
1270This sounds a bit complicated, but here is a useful and typical 1787This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1271example: Imagine you have a TCP connection and you want a so-called idle 1788usage example.
1272timeout, that is, you want to be called when there have been, say, 60
1273seconds of inactivity on the socket. The easiest way to do this is to
1274configure an C<ev_timer> with a C<repeat> value of C<60> and then call
1275C<ev_timer_again> each time you successfully read or write some data. If
1276you go into an idle state where you do not expect data to travel on the
1277socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
1278automatically restart it if need be.
1279
1280That means you can ignore the C<after> value and C<ev_timer_start>
1281altogether and only ever use the C<repeat> value and C<ev_timer_again>:
1282
1283 ev_timer_init (timer, callback, 0., 5.);
1284 ev_timer_again (loop, timer);
1285 ...
1286 timer->again = 17.;
1287 ev_timer_again (loop, timer);
1288 ...
1289 timer->again = 10.;
1290 ev_timer_again (loop, timer);
1291
1292This is more slightly efficient then stopping/starting the timer each time
1293you want to modify its timeout value.
1294 1789
1295=item ev_tstamp repeat [read-write] 1790=item ev_tstamp repeat [read-write]
1296 1791
1297The current C<repeat> value. Will be used each time the watcher times out 1792The current C<repeat> value. Will be used each time the watcher times out
1298or C<ev_timer_again> is called and determines the next timeout (if any), 1793or C<ev_timer_again> is called, and determines the next timeout (if any),
1299which is also when any modifications are taken into account. 1794which is also when any modifications are taken into account.
1300 1795
1301=back 1796=back
1302 1797
1303=head3 Examples 1798=head3 Examples
1304 1799
1305Example: Create a timer that fires after 60 seconds. 1800Example: Create a timer that fires after 60 seconds.
1306 1801
1307 static void 1802 static void
1308 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1803 one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents)
1309 { 1804 {
1310 .. one minute over, w is actually stopped right here 1805 .. one minute over, w is actually stopped right here
1311 } 1806 }
1312 1807
1313 struct ev_timer mytimer; 1808 ev_timer mytimer;
1314 ev_timer_init (&mytimer, one_minute_cb, 60., 0.); 1809 ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1315 ev_timer_start (loop, &mytimer); 1810 ev_timer_start (loop, &mytimer);
1316 1811
1317Example: Create a timeout timer that times out after 10 seconds of 1812Example: Create a timeout timer that times out after 10 seconds of
1318inactivity. 1813inactivity.
1319 1814
1320 static void 1815 static void
1321 timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1816 timeout_cb (struct ev_loop *loop, ev_timer *w, int revents)
1322 { 1817 {
1323 .. ten seconds without any activity 1818 .. ten seconds without any activity
1324 } 1819 }
1325 1820
1326 struct ev_timer mytimer; 1821 ev_timer mytimer;
1327 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 1822 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1328 ev_timer_again (&mytimer); /* start timer */ 1823 ev_timer_again (&mytimer); /* start timer */
1329 ev_loop (loop, 0); 1824 ev_loop (loop, 0);
1330 1825
1331 // and in some piece of code that gets executed on any "activity": 1826 // and in some piece of code that gets executed on any "activity":
1336=head2 C<ev_periodic> - to cron or not to cron? 1831=head2 C<ev_periodic> - to cron or not to cron?
1337 1832
1338Periodic watchers are also timers of a kind, but they are very versatile 1833Periodic watchers are also timers of a kind, but they are very versatile
1339(and unfortunately a bit complex). 1834(and unfortunately a bit complex).
1340 1835
1341Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1836Unlike C<ev_timer>, periodic watchers are not based on real time (or
1342but on wall clock time (absolute time). You can tell a periodic watcher 1837relative time, the physical time that passes) but on wall clock time
1343to trigger after some specific point in time. For example, if you tell a 1838(absolute time, the thing you can read on your calender or clock). The
1344periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now () 1839difference is that wall clock time can run faster or slower than real
1345+ 10.>, that is, an absolute time not a delay) and then reset your system 1840time, and time jumps are not uncommon (e.g. when you adjust your
1346clock to January of the previous year, then it will take more than year 1841wrist-watch).
1347to trigger the event (unlike an C<ev_timer>, which would still trigger
1348roughly 10 seconds later as it uses a relative timeout).
1349 1842
1843You can tell a periodic watcher to trigger after some specific point
1844in time: for example, if you tell a periodic watcher to trigger "in 10
1845seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
1846not a delay) and then reset your system clock to January of the previous
1847year, then it will take a year or more to trigger the event (unlike an
1848C<ev_timer>, which would still trigger roughly 10 seconds after starting
1849it, as it uses a relative timeout).
1850
1350C<ev_periodic>s can also be used to implement vastly more complex timers, 1851C<ev_periodic> watchers can also be used to implement vastly more complex
1351such as triggering an event on each "midnight, local time", or other 1852timers, such as triggering an event on each "midnight, local time", or
1352complicated, rules. 1853other complicated rules. This cannot be done with C<ev_timer> watchers, as
1854those cannot react to time jumps.
1353 1855
1354As with timers, the callback is guaranteed to be invoked only when the 1856As with timers, the callback is guaranteed to be invoked only when the
1355time (C<at>) has passed, but if multiple periodic timers become ready 1857point in time where it is supposed to trigger has passed. If multiple
1356during the same loop iteration then order of execution is undefined. 1858timers become ready during the same loop iteration then the ones with
1859earlier time-out values are invoked before ones with later time-out values
1860(but this is no longer true when a callback calls C<ev_loop> recursively).
1357 1861
1358=head3 Watcher-Specific Functions and Data Members 1862=head3 Watcher-Specific Functions and Data Members
1359 1863
1360=over 4 1864=over 4
1361 1865
1362=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1866=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1363 1867
1364=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1868=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1365 1869
1366Lots of arguments, lets sort it out... There are basically three modes of 1870Lots of arguments, let's sort it out... There are basically three modes of
1367operation, and we will explain them from simplest to complex: 1871operation, and we will explain them from simplest to most complex:
1368 1872
1369=over 4 1873=over 4
1370 1874
1371=item * absolute timer (at = time, interval = reschedule_cb = 0) 1875=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1372 1876
1373In this configuration the watcher triggers an event after the wall clock 1877In this configuration the watcher triggers an event after the wall clock
1374time C<at> has passed and doesn't repeat. It will not adjust when a time 1878time C<offset> has passed. It will not repeat and will not adjust when a
1375jump occurs, that is, if it is to be run at January 1st 2011 then it will 1879time jump occurs, that is, if it is to be run at January 1st 2011 then it
1376run when the system time reaches or surpasses this time. 1880will be stopped and invoked when the system clock reaches or surpasses
1881this point in time.
1377 1882
1378=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1883=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1379 1884
1380In this mode the watcher will always be scheduled to time out at the next 1885In this mode the watcher will always be scheduled to time out at the next
1381C<at + N * interval> time (for some integer N, which can also be negative) 1886C<offset + N * interval> time (for some integer N, which can also be
1382and then repeat, regardless of any time jumps. 1887negative) and then repeat, regardless of any time jumps. The C<offset>
1888argument is merely an offset into the C<interval> periods.
1383 1889
1384This can be used to create timers that do not drift with respect to system 1890This can be used to create timers that do not drift with respect to the
1385time, for example, here is a C<ev_periodic> that triggers each hour, on 1891system clock, for example, here is an C<ev_periodic> that triggers each
1386the hour: 1892hour, on the hour (with respect to UTC):
1387 1893
1388 ev_periodic_set (&periodic, 0., 3600., 0); 1894 ev_periodic_set (&periodic, 0., 3600., 0);
1389 1895
1390This doesn't mean there will always be 3600 seconds in between triggers, 1896This doesn't mean there will always be 3600 seconds in between triggers,
1391but only that the callback will be called when the system time shows a 1897but only that the callback will be called when the system time shows a
1392full hour (UTC), or more correctly, when the system time is evenly divisible 1898full hour (UTC), or more correctly, when the system time is evenly divisible
1393by 3600. 1899by 3600.
1394 1900
1395Another way to think about it (for the mathematically inclined) is that 1901Another way to think about it (for the mathematically inclined) is that
1396C<ev_periodic> will try to run the callback in this mode at the next possible 1902C<ev_periodic> will try to run the callback in this mode at the next possible
1397time where C<time = at (mod interval)>, regardless of any time jumps. 1903time where C<time = offset (mod interval)>, regardless of any time jumps.
1398 1904
1399For numerical stability it is preferable that the C<at> value is near 1905For numerical stability it is preferable that the C<offset> value is near
1400C<ev_now ()> (the current time), but there is no range requirement for 1906C<ev_now ()> (the current time), but there is no range requirement for
1401this value, and in fact is often specified as zero. 1907this value, and in fact is often specified as zero.
1402 1908
1403Note also that there is an upper limit to how often a timer can fire (CPU 1909Note also that there is an upper limit to how often a timer can fire (CPU
1404speed for example), so if C<interval> is very small then timing stability 1910speed for example), so if C<interval> is very small then timing stability
1405will of course deteriorate. Libev itself tries to be exact to be about one 1911will of course deteriorate. Libev itself tries to be exact to be about one
1406millisecond (if the OS supports it and the machine is fast enough). 1912millisecond (if the OS supports it and the machine is fast enough).
1407 1913
1408=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1914=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1409 1915
1410In this mode the values for C<interval> and C<at> are both being 1916In this mode the values for C<interval> and C<offset> are both being
1411ignored. Instead, each time the periodic watcher gets scheduled, the 1917ignored. Instead, each time the periodic watcher gets scheduled, the
1412reschedule callback will be called with the watcher as first, and the 1918reschedule callback will be called with the watcher as first, and the
1413current time as second argument. 1919current time as second argument.
1414 1920
1415NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1921NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1416ever, or make ANY event loop modifications whatsoever>. 1922or make ANY other event loop modifications whatsoever, unless explicitly
1923allowed by documentation here>.
1417 1924
1418If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 1925If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1419it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 1926it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1420only event loop modification you are allowed to do). 1927only event loop modification you are allowed to do).
1421 1928
1422The callback prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic 1929The callback prototype is C<ev_tstamp (*reschedule_cb)(ev_periodic
1423*w, ev_tstamp now)>, e.g.: 1930*w, ev_tstamp now)>, e.g.:
1424 1931
1932 static ev_tstamp
1425 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1933 my_rescheduler (ev_periodic *w, ev_tstamp now)
1426 { 1934 {
1427 return now + 60.; 1935 return now + 60.;
1428 } 1936 }
1429 1937
1430It must return the next time to trigger, based on the passed time value 1938It must return the next time to trigger, based on the passed time value
1450a different time than the last time it was called (e.g. in a crond like 1958a different time than the last time it was called (e.g. in a crond like
1451program when the crontabs have changed). 1959program when the crontabs have changed).
1452 1960
1453=item ev_tstamp ev_periodic_at (ev_periodic *) 1961=item ev_tstamp ev_periodic_at (ev_periodic *)
1454 1962
1455When active, returns the absolute time that the watcher is supposed to 1963When active, returns the absolute time that the watcher is supposed
1456trigger next. 1964to trigger next. This is not the same as the C<offset> argument to
1965C<ev_periodic_set>, but indeed works even in interval and manual
1966rescheduling modes.
1457 1967
1458=item ev_tstamp offset [read-write] 1968=item ev_tstamp offset [read-write]
1459 1969
1460When repeating, this contains the offset value, otherwise this is the 1970When repeating, this contains the offset value, otherwise this is the
1461absolute point in time (the C<at> value passed to C<ev_periodic_set>). 1971absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
1972although libev might modify this value for better numerical stability).
1462 1973
1463Can be modified any time, but changes only take effect when the periodic 1974Can be modified any time, but changes only take effect when the periodic
1464timer fires or C<ev_periodic_again> is being called. 1975timer fires or C<ev_periodic_again> is being called.
1465 1976
1466=item ev_tstamp interval [read-write] 1977=item ev_tstamp interval [read-write]
1467 1978
1468The current interval value. Can be modified any time, but changes only 1979The current interval value. Can be modified any time, but changes only
1469take effect when the periodic timer fires or C<ev_periodic_again> is being 1980take effect when the periodic timer fires or C<ev_periodic_again> is being
1470called. 1981called.
1471 1982
1472=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] 1983=item ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]
1473 1984
1474The current reschedule callback, or C<0>, if this functionality is 1985The current reschedule callback, or C<0>, if this functionality is
1475switched off. Can be changed any time, but changes only take effect when 1986switched off. Can be changed any time, but changes only take effect when
1476the periodic timer fires or C<ev_periodic_again> is being called. 1987the periodic timer fires or C<ev_periodic_again> is being called.
1477 1988
1478=back 1989=back
1479 1990
1480=head3 Examples 1991=head3 Examples
1481 1992
1482Example: Call a callback every hour, or, more precisely, whenever the 1993Example: Call a callback every hour, or, more precisely, whenever the
1483system clock is divisible by 3600. The callback invocation times have 1994system time is divisible by 3600. The callback invocation times have
1484potentially a lot of jitter, but good long-term stability. 1995potentially a lot of jitter, but good long-term stability.
1485 1996
1486 static void 1997 static void
1487 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1998 clock_cb (struct ev_loop *loop, ev_io *w, int revents)
1488 { 1999 {
1489 ... its now a full hour (UTC, or TAI or whatever your clock follows) 2000 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1490 } 2001 }
1491 2002
1492 struct ev_periodic hourly_tick; 2003 ev_periodic hourly_tick;
1493 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); 2004 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1494 ev_periodic_start (loop, &hourly_tick); 2005 ev_periodic_start (loop, &hourly_tick);
1495 2006
1496Example: The same as above, but use a reschedule callback to do it: 2007Example: The same as above, but use a reschedule callback to do it:
1497 2008
1498 #include <math.h> 2009 #include <math.h>
1499 2010
1500 static ev_tstamp 2011 static ev_tstamp
1501 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 2012 my_scheduler_cb (ev_periodic *w, ev_tstamp now)
1502 { 2013 {
1503 return fmod (now, 3600.) + 3600.; 2014 return now + (3600. - fmod (now, 3600.));
1504 } 2015 }
1505 2016
1506 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); 2017 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1507 2018
1508Example: Call a callback every hour, starting now: 2019Example: Call a callback every hour, starting now:
1509 2020
1510 struct ev_periodic hourly_tick; 2021 ev_periodic hourly_tick;
1511 ev_periodic_init (&hourly_tick, clock_cb, 2022 ev_periodic_init (&hourly_tick, clock_cb,
1512 fmod (ev_now (loop), 3600.), 3600., 0); 2023 fmod (ev_now (loop), 3600.), 3600., 0);
1513 ev_periodic_start (loop, &hourly_tick); 2024 ev_periodic_start (loop, &hourly_tick);
1514 2025
1515 2026
1518Signal watchers will trigger an event when the process receives a specific 2029Signal watchers will trigger an event when the process receives a specific
1519signal one or more times. Even though signals are very asynchronous, libev 2030signal one or more times. Even though signals are very asynchronous, libev
1520will try it's best to deliver signals synchronously, i.e. as part of the 2031will try it's best to deliver signals synchronously, i.e. as part of the
1521normal event processing, like any other event. 2032normal event processing, like any other event.
1522 2033
2034If you want signals asynchronously, just use C<sigaction> as you would
2035do without libev and forget about sharing the signal. You can even use
2036C<ev_async> from a signal handler to synchronously wake up an event loop.
2037
1523You can configure as many watchers as you like per signal. Only when the 2038You can configure as many watchers as you like per signal. Only when the
1524first watcher gets started will libev actually register a signal watcher 2039first watcher gets started will libev actually register a signal handler
1525with the kernel (thus it coexists with your own signal handlers as long 2040with the kernel (thus it coexists with your own signal handlers as long as
1526as you don't register any with libev). Similarly, when the last signal 2041you don't register any with libev for the same signal). Similarly, when
1527watcher for a signal is stopped libev will reset the signal handler to 2042the last signal watcher for a signal is stopped, libev will reset the
1528SIG_DFL (regardless of what it was set to before). 2043signal handler to SIG_DFL (regardless of what it was set to before).
1529 2044
1530If possible and supported, libev will install its handlers with 2045If possible and supported, libev will install its handlers with
1531C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2046C<SA_RESTART> behaviour enabled, so system calls should not be unduly
1532interrupted. If you have a problem with system calls getting interrupted by 2047interrupted. If you have a problem with system calls getting interrupted by
1533signals you can block all signals in an C<ev_check> watcher and unblock 2048signals you can block all signals in an C<ev_check> watcher and unblock
1550 2065
1551=back 2066=back
1552 2067
1553=head3 Examples 2068=head3 Examples
1554 2069
1555Example: Try to exit cleanly on SIGINT and SIGTERM. 2070Example: Try to exit cleanly on SIGINT.
1556 2071
1557 static void 2072 static void
1558 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 2073 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
1559 { 2074 {
1560 ev_unloop (loop, EVUNLOOP_ALL); 2075 ev_unloop (loop, EVUNLOOP_ALL);
1561 } 2076 }
1562 2077
1563 struct ev_signal signal_watcher; 2078 ev_signal signal_watcher;
1564 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 2079 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1565 ev_signal_start (loop, &sigint_cb); 2080 ev_signal_start (loop, &signal_watcher);
1566 2081
1567 2082
1568=head2 C<ev_child> - watch out for process status changes 2083=head2 C<ev_child> - watch out for process status changes
1569 2084
1570Child watchers trigger when your process receives a SIGCHLD in response to 2085Child watchers trigger when your process receives a SIGCHLD in response to
1571some child status changes (most typically when a child of yours dies). It 2086some child status changes (most typically when a child of yours dies or
1572is permissible to install a child watcher I<after> the child has been 2087exits). It is permissible to install a child watcher I<after> the child
1573forked (which implies it might have already exited), as long as the event 2088has been forked (which implies it might have already exited), as long
1574loop isn't entered (or is continued from a watcher). 2089as the event loop isn't entered (or is continued from a watcher), i.e.,
2090forking and then immediately registering a watcher for the child is fine,
2091but forking and registering a watcher a few event loop iterations later or
2092in the next callback invocation is not.
1575 2093
1576Only the default event loop is capable of handling signals, and therefore 2094Only the default event loop is capable of handling signals, and therefore
1577you can only register child watchers in the default event loop. 2095you can only register child watchers in the default event loop.
2096
2097Due to some design glitches inside libev, child watchers will always be
2098handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2099libev)
1578 2100
1579=head3 Process Interaction 2101=head3 Process Interaction
1580 2102
1581Libev grabs C<SIGCHLD> as soon as the default event loop is 2103Libev grabs C<SIGCHLD> as soon as the default event loop is
1582initialised. This is necessary to guarantee proper behaviour even if 2104initialised. This is necessary to guarantee proper behaviour even if
1640its completion. 2162its completion.
1641 2163
1642 ev_child cw; 2164 ev_child cw;
1643 2165
1644 static void 2166 static void
1645 child_cb (EV_P_ struct ev_child *w, int revents) 2167 child_cb (EV_P_ ev_child *w, int revents)
1646 { 2168 {
1647 ev_child_stop (EV_A_ w); 2169 ev_child_stop (EV_A_ w);
1648 printf ("process %d exited with status %x\n", w->rpid, w->rstatus); 2170 printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
1649 } 2171 }
1650 2172
1665 2187
1666 2188
1667=head2 C<ev_stat> - did the file attributes just change? 2189=head2 C<ev_stat> - did the file attributes just change?
1668 2190
1669This watches a file system path for attribute changes. That is, it calls 2191This watches a file system path for attribute changes. That is, it calls
1670C<stat> regularly (or when the OS says it changed) and sees if it changed 2192C<stat> on that path in regular intervals (or when the OS says it changed)
1671compared to the last time, invoking the callback if it did. 2193and sees if it changed compared to the last time, invoking the callback if
2194it did.
1672 2195
1673The path does not need to exist: changing from "path exists" to "path does 2196The path does not need to exist: changing from "path exists" to "path does
1674not exist" is a status change like any other. The condition "path does 2197not exist" is a status change like any other. The condition "path does not
1675not exist" is signified by the C<st_nlink> field being zero (which is 2198exist" (or more correctly "path cannot be stat'ed") is signified by the
1676otherwise always forced to be at least one) and all the other fields of 2199C<st_nlink> field being zero (which is otherwise always forced to be at
1677the stat buffer having unspecified contents. 2200least one) and all the other fields of the stat buffer having unspecified
2201contents.
1678 2202
1679The path I<should> be absolute and I<must not> end in a slash. If it is 2203The path I<must not> end in a slash or contain special components such as
2204C<.> or C<..>. The path I<should> be absolute: If it is relative and
1680relative and your working directory changes, the behaviour is undefined. 2205your working directory changes, then the behaviour is undefined.
1681 2206
1682Since there is no standard to do this, the portable implementation simply 2207Since there is no portable change notification interface available, the
1683calls C<stat (2)> regularly on the path to see if it changed somehow. You 2208portable implementation simply calls C<stat(2)> regularly on the path
1684can specify a recommended polling interval for this case. If you specify 2209to see if it changed somehow. You can specify a recommended polling
1685a polling interval of C<0> (highly recommended!) then a I<suitable, 2210interval for this case. If you specify a polling interval of C<0> (highly
1686unspecified default> value will be used (which you can expect to be around 2211recommended!) then a I<suitable, unspecified default> value will be used
1687five seconds, although this might change dynamically). Libev will also 2212(which you can expect to be around five seconds, although this might
1688impose a minimum interval which is currently around C<0.1>, but thats 2213change dynamically). Libev will also impose a minimum interval which is
1689usually overkill. 2214currently around C<0.1>, but that's usually overkill.
1690 2215
1691This watcher type is not meant for massive numbers of stat watchers, 2216This watcher type is not meant for massive numbers of stat watchers,
1692as even with OS-supported change notifications, this can be 2217as even with OS-supported change notifications, this can be
1693resource-intensive. 2218resource-intensive.
1694 2219
1695At the time of this writing, only the Linux inotify interface is 2220At the time of this writing, the only OS-specific interface implemented
1696implemented (implementing kqueue support is left as an exercise for the 2221is the Linux inotify interface (implementing kqueue support is left as an
1697reader, note, however, that the author sees no way of implementing ev_stat 2222exercise for the reader. Note, however, that the author sees no way of
1698semantics with kqueue). Inotify will be used to give hints only and should 2223implementing C<ev_stat> semantics with kqueue, except as a hint).
1699not change the semantics of C<ev_stat> watchers, which means that libev
1700sometimes needs to fall back to regular polling again even with inotify,
1701but changes are usually detected immediately, and if the file exists there
1702will be no polling.
1703 2224
1704=head3 ABI Issues (Largefile Support) 2225=head3 ABI Issues (Largefile Support)
1705 2226
1706Libev by default (unless the user overrides this) uses the default 2227Libev by default (unless the user overrides this) uses the default
1707compilation environment, which means that on systems with large file 2228compilation environment, which means that on systems with large file
1708support disabled by default, you get the 32 bit version of the stat 2229support disabled by default, you get the 32 bit version of the stat
1709structure. When using the library from programs that change the ABI to 2230structure. When using the library from programs that change the ABI to
1710use 64 bit file offsets the programs will fail. In that case you have to 2231use 64 bit file offsets the programs will fail. In that case you have to
1711compile libev with the same flags to get binary compatibility. This is 2232compile libev with the same flags to get binary compatibility. This is
1712obviously the case with any flags that change the ABI, but the problem is 2233obviously the case with any flags that change the ABI, but the problem is
1713most noticeably disabled with ev_stat and large file support. 2234most noticeably displayed with ev_stat and large file support.
1714 2235
1715The solution for this is to lobby your distribution maker to make large 2236The solution for this is to lobby your distribution maker to make large
1716file interfaces available by default (as e.g. FreeBSD does) and not 2237file interfaces available by default (as e.g. FreeBSD does) and not
1717optional. Libev cannot simply switch on large file support because it has 2238optional. Libev cannot simply switch on large file support because it has
1718to exchange stat structures with application programs compiled using the 2239to exchange stat structures with application programs compiled using the
1719default compilation environment. 2240default compilation environment.
1720 2241
1721=head3 Inotify 2242=head3 Inotify and Kqueue
1722 2243
1723When C<inotify (7)> support has been compiled into libev (generally only 2244When C<inotify (7)> support has been compiled into libev and present at
1724available on Linux) and present at runtime, it will be used to speed up 2245runtime, it will be used to speed up change detection where possible. The
1725change detection where possible. The inotify descriptor will be created lazily 2246inotify descriptor will be created lazily when the first C<ev_stat>
1726when the first C<ev_stat> watcher is being started. 2247watcher is being started.
1727 2248
1728Inotify presence does not change the semantics of C<ev_stat> watchers 2249Inotify presence does not change the semantics of C<ev_stat> watchers
1729except that changes might be detected earlier, and in some cases, to avoid 2250except that changes might be detected earlier, and in some cases, to avoid
1730making regular C<stat> calls. Even in the presence of inotify support 2251making regular C<stat> calls. Even in the presence of inotify support
1731there are many cases where libev has to resort to regular C<stat> polling. 2252there are many cases where libev has to resort to regular C<stat> polling,
2253but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too
2254many bugs), the path exists (i.e. stat succeeds), and the path resides on
2255a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and
2256xfs are fully working) libev usually gets away without polling.
1732 2257
1733(There is no support for kqueue, as apparently it cannot be used to 2258There is no support for kqueue, as apparently it cannot be used to
1734implement this functionality, due to the requirement of having a file 2259implement this functionality, due to the requirement of having a file
1735descriptor open on the object at all times). 2260descriptor open on the object at all times, and detecting renames, unlinks
2261etc. is difficult.
2262
2263=head3 C<stat ()> is a synchronous operation
2264
2265Libev doesn't normally do any kind of I/O itself, and so is not blocking
2266the process. The exception are C<ev_stat> watchers - those call C<stat
2267()>, which is a synchronous operation.
2268
2269For local paths, this usually doesn't matter: unless the system is very
2270busy or the intervals between stat's are large, a stat call will be fast,
2271as the path data is usually in memory already (except when starting the
2272watcher).
2273
2274For networked file systems, calling C<stat ()> can block an indefinite
2275time due to network issues, and even under good conditions, a stat call
2276often takes multiple milliseconds.
2277
2278Therefore, it is best to avoid using C<ev_stat> watchers on networked
2279paths, although this is fully supported by libev.
1736 2280
1737=head3 The special problem of stat time resolution 2281=head3 The special problem of stat time resolution
1738 2282
1739The C<stat ()> system call only supports full-second resolution portably, and 2283The C<stat ()> system call only supports full-second resolution portably,
1740even on systems where the resolution is higher, many file systems still 2284and even on systems where the resolution is higher, most file systems
1741only support whole seconds. 2285still only support whole seconds.
1742 2286
1743That means that, if the time is the only thing that changes, you can 2287That means that, if the time is the only thing that changes, you can
1744easily miss updates: on the first update, C<ev_stat> detects a change and 2288easily miss updates: on the first update, C<ev_stat> detects a change and
1745calls your callback, which does something. When there is another update 2289calls your callback, which does something. When there is another update
1746within the same second, C<ev_stat> will be unable to detect it as the stat 2290within the same second, C<ev_stat> will be unable to detect unless the
1747data does not change. 2291stat data does change in other ways (e.g. file size).
1748 2292
1749The solution to this is to delay acting on a change for slightly more 2293The solution to this is to delay acting on a change for slightly more
1750than a second (or till slightly after the next full second boundary), using 2294than a second (or till slightly after the next full second boundary), using
1751a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02); 2295a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
1752ev_timer_again (loop, w)>). 2296ev_timer_again (loop, w)>).
1772C<path>. The C<interval> is a hint on how quickly a change is expected to 2316C<path>. The C<interval> is a hint on how quickly a change is expected to
1773be detected and should normally be specified as C<0> to let libev choose 2317be detected and should normally be specified as C<0> to let libev choose
1774a suitable value. The memory pointed to by C<path> must point to the same 2318a suitable value. The memory pointed to by C<path> must point to the same
1775path for as long as the watcher is active. 2319path for as long as the watcher is active.
1776 2320
1777The callback will receive C<EV_STAT> when a change was detected, relative 2321The callback will receive an C<EV_STAT> event when a change was detected,
1778to the attributes at the time the watcher was started (or the last change 2322relative to the attributes at the time the watcher was started (or the
1779was detected). 2323last change was detected).
1780 2324
1781=item ev_stat_stat (loop, ev_stat *) 2325=item ev_stat_stat (loop, ev_stat *)
1782 2326
1783Updates the stat buffer immediately with new values. If you change the 2327Updates the stat buffer immediately with new values. If you change the
1784watched path in your callback, you could call this function to avoid 2328watched path in your callback, you could call this function to avoid
1867 2411
1868 2412
1869=head2 C<ev_idle> - when you've got nothing better to do... 2413=head2 C<ev_idle> - when you've got nothing better to do...
1870 2414
1871Idle watchers trigger events when no other events of the same or higher 2415Idle watchers trigger events when no other events of the same or higher
1872priority are pending (prepare, check and other idle watchers do not 2416priority are pending (prepare, check and other idle watchers do not count
1873count). 2417as receiving "events").
1874 2418
1875That is, as long as your process is busy handling sockets or timeouts 2419That is, as long as your process is busy handling sockets or timeouts
1876(or even signals, imagine) of the same or higher priority it will not be 2420(or even signals, imagine) of the same or higher priority it will not be
1877triggered. But when your process is idle (or only lower-priority watchers 2421triggered. But when your process is idle (or only lower-priority watchers
1878are pending), the idle watchers are being called once per event loop 2422are pending), the idle watchers are being called once per event loop
1889 2433
1890=head3 Watcher-Specific Functions and Data Members 2434=head3 Watcher-Specific Functions and Data Members
1891 2435
1892=over 4 2436=over 4
1893 2437
1894=item ev_idle_init (ev_signal *, callback) 2438=item ev_idle_init (ev_idle *, callback)
1895 2439
1896Initialises and configures the idle watcher - it has no parameters of any 2440Initialises and configures the idle watcher - it has no parameters of any
1897kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 2441kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
1898believe me. 2442believe me.
1899 2443
1903 2447
1904Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the 2448Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
1905callback, free it. Also, use no error checking, as usual. 2449callback, free it. Also, use no error checking, as usual.
1906 2450
1907 static void 2451 static void
1908 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) 2452 idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
1909 { 2453 {
1910 free (w); 2454 free (w);
1911 // now do something you wanted to do when the program has 2455 // now do something you wanted to do when the program has
1912 // no longer anything immediate to do. 2456 // no longer anything immediate to do.
1913 } 2457 }
1914 2458
1915 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 2459 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
1916 ev_idle_init (idle_watcher, idle_cb); 2460 ev_idle_init (idle_watcher, idle_cb);
1917 ev_idle_start (loop, idle_cb); 2461 ev_idle_start (loop, idle_watcher);
1918 2462
1919 2463
1920=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2464=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
1921 2465
1922Prepare and check watchers are usually (but not always) used in tandem: 2466Prepare and check watchers are usually (but not always) used in pairs:
1923prepare watchers get invoked before the process blocks and check watchers 2467prepare watchers get invoked before the process blocks and check watchers
1924afterwards. 2468afterwards.
1925 2469
1926You I<must not> call C<ev_loop> or similar functions that enter 2470You I<must not> call C<ev_loop> or similar functions that enter
1927the current event loop from either C<ev_prepare> or C<ev_check> 2471the current event loop from either C<ev_prepare> or C<ev_check>
1930those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 2474those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
1931C<ev_check> so if you have one watcher of each kind they will always be 2475C<ev_check> so if you have one watcher of each kind they will always be
1932called in pairs bracketing the blocking call. 2476called in pairs bracketing the blocking call.
1933 2477
1934Their main purpose is to integrate other event mechanisms into libev and 2478Their main purpose is to integrate other event mechanisms into libev and
1935their use is somewhat advanced. This could be used, for example, to track 2479their use is somewhat advanced. They could be used, for example, to track
1936variable changes, implement your own watchers, integrate net-snmp or a 2480variable changes, implement your own watchers, integrate net-snmp or a
1937coroutine library and lots more. They are also occasionally useful if 2481coroutine library and lots more. They are also occasionally useful if
1938you cache some data and want to flush it before blocking (for example, 2482you cache some data and want to flush it before blocking (for example,
1939in X programs you might want to do an C<XFlush ()> in an C<ev_prepare> 2483in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
1940watcher). 2484watcher).
1941 2485
1942This is done by examining in each prepare call which file descriptors need 2486This is done by examining in each prepare call which file descriptors
1943to be watched by the other library, registering C<ev_io> watchers for 2487need to be watched by the other library, registering C<ev_io> watchers
1944them and starting an C<ev_timer> watcher for any timeouts (many libraries 2488for them and starting an C<ev_timer> watcher for any timeouts (many
1945provide just this functionality). Then, in the check watcher you check for 2489libraries provide exactly this functionality). Then, in the check watcher,
1946any events that occurred (by checking the pending status of all watchers 2490you check for any events that occurred (by checking the pending status
1947and stopping them) and call back into the library. The I/O and timer 2491of all watchers and stopping them) and call back into the library. The
1948callbacks will never actually be called (but must be valid nevertheless, 2492I/O and timer callbacks will never actually be called (but must be valid
1949because you never know, you know?). 2493nevertheless, because you never know, you know?).
1950 2494
1951As another example, the Perl Coro module uses these hooks to integrate 2495As another example, the Perl Coro module uses these hooks to integrate
1952coroutines into libev programs, by yielding to other active coroutines 2496coroutines into libev programs, by yielding to other active coroutines
1953during each prepare and only letting the process block if no coroutines 2497during each prepare and only letting the process block if no coroutines
1954are ready to run (it's actually more complicated: it only runs coroutines 2498are ready to run (it's actually more complicated: it only runs coroutines
1957loop from blocking if lower-priority coroutines are active, thus mapping 2501loop from blocking if lower-priority coroutines are active, thus mapping
1958low-priority coroutines to idle/background tasks). 2502low-priority coroutines to idle/background tasks).
1959 2503
1960It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 2504It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1961priority, to ensure that they are being run before any other watchers 2505priority, to ensure that they are being run before any other watchers
2506after the poll (this doesn't matter for C<ev_prepare> watchers).
2507
1962after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers, 2508Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not
1963too) should not activate ("feed") events into libev. While libev fully 2509activate ("feed") events into libev. While libev fully supports this, they
1964supports this, they might get executed before other C<ev_check> watchers 2510might get executed before other C<ev_check> watchers did their job. As
1965did their job. As C<ev_check> watchers are often used to embed other 2511C<ev_check> watchers are often used to embed other (non-libev) event
1966(non-libev) event loops those other event loops might be in an unusable 2512loops those other event loops might be in an unusable state until their
1967state until their C<ev_check> watcher ran (always remind yourself to 2513C<ev_check> watcher ran (always remind yourself to coexist peacefully with
1968coexist peacefully with others). 2514others).
1969 2515
1970=head3 Watcher-Specific Functions and Data Members 2516=head3 Watcher-Specific Functions and Data Members
1971 2517
1972=over 4 2518=over 4
1973 2519
1975 2521
1976=item ev_check_init (ev_check *, callback) 2522=item ev_check_init (ev_check *, callback)
1977 2523
1978Initialises and configures the prepare or check watcher - they have no 2524Initialises and configures the prepare or check watcher - they have no
1979parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 2525parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1980macros, but using them is utterly, utterly and completely pointless. 2526macros, but using them is utterly, utterly, utterly and completely
2527pointless.
1981 2528
1982=back 2529=back
1983 2530
1984=head3 Examples 2531=head3 Examples
1985 2532
1998 2545
1999 static ev_io iow [nfd]; 2546 static ev_io iow [nfd];
2000 static ev_timer tw; 2547 static ev_timer tw;
2001 2548
2002 static void 2549 static void
2003 io_cb (ev_loop *loop, ev_io *w, int revents) 2550 io_cb (struct ev_loop *loop, ev_io *w, int revents)
2004 { 2551 {
2005 } 2552 }
2006 2553
2007 // create io watchers for each fd and a timer before blocking 2554 // create io watchers for each fd and a timer before blocking
2008 static void 2555 static void
2009 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 2556 adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents)
2010 { 2557 {
2011 int timeout = 3600000; 2558 int timeout = 3600000;
2012 struct pollfd fds [nfd]; 2559 struct pollfd fds [nfd];
2013 // actual code will need to loop here and realloc etc. 2560 // actual code will need to loop here and realloc etc.
2014 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2561 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2015 2562
2016 /* the callback is illegal, but won't be called as we stop during check */ 2563 /* the callback is illegal, but won't be called as we stop during check */
2017 ev_timer_init (&tw, 0, timeout * 1e-3); 2564 ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
2018 ev_timer_start (loop, &tw); 2565 ev_timer_start (loop, &tw);
2019 2566
2020 // create one ev_io per pollfd 2567 // create one ev_io per pollfd
2021 for (int i = 0; i < nfd; ++i) 2568 for (int i = 0; i < nfd; ++i)
2022 { 2569 {
2029 } 2576 }
2030 } 2577 }
2031 2578
2032 // stop all watchers after blocking 2579 // stop all watchers after blocking
2033 static void 2580 static void
2034 adns_check_cb (ev_loop *loop, ev_check *w, int revents) 2581 adns_check_cb (struct ev_loop *loop, ev_check *w, int revents)
2035 { 2582 {
2036 ev_timer_stop (loop, &tw); 2583 ev_timer_stop (loop, &tw);
2037 2584
2038 for (int i = 0; i < nfd; ++i) 2585 for (int i = 0; i < nfd; ++i)
2039 { 2586 {
2078 } 2625 }
2079 2626
2080 // do not ever call adns_afterpoll 2627 // do not ever call adns_afterpoll
2081 2628
2082Method 4: Do not use a prepare or check watcher because the module you 2629Method 4: Do not use a prepare or check watcher because the module you
2083want to embed is too inflexible to support it. Instead, you can override 2630want to embed is not flexible enough to support it. Instead, you can
2084their poll function. The drawback with this solution is that the main 2631override their poll function. The drawback with this solution is that the
2085loop is now no longer controllable by EV. The C<Glib::EV> module does 2632main loop is now no longer controllable by EV. The C<Glib::EV> module uses
2086this. 2633this approach, effectively embedding EV as a client into the horrible
2634libglib event loop.
2087 2635
2088 static gint 2636 static gint
2089 event_poll_func (GPollFD *fds, guint nfds, gint timeout) 2637 event_poll_func (GPollFD *fds, guint nfds, gint timeout)
2090 { 2638 {
2091 int got_events = 0; 2639 int got_events = 0;
2122prioritise I/O. 2670prioritise I/O.
2123 2671
2124As an example for a bug workaround, the kqueue backend might only support 2672As an example for a bug workaround, the kqueue backend might only support
2125sockets on some platform, so it is unusable as generic backend, but you 2673sockets on some platform, so it is unusable as generic backend, but you
2126still want to make use of it because you have many sockets and it scales 2674still want to make use of it because you have many sockets and it scales
2127so nicely. In this case, you would create a kqueue-based loop and embed it 2675so nicely. In this case, you would create a kqueue-based loop and embed
2128into your default loop (which might use e.g. poll). Overall operation will 2676it into your default loop (which might use e.g. poll). Overall operation
2129be a bit slower because first libev has to poll and then call kevent, but 2677will be a bit slower because first libev has to call C<poll> and then
2130at least you can use both at what they are best. 2678C<kevent>, but at least you can use both mechanisms for what they are
2679best: C<kqueue> for scalable sockets and C<poll> if you want it to work :)
2131 2680
2132As for prioritising I/O: rarely you have the case where some fds have 2681As for prioritising I/O: under rare circumstances you have the case where
2133to be watched and handled very quickly (with low latency), and even 2682some fds have to be watched and handled very quickly (with low latency),
2134priorities and idle watchers might have too much overhead. In this case 2683and even priorities and idle watchers might have too much overhead. In
2135you would put all the high priority stuff in one loop and all the rest in 2684this case you would put all the high priority stuff in one loop and all
2136a second one, and embed the second one in the first. 2685the rest in a second one, and embed the second one in the first.
2137 2686
2138As long as the watcher is active, the callback will be invoked every time 2687As long as the watcher is active, the callback will be invoked every
2139there might be events pending in the embedded loop. The callback must then 2688time there might be events pending in the embedded loop. The callback
2140call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2689must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
2141their callbacks (you could also start an idle watcher to give the embedded 2690sweep and invoke their callbacks (the callback doesn't need to invoke the
2142loop strictly lower priority for example). You can also set the callback 2691C<ev_embed_sweep> function directly, it could also start an idle watcher
2143to C<0>, in which case the embed watcher will automatically execute the 2692to give the embedded loop strictly lower priority for example).
2144embedded loop sweep.
2145 2693
2146As long as the watcher is started it will automatically handle events. The 2694You can also set the callback to C<0>, in which case the embed watcher
2147callback will be invoked whenever some events have been handled. You can 2695will automatically execute the embedded loop sweep whenever necessary.
2148set the callback to C<0> to avoid having to specify one if you are not
2149interested in that.
2150 2696
2151Also, there have not currently been made special provisions for forking: 2697Fork detection will be handled transparently while the C<ev_embed> watcher
2152when you fork, you not only have to call C<ev_loop_fork> on both loops, 2698is active, i.e., the embedded loop will automatically be forked when the
2153but you will also have to stop and restart any C<ev_embed> watchers 2699embedding loop forks. In other cases, the user is responsible for calling
2154yourself. 2700C<ev_loop_fork> on the embedded loop.
2155 2701
2156Unfortunately, not all backends are embeddable, only the ones returned by 2702Unfortunately, not all backends are embeddable: only the ones returned by
2157C<ev_embeddable_backends> are, which, unfortunately, does not include any 2703C<ev_embeddable_backends> are, which, unfortunately, does not include any
2158portable one. 2704portable one.
2159 2705
2160So when you want to use this feature you will always have to be prepared 2706So when you want to use this feature you will always have to be prepared
2161that you cannot get an embeddable loop. The recommended way to get around 2707that you cannot get an embeddable loop. The recommended way to get around
2162this is to have a separate variables for your embeddable loop, try to 2708this is to have a separate variables for your embeddable loop, try to
2163create it, and if that fails, use the normal loop for everything. 2709create it, and if that fails, use the normal loop for everything.
2710
2711=head3 C<ev_embed> and fork
2712
2713While the C<ev_embed> watcher is running, forks in the embedding loop will
2714automatically be applied to the embedded loop as well, so no special
2715fork handling is required in that case. When the watcher is not running,
2716however, it is still the task of the libev user to call C<ev_loop_fork ()>
2717as applicable.
2164 2718
2165=head3 Watcher-Specific Functions and Data Members 2719=head3 Watcher-Specific Functions and Data Members
2166 2720
2167=over 4 2721=over 4
2168 2722
2196C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be 2750C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be
2197used). 2751used).
2198 2752
2199 struct ev_loop *loop_hi = ev_default_init (0); 2753 struct ev_loop *loop_hi = ev_default_init (0);
2200 struct ev_loop *loop_lo = 0; 2754 struct ev_loop *loop_lo = 0;
2201 struct ev_embed embed; 2755 ev_embed embed;
2202 2756
2203 // see if there is a chance of getting one that works 2757 // see if there is a chance of getting one that works
2204 // (remember that a flags value of 0 means autodetection) 2758 // (remember that a flags value of 0 means autodetection)
2205 loop_lo = ev_embeddable_backends () & ev_recommended_backends () 2759 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2206 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 2760 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2220kqueue implementation). Store the kqueue/socket-only event loop in 2774kqueue implementation). Store the kqueue/socket-only event loop in
2221C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). 2775C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
2222 2776
2223 struct ev_loop *loop = ev_default_init (0); 2777 struct ev_loop *loop = ev_default_init (0);
2224 struct ev_loop *loop_socket = 0; 2778 struct ev_loop *loop_socket = 0;
2225 struct ev_embed embed; 2779 ev_embed embed;
2226 2780
2227 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 2781 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2228 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 2782 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2229 { 2783 {
2230 ev_embed_init (&embed, 0, loop_socket); 2784 ev_embed_init (&embed, 0, loop_socket);
2245event loop blocks next and before C<ev_check> watchers are being called, 2799event loop blocks next and before C<ev_check> watchers are being called,
2246and only in the child after the fork. If whoever good citizen calling 2800and only in the child after the fork. If whoever good citizen calling
2247C<ev_default_fork> cheats and calls it in the wrong process, the fork 2801C<ev_default_fork> cheats and calls it in the wrong process, the fork
2248handlers will be invoked, too, of course. 2802handlers will be invoked, too, of course.
2249 2803
2804=head3 The special problem of life after fork - how is it possible?
2805
2806Most uses of C<fork()> consist of forking, then some simple calls to ste
2807up/change the process environment, followed by a call to C<exec()>. This
2808sequence should be handled by libev without any problems.
2809
2810This changes when the application actually wants to do event handling
2811in the child, or both parent in child, in effect "continuing" after the
2812fork.
2813
2814The default mode of operation (for libev, with application help to detect
2815forks) is to duplicate all the state in the child, as would be expected
2816when I<either> the parent I<or> the child process continues.
2817
2818When both processes want to continue using libev, then this is usually the
2819wrong result. In that case, usually one process (typically the parent) is
2820supposed to continue with all watchers in place as before, while the other
2821process typically wants to start fresh, i.e. without any active watchers.
2822
2823The cleanest and most efficient way to achieve that with libev is to
2824simply create a new event loop, which of course will be "empty", and
2825use that for new watchers. This has the advantage of not touching more
2826memory than necessary, and thus avoiding the copy-on-write, and the
2827disadvantage of having to use multiple event loops (which do not support
2828signal watchers).
2829
2830When this is not possible, or you want to use the default loop for
2831other reasons, then in the process that wants to start "fresh", call
2832C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
2833the default loop will "orphan" (not stop) all registered watchers, so you
2834have to be careful not to execute code that modifies those watchers. Note
2835also that in that case, you have to re-register any signal watchers.
2836
2250=head3 Watcher-Specific Functions and Data Members 2837=head3 Watcher-Specific Functions and Data Members
2251 2838
2252=over 4 2839=over 4
2253 2840
2254=item ev_fork_init (ev_signal *, callback) 2841=item ev_fork_init (ev_signal *, callback)
2286is that the author does not know of a simple (or any) algorithm for a 2873is that the author does not know of a simple (or any) algorithm for a
2287multiple-writer-single-reader queue that works in all cases and doesn't 2874multiple-writer-single-reader queue that works in all cases and doesn't
2288need elaborate support such as pthreads. 2875need elaborate support such as pthreads.
2289 2876
2290That means that if you want to queue data, you have to provide your own 2877That means that if you want to queue data, you have to provide your own
2291queue. But at least I can tell you would implement locking around your 2878queue. But at least I can tell you how to implement locking around your
2292queue: 2879queue:
2293 2880
2294=over 4 2881=over 4
2295 2882
2296=item queueing from a signal handler context 2883=item queueing from a signal handler context
2297 2884
2298To implement race-free queueing, you simply add to the queue in the signal 2885To implement race-free queueing, you simply add to the queue in the signal
2299handler but you block the signal handler in the watcher callback. Here is an example that does that for 2886handler but you block the signal handler in the watcher callback. Here is
2300some fictitious SIGUSR1 handler: 2887an example that does that for some fictitious SIGUSR1 handler:
2301 2888
2302 static ev_async mysig; 2889 static ev_async mysig;
2303 2890
2304 static void 2891 static void
2305 sigusr1_handler (void) 2892 sigusr1_handler (void)
2371=over 4 2958=over 4
2372 2959
2373=item ev_async_init (ev_async *, callback) 2960=item ev_async_init (ev_async *, callback)
2374 2961
2375Initialises and configures the async watcher - it has no parameters of any 2962Initialises and configures the async watcher - it has no parameters of any
2376kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, 2963kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
2377believe me. 2964trust me.
2378 2965
2379=item ev_async_send (loop, ev_async *) 2966=item ev_async_send (loop, ev_async *)
2380 2967
2381Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2968Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2382an C<EV_ASYNC> event on the watcher into the event loop. Unlike 2969an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2383C<ev_feed_event>, this call is safe to do in other threads, signal or 2970C<ev_feed_event>, this call is safe to do from other threads, signal or
2384similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 2971similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2385section below on what exactly this means). 2972section below on what exactly this means).
2386 2973
2974Note that, as with other watchers in libev, multiple events might get
2975compressed into a single callback invocation (another way to look at this
2976is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
2977reset when the event loop detects that).
2978
2387This call incurs the overhead of a system call only once per loop iteration, 2979This call incurs the overhead of a system call only once per event loop
2388so while the overhead might be noticeable, it doesn't apply to repeated 2980iteration, so while the overhead might be noticeable, it doesn't apply to
2389calls to C<ev_async_send>. 2981repeated calls to C<ev_async_send> for the same event loop.
2390 2982
2391=item bool = ev_async_pending (ev_async *) 2983=item bool = ev_async_pending (ev_async *)
2392 2984
2393Returns a non-zero value when C<ev_async_send> has been called on the 2985Returns a non-zero value when C<ev_async_send> has been called on the
2394watcher but the event has not yet been processed (or even noted) by the 2986watcher but the event has not yet been processed (or even noted) by the
2397C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 2989C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2398the loop iterates next and checks for the watcher to have become active, 2990the loop iterates next and checks for the watcher to have become active,
2399it will reset the flag again. C<ev_async_pending> can be used to very 2991it will reset the flag again. C<ev_async_pending> can be used to very
2400quickly check whether invoking the loop might be a good idea. 2992quickly check whether invoking the loop might be a good idea.
2401 2993
2402Not that this does I<not> check whether the watcher itself is pending, only 2994Not that this does I<not> check whether the watcher itself is pending,
2403whether it has been requested to make this watcher pending. 2995only whether it has been requested to make this watcher pending: there
2996is a time window between the event loop checking and resetting the async
2997notification, and the callback being invoked.
2404 2998
2405=back 2999=back
2406 3000
2407 3001
2408=head1 OTHER FUNCTIONS 3002=head1 OTHER FUNCTIONS
2412=over 4 3006=over 4
2413 3007
2414=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 3008=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
2415 3009
2416This function combines a simple timer and an I/O watcher, calls your 3010This function combines a simple timer and an I/O watcher, calls your
2417callback on whichever event happens first and automatically stop both 3011callback on whichever event happens first and automatically stops both
2418watchers. This is useful if you want to wait for a single event on an fd 3012watchers. This is useful if you want to wait for a single event on an fd
2419or timeout without having to allocate/configure/start/stop/free one or 3013or timeout without having to allocate/configure/start/stop/free one or
2420more watchers yourself. 3014more watchers yourself.
2421 3015
2422If C<fd> is less than 0, then no I/O watcher will be started and events 3016If C<fd> is less than 0, then no I/O watcher will be started and the
2423is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and 3017C<events> argument is being ignored. Otherwise, an C<ev_io> watcher for
2424C<events> set will be created and started. 3018the given C<fd> and C<events> set will be created and started.
2425 3019
2426If C<timeout> is less than 0, then no timeout watcher will be 3020If C<timeout> is less than 0, then no timeout watcher will be
2427started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3021started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2428repeat = 0) will be started. While C<0> is a valid timeout, it is of 3022repeat = 0) will be started. C<0> is a valid timeout.
2429dubious value.
2430 3023
2431The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3024The callback has the type C<void (*cb)(int revents, void *arg)> and gets
2432passed an C<revents> set like normal event callbacks (a combination of 3025passed an C<revents> set like normal event callbacks (a combination of
2433C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3026C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
2434value passed to C<ev_once>: 3027value passed to C<ev_once>. Note that it is possible to receive I<both>
3028a timeout and an io event at the same time - you probably should give io
3029events precedence.
3030
3031Example: wait up to ten seconds for data to appear on STDIN_FILENO.
2435 3032
2436 static void stdin_ready (int revents, void *arg) 3033 static void stdin_ready (int revents, void *arg)
2437 { 3034 {
3035 if (revents & EV_READ)
3036 /* stdin might have data for us, joy! */;
2438 if (revents & EV_TIMEOUT) 3037 else if (revents & EV_TIMEOUT)
2439 /* doh, nothing entered */; 3038 /* doh, nothing entered */;
2440 else if (revents & EV_READ)
2441 /* stdin might have data for us, joy! */;
2442 } 3039 }
2443 3040
2444 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3041 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2445 3042
2446=item ev_feed_event (ev_loop *, watcher *, int revents) 3043=item ev_feed_event (struct ev_loop *, watcher *, int revents)
2447 3044
2448Feeds the given event set into the event loop, as if the specified event 3045Feeds the given event set into the event loop, as if the specified event
2449had happened for the specified watcher (which must be a pointer to an 3046had happened for the specified watcher (which must be a pointer to an
2450initialised but not necessarily started event watcher). 3047initialised but not necessarily started event watcher).
2451 3048
2452=item ev_feed_fd_event (ev_loop *, int fd, int revents) 3049=item ev_feed_fd_event (struct ev_loop *, int fd, int revents)
2453 3050
2454Feed an event on the given fd, as if a file descriptor backend detected 3051Feed an event on the given fd, as if a file descriptor backend detected
2455the given events it. 3052the given events it.
2456 3053
2457=item ev_feed_signal_event (ev_loop *loop, int signum) 3054=item ev_feed_signal_event (struct ev_loop *loop, int signum)
2458 3055
2459Feed an event as if the given signal occurred (C<loop> must be the default 3056Feed an event as if the given signal occurred (C<loop> must be the default
2460loop!). 3057loop!).
2461 3058
2462=back 3059=back
2584 3181
2585 myclass obj; 3182 myclass obj;
2586 ev::io iow; 3183 ev::io iow;
2587 iow.set <myclass, &myclass::io_cb> (&obj); 3184 iow.set <myclass, &myclass::io_cb> (&obj);
2588 3185
3186=item w->set (object *)
3187
3188This is an B<experimental> feature that might go away in a future version.
3189
3190This is a variation of a method callback - leaving out the method to call
3191will default the method to C<operator ()>, which makes it possible to use
3192functor objects without having to manually specify the C<operator ()> all
3193the time. Incidentally, you can then also leave out the template argument
3194list.
3195
3196The C<operator ()> method prototype must be C<void operator ()(watcher &w,
3197int revents)>.
3198
3199See the method-C<set> above for more details.
3200
3201Example: use a functor object as callback.
3202
3203 struct myfunctor
3204 {
3205 void operator() (ev::io &w, int revents)
3206 {
3207 ...
3208 }
3209 }
3210
3211 myfunctor f;
3212
3213 ev::io w;
3214 w.set (&f);
3215
2589=item w->set<function> (void *data = 0) 3216=item w->set<function> (void *data = 0)
2590 3217
2591Also sets a callback, but uses a static method or plain function as 3218Also sets a callback, but uses a static method or plain function as
2592callback. The optional C<data> argument will be stored in the watcher's 3219callback. The optional C<data> argument will be stored in the watcher's
2593C<data> member and is free for you to use. 3220C<data> member and is free for you to use.
2594 3221
2595The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. 3222The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
2596 3223
2597See the method-C<set> above for more details. 3224See the method-C<set> above for more details.
2598 3225
2599Example: 3226Example: Use a plain function as callback.
2600 3227
2601 static void io_cb (ev::io &w, int revents) { } 3228 static void io_cb (ev::io &w, int revents) { }
2602 iow.set <io_cb> (); 3229 iow.set <io_cb> ();
2603 3230
2604=item w->set (struct ev_loop *) 3231=item w->set (struct ev_loop *)
2642Example: Define a class with an IO and idle watcher, start one of them in 3269Example: Define a class with an IO and idle watcher, start one of them in
2643the constructor. 3270the constructor.
2644 3271
2645 class myclass 3272 class myclass
2646 { 3273 {
2647 ev::io io; void io_cb (ev::io &w, int revents); 3274 ev::io io ; void io_cb (ev::io &w, int revents);
2648 ev:idle idle void idle_cb (ev::idle &w, int revents); 3275 ev::idle idle; void idle_cb (ev::idle &w, int revents);
2649 3276
2650 myclass (int fd) 3277 myclass (int fd)
2651 { 3278 {
2652 io .set <myclass, &myclass::io_cb > (this); 3279 io .set <myclass, &myclass::io_cb > (this);
2653 idle.set <myclass, &myclass::idle_cb> (this); 3280 idle.set <myclass, &myclass::idle_cb> (this);
2669=item Perl 3296=item Perl
2670 3297
2671The EV module implements the full libev API and is actually used to test 3298The EV module implements the full libev API and is actually used to test
2672libev. EV is developed together with libev. Apart from the EV core module, 3299libev. EV is developed together with libev. Apart from the EV core module,
2673there are additional modules that implement libev-compatible interfaces 3300there are additional modules that implement libev-compatible interfaces
2674to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the 3301to C<libadns> (C<EV::ADNS>, but C<AnyEvent::DNS> is preferred nowadays),
2675C<libglib> event core (C<Glib::EV> and C<EV::Glib>). 3302C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV>
3303and C<EV::Glib>).
2676 3304
2677It can be found and installed via CPAN, its homepage is at 3305It can be found and installed via CPAN, its homepage is at
2678L<http://software.schmorp.de/pkg/EV>. 3306L<http://software.schmorp.de/pkg/EV>.
2679 3307
2680=item Python 3308=item Python
2681 3309
2682Python bindings can be found at L<http://code.google.com/p/pyev/>. It 3310Python bindings can be found at L<http://code.google.com/p/pyev/>. It
2683seems to be quite complete and well-documented. Note, however, that the 3311seems to be quite complete and well-documented.
2684patch they require for libev is outright dangerous as it breaks the ABI
2685for everybody else, and therefore, should never be applied in an installed
2686libev (if python requires an incompatible ABI then it needs to embed
2687libev).
2688 3312
2689=item Ruby 3313=item Ruby
2690 3314
2691Tony Arcieri has written a ruby extension that offers access to a subset 3315Tony Arcieri has written a ruby extension that offers access to a subset
2692of the libev API and adds file handle abstractions, asynchronous DNS and 3316of the libev API and adds file handle abstractions, asynchronous DNS and
2693more on top of it. It can be found via gem servers. Its homepage is at 3317more on top of it. It can be found via gem servers. Its homepage is at
2694L<http://rev.rubyforge.org/>. 3318L<http://rev.rubyforge.org/>.
2695 3319
3320Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3321makes rev work even on mingw.
3322
3323=item Haskell
3324
3325A haskell binding to libev is available at
3326L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3327
2696=item D 3328=item D
2697 3329
2698Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 3330Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2699be found at L<http://proj.llucax.com.ar/wiki/evd>. 3331be found at L<http://proj.llucax.com.ar/wiki/evd>.
3332
3333=item Ocaml
3334
3335Erkki Seppala has written Ocaml bindings for libev, to be found at
3336L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
2700 3337
2701=back 3338=back
2702 3339
2703 3340
2704=head1 MACRO MAGIC 3341=head1 MACRO MAGIC
2805 3442
2806 #define EV_STANDALONE 1 3443 #define EV_STANDALONE 1
2807 #include "ev.h" 3444 #include "ev.h"
2808 3445
2809Both header files and implementation files can be compiled with a C++ 3446Both header files and implementation files can be compiled with a C++
2810compiler (at least, thats a stated goal, and breakage will be treated 3447compiler (at least, that's a stated goal, and breakage will be treated
2811as a bug). 3448as a bug).
2812 3449
2813You need the following files in your source tree, or in a directory 3450You need the following files in your source tree, or in a directory
2814in your include path (e.g. in libev/ when using -Ilibev): 3451in your include path (e.g. in libev/ when using -Ilibev):
2815 3452
2859 3496
2860=head2 PREPROCESSOR SYMBOLS/MACROS 3497=head2 PREPROCESSOR SYMBOLS/MACROS
2861 3498
2862Libev can be configured via a variety of preprocessor symbols you have to 3499Libev can be configured via a variety of preprocessor symbols you have to
2863define before including any of its files. The default in the absence of 3500define before including any of its files. The default in the absence of
2864autoconf is noted for every option. 3501autoconf is documented for every option.
2865 3502
2866=over 4 3503=over 4
2867 3504
2868=item EV_STANDALONE 3505=item EV_STANDALONE
2869 3506
2871keeps libev from including F<config.h>, and it also defines dummy 3508keeps libev from including F<config.h>, and it also defines dummy
2872implementations for some libevent functions (such as logging, which is not 3509implementations for some libevent functions (such as logging, which is not
2873supported). It will also not define any of the structs usually found in 3510supported). It will also not define any of the structs usually found in
2874F<event.h> that are not directly supported by the libev core alone. 3511F<event.h> that are not directly supported by the libev core alone.
2875 3512
3513In stanbdalone mode, libev will still try to automatically deduce the
3514configuration, but has to be more conservative.
3515
2876=item EV_USE_MONOTONIC 3516=item EV_USE_MONOTONIC
2877 3517
2878If defined to be C<1>, libev will try to detect the availability of the 3518If defined to be C<1>, libev will try to detect the availability of the
2879monotonic clock option at both compile time and runtime. Otherwise no use 3519monotonic clock option at both compile time and runtime. Otherwise no
2880of the monotonic clock option will be attempted. If you enable this, you 3520use of the monotonic clock option will be attempted. If you enable this,
2881usually have to link against librt or something similar. Enabling it when 3521you usually have to link against librt or something similar. Enabling it
2882the functionality isn't available is safe, though, although you have 3522when the functionality isn't available is safe, though, although you have
2883to make sure you link against any libraries where the C<clock_gettime> 3523to make sure you link against any libraries where the C<clock_gettime>
2884function is hiding in (often F<-lrt>). 3524function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
2885 3525
2886=item EV_USE_REALTIME 3526=item EV_USE_REALTIME
2887 3527
2888If defined to be C<1>, libev will try to detect the availability of the 3528If defined to be C<1>, libev will try to detect the availability of the
2889real-time clock option at compile time (and assume its availability at 3529real-time clock option at compile time (and assume its availability
2890runtime if successful). Otherwise no use of the real-time clock option will 3530at runtime if successful). Otherwise no use of the real-time clock
2891be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3531option will be attempted. This effectively replaces C<gettimeofday>
2892(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3532by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
2893note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3533correctness. See the note about libraries in the description of
3534C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
3535C<EV_USE_CLOCK_SYSCALL>.
3536
3537=item EV_USE_CLOCK_SYSCALL
3538
3539If defined to be C<1>, libev will try to use a direct syscall instead
3540of calling the system-provided C<clock_gettime> function. This option
3541exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt>
3542unconditionally pulls in C<libpthread>, slowing down single-threaded
3543programs needlessly. Using a direct syscall is slightly slower (in
3544theory), because no optimised vdso implementation can be used, but avoids
3545the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or
3546higher, as it simplifies linking (no need for C<-lrt>).
2894 3547
2895=item EV_USE_NANOSLEEP 3548=item EV_USE_NANOSLEEP
2896 3549
2897If defined to be C<1>, libev will assume that C<nanosleep ()> is available 3550If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2898and will use it for delays. Otherwise it will use C<select ()>. 3551and will use it for delays. Otherwise it will use C<select ()>.
2914 3567
2915=item EV_SELECT_USE_FD_SET 3568=item EV_SELECT_USE_FD_SET
2916 3569
2917If defined to C<1>, then the select backend will use the system C<fd_set> 3570If defined to C<1>, then the select backend will use the system C<fd_set>
2918structure. This is useful if libev doesn't compile due to a missing 3571structure. This is useful if libev doesn't compile due to a missing
2919C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout on 3572C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout
2920exotic systems. This usually limits the range of file descriptors to some 3573on exotic systems. This usually limits the range of file descriptors to
2921low limit such as 1024 or might have other limitations (winsocket only 3574some low limit such as 1024 or might have other limitations (winsocket
2922allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3575only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation,
2923influence the size of the C<fd_set> used. 3576configures the maximum size of the C<fd_set>.
2924 3577
2925=item EV_SELECT_IS_WINSOCKET 3578=item EV_SELECT_IS_WINSOCKET
2926 3579
2927When defined to C<1>, the select backend will assume that 3580When defined to C<1>, the select backend will assume that
2928select/socket/connect etc. don't understand file descriptors but 3581select/socket/connect etc. don't understand file descriptors but
3039When doing priority-based operations, libev usually has to linearly search 3692When doing priority-based operations, libev usually has to linearly search
3040all the priorities, so having many of them (hundreds) uses a lot of space 3693all the priorities, so having many of them (hundreds) uses a lot of space
3041and time, so using the defaults of five priorities (-2 .. +2) is usually 3694and time, so using the defaults of five priorities (-2 .. +2) is usually
3042fine. 3695fine.
3043 3696
3044If your embedding application does not need any priorities, defining these both to 3697If your embedding application does not need any priorities, defining these
3045C<0> will save some memory and CPU. 3698both to C<0> will save some memory and CPU.
3046 3699
3047=item EV_PERIODIC_ENABLE 3700=item EV_PERIODIC_ENABLE
3048 3701
3049If undefined or defined to be C<1>, then periodic timers are supported. If 3702If undefined or defined to be C<1>, then periodic timers are supported. If
3050defined to be C<0>, then they are not. Disabling them saves a few kB of 3703defined to be C<0>, then they are not. Disabling them saves a few kB of
3057code. 3710code.
3058 3711
3059=item EV_EMBED_ENABLE 3712=item EV_EMBED_ENABLE
3060 3713
3061If undefined or defined to be C<1>, then embed watchers are supported. If 3714If undefined or defined to be C<1>, then embed watchers are supported. If
3062defined to be C<0>, then they are not. 3715defined to be C<0>, then they are not. Embed watchers rely on most other
3716watcher types, which therefore must not be disabled.
3063 3717
3064=item EV_STAT_ENABLE 3718=item EV_STAT_ENABLE
3065 3719
3066If undefined or defined to be C<1>, then stat watchers are supported. If 3720If undefined or defined to be C<1>, then stat watchers are supported. If
3067defined to be C<0>, then they are not. 3721defined to be C<0>, then they are not.
3077defined to be C<0>, then they are not. 3731defined to be C<0>, then they are not.
3078 3732
3079=item EV_MINIMAL 3733=item EV_MINIMAL
3080 3734
3081If you need to shave off some kilobytes of code at the expense of some 3735If you need to shave off some kilobytes of code at the expense of some
3082speed, define this symbol to C<1>. Currently this is used to override some 3736speed (but with the full API), define this symbol to C<1>. Currently this
3083inlining decisions, saves roughly 30% code size on amd64. It also selects a 3737is used to override some inlining decisions, saves roughly 30% code size
3084much smaller 2-heap for timer management over the default 4-heap. 3738on amd64. It also selects a much smaller 2-heap for timer management over
3739the default 4-heap.
3740
3741You can save even more by disabling watcher types you do not need
3742and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>
3743(C<-DNDEBUG>) will usually reduce code size a lot.
3744
3745Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
3746provide a bare-bones event library. See C<ev.h> for details on what parts
3747of the API are still available, and do not complain if this subset changes
3748over time.
3085 3749
3086=item EV_PID_HASHSIZE 3750=item EV_PID_HASHSIZE
3087 3751
3088C<ev_child> watchers use a small hash table to distribute workload by 3752C<ev_child> watchers use a small hash table to distribute workload by
3089pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3753pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
3099two). 3763two).
3100 3764
3101=item EV_USE_4HEAP 3765=item EV_USE_4HEAP
3102 3766
3103Heaps are not very cache-efficient. To improve the cache-efficiency of the 3767Heaps are not very cache-efficient. To improve the cache-efficiency of the
3104timer and periodics heap, libev uses a 4-heap when this symbol is defined 3768timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3105to C<1>. The 4-heap uses more complicated (longer) code but has 3769to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3106noticeably faster performance with many (thousands) of watchers. 3770faster performance with many (thousands) of watchers.
3107 3771
3108The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 3772The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3109(disabled). 3773(disabled).
3110 3774
3111=item EV_HEAP_CACHE_AT 3775=item EV_HEAP_CACHE_AT
3112 3776
3113Heaps are not very cache-efficient. To improve the cache-efficiency of the 3777Heaps are not very cache-efficient. To improve the cache-efficiency of the
3114timer and periodics heap, libev can cache the timestamp (I<at>) within 3778timer and periodics heaps, libev can cache the timestamp (I<at>) within
3115the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 3779the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3116which uses 8-12 bytes more per watcher and a few hundred bytes more code, 3780which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3117but avoids random read accesses on heap changes. This improves performance 3781but avoids random read accesses on heap changes. This improves performance
3118noticeably with with many (hundreds) of watchers. 3782noticeably with many (hundreds) of watchers.
3119 3783
3120The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 3784The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3121(disabled). 3785(disabled).
3122 3786
3123=item EV_VERIFY 3787=item EV_VERIFY
3129called once per loop, which can slow down libev. If set to C<3>, then the 3793called once per loop, which can slow down libev. If set to C<3>, then the
3130verification code will be called very frequently, which will slow down 3794verification code will be called very frequently, which will slow down
3131libev considerably. 3795libev considerably.
3132 3796
3133The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 3797The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be
3134C<0.> 3798C<0>.
3135 3799
3136=item EV_COMMON 3800=item EV_COMMON
3137 3801
3138By default, all watchers have a C<void *data> member. By redefining 3802By default, all watchers have a C<void *data> member. By redefining
3139this macro to a something else you can include more and other types of 3803this macro to a something else you can include more and other types of
3156and the way callbacks are invoked and set. Must expand to a struct member 3820and the way callbacks are invoked and set. Must expand to a struct member
3157definition and a statement, respectively. See the F<ev.h> header file for 3821definition and a statement, respectively. See the F<ev.h> header file for
3158their default definitions. One possible use for overriding these is to 3822their default definitions. One possible use for overriding these is to
3159avoid the C<struct ev_loop *> as first argument in all cases, or to use 3823avoid the C<struct ev_loop *> as first argument in all cases, or to use
3160method calls instead of plain function calls in C++. 3824method calls instead of plain function calls in C++.
3825
3826=back
3161 3827
3162=head2 EXPORTED API SYMBOLS 3828=head2 EXPORTED API SYMBOLS
3163 3829
3164If you need to re-export the API (e.g. via a DLL) and you need a list of 3830If you need to re-export the API (e.g. via a DLL) and you need a list of
3165exported symbols, you can use the provided F<Symbol.*> files which list 3831exported symbols, you can use the provided F<Symbol.*> files which list
3212And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 3878And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3213 3879
3214 #include "ev_cpp.h" 3880 #include "ev_cpp.h"
3215 #include "ev.c" 3881 #include "ev.c"
3216 3882
3883=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
3217 3884
3218=head1 THREADS AND COROUTINES 3885=head2 THREADS AND COROUTINES
3219 3886
3220=head2 THREADS 3887=head3 THREADS
3221 3888
3222Libev itself is completely thread-safe, but it uses no locking. This 3889All libev functions are reentrant and thread-safe unless explicitly
3890documented otherwise, but libev implements no locking itself. This means
3223means that you can use as many loops as you want in parallel, as long as 3891that you can use as many loops as you want in parallel, as long as there
3224only one thread ever calls into one libev function with the same loop 3892are no concurrent calls into any libev function with the same loop
3225parameter. 3893parameter (C<ev_default_*> calls have an implicit default loop parameter,
3894of course): libev guarantees that different event loops share no data
3895structures that need any locking.
3226 3896
3227Or put differently: calls with different loop parameters can be done in 3897Or to put it differently: calls with different loop parameters can be done
3228parallel from multiple threads, calls with the same loop parameter must be 3898concurrently from multiple threads, calls with the same loop parameter
3229done serially (but can be done from different threads, as long as only one 3899must be done serially (but can be done from different threads, as long as
3230thread ever is inside a call at any point in time, e.g. by using a mutex 3900only one thread ever is inside a call at any point in time, e.g. by using
3231per loop). 3901a mutex per loop).
3902
3903Specifically to support threads (and signal handlers), libev implements
3904so-called C<ev_async> watchers, which allow some limited form of
3905concurrency on the same event loop, namely waking it up "from the
3906outside".
3232 3907
3233If you want to know which design (one loop, locking, or multiple loops 3908If you want to know which design (one loop, locking, or multiple loops
3234without or something else still) is best for your problem, then I cannot 3909without or something else still) is best for your problem, then I cannot
3235help you. I can give some generic advice however: 3910help you, but here is some generic advice:
3236 3911
3237=over 4 3912=over 4
3238 3913
3239=item * most applications have a main thread: use the default libev loop 3914=item * most applications have a main thread: use the default libev loop
3240in that thread, or create a separate thread running only the default loop. 3915in that thread, or create a separate thread running only the default loop.
3252 3927
3253Choosing a model is hard - look around, learn, know that usually you can do 3928Choosing a model is hard - look around, learn, know that usually you can do
3254better than you currently do :-) 3929better than you currently do :-)
3255 3930
3256=item * often you need to talk to some other thread which blocks in the 3931=item * often you need to talk to some other thread which blocks in the
3932event loop.
3933
3257event loop - C<ev_async> watchers can be used to wake them up from other 3934C<ev_async> watchers can be used to wake them up from other threads safely
3258threads safely (or from signal contexts...). 3935(or from signal contexts...).
3936
3937An example use would be to communicate signals or other events that only
3938work in the default loop by registering the signal watcher with the
3939default loop and triggering an C<ev_async> watcher from the default loop
3940watcher callback into the event loop interested in the signal.
3259 3941
3260=back 3942=back
3261 3943
3944=head4 THREAD LOCKING EXAMPLE
3945
3946Here is a fictitious example of how to run an event loop in a different
3947thread than where callbacks are being invoked and watchers are
3948created/added/removed.
3949
3950For a real-world example, see the C<EV::Loop::Async> perl module,
3951which uses exactly this technique (which is suited for many high-level
3952languages).
3953
3954The example uses a pthread mutex to protect the loop data, a condition
3955variable to wait for callback invocations, an async watcher to notify the
3956event loop thread and an unspecified mechanism to wake up the main thread.
3957
3958First, you need to associate some data with the event loop:
3959
3960 typedef struct {
3961 mutex_t lock; /* global loop lock */
3962 ev_async async_w;
3963 thread_t tid;
3964 cond_t invoke_cv;
3965 } userdata;
3966
3967 void prepare_loop (EV_P)
3968 {
3969 // for simplicity, we use a static userdata struct.
3970 static userdata u;
3971
3972 ev_async_init (&u->async_w, async_cb);
3973 ev_async_start (EV_A_ &u->async_w);
3974
3975 pthread_mutex_init (&u->lock, 0);
3976 pthread_cond_init (&u->invoke_cv, 0);
3977
3978 // now associate this with the loop
3979 ev_set_userdata (EV_A_ u);
3980 ev_set_invoke_pending_cb (EV_A_ l_invoke);
3981 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3982
3983 // then create the thread running ev_loop
3984 pthread_create (&u->tid, 0, l_run, EV_A);
3985 }
3986
3987The callback for the C<ev_async> watcher does nothing: the watcher is used
3988solely to wake up the event loop so it takes notice of any new watchers
3989that might have been added:
3990
3991 static void
3992 async_cb (EV_P_ ev_async *w, int revents)
3993 {
3994 // just used for the side effects
3995 }
3996
3997The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
3998protecting the loop data, respectively.
3999
4000 static void
4001 l_release (EV_P)
4002 {
4003 userdata *u = ev_userdata (EV_A);
4004 pthread_mutex_unlock (&u->lock);
4005 }
4006
4007 static void
4008 l_acquire (EV_P)
4009 {
4010 userdata *u = ev_userdata (EV_A);
4011 pthread_mutex_lock (&u->lock);
4012 }
4013
4014The event loop thread first acquires the mutex, and then jumps straight
4015into C<ev_loop>:
4016
4017 void *
4018 l_run (void *thr_arg)
4019 {
4020 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4021
4022 l_acquire (EV_A);
4023 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4024 ev_loop (EV_A_ 0);
4025 l_release (EV_A);
4026
4027 return 0;
4028 }
4029
4030Instead of invoking all pending watchers, the C<l_invoke> callback will
4031signal the main thread via some unspecified mechanism (signals? pipe
4032writes? C<Async::Interrupt>?) and then waits until all pending watchers
4033have been called:
4034
4035 static void
4036 l_invoke (EV_P)
4037 {
4038 userdata *u = ev_userdata (EV_A);
4039
4040 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4041
4042 pthread_cond_wait (&u->invoke_cv, &u->lock);
4043 }
4044
4045Now, whenever the main thread gets told to invoke pending watchers, it
4046will grab the lock, call C<ev_invoke_pending> and then signal the loop
4047thread to continue:
4048
4049 static void
4050 real_invoke_pending (EV_P)
4051 {
4052 userdata *u = ev_userdata (EV_A);
4053
4054 pthread_mutex_lock (&u->lock);
4055 ev_invoke_pending (EV_A);
4056 pthread_cond_signal (&u->invoke_cv);
4057 pthread_mutex_unlock (&u->lock);
4058 }
4059
4060Whenever you want to start/stop a watcher or do other modifications to an
4061event loop, you will now have to lock:
4062
4063 ev_timer timeout_watcher;
4064 userdata *u = ev_userdata (EV_A);
4065
4066 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4067
4068 pthread_mutex_lock (&u->lock);
4069 ev_timer_start (EV_A_ &timeout_watcher);
4070 ev_async_send (EV_A_ &u->async_w);
4071 pthread_mutex_unlock (&u->lock);
4072
4073Note that sending the C<ev_async> watcher is required because otherwise
4074an event loop currently blocking in the kernel will have no knowledge
4075about the newly added timer. By waking up the loop it will pick up any new
4076watchers in the next event loop iteration.
4077
3262=head2 COROUTINES 4078=head3 COROUTINES
3263 4079
3264Libev is much more accommodating to coroutines ("cooperative threads"): 4080Libev is very accommodating to coroutines ("cooperative threads"):
3265libev fully supports nesting calls to it's functions from different 4081libev fully supports nesting calls to its functions from different
3266coroutines (e.g. you can call C<ev_loop> on the same loop from two 4082coroutines (e.g. you can call C<ev_loop> on the same loop from two
3267different coroutines and switch freely between both coroutines running the 4083different coroutines, and switch freely between both coroutines running
3268loop, as long as you don't confuse yourself). The only exception is that 4084the loop, as long as you don't confuse yourself). The only exception is
3269you must not do this from C<ev_periodic> reschedule callbacks. 4085that you must not do this from C<ev_periodic> reschedule callbacks.
3270 4086
3271Care has been invested into making sure that libev does not keep local 4087Care has been taken to ensure that libev does not keep local state inside
3272state inside C<ev_loop>, and other calls do not usually allow coroutine 4088C<ev_loop>, and other calls do not usually allow for coroutine switches as
3273switches. 4089they do not call any callbacks.
3274 4090
4091=head2 COMPILER WARNINGS
3275 4092
3276=head1 COMPLEXITIES 4093Depending on your compiler and compiler settings, you might get no or a
4094lot of warnings when compiling libev code. Some people are apparently
4095scared by this.
3277 4096
3278In this section the complexities of (many of) the algorithms used inside 4097However, these are unavoidable for many reasons. For one, each compiler
3279libev will be explained. For complexity discussions about backends see the 4098has different warnings, and each user has different tastes regarding
3280documentation for C<ev_default_init>. 4099warning options. "Warn-free" code therefore cannot be a goal except when
4100targeting a specific compiler and compiler-version.
3281 4101
3282All of the following are about amortised time: If an array needs to be 4102Another reason is that some compiler warnings require elaborate
3283extended, libev needs to realloc and move the whole array, but this 4103workarounds, or other changes to the code that make it less clear and less
3284happens asymptotically never with higher number of elements, so O(1) might 4104maintainable.
3285mean it might do a lengthy realloc operation in rare cases, but on average
3286it is much faster and asymptotically approaches constant time.
3287 4105
3288=over 4 4106And of course, some compiler warnings are just plain stupid, or simply
4107wrong (because they don't actually warn about the condition their message
4108seems to warn about). For example, certain older gcc versions had some
4109warnings that resulted an extreme number of false positives. These have
4110been fixed, but some people still insist on making code warn-free with
4111such buggy versions.
3289 4112
3290=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 4113While libev is written to generate as few warnings as possible,
4114"warn-free" code is not a goal, and it is recommended not to build libev
4115with any compiler warnings enabled unless you are prepared to cope with
4116them (e.g. by ignoring them). Remember that warnings are just that:
4117warnings, not errors, or proof of bugs.
3291 4118
3292This means that, when you have a watcher that triggers in one hour and
3293there are 100 watchers that would trigger before that then inserting will
3294have to skip roughly seven (C<ld 100>) of these watchers.
3295 4119
3296=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) 4120=head2 VALGRIND
3297 4121
3298That means that changing a timer costs less than removing/adding them 4122Valgrind has a special section here because it is a popular tool that is
3299as only the relative motion in the event queue has to be paid for. 4123highly useful. Unfortunately, valgrind reports are very hard to interpret.
3300 4124
3301=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) 4125If you think you found a bug (memory leak, uninitialised data access etc.)
4126in libev, then check twice: If valgrind reports something like:
3302 4127
3303These just add the watcher into an array or at the head of a list. 4128 ==2274== definitely lost: 0 bytes in 0 blocks.
4129 ==2274== possibly lost: 0 bytes in 0 blocks.
4130 ==2274== still reachable: 256 bytes in 1 blocks.
3304 4131
3305=item Stopping check/prepare/idle/fork/async watchers: O(1) 4132Then there is no memory leak, just as memory accounted to global variables
4133is not a memleak - the memory is still being referenced, and didn't leak.
3306 4134
3307=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 4135Similarly, under some circumstances, valgrind might report kernel bugs
4136as if it were a bug in libev (e.g. in realloc or in the poll backend,
4137although an acceptable workaround has been found here), or it might be
4138confused.
3308 4139
3309These watchers are stored in lists then need to be walked to find the 4140Keep in mind that valgrind is a very good tool, but only a tool. Don't
3310correct watcher to remove. The lists are usually short (you don't usually 4141make it into some kind of religion.
3311have many watchers waiting for the same fd or signal).
3312 4142
3313=item Finding the next timer in each loop iteration: O(1) 4143If you are unsure about something, feel free to contact the mailing list
4144with the full valgrind report and an explanation on why you think this
4145is a bug in libev (best check the archives, too :). However, don't be
4146annoyed when you get a brisk "this is no bug" answer and take the chance
4147of learning how to interpret valgrind properly.
3314 4148
3315By virtue of using a binary or 4-heap, the next timer is always found at a 4149If you need, for some reason, empty reports from valgrind for your project
3316fixed position in the storage array. 4150I suggest using suppression lists.
3317 4151
3318=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
3319 4152
3320A change means an I/O watcher gets started or stopped, which requires 4153=head1 PORTABILITY NOTES
3321libev to recalculate its status (and possibly tell the kernel, depending
3322on backend and whether C<ev_io_set> was used).
3323 4154
3324=item Activating one watcher (putting it into the pending state): O(1)
3325
3326=item Priority handling: O(number_of_priorities)
3327
3328Priorities are implemented by allocating some space for each
3329priority. When doing priority-based operations, libev usually has to
3330linearly search all the priorities, but starting/stopping and activating
3331watchers becomes O(1) w.r.t. priority handling.
3332
3333=item Sending an ev_async: O(1)
3334
3335=item Processing ev_async_send: O(number_of_async_watchers)
3336
3337=item Processing signals: O(max_signal_number)
3338
3339Sending involves a system call I<iff> there were no other C<ev_async_send>
3340calls in the current loop iteration. Checking for async and signal events
3341involves iterating over all running async watchers or all signal numbers.
3342
3343=back
3344
3345
3346=head1 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 4155=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
3347 4156
3348Win32 doesn't support any of the standards (e.g. POSIX) that libev 4157Win32 doesn't support any of the standards (e.g. POSIX) that libev
3349requires, and its I/O model is fundamentally incompatible with the POSIX 4158requires, and its I/O model is fundamentally incompatible with the POSIX
3350model. Libev still offers limited functionality on this platform in 4159model. Libev still offers limited functionality on this platform in
3351the form of the C<EVBACKEND_SELECT> backend, and only supports socket 4160the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3358way (note also that glib is the slowest event library known to man). 4167way (note also that glib is the slowest event library known to man).
3359 4168
3360There is no supported compilation method available on windows except 4169There is no supported compilation method available on windows except
3361embedding it into other applications. 4170embedding it into other applications.
3362 4171
4172Sensible signal handling is officially unsupported by Microsoft - libev
4173tries its best, but under most conditions, signals will simply not work.
4174
3363Not a libev limitation but worth mentioning: windows apparently doesn't 4175Not a libev limitation but worth mentioning: windows apparently doesn't
3364accept large writes: instead of resulting in a partial write, windows will 4176accept large writes: instead of resulting in a partial write, windows will
3365either accept everything or return C<ENOBUFS> if the buffer is too large, 4177either accept everything or return C<ENOBUFS> if the buffer is too large,
3366so make sure you only write small amounts into your sockets (less than a 4178so make sure you only write small amounts into your sockets (less than a
3367megabyte seems safe, but thsi apparently depends on the amount of memory 4179megabyte seems safe, but this apparently depends on the amount of memory
3368available). 4180available).
3369 4181
3370Due to the many, low, and arbitrary limits on the win32 platform and 4182Due to the many, low, and arbitrary limits on the win32 platform and
3371the abysmal performance of winsockets, using a large number of sockets 4183the abysmal performance of winsockets, using a large number of sockets
3372is not recommended (and not reasonable). If your program needs to use 4184is not recommended (and not reasonable). If your program needs to use
3373more than a hundred or so sockets, then likely it needs to use a totally 4185more than a hundred or so sockets, then likely it needs to use a totally
3374different implementation for windows, as libev offers the POSIX readiness 4186different implementation for windows, as libev offers the POSIX readiness
3375notification model, which cannot be implemented efficiently on windows 4187notification model, which cannot be implemented efficiently on windows
3376(Microsoft monopoly games). 4188(due to Microsoft monopoly games).
3377 4189
3378A typical way to use libev under windows is to embed it (see the embedding 4190A typical way to use libev under windows is to embed it (see the embedding
3379section for details) and use the following F<evwrap.h> header file instead 4191section for details) and use the following F<evwrap.h> header file instead
3380of F<ev.h>: 4192of F<ev.h>:
3381 4193
3383 #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ 4195 #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */
3384 4196
3385 #include "ev.h" 4197 #include "ev.h"
3386 4198
3387And compile the following F<evwrap.c> file into your project (make sure 4199And compile the following F<evwrap.c> file into your project (make sure
3388you do I<not> compile the F<ev.c> or any other embedded soruce files!): 4200you do I<not> compile the F<ev.c> or any other embedded source files!):
3389 4201
3390 #include "evwrap.h" 4202 #include "evwrap.h"
3391 #include "ev.c" 4203 #include "ev.c"
3392 4204
3393=over 4 4205=over 4
3417 4229
3418Early versions of winsocket's select only supported waiting for a maximum 4230Early versions of winsocket's select only supported waiting for a maximum
3419of C<64> handles (probably owning to the fact that all windows kernels 4231of C<64> handles (probably owning to the fact that all windows kernels
3420can only wait for C<64> things at the same time internally; Microsoft 4232can only wait for C<64> things at the same time internally; Microsoft
3421recommends spawning a chain of threads and wait for 63 handles and the 4233recommends spawning a chain of threads and wait for 63 handles and the
3422previous thread in each. Great). 4234previous thread in each. Sounds great!).
3423 4235
3424Newer versions support more handles, but you need to define C<FD_SETSIZE> 4236Newer versions support more handles, but you need to define C<FD_SETSIZE>
3425to some high number (e.g. C<2048>) before compiling the winsocket select 4237to some high number (e.g. C<2048>) before compiling the winsocket select
3426call (which might be in libev or elsewhere, for example, perl does its own 4238call (which might be in libev or elsewhere, for example, perl and many
3427select emulation on windows). 4239other interpreters do their own select emulation on windows).
3428 4240
3429Another limit is the number of file descriptors in the Microsoft runtime 4241Another limit is the number of file descriptors in the Microsoft runtime
3430libraries, which by default is C<64> (there must be a hidden I<64> fetish 4242libraries, which by default is C<64> (there must be a hidden I<64>
3431or something like this inside Microsoft). You can increase this by calling 4243fetish or something like this inside Microsoft). You can increase this
3432C<_setmaxstdio>, which can increase this limit to C<2048> (another 4244by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3433arbitrary limit), but is broken in many versions of the Microsoft runtime 4245(another arbitrary limit), but is broken in many versions of the Microsoft
3434libraries.
3435
3436This might get you to about C<512> or C<2048> sockets (depending on 4246runtime libraries. This might get you to about C<512> or C<2048> sockets
3437windows version and/or the phase of the moon). To get more, you need to 4247(depending on windows version and/or the phase of the moon). To get more,
3438wrap all I/O functions and provide your own fd management, but the cost of 4248you need to wrap all I/O functions and provide your own fd management, but
3439calling select (O(n²)) will likely make this unworkable. 4249the cost of calling select (O(n²)) will likely make this unworkable.
3440 4250
3441=back 4251=back
3442 4252
3443
3444=head1 PORTABILITY REQUIREMENTS 4253=head2 PORTABILITY REQUIREMENTS
3445 4254
3446In addition to a working ISO-C implementation, libev relies on a few 4255In addition to a working ISO-C implementation and of course the
3447additional extensions: 4256backend-specific APIs, libev relies on a few additional extensions:
3448 4257
3449=over 4 4258=over 4
3450 4259
3451=item C<void (*)(ev_watcher_type *, int revents)> must have compatible 4260=item C<void (*)(ev_watcher_type *, int revents)> must have compatible
3452calling conventions regardless of C<ev_watcher_type *>. 4261calling conventions regardless of C<ev_watcher_type *>.
3458calls them using an C<ev_watcher *> internally. 4267calls them using an C<ev_watcher *> internally.
3459 4268
3460=item C<sig_atomic_t volatile> must be thread-atomic as well 4269=item C<sig_atomic_t volatile> must be thread-atomic as well
3461 4270
3462The type C<sig_atomic_t volatile> (or whatever is defined as 4271The type C<sig_atomic_t volatile> (or whatever is defined as
3463C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different 4272C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
3464threads. This is not part of the specification for C<sig_atomic_t>, but is 4273threads. This is not part of the specification for C<sig_atomic_t>, but is
3465believed to be sufficiently portable. 4274believed to be sufficiently portable.
3466 4275
3467=item C<sigprocmask> must work in a threaded environment 4276=item C<sigprocmask> must work in a threaded environment
3468 4277
3477except the initial one, and run the default loop in the initial thread as 4286except the initial one, and run the default loop in the initial thread as
3478well. 4287well.
3479 4288
3480=item C<long> must be large enough for common memory allocation sizes 4289=item C<long> must be large enough for common memory allocation sizes
3481 4290
3482To improve portability and simplify using libev, libev uses C<long> 4291To improve portability and simplify its API, libev uses C<long> internally
3483internally instead of C<size_t> when allocating its data structures. On 4292instead of C<size_t> when allocating its data structures. On non-POSIX
3484non-POSIX systems (Microsoft...) this might be unexpectedly low, but 4293systems (Microsoft...) this might be unexpectedly low, but is still at
3485is still at least 31 bits everywhere, which is enough for hundreds of 4294least 31 bits everywhere, which is enough for hundreds of millions of
3486millions of watchers. 4295watchers.
3487 4296
3488=item C<double> must hold a time value in seconds with enough accuracy 4297=item C<double> must hold a time value in seconds with enough accuracy
3489 4298
3490The type C<double> is used to represent timestamps. It is required to 4299The type C<double> is used to represent timestamps. It is required to
3491have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4300have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3492enough for at least into the year 4000. This requirement is fulfilled by 4301enough for at least into the year 4000. This requirement is fulfilled by
3493implementations implementing IEEE 754 (basically all existing ones). 4302implementations implementing IEEE 754, which is basically all existing
4303ones. With IEEE 754 doubles, you get microsecond accuracy until at least
43042200.
3494 4305
3495=back 4306=back
3496 4307
3497If you know of other additional requirements drop me a note. 4308If you know of other additional requirements drop me a note.
3498 4309
3499 4310
3500=head1 COMPILER WARNINGS 4311=head1 ALGORITHMIC COMPLEXITIES
3501 4312
3502Depending on your compiler and compiler settings, you might get no or a 4313In this section the complexities of (many of) the algorithms used inside
3503lot of warnings when compiling libev code. Some people are apparently 4314libev will be documented. For complexity discussions about backends see
3504scared by this. 4315the documentation for C<ev_default_init>.
3505 4316
3506However, these are unavoidable for many reasons. For one, each compiler 4317All of the following are about amortised time: If an array needs to be
3507has different warnings, and each user has different tastes regarding 4318extended, libev needs to realloc and move the whole array, but this
3508warning options. "Warn-free" code therefore cannot be a goal except when 4319happens asymptotically rarer with higher number of elements, so O(1) might
3509targeting a specific compiler and compiler-version. 4320mean that libev does a lengthy realloc operation in rare cases, but on
4321average it is much faster and asymptotically approaches constant time.
3510 4322
3511Another reason is that some compiler warnings require elaborate 4323=over 4
3512workarounds, or other changes to the code that make it less clear and less
3513maintainable.
3514 4324
3515And of course, some compiler warnings are just plain stupid, or simply 4325=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
3516wrong (because they don't actually warn about the condition their message
3517seems to warn about).
3518 4326
3519While libev is written to generate as few warnings as possible, 4327This means that, when you have a watcher that triggers in one hour and
3520"warn-free" code is not a goal, and it is recommended not to build libev 4328there are 100 watchers that would trigger before that, then inserting will
3521with any compiler warnings enabled unless you are prepared to cope with 4329have to skip roughly seven (C<ld 100>) of these watchers.
3522them (e.g. by ignoring them). Remember that warnings are just that:
3523warnings, not errors, or proof of bugs.
3524 4330
4331=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
3525 4332
3526=head1 VALGRIND 4333That means that changing a timer costs less than removing/adding them,
4334as only the relative motion in the event queue has to be paid for.
3527 4335
3528Valgrind has a special section here because it is a popular tool that is 4336=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
3529highly useful, but valgrind reports are very hard to interpret.
3530 4337
3531If you think you found a bug (memory leak, uninitialised data access etc.) 4338These just add the watcher into an array or at the head of a list.
3532in libev, then check twice: If valgrind reports something like:
3533 4339
3534 ==2274== definitely lost: 0 bytes in 0 blocks. 4340=item Stopping check/prepare/idle/fork/async watchers: O(1)
3535 ==2274== possibly lost: 0 bytes in 0 blocks.
3536 ==2274== still reachable: 256 bytes in 1 blocks.
3537 4341
3538Then there is no memory leak. Similarly, under some circumstances, 4342=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
3539valgrind might report kernel bugs as if it were a bug in libev, or it
3540might be confused (it is a very good tool, but only a tool).
3541 4343
3542If you are unsure about something, feel free to contact the mailing list 4344These watchers are stored in lists, so they need to be walked to find the
3543with the full valgrind report and an explanation on why you think this is 4345correct watcher to remove. The lists are usually short (you don't usually
3544a bug in libev. However, don't be annoyed when you get a brisk "this is 4346have many watchers waiting for the same fd or signal: one is typical, two
3545no bug" answer and take the chance of learning how to interpret valgrind 4347is rare).
3546properly.
3547 4348
3548If you need, for some reason, empty reports from valgrind for your project 4349=item Finding the next timer in each loop iteration: O(1)
3549I suggest using suppression lists.
3550 4350
4351By virtue of using a binary or 4-heap, the next timer is always found at a
4352fixed position in the storage array.
4353
4354=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
4355
4356A change means an I/O watcher gets started or stopped, which requires
4357libev to recalculate its status (and possibly tell the kernel, depending
4358on backend and whether C<ev_io_set> was used).
4359
4360=item Activating one watcher (putting it into the pending state): O(1)
4361
4362=item Priority handling: O(number_of_priorities)
4363
4364Priorities are implemented by allocating some space for each
4365priority. When doing priority-based operations, libev usually has to
4366linearly search all the priorities, but starting/stopping and activating
4367watchers becomes O(1) with respect to priority handling.
4368
4369=item Sending an ev_async: O(1)
4370
4371=item Processing ev_async_send: O(number_of_async_watchers)
4372
4373=item Processing signals: O(max_signal_number)
4374
4375Sending involves a system call I<iff> there were no other C<ev_async_send>
4376calls in the current loop iteration. Checking for async and signal events
4377involves iterating over all running async watchers or all signal numbers.
4378
4379=back
4380
4381
4382=head1 GLOSSARY
4383
4384=over 4
4385
4386=item active
4387
4388A watcher is active as long as it has been started (has been attached to
4389an event loop) but not yet stopped (disassociated from the event loop).
4390
4391=item application
4392
4393In this document, an application is whatever is using libev.
4394
4395=item callback
4396
4397The address of a function that is called when some event has been
4398detected. Callbacks are being passed the event loop, the watcher that
4399received the event, and the actual event bitset.
4400
4401=item callback invocation
4402
4403The act of calling the callback associated with a watcher.
4404
4405=item event
4406
4407A change of state of some external event, such as data now being available
4408for reading on a file descriptor, time having passed or simply not having
4409any other events happening anymore.
4410
4411In libev, events are represented as single bits (such as C<EV_READ> or
4412C<EV_TIMEOUT>).
4413
4414=item event library
4415
4416A software package implementing an event model and loop.
4417
4418=item event loop
4419
4420An entity that handles and processes external events and converts them
4421into callback invocations.
4422
4423=item event model
4424
4425The model used to describe how an event loop handles and processes
4426watchers and events.
4427
4428=item pending
4429
4430A watcher is pending as soon as the corresponding event has been detected,
4431and stops being pending as soon as the watcher will be invoked or its
4432pending status is explicitly cleared by the application.
4433
4434A watcher can be pending, but not active. Stopping a watcher also clears
4435its pending status.
4436
4437=item real time
4438
4439The physical time that is observed. It is apparently strictly monotonic :)
4440
4441=item wall-clock time
4442
4443The time and date as shown on clocks. Unlike real time, it can actually
4444be wrong and jump forwards and backwards, e.g. when the you adjust your
4445clock.
4446
4447=item watcher
4448
4449A data structure that describes interest in certain events. Watchers need
4450to be started (attached to an event loop) before they can receive events.
4451
4452=item watcher invocation
4453
4454The act of calling the callback associated with a watcher.
4455
4456=back
3551 4457
3552=head1 AUTHOR 4458=head1 AUTHOR
3553 4459
3554Marc Lehmann <libev@schmorp.de>. 4460Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3555 4461

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines