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

Comparing libev/ev.pod (file contents):
Revision 1.198 by root, Thu Oct 23 06:30:48 2008 UTC vs.
Revision 1.271 by root, Fri Sep 18 21:16:10 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
41 43
42 int 44 int
43 main (void) 45 main (void)
44 { 46 {
45 // use the default event loop unless you have special needs 47 // use the default event loop unless you have special needs
46 ev_loop *loop = ev_default_loop (0); 48 struct ev_loop *loop = ev_default_loop (0);
47 49
48 // initialise an io watcher, then start it 50 // initialise an io watcher, then start it
49 // this one will watch for stdin to become readable 51 // this one will watch for stdin to become readable
50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 52 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
51 ev_io_start (loop, &stdin_watcher); 53 ev_io_start (loop, &stdin_watcher);
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
84=head2 FEATURES 98=head2 FEATURES
85 99
86Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 100Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
87BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 101BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
88for file descriptor events (C<ev_io>), the Linux C<inotify> interface 102for file descriptor events (C<ev_io>), the Linux C<inotify> interface
89(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 103(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
90with customised rescheduling (C<ev_periodic>), synchronous signals 104inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
91(C<ev_signal>), process status change events (C<ev_child>), and event 105timers (C<ev_timer>), absolute timers with customised rescheduling
92watchers dealing with the event loop mechanism itself (C<ev_idle>, 106(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
93C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 107change events (C<ev_child>), and event watchers dealing with the event
94file watchers (C<ev_stat>) and even limited support for fork events 108loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
95(C<ev_fork>). 109C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
110limited support for fork events (C<ev_fork>).
96 111
97It also is quite fast (see this 112It also is quite fast (see this
98L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 113L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
99for example). 114for example).
100 115
108name C<loop> (which is always of type C<ev_loop *>) will not have 123name C<loop> (which is always of type C<ev_loop *>) will not have
109this argument. 124this argument.
110 125
111=head2 TIME REPRESENTATION 126=head2 TIME REPRESENTATION
112 127
113Libev represents time as a single floating point number, representing the 128Libev represents time as a single floating point number, representing
114(fractional) number of seconds since the (POSIX) epoch (somewhere near 129the (fractional) number of seconds since the (POSIX) epoch (somewhere
115the beginning of 1970, details are complicated, don't ask). This type is 130near 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 131type 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 132aliases 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 133on 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 134component C<stamp> might indicate, it is also used for time differences
120throughout libev. 135throughout libev.
121 136
122=head1 ERROR HANDLING 137=head1 ERROR HANDLING
123 138
276 291
277=back 292=back
278 293
279=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 294=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
280 295
281An event loop is described by a C<ev_loop *>. The library knows two 296An 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 297is I<not> optional in this case, as there is also an C<ev_loop>
283events, and dynamically created loops which do not. 298I<function>).
299
300The library knows two types of such loops, the I<default> loop, which
301supports signals and child events, and dynamically created loops which do
302not.
284 303
285=over 4 304=over 4
286 305
287=item struct ev_loop *ev_default_loop (unsigned int flags) 306=item struct ev_loop *ev_default_loop (unsigned int flags)
288 307
294If you don't know what event loop to use, use the one returned from this 313If you don't know what event loop to use, use the one returned from this
295function. 314function.
296 315
297Note that this function is I<not> thread-safe, so if you want to use it 316Note 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, 317from multiple threads, you have to lock (note also that this is unlikely,
299as loops cannot bes hared easily between threads anyway). 318as loops cannot be shared easily between threads anyway).
300 319
301The default loop is the only loop that can handle C<ev_signal> and 320The 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 321C<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 322for 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 323create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
344flag. 363flag.
345 364
346This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 365This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
347environment variable. 366environment variable.
348 367
368=item C<EVFLAG_NOINOTIFY>
369
370When this flag is specified, then libev will not attempt to use the
371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372testing, this flag can be useful to conserve inotify file descriptors, as
373otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374
375=item C<EVFLAG_NOSIGFD>
376
377When this flag is specified, then libev will not attempt to use the
378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is
379probably only useful to work around any bugs in libev. Consequently, this
380flag might go away once the signalfd functionality is considered stable,
381so it's useful mostly in environment variables and not in program code.
382
349=item C<EVBACKEND_SELECT> (value 1, portable select backend) 383=item C<EVBACKEND_SELECT> (value 1, portable select backend)
350 384
351This is your standard select(2) backend. Not I<completely> standard, as 385This is your standard select(2) backend. Not I<completely> standard, as
352libev tries to roll its own fd_set with no limits on the number of fds, 386libev tries to roll its own fd_set with no limits on the number of fds,
353but if that fails, expect a fairly low limit on the number of fds when 387but if that fails, expect a fairly low limit on the number of fds when
380=item C<EVBACKEND_EPOLL> (value 4, Linux) 414=item C<EVBACKEND_EPOLL> (value 4, Linux)
381 415
382For few fds, this backend is a bit little slower than poll and select, 416For few fds, this backend is a bit little slower than poll and select,
383but it scales phenomenally better. While poll and select usually scale 417but it scales phenomenally better. While poll and select usually scale
384like O(total_fds) where n is the total number of fds (or the highest fd), 418like O(total_fds) where n is the total number of fds (or the highest fd),
385epoll scales either O(1) or O(active_fds). The epoll design has a number 419epoll scales either O(1) or O(active_fds).
386of shortcomings, such as silently dropping events in some hard-to-detect 420
387cases and requiring a system call per fd change, no fork support and bad 421The epoll mechanism deserves honorable mention as the most misdesigned
388support for dup. 422of the more advanced event mechanisms: mere annoyances include silently
423dropping file descriptors, requiring a system call per change per file
424descriptor (and unnecessary guessing of parameters), problems with dup and
425so on. The biggest issue is fork races, however - if a program forks then
426I<both> parent and child process have to recreate the epoll set, which can
427take considerable time (one syscall per file descriptor) and is of course
428hard to detect.
429
430Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
431of course I<doesn't>, and epoll just loves to report events for totally
432I<different> file descriptors (even already closed ones, so one cannot
433even remove them from the set) than registered in the set (especially
434on SMP systems). Libev tries to counter these spurious notifications by
435employing an additional generation counter and comparing that against the
436events to filter out spurious ones, recreating the set when required.
389 437
390While stopping, setting and starting an I/O watcher in the same iteration 438While stopping, setting and starting an I/O watcher in the same iteration
391will result in some caching, there is still a system call per such incident 439will result in some caching, there is still a system call per such
392(because the fd could point to a different file description now), so its 440incident (because the same I<file descriptor> could point to a different
393best to avoid that. Also, C<dup ()>'ed file descriptors might not work 441I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
394very well if you register events for both fds. 442file descriptors might not work very well if you register events for both
395 443file descriptors.
396Please note that epoll sometimes generates spurious notifications, so you
397need to use non-blocking I/O or other means to avoid blocking when no data
398(or space) is available.
399 444
400Best performance from this backend is achieved by not unregistering all 445Best performance from this backend is achieved by not unregistering all
401watchers for a file descriptor until it has been closed, if possible, 446watchers for a file descriptor until it has been closed, if possible,
402i.e. keep at least one watcher active per fd at all times. Stopping and 447i.e. keep at least one watcher active per fd at all times. Stopping and
403starting a watcher (without re-setting it) also usually doesn't cause 448starting a watcher (without re-setting it) also usually doesn't cause
404extra overhead. 449extra overhead. A fork can both result in spurious notifications as well
450as in libev having to destroy and recreate the epoll object, which can
451take considerable time and thus should be avoided.
452
453All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
454faster than epoll for maybe up to a hundred file descriptors, depending on
455the usage. So sad.
405 456
406While nominally embeddable in other event loops, this feature is broken in 457While nominally embeddable in other event loops, this feature is broken in
407all kernel versions tested so far. 458all kernel versions tested so far.
408 459
409This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 460This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
410C<EVBACKEND_POLL>. 461C<EVBACKEND_POLL>.
411 462
412=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 463=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
413 464
414Kqueue deserves special mention, as at the time of this writing, it was 465Kqueue deserves special mention, as at the time of this writing, it
415broken on all BSDs except NetBSD (usually it doesn't work reliably with 466was broken on all BSDs except NetBSD (usually it doesn't work reliably
416anything but sockets and pipes, except on Darwin, where of course it's 467with anything but sockets and pipes, except on Darwin, where of course
417completely useless). For this reason it's not being "auto-detected" unless 468it's completely useless). Unlike epoll, however, whose brokenness
418you explicitly specify it in the flags (i.e. using C<EVBACKEND_KQUEUE>) or 469is by design, these kqueue bugs can (and eventually will) be fixed
419libev was compiled on a known-to-be-good (-enough) system like NetBSD. 470without API changes to existing programs. For this reason it's not being
471"auto-detected" unless you explicitly specify it in the flags (i.e. using
472C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
473system like NetBSD.
420 474
421You still can embed kqueue into a normal poll or select backend and use it 475You still can embed kqueue into a normal poll or select backend and use it
422only for sockets (after having made sure that sockets work with kqueue on 476only for sockets (after having made sure that sockets work with kqueue on
423the target platform). See C<ev_embed> watchers for more info. 477the target platform). See C<ev_embed> watchers for more info.
424 478
425It scales in the same way as the epoll backend, but the interface to the 479It scales in the same way as the epoll backend, but the interface to the
426kernel is more efficient (which says nothing about its actual speed, of 480kernel is more efficient (which says nothing about its actual speed, of
427course). While stopping, setting and starting an I/O watcher does never 481course). While stopping, setting and starting an I/O watcher does never
428cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 482cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
429two event changes per incident. Support for C<fork ()> is very bad and it 483two event changes per incident. Support for C<fork ()> is very bad (but
430drops fds silently in similarly hard-to-detect cases. 484sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
485cases
431 486
432This backend usually performs well under most conditions. 487This backend usually performs well under most conditions.
433 488
434While nominally embeddable in other event loops, this doesn't work 489While nominally embeddable in other event loops, this doesn't work
435everywhere, so you might need to test for this. And since it is broken 490everywhere, so you might need to test for this. And since it is broken
436almost everywhere, you should only use it when you have a lot of sockets 491almost everywhere, you should only use it when you have a lot of sockets
437(for which it usually works), by embedding it into another event loop 492(for which it usually works), by embedding it into another event loop
438(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it, 493(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
439using it only for sockets. 494also broken on OS X)) and, did I mention it, using it only for sockets.
440 495
441This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with 496This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
442C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with 497C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
443C<NOTE_EOF>. 498C<NOTE_EOF>.
444 499
464might perform better. 519might perform better.
465 520
466On the positive side, with the exception of the spurious readiness 521On the positive side, with the exception of the spurious readiness
467notifications, this backend actually performed fully to specification 522notifications, this backend actually performed fully to specification
468in all tests and is fully embeddable, which is a rare feat among the 523in all tests and is fully embeddable, which is a rare feat among the
469OS-specific backends. 524OS-specific backends (I vastly prefer correctness over speed hacks).
470 525
471This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 526This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
472C<EVBACKEND_POLL>. 527C<EVBACKEND_POLL>.
473 528
474=item C<EVBACKEND_ALL> 529=item C<EVBACKEND_ALL>
479 534
480It is definitely not recommended to use this flag. 535It is definitely not recommended to use this flag.
481 536
482=back 537=back
483 538
484If one or more of these are or'ed into the flags value, then only these 539If one or more of the backend flags are or'ed into the flags value,
485backends will be tried (in the reverse order as listed here). If none are 540then only these backends will be tried (in the reverse order as listed
486specified, all backends in C<ev_recommended_backends ()> will be tried. 541here). If none are specified, all backends in C<ev_recommended_backends
542()> will be tried.
487 543
488Example: This is the most typical usage. 544Example: This is the most typical usage.
489 545
490 if (!ev_default_loop (0)) 546 if (!ev_default_loop (0))
491 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 547 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
527responsibility to either stop all watchers cleanly yourself I<before> 583responsibility to either stop all watchers cleanly yourself I<before>
528calling this function, or cope with the fact afterwards (which is usually 584calling this function, or cope with the fact afterwards (which is usually
529the easiest thing, you can just ignore the watchers and/or C<free ()> them 585the easiest thing, you can just ignore the watchers and/or C<free ()> them
530for example). 586for example).
531 587
532Note that certain global state, such as signal state, will not be freed by 588Note that certain global state, such as signal state (and installed signal
533this function, and related watchers (such as signal and child watchers) 589handlers), will not be freed by this function, and related watchers (such
534would need to be stopped manually. 590as signal and child watchers) would need to be stopped manually.
535 591
536In general it is not advisable to call this function except in the 592In general it is not advisable to call this function except in the
537rare occasion where you really need to free e.g. the signal handling 593rare occasion where you really need to free e.g. the signal handling
538pipe fds. If you need dynamically allocated loops it is better to use 594pipe fds. If you need dynamically allocated loops it is better to use
539C<ev_loop_new> and C<ev_loop_destroy>). 595C<ev_loop_new> and C<ev_loop_destroy>.
540 596
541=item ev_loop_destroy (loop) 597=item ev_loop_destroy (loop)
542 598
543Like C<ev_default_destroy>, but destroys an event loop created by an 599Like C<ev_default_destroy>, but destroys an event loop created by an
544earlier call to C<ev_loop_new>. 600earlier call to C<ev_loop_new>.
582 638
583This value can sometimes be useful as a generation counter of sorts (it 639This value can sometimes be useful as a generation counter of sorts (it
584"ticks" the number of loop iterations), as it roughly corresponds with 640"ticks" the number of loop iterations), as it roughly corresponds with
585C<ev_prepare> and C<ev_check> calls. 641C<ev_prepare> and C<ev_check> calls.
586 642
643=item unsigned int ev_loop_depth (loop)
644
645Returns the number of times C<ev_loop> was entered minus the number of
646times C<ev_loop> was exited, in other words, the recursion depth.
647
648Outside C<ev_loop>, this number is zero. In a callback, this number is
649C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
650in which case it is higher.
651
652Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
653etc.), doesn't count as exit.
654
587=item unsigned int ev_backend (loop) 655=item unsigned int ev_backend (loop)
588 656
589Returns one of the C<EVBACKEND_*> flags indicating the event backend in 657Returns one of the C<EVBACKEND_*> flags indicating the event backend in
590use. 658use.
591 659
605 673
606This function is rarely useful, but when some event callback runs for a 674This function is rarely useful, but when some event callback runs for a
607very long time without entering the event loop, updating libev's idea of 675very long time without entering the event loop, updating libev's idea of
608the current time is a good idea. 676the current time is a good idea.
609 677
610See also "The special problem of time updates" in the C<ev_timer> section. 678See also L<The special problem of time updates> in the C<ev_timer> section.
679
680=item ev_suspend (loop)
681
682=item ev_resume (loop)
683
684These two functions suspend and resume a loop, for use when the loop is
685not used for a while and timeouts should not be processed.
686
687A typical use case would be an interactive program such as a game: When
688the user presses C<^Z> to suspend the game and resumes it an hour later it
689would be best to handle timeouts as if no time had actually passed while
690the program was suspended. This can be achieved by calling C<ev_suspend>
691in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
692C<ev_resume> directly afterwards to resume timer processing.
693
694Effectively, all C<ev_timer> watchers will be delayed by the time spend
695between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
696will be rescheduled (that is, they will lose any events that would have
697occured while suspended).
698
699After calling C<ev_suspend> you B<must not> call I<any> function on the
700given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
701without a previous call to C<ev_suspend>.
702
703Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
704event loop time (see C<ev_now_update>).
611 705
612=item ev_loop (loop, int flags) 706=item ev_loop (loop, int flags)
613 707
614Finally, this is it, the event handler. This function usually is called 708Finally, this is it, the event handler. This function usually is called
615after you initialised all your watchers and you want to start handling 709after you have initialised all your watchers and you want to start
616events. 710handling events.
617 711
618If the flags argument is specified as C<0>, it will not return until 712If the flags argument is specified as C<0>, it will not return until
619either no event watchers are active anymore or C<ev_unloop> was called. 713either no event watchers are active anymore or C<ev_unloop> was called.
620 714
621Please note that an explicit C<ev_unloop> is usually better than 715Please note that an explicit C<ev_unloop> is usually better than
631the loop. 725the loop.
632 726
633A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 727A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
634necessary) and will handle those and any already outstanding ones. It 728necessary) and will handle those and any already outstanding ones. It
635will block your process until at least one new event arrives (which could 729will block your process until at least one new event arrives (which could
636be an event internal to libev itself, so there is no guarentee that a 730be an event internal to libev itself, so there is no guarantee that a
637user-registered callback will be called), and will return after one 731user-registered callback will be called), and will return after one
638iteration of the loop. 732iteration of the loop.
639 733
640This is useful if you are waiting for some external event in conjunction 734This is useful if you are waiting for some external event in conjunction
641with something not expressible using other libev watchers (i.e. "roll your 735with something not expressible using other libev watchers (i.e. "roll your
699 793
700If you have a watcher you never unregister that should not keep C<ev_loop> 794If you have a watcher you never unregister that should not keep C<ev_loop>
701from returning, call ev_unref() after starting, and ev_ref() before 795from returning, call ev_unref() after starting, and ev_ref() before
702stopping it. 796stopping it.
703 797
704As an example, libev itself uses this for its internal signal pipe: It is 798As an example, libev itself uses this for its internal signal pipe: It
705not visible to the libev user and should not keep C<ev_loop> from exiting 799is not visible to the libev user and should not keep C<ev_loop> from
706if no event watchers registered by it are active. It is also an excellent 800exiting if no event watchers registered by it are active. It is also an
707way to do this for generic recurring timers or from within third-party 801excellent way to do this for generic recurring timers or from within
708libraries. Just remember to I<unref after start> and I<ref before stop> 802third-party libraries. Just remember to I<unref after start> and I<ref
709(but only if the watcher wasn't active before, or was active before, 803before stop> (but only if the watcher wasn't active before, or was active
710respectively). 804before, respectively. Note also that libev might stop watchers itself
805(e.g. non-repeating timers) in which case you have to C<ev_ref>
806in the callback).
711 807
712Example: Create a signal watcher, but keep it from keeping C<ev_loop> 808Example: Create a signal watcher, but keep it from keeping C<ev_loop>
713running when nothing else is active. 809running when nothing else is active.
714 810
715 ev_signal exitsig; 811 ev_signal exitsig;
744 840
745By setting a higher I<io collect interval> you allow libev to spend more 841By setting a higher I<io collect interval> you allow libev to spend more
746time collecting I/O events, so you can handle more events per iteration, 842time collecting I/O events, so you can handle more events per iteration,
747at the cost of increasing latency. Timeouts (both C<ev_periodic> and 843at the cost of increasing latency. Timeouts (both C<ev_periodic> and
748C<ev_timer>) will be not affected. Setting this to a non-null value will 844C<ev_timer>) will be not affected. Setting this to a non-null value will
749introduce an additional C<ev_sleep ()> call into most loop iterations. 845introduce an additional C<ev_sleep ()> call into most loop iterations. The
846sleep time ensures that libev will not poll for I/O events more often then
847once per this interval, on average.
750 848
751Likewise, by setting a higher I<timeout collect interval> you allow libev 849Likewise, by setting a higher I<timeout collect interval> you allow libev
752to spend more time collecting timeouts, at the expense of increased 850to spend more time collecting timeouts, at the expense of increased
753latency/jitter/inexactness (the watcher callback will be called 851latency/jitter/inexactness (the watcher callback will be called
754later). C<ev_io> watchers will not be affected. Setting this to a non-null 852later). C<ev_io> watchers will not be affected. Setting this to a non-null
756 854
757Many (busy) programs can usually benefit by setting the I/O collect 855Many (busy) programs can usually benefit by setting the I/O collect
758interval to a value near C<0.1> or so, which is often enough for 856interval to a value near C<0.1> or so, which is often enough for
759interactive servers (of course not for games), likewise for timeouts. It 857interactive servers (of course not for games), likewise for timeouts. It
760usually doesn't make much sense to set it to a lower value than C<0.01>, 858usually doesn't make much sense to set it to a lower value than C<0.01>,
761as this approaches the timing granularity of most systems. 859as this approaches the timing granularity of most systems. Note that if
860you do transactions with the outside world and you can't increase the
861parallelity, then this setting will limit your transaction rate (if you
862need to poll once per transaction and the I/O collect interval is 0.01,
863then you can't do more than 100 transations per second).
762 864
763Setting the I<timeout collect interval> can improve the opportunity for 865Setting the I<timeout collect interval> can improve the opportunity for
764saving power, as the program will "bundle" timer callback invocations that 866saving power, as the program will "bundle" timer callback invocations that
765are "near" in time together, by delaying some, thus reducing the number of 867are "near" in time together, by delaying some, thus reducing the number of
766times the process sleeps and wakes up again. Another useful technique to 868times the process sleeps and wakes up again. Another useful technique to
767reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure 869reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
768they fire on, say, one-second boundaries only. 870they fire on, say, one-second boundaries only.
769 871
872Example: we only need 0.1s timeout granularity, and we wish not to poll
873more often than 100 times per second:
874
875 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
876 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
877
878=item ev_invoke_pending (loop)
879
880This call will simply invoke all pending watchers while resetting their
881pending state. Normally, C<ev_loop> does this automatically when required,
882but when overriding the invoke callback this call comes handy.
883
884=item int ev_pending_count (loop)
885
886Returns the number of pending watchers - zero indicates that no watchers
887are pending.
888
889=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
890
891This overrides the invoke pending functionality of the loop: Instead of
892invoking all pending watchers when there are any, C<ev_loop> will call
893this callback instead. This is useful, for example, when you want to
894invoke the actual watchers inside another context (another thread etc.).
895
896If you want to reset the callback, use C<ev_invoke_pending> as new
897callback.
898
899=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
900
901Sometimes you want to share the same loop between multiple threads. This
902can be done relatively simply by putting mutex_lock/unlock calls around
903each call to a libev function.
904
905However, C<ev_loop> can run an indefinite time, so it is not feasible to
906wait for it to return. One way around this is to wake up the loop via
907C<ev_unloop> and C<av_async_send>, another way is to set these I<release>
908and I<acquire> callbacks on the loop.
909
910When set, then C<release> will be called just before the thread is
911suspended waiting for new events, and C<acquire> is called just
912afterwards.
913
914Ideally, C<release> will just call your mutex_unlock function, and
915C<acquire> will just call the mutex_lock function again.
916
917While event loop modifications are allowed between invocations of
918C<release> and C<acquire> (that's their only purpose after all), no
919modifications done will affect the event loop, i.e. adding watchers will
920have no effect on the set of file descriptors being watched, or the time
921waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it
922to take note of any changes you made.
923
924In theory, threads executing C<ev_loop> will be async-cancel safe between
925invocations of C<release> and C<acquire>.
926
927See also the locking example in the C<THREADS> section later in this
928document.
929
930=item ev_set_userdata (loop, void *data)
931
932=item ev_userdata (loop)
933
934Set and retrieve a single C<void *> associated with a loop. When
935C<ev_set_userdata> has never been called, then C<ev_userdata> returns
936C<0.>
937
938These two functions can be used to associate arbitrary data with a loop,
939and are intended solely for the C<invoke_pending_cb>, C<release> and
940C<acquire> callbacks described above, but of course can be (ab-)used for
941any other purpose as well.
942
770=item ev_loop_verify (loop) 943=item ev_loop_verify (loop)
771 944
772This function only does something when C<EV_VERIFY> support has been 945This function only does something when C<EV_VERIFY> support has been
773compiled in. which is the default for non-minimal builds. It tries to go 946compiled in, which is the default for non-minimal builds. It tries to go
774through all internal structures and checks them for validity. If anything 947through all internal structures and checks them for validity. If anything
775is found to be inconsistent, it will print an error message to standard 948is found to be inconsistent, it will print an error message to standard
776error and call C<abort ()>. 949error and call C<abort ()>.
777 950
778This can be used to catch bugs inside libev itself: under normal 951This can be used to catch bugs inside libev itself: under normal
782=back 955=back
783 956
784 957
785=head1 ANATOMY OF A WATCHER 958=head1 ANATOMY OF A WATCHER
786 959
960In the following description, uppercase C<TYPE> in names stands for the
961watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
962watchers and C<ev_io_start> for I/O watchers.
963
787A watcher is a structure that you create and register to record your 964A watcher is a structure that you create and register to record your
788interest in some event. For instance, if you want to wait for STDIN to 965interest in some event. For instance, if you want to wait for STDIN to
789become readable, you would create an C<ev_io> watcher for that: 966become readable, you would create an C<ev_io> watcher for that:
790 967
791 static void my_cb (struct ev_loop *loop, ev_io *w, int revents) 968 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
793 ev_io_stop (w); 970 ev_io_stop (w);
794 ev_unloop (loop, EVUNLOOP_ALL); 971 ev_unloop (loop, EVUNLOOP_ALL);
795 } 972 }
796 973
797 struct ev_loop *loop = ev_default_loop (0); 974 struct ev_loop *loop = ev_default_loop (0);
975
798 ev_io stdin_watcher; 976 ev_io stdin_watcher;
977
799 ev_init (&stdin_watcher, my_cb); 978 ev_init (&stdin_watcher, my_cb);
800 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 979 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
801 ev_io_start (loop, &stdin_watcher); 980 ev_io_start (loop, &stdin_watcher);
981
802 ev_loop (loop, 0); 982 ev_loop (loop, 0);
803 983
804As you can see, you are responsible for allocating the memory for your 984As you can see, you are responsible for allocating the memory for your
805watcher structures (and it is usually a bad idea to do this on the stack, 985watcher structures (and it is I<usually> a bad idea to do this on the
806although this can sometimes be quite valid). 986stack).
987
988Each watcher has an associated watcher structure (called C<struct ev_TYPE>
989or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
807 990
808Each watcher structure must be initialised by a call to C<ev_init 991Each watcher structure must be initialised by a call to C<ev_init
809(watcher *, callback)>, which expects a callback to be provided. This 992(watcher *, callback)>, which expects a callback to be provided. This
810callback gets invoked each time the event occurs (or, in the case of I/O 993callback gets invoked each time the event occurs (or, in the case of I/O
811watchers, each time the event loop detects that the file descriptor given 994watchers, each time the event loop detects that the file descriptor given
812is readable and/or writable). 995is readable and/or writable).
813 996
814Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 997Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
815with arguments specific to this watcher type. There is also a macro 998macro to configure it, with arguments specific to the watcher type. There
816to combine initialisation and setting in one call: C<< ev_<type>_init 999is also a macro to combine initialisation and setting in one call: C<<
817(watcher *, callback, ...) >>. 1000ev_TYPE_init (watcher *, callback, ...) >>.
818 1001
819To make the watcher actually watch out for events, you have to start it 1002To make the watcher actually watch out for events, you have to start it
820with a watcher-specific start function (C<< ev_<type>_start (loop, watcher 1003with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
821*) >>), and you can stop watching for events at any time by calling the 1004*) >>), and you can stop watching for events at any time by calling the
822corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>. 1005corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
823 1006
824As long as your watcher is active (has been started but not stopped) you 1007As long as your watcher is active (has been started but not stopped) you
825must not touch the values stored in it. Most specifically you must never 1008must not touch the values stored in it. Most specifically you must never
826reinitialise it or call its C<set> macro. 1009reinitialise it or call its C<ev_TYPE_set> macro.
827 1010
828Each and every callback receives the event loop pointer as first, the 1011Each and every callback receives the event loop pointer as first, the
829registered watcher structure as second, and a bitset of received events as 1012registered watcher structure as second, and a bitset of received events as
830third argument. 1013third argument.
831 1014
889 1072
890=item C<EV_ASYNC> 1073=item C<EV_ASYNC>
891 1074
892The given async watcher has been asynchronously notified (see C<ev_async>). 1075The given async watcher has been asynchronously notified (see C<ev_async>).
893 1076
1077=item C<EV_CUSTOM>
1078
1079Not ever sent (or otherwise used) by libev itself, but can be freely used
1080by libev users to signal watchers (e.g. via C<ev_feed_event>).
1081
894=item C<EV_ERROR> 1082=item C<EV_ERROR>
895 1083
896An unspecified error has occurred, the watcher has been stopped. This might 1084An unspecified error has occurred, the watcher has been stopped. This might
897happen because the watcher could not be properly started because libev 1085happen because the watcher could not be properly started because libev
898ran out of memory, a file descriptor was found to be closed or any other 1086ran out of memory, a file descriptor was found to be closed or any other
912 1100
913=back 1101=back
914 1102
915=head2 GENERIC WATCHER FUNCTIONS 1103=head2 GENERIC WATCHER FUNCTIONS
916 1104
917In the following description, C<TYPE> stands for the watcher type,
918e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
919
920=over 4 1105=over 4
921 1106
922=item C<ev_init> (ev_TYPE *watcher, callback) 1107=item C<ev_init> (ev_TYPE *watcher, callback)
923 1108
924This macro initialises the generic portion of a watcher. The contents 1109This macro initialises the generic portion of a watcher. The contents
1016integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1201integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1017(default: C<-2>). Pending watchers with higher priority will be invoked 1202(default: C<-2>). Pending watchers with higher priority will be invoked
1018before watchers with lower priority, but priority will not keep watchers 1203before watchers with lower priority, but priority will not keep watchers
1019from being executed (except for C<ev_idle> watchers). 1204from being executed (except for C<ev_idle> watchers).
1020 1205
1021This means that priorities are I<only> used for ordering callback
1022invocation after new events have been received. This is useful, for
1023example, to reduce latency after idling, or more often, to bind two
1024watchers on the same event and make sure one is called first.
1025
1026If you need to suppress invocation when higher priority events are pending 1206If you need to suppress invocation when higher priority events are pending
1027you need to look at C<ev_idle> watchers, which provide this functionality. 1207you need to look at C<ev_idle> watchers, which provide this functionality.
1028 1208
1029You I<must not> change the priority of a watcher as long as it is active or 1209You I<must not> change the priority of a watcher as long as it is active or
1030pending. 1210pending.
1031 1211
1212Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1213fine, as long as you do not mind that the priority value you query might
1214or might not have been clamped to the valid range.
1215
1032The default priority used by watchers when no priority has been set is 1216The default priority used by watchers when no priority has been set is
1033always C<0>, which is supposed to not be too high and not be too low :). 1217always C<0>, which is supposed to not be too high and not be too low :).
1034 1218
1035Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1219See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1036fine, as long as you do not mind that the priority value you query might 1220priorities.
1037or might not have been adjusted to be within valid range.
1038 1221
1039=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1222=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1040 1223
1041Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1224Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1042C<loop> nor C<revents> need to be valid as long as the watcher callback 1225C<loop> nor C<revents> need to be valid as long as the watcher callback
1107 #include <stddef.h> 1290 #include <stddef.h>
1108 1291
1109 static void 1292 static void
1110 t1_cb (EV_P_ ev_timer *w, int revents) 1293 t1_cb (EV_P_ ev_timer *w, int revents)
1111 { 1294 {
1112 struct my_biggy big = (struct my_biggy * 1295 struct my_biggy big = (struct my_biggy *)
1113 (((char *)w) - offsetof (struct my_biggy, t1)); 1296 (((char *)w) - offsetof (struct my_biggy, t1));
1114 } 1297 }
1115 1298
1116 static void 1299 static void
1117 t2_cb (EV_P_ ev_timer *w, int revents) 1300 t2_cb (EV_P_ ev_timer *w, int revents)
1118 { 1301 {
1119 struct my_biggy big = (struct my_biggy * 1302 struct my_biggy big = (struct my_biggy *)
1120 (((char *)w) - offsetof (struct my_biggy, t2)); 1303 (((char *)w) - offsetof (struct my_biggy, t2));
1121 } 1304 }
1305
1306=head2 WATCHER PRIORITY MODELS
1307
1308Many event loops support I<watcher priorities>, which are usually small
1309integers that influence the ordering of event callback invocation
1310between watchers in some way, all else being equal.
1311
1312In libev, Watcher priorities can be set using C<ev_set_priority>. See its
1313description for the more technical details such as the actual priority
1314range.
1315
1316There are two common ways how these these priorities are being interpreted
1317by event loops:
1318
1319In the more common lock-out model, higher priorities "lock out" invocation
1320of lower priority watchers, which means as long as higher priority
1321watchers receive events, lower priority watchers are not being invoked.
1322
1323The less common only-for-ordering model uses priorities solely to order
1324callback invocation within a single event loop iteration: Higher priority
1325watchers are invoked before lower priority ones, but they all get invoked
1326before polling for new events.
1327
1328Libev uses the second (only-for-ordering) model for all its watchers
1329except for idle watchers (which use the lock-out model).
1330
1331The rationale behind this is that implementing the lock-out model for
1332watchers is not well supported by most kernel interfaces, and most event
1333libraries will just poll for the same events again and again as long as
1334their callbacks have not been executed, which is very inefficient in the
1335common case of one high-priority watcher locking out a mass of lower
1336priority ones.
1337
1338Static (ordering) priorities are most useful when you have two or more
1339watchers handling the same resource: a typical usage example is having an
1340C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
1341timeouts. Under load, data might be received while the program handles
1342other jobs, but since timers normally get invoked first, the timeout
1343handler will be executed before checking for data. In that case, giving
1344the timer a lower priority than the I/O watcher ensures that I/O will be
1345handled first even under adverse conditions (which is usually, but not
1346always, what you want).
1347
1348Since idle watchers use the "lock-out" model, meaning that idle watchers
1349will only be executed when no same or higher priority watchers have
1350received events, they can be used to implement the "lock-out" model when
1351required.
1352
1353For example, to emulate how many other event libraries handle priorities,
1354you can associate an C<ev_idle> watcher to each such watcher, and in
1355the normal watcher callback, you just start the idle watcher. The real
1356processing is done in the idle watcher callback. This causes libev to
1357continously poll and process kernel event data for the watcher, but when
1358the lock-out case is known to be rare (which in turn is rare :), this is
1359workable.
1360
1361Usually, however, the lock-out model implemented that way will perform
1362miserably under the type of load it was designed to handle. In that case,
1363it might be preferable to stop the real watcher before starting the
1364idle watcher, so the kernel will not have to process the event in case
1365the actual processing will be delayed for considerable time.
1366
1367Here is an example of an I/O watcher that should run at a strictly lower
1368priority than the default, and which should only process data when no
1369other events are pending:
1370
1371 ev_idle idle; // actual processing watcher
1372 ev_io io; // actual event watcher
1373
1374 static void
1375 io_cb (EV_P_ ev_io *w, int revents)
1376 {
1377 // stop the I/O watcher, we received the event, but
1378 // are not yet ready to handle it.
1379 ev_io_stop (EV_A_ w);
1380
1381 // start the idle watcher to ahndle the actual event.
1382 // it will not be executed as long as other watchers
1383 // with the default priority are receiving events.
1384 ev_idle_start (EV_A_ &idle);
1385 }
1386
1387 static void
1388 idle_cb (EV_P_ ev_idle *w, int revents)
1389 {
1390 // actual processing
1391 read (STDIN_FILENO, ...);
1392
1393 // have to start the I/O watcher again, as
1394 // we have handled the event
1395 ev_io_start (EV_P_ &io);
1396 }
1397
1398 // initialisation
1399 ev_idle_init (&idle, idle_cb);
1400 ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
1401 ev_io_start (EV_DEFAULT_ &io);
1402
1403In the "real" world, it might also be beneficial to start a timer, so that
1404low-priority connections can not be locked out forever under load. This
1405enables your program to keep a lower latency for important connections
1406during short periods of high load, while not completely locking out less
1407important ones.
1122 1408
1123 1409
1124=head1 WATCHER TYPES 1410=head1 WATCHER TYPES
1125 1411
1126This section describes each watcher in detail, but will not repeat 1412This section describes each watcher in detail, but will not repeat
1152descriptors to non-blocking mode is also usually a good idea (but not 1438descriptors to non-blocking mode is also usually a good idea (but not
1153required if you know what you are doing). 1439required if you know what you are doing).
1154 1440
1155If you cannot use non-blocking mode, then force the use of a 1441If you cannot use non-blocking mode, then force the use of a
1156known-to-be-good backend (at the time of this writing, this includes only 1442known-to-be-good backend (at the time of this writing, this includes only
1157C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). 1443C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1444descriptors for which non-blocking operation makes no sense (such as
1445files) - libev doesn't guarentee any specific behaviour in that case.
1158 1446
1159Another thing you have to watch out for is that it is quite easy to 1447Another thing you have to watch out for is that it is quite easy to
1160receive "spurious" readiness notifications, that is your callback might 1448receive "spurious" readiness notifications, that is your callback might
1161be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1449be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1162because there is no data. Not only are some backends known to create a 1450because there is no data. Not only are some backends known to create a
1283year, it will still time out after (roughly) one hour. "Roughly" because 1571year, it will still time out after (roughly) one hour. "Roughly" because
1284detecting time jumps is hard, and some inaccuracies are unavoidable (the 1572detecting time jumps is hard, and some inaccuracies are unavoidable (the
1285monotonic clock option helps a lot here). 1573monotonic clock option helps a lot here).
1286 1574
1287The callback is guaranteed to be invoked only I<after> its timeout has 1575The callback is guaranteed to be invoked only I<after> its timeout has
1288passed, but if multiple timers become ready during the same loop iteration 1576passed (not I<at>, so on systems with very low-resolution clocks this
1289then order of execution is undefined. 1577might introduce a small delay). If multiple timers become ready during the
1578same loop iteration then the ones with earlier time-out values are invoked
1579before ones of the same priority with later time-out values (but this is
1580no longer true when a callback calls C<ev_loop> recursively).
1290 1581
1291=head3 Be smart about timeouts 1582=head3 Be smart about timeouts
1292 1583
1293Many real-world problems invole some kind of time-out, usually for error 1584Many real-world problems involve some kind of timeout, usually for error
1294recovery. A typical example is an HTTP request - if the other side hangs, 1585recovery. A typical example is an HTTP request - if the other side hangs,
1295you want to raise some error after a while. 1586you want to raise some error after a while.
1296 1587
1297Here are some ways on how to handle this problem, from simple and 1588What follows are some ways to handle this problem, from obvious and
1298inefficient to very efficient. 1589inefficient to smart and efficient.
1299 1590
1300In the following examples a 60 second activity timeout is assumed - a 1591In the following, a 60 second activity timeout is assumed - a timeout that
1301timeout that gets reset to 60 seconds each time some data ("a lifesign") 1592gets reset to 60 seconds each time there is activity (e.g. each time some
1302was received. 1593data or other life sign was received).
1303 1594
1304=over 4 1595=over 4
1305 1596
1306=item 1. Use a timer and stop, reinitialise, start it on activity. 1597=item 1. Use a timer and stop, reinitialise and start it on activity.
1307 1598
1308This is the most obvious, but not the most simple way: In the beginning, 1599This is the most obvious, but not the most simple way: In the beginning,
1309start the watcher: 1600start the watcher:
1310 1601
1311 ev_timer_init (timer, callback, 60., 0.); 1602 ev_timer_init (timer, callback, 60., 0.);
1312 ev_timer_start (loop, timer); 1603 ev_timer_start (loop, timer);
1313 1604
1314Then, each time there is some activity, C<ev_timer_stop> the timer, 1605Then, each time there is some activity, C<ev_timer_stop> it, initialise it
1315initialise it again, and start it: 1606and start it again:
1316 1607
1317 ev_timer_stop (loop, timer); 1608 ev_timer_stop (loop, timer);
1318 ev_timer_set (timer, 60., 0.); 1609 ev_timer_set (timer, 60., 0.);
1319 ev_timer_start (loop, timer); 1610 ev_timer_start (loop, timer);
1320 1611
1321This is relatively simple to implement, but means that each time there 1612This is relatively simple to implement, but means that each time there is
1322is some activity, libev will first have to remove the timer from it's 1613some activity, libev will first have to remove the timer from its internal
1323internal data strcuture and then add it again. 1614data structure and then add it again. Libev tries to be fast, but it's
1615still not a constant-time operation.
1324 1616
1325=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity. 1617=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity.
1326 1618
1327This is the easiest way, and involves using C<ev_timer_again> instead of 1619This is the easiest way, and involves using C<ev_timer_again> instead of
1328C<ev_timer_start>. 1620C<ev_timer_start>.
1329 1621
1330For this, configure an C<ev_timer> with a C<repeat> value of C<60> and 1622To implement this, configure an C<ev_timer> with a C<repeat> value
1331then call C<ev_timer_again> at start and each time you successfully read 1623of C<60> and then call C<ev_timer_again> at start and each time you
1332or write some data. If you go into an idle state where you do not expect 1624successfully read or write some data. If you go into an idle state where
1333data to travel on the socket, you can C<ev_timer_stop> the timer, and 1625you do not expect data to travel on the socket, you can C<ev_timer_stop>
1334C<ev_timer_again> will automatically restart it if need be. 1626the timer, and C<ev_timer_again> will automatically restart it if need be.
1335 1627
1336That means you can ignore the C<after> value and C<ev_timer_start> 1628That means you can ignore both the C<ev_timer_start> function and the
1337altogether and only ever use the C<repeat> value and C<ev_timer_again>. 1629C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1630member and C<ev_timer_again>.
1338 1631
1339At start: 1632At start:
1340 1633
1341 ev_timer_init (timer, callback, 0., 60.); 1634 ev_init (timer, callback);
1635 timer->repeat = 60.;
1342 ev_timer_again (loop, timer); 1636 ev_timer_again (loop, timer);
1343 1637
1344Each time you receive some data: 1638Each time there is some activity:
1345 1639
1346 ev_timer_again (loop, timer); 1640 ev_timer_again (loop, timer);
1347 1641
1348It is even possible to change the time-out on the fly: 1642It is even possible to change the time-out on the fly, regardless of
1643whether the watcher is active or not:
1349 1644
1350 timer->repeat = 30.; 1645 timer->repeat = 30.;
1351 ev_timer_again (loop, timer); 1646 ev_timer_again (loop, timer);
1352 1647
1353This is slightly more efficient then stopping/starting the timer each time 1648This is slightly more efficient then stopping/starting the timer each time
1354you want to modify its timeout value, as libev does not have to completely 1649you want to modify its timeout value, as libev does not have to completely
1355remove and re-insert the timer from/into it's internal data structure. 1650remove and re-insert the timer from/into its internal data structure.
1651
1652It is, however, even simpler than the "obvious" way to do it.
1356 1653
1357=item 3. Let the timer time out, but then re-arm it as required. 1654=item 3. Let the timer time out, but then re-arm it as required.
1358 1655
1359This method is more tricky, but usually most efficient: Most timeouts are 1656This method is more tricky, but usually most efficient: Most timeouts are
1360relatively long compared to the loop iteration time - in our example, 1657relatively long compared to the intervals between other activity - in
1361within 60 seconds, there are usually many I/O events with associated 1658our example, within 60 seconds, there are usually many I/O events with
1362activity resets. 1659associated activity resets.
1363 1660
1364In this case, it would be more efficient to leave the C<ev_timer> alone, 1661In this case, it would be more efficient to leave the C<ev_timer> alone,
1365but remember the time of last activity, and check for a real timeout only 1662but remember the time of last activity, and check for a real timeout only
1366within the callback: 1663within the callback:
1367 1664
1368 ev_tstamp last_activity; // time of last activity 1665 ev_tstamp last_activity; // time of last activity
1369 1666
1370 static void 1667 static void
1371 callback (EV_P_ ev_timer *w, int revents) 1668 callback (EV_P_ ev_timer *w, int revents)
1372 { 1669 {
1373 ev_tstamp now = ev_now (EV_A); 1670 ev_tstamp now = ev_now (EV_A);
1374 ev_tstamp timeout = last_activity + 60.; 1671 ev_tstamp timeout = last_activity + 60.;
1375 1672
1376 // if last_activity is older than now - timeout, we did time out 1673 // if last_activity + 60. is older than now, we did time out
1377 if (timeout < now) 1674 if (timeout < now)
1378 { 1675 {
1379 // timeout occured, take action 1676 // timeout occured, take action
1380 } 1677 }
1381 else 1678 else
1382 { 1679 {
1383 // callback was invoked, but there was some activity, re-arm 1680 // callback was invoked, but there was some activity, re-arm
1384 // to fire in last_activity + 60. 1681 // the watcher to fire in last_activity + 60, which is
1682 // guaranteed to be in the future, so "again" is positive:
1385 w->again = timeout - now; 1683 w->repeat = timeout - now;
1386 ev_timer_again (EV_A_ w); 1684 ev_timer_again (EV_A_ w);
1387 } 1685 }
1388 } 1686 }
1389 1687
1390To summarise the callback: first calculate the real time-out (defined as 1688To summarise the callback: first calculate the real timeout (defined
1391"60 seconds after the last activity"), then check if that time has been 1689as "60 seconds after the last activity"), then check if that time has
1392reached, which means there was a real timeout. Otherwise the callback was 1690been reached, which means something I<did>, in fact, time out. Otherwise
1393invoked too early (timeout is in the future), so re-schedule the timer to 1691the callback was invoked too early (C<timeout> is in the future), so
1394fire at that future time. 1692re-schedule the timer to fire at that future time, to see if maybe we have
1693a timeout then.
1395 1694
1396Note how C<ev_timer_again> is used, taking advantage of the 1695Note how C<ev_timer_again> is used, taking advantage of the
1397C<ev_timer_again> optimisation when the timer is already running. 1696C<ev_timer_again> optimisation when the timer is already running.
1398 1697
1399This scheme causes more callback invocations (about one every 60 seconds), 1698This scheme causes more callback invocations (about one every 60 seconds
1400but virtually no calls to libev to change the timeout. 1699minus half the average time between activity), but virtually no calls to
1700libev to change the timeout.
1401 1701
1402To start the timer, simply intiialise the watcher and C<last_activity>, 1702To start the timer, simply initialise the watcher and set C<last_activity>
1403then call the callback: 1703to the current time (meaning we just have some activity :), then call the
1704callback, which will "do the right thing" and start the timer:
1404 1705
1405 ev_timer_init (timer, callback); 1706 ev_init (timer, callback);
1406 last_activity = ev_now (loop); 1707 last_activity = ev_now (loop);
1407 callback (loop, timer, EV_TIMEOUT); 1708 callback (loop, timer, EV_TIMEOUT);
1408 1709
1409And when there is some activity, simply remember the time in 1710And when there is some activity, simply store the current time in
1410C<last_activity>: 1711C<last_activity>, no libev calls at all:
1411 1712
1412 last_actiivty = ev_now (loop); 1713 last_actiivty = ev_now (loop);
1413 1714
1414This technique is slightly more complex, but in most cases where the 1715This technique is slightly more complex, but in most cases where the
1415time-out is unlikely to be triggered, much more efficient. 1716time-out is unlikely to be triggered, much more efficient.
1416 1717
1718Changing the timeout is trivial as well (if it isn't hard-coded in the
1719callback :) - just change the timeout and invoke the callback, which will
1720fix things for you.
1721
1722=item 4. Wee, just use a double-linked list for your timeouts.
1723
1724If there is not one request, but many thousands (millions...), all
1725employing some kind of timeout with the same timeout value, then one can
1726do even better:
1727
1728When starting the timeout, calculate the timeout value and put the timeout
1729at the I<end> of the list.
1730
1731Then use an C<ev_timer> to fire when the timeout at the I<beginning> of
1732the list is expected to fire (for example, using the technique #3).
1733
1734When there is some activity, remove the timer from the list, recalculate
1735the timeout, append it to the end of the list again, and make sure to
1736update the C<ev_timer> if it was taken from the beginning of the list.
1737
1738This way, one can manage an unlimited number of timeouts in O(1) time for
1739starting, stopping and updating the timers, at the expense of a major
1740complication, and having to use a constant timeout. The constant timeout
1741ensures that the list stays sorted.
1742
1417=back 1743=back
1744
1745So which method the best?
1746
1747Method #2 is a simple no-brain-required solution that is adequate in most
1748situations. Method #3 requires a bit more thinking, but handles many cases
1749better, and isn't very complicated either. In most case, choosing either
1750one is fine, with #3 being better in typical situations.
1751
1752Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1753rather complicated, but extremely efficient, something that really pays
1754off after the first million or so of active timers, i.e. it's usually
1755overkill :)
1418 1756
1419=head3 The special problem of time updates 1757=head3 The special problem of time updates
1420 1758
1421Establishing the current time is a costly operation (it usually takes at 1759Establishing the current time is a costly operation (it usually takes at
1422least two system calls): EV therefore updates its idea of the current 1760least two system calls): EV therefore updates its idea of the current
1434 1772
1435If the event loop is suspended for a long time, you can also force an 1773If the event loop is suspended for a long time, you can also force an
1436update of the time returned by C<ev_now ()> by calling C<ev_now_update 1774update of the time returned by C<ev_now ()> by calling C<ev_now_update
1437()>. 1775()>.
1438 1776
1777=head3 The special problems of suspended animation
1778
1779When you leave the server world it is quite customary to hit machines that
1780can suspend/hibernate - what happens to the clocks during such a suspend?
1781
1782Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
1783all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
1784to run until the system is suspended, but they will not advance while the
1785system is suspended. That means, on resume, it will be as if the program
1786was frozen for a few seconds, but the suspend time will not be counted
1787towards C<ev_timer> when a monotonic clock source is used. The real time
1788clock advanced as expected, but if it is used as sole clocksource, then a
1789long suspend would be detected as a time jump by libev, and timers would
1790be adjusted accordingly.
1791
1792I would not be surprised to see different behaviour in different between
1793operating systems, OS versions or even different hardware.
1794
1795The other form of suspend (job control, or sending a SIGSTOP) will see a
1796time jump in the monotonic clocks and the realtime clock. If the program
1797is suspended for a very long time, and monotonic clock sources are in use,
1798then you can expect C<ev_timer>s to expire as the full suspension time
1799will be counted towards the timers. When no monotonic clock source is in
1800use, then libev will again assume a timejump and adjust accordingly.
1801
1802It might be beneficial for this latter case to call C<ev_suspend>
1803and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
1804deterministic behaviour in this case (you can do nothing against
1805C<SIGSTOP>).
1806
1439=head3 Watcher-Specific Functions and Data Members 1807=head3 Watcher-Specific Functions and Data Members
1440 1808
1441=over 4 1809=over 4
1442 1810
1443=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1811=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1466If the timer is started but non-repeating, stop it (as if it timed out). 1834If the timer is started but non-repeating, stop it (as if it timed out).
1467 1835
1468If the timer is repeating, either start it if necessary (with the 1836If the timer is repeating, either start it if necessary (with the
1469C<repeat> value), or reset the running timer to the C<repeat> value. 1837C<repeat> value), or reset the running timer to the C<repeat> value.
1470 1838
1471This sounds a bit complicated, see "Be smart about timeouts", above, for a 1839This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1472usage example. 1840usage example.
1841
1842=item ev_timer_remaining (loop, ev_timer *)
1843
1844Returns the remaining time until a timer fires. If the timer is active,
1845then this time is relative to the current event loop time, otherwise it's
1846the timeout value currently configured.
1847
1848That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1849C<5>. When the timer is started and one second passes, C<ev_timer_remain>
1850will return C<4>. When the timer expires and is restarted, it will return
1851roughly C<7> (likely slightly less as callback invocation takes some time,
1852too), and so on.
1473 1853
1474=item ev_tstamp repeat [read-write] 1854=item ev_tstamp repeat [read-write]
1475 1855
1476The current C<repeat> value. Will be used each time the watcher times out 1856The current C<repeat> value. Will be used each time the watcher times out
1477or C<ev_timer_again> is called, and determines the next timeout (if any), 1857or C<ev_timer_again> is called, and determines the next timeout (if any),
1515=head2 C<ev_periodic> - to cron or not to cron? 1895=head2 C<ev_periodic> - to cron or not to cron?
1516 1896
1517Periodic watchers are also timers of a kind, but they are very versatile 1897Periodic watchers are also timers of a kind, but they are very versatile
1518(and unfortunately a bit complex). 1898(and unfortunately a bit complex).
1519 1899
1520Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1900Unlike C<ev_timer>, periodic watchers are not based on real time (or
1521but on wall clock time (absolute time). You can tell a periodic watcher 1901relative time, the physical time that passes) but on wall clock time
1522to trigger after some specific point in time. For example, if you tell a 1902(absolute time, the thing you can read on your calender or clock). The
1523periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now () 1903difference is that wall clock time can run faster or slower than real
1524+ 10.>, that is, an absolute time not a delay) and then reset your system 1904time, and time jumps are not uncommon (e.g. when you adjust your
1525clock to January of the previous year, then it will take more than year 1905wrist-watch).
1526to trigger the event (unlike an C<ev_timer>, which would still trigger
1527roughly 10 seconds later as it uses a relative timeout).
1528 1906
1907You can tell a periodic watcher to trigger after some specific point
1908in time: for example, if you tell a periodic watcher to trigger "in 10
1909seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
1910not a delay) and then reset your system clock to January of the previous
1911year, then it will take a year or more to trigger the event (unlike an
1912C<ev_timer>, which would still trigger roughly 10 seconds after starting
1913it, as it uses a relative timeout).
1914
1529C<ev_periodic>s can also be used to implement vastly more complex timers, 1915C<ev_periodic> watchers can also be used to implement vastly more complex
1530such as triggering an event on each "midnight, local time", or other 1916timers, such as triggering an event on each "midnight, local time", or
1531complicated rules. 1917other complicated rules. This cannot be done with C<ev_timer> watchers, as
1918those cannot react to time jumps.
1532 1919
1533As with timers, the callback is guaranteed to be invoked only when the 1920As with timers, the callback is guaranteed to be invoked only when the
1534time (C<at>) has passed, but if multiple periodic timers become ready 1921point in time where it is supposed to trigger has passed. If multiple
1535during the same loop iteration, then order of execution is undefined. 1922timers become ready during the same loop iteration then the ones with
1923earlier time-out values are invoked before ones with later time-out values
1924(but this is no longer true when a callback calls C<ev_loop> recursively).
1536 1925
1537=head3 Watcher-Specific Functions and Data Members 1926=head3 Watcher-Specific Functions and Data Members
1538 1927
1539=over 4 1928=over 4
1540 1929
1541=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1930=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1542 1931
1543=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1932=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1544 1933
1545Lots of arguments, lets sort it out... There are basically three modes of 1934Lots of arguments, let's sort it out... There are basically three modes of
1546operation, and we will explain them from simplest to most complex: 1935operation, and we will explain them from simplest to most complex:
1547 1936
1548=over 4 1937=over 4
1549 1938
1550=item * absolute timer (at = time, interval = reschedule_cb = 0) 1939=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1551 1940
1552In this configuration the watcher triggers an event after the wall clock 1941In this configuration the watcher triggers an event after the wall clock
1553time C<at> has passed. It will not repeat and will not adjust when a time 1942time C<offset> has passed. It will not repeat and will not adjust when a
1554jump occurs, that is, if it is to be run at January 1st 2011 then it will 1943time jump occurs, that is, if it is to be run at January 1st 2011 then it
1555only run when the system clock reaches or surpasses this time. 1944will be stopped and invoked when the system clock reaches or surpasses
1945this point in time.
1556 1946
1557=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1947=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1558 1948
1559In this mode the watcher will always be scheduled to time out at the next 1949In this mode the watcher will always be scheduled to time out at the next
1560C<at + N * interval> time (for some integer N, which can also be negative) 1950C<offset + N * interval> time (for some integer N, which can also be
1561and then repeat, regardless of any time jumps. 1951negative) and then repeat, regardless of any time jumps. The C<offset>
1952argument is merely an offset into the C<interval> periods.
1562 1953
1563This can be used to create timers that do not drift with respect to the 1954This can be used to create timers that do not drift with respect to the
1564system clock, for example, here is a C<ev_periodic> that triggers each 1955system clock, for example, here is an C<ev_periodic> that triggers each
1565hour, on the hour: 1956hour, on the hour (with respect to UTC):
1566 1957
1567 ev_periodic_set (&periodic, 0., 3600., 0); 1958 ev_periodic_set (&periodic, 0., 3600., 0);
1568 1959
1569This doesn't mean there will always be 3600 seconds in between triggers, 1960This doesn't mean there will always be 3600 seconds in between triggers,
1570but only that the callback will be called when the system time shows a 1961but only that the callback will be called when the system time shows a
1571full hour (UTC), or more correctly, when the system time is evenly divisible 1962full hour (UTC), or more correctly, when the system time is evenly divisible
1572by 3600. 1963by 3600.
1573 1964
1574Another way to think about it (for the mathematically inclined) is that 1965Another way to think about it (for the mathematically inclined) is that
1575C<ev_periodic> will try to run the callback in this mode at the next possible 1966C<ev_periodic> will try to run the callback in this mode at the next possible
1576time where C<time = at (mod interval)>, regardless of any time jumps. 1967time where C<time = offset (mod interval)>, regardless of any time jumps.
1577 1968
1578For numerical stability it is preferable that the C<at> value is near 1969For numerical stability it is preferable that the C<offset> value is near
1579C<ev_now ()> (the current time), but there is no range requirement for 1970C<ev_now ()> (the current time), but there is no range requirement for
1580this value, and in fact is often specified as zero. 1971this value, and in fact is often specified as zero.
1581 1972
1582Note also that there is an upper limit to how often a timer can fire (CPU 1973Note also that there is an upper limit to how often a timer can fire (CPU
1583speed for example), so if C<interval> is very small then timing stability 1974speed for example), so if C<interval> is very small then timing stability
1584will of course deteriorate. Libev itself tries to be exact to be about one 1975will of course deteriorate. Libev itself tries to be exact to be about one
1585millisecond (if the OS supports it and the machine is fast enough). 1976millisecond (if the OS supports it and the machine is fast enough).
1586 1977
1587=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1978=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1588 1979
1589In this mode the values for C<interval> and C<at> are both being 1980In this mode the values for C<interval> and C<offset> are both being
1590ignored. Instead, each time the periodic watcher gets scheduled, the 1981ignored. Instead, each time the periodic watcher gets scheduled, the
1591reschedule callback will be called with the watcher as first, and the 1982reschedule callback will be called with the watcher as first, and the
1592current time as second argument. 1983current time as second argument.
1593 1984
1594NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1985NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1595ever, or make ANY event loop modifications whatsoever>. 1986or make ANY other event loop modifications whatsoever, unless explicitly
1987allowed by documentation here>.
1596 1988
1597If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 1989If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1598it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 1990it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1599only event loop modification you are allowed to do). 1991only event loop modification you are allowed to do).
1600 1992
1630a different time than the last time it was called (e.g. in a crond like 2022a different time than the last time it was called (e.g. in a crond like
1631program when the crontabs have changed). 2023program when the crontabs have changed).
1632 2024
1633=item ev_tstamp ev_periodic_at (ev_periodic *) 2025=item ev_tstamp ev_periodic_at (ev_periodic *)
1634 2026
1635When active, returns the absolute time that the watcher is supposed to 2027When active, returns the absolute time that the watcher is supposed
1636trigger next. 2028to trigger next. This is not the same as the C<offset> argument to
2029C<ev_periodic_set>, but indeed works even in interval and manual
2030rescheduling modes.
1637 2031
1638=item ev_tstamp offset [read-write] 2032=item ev_tstamp offset [read-write]
1639 2033
1640When repeating, this contains the offset value, otherwise this is the 2034When repeating, this contains the offset value, otherwise this is the
1641absolute point in time (the C<at> value passed to C<ev_periodic_set>). 2035absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
2036although libev might modify this value for better numerical stability).
1642 2037
1643Can be modified any time, but changes only take effect when the periodic 2038Can be modified any time, but changes only take effect when the periodic
1644timer fires or C<ev_periodic_again> is being called. 2039timer fires or C<ev_periodic_again> is being called.
1645 2040
1646=item ev_tstamp interval [read-write] 2041=item ev_tstamp interval [read-write]
1698Signal watchers will trigger an event when the process receives a specific 2093Signal watchers will trigger an event when the process receives a specific
1699signal one or more times. Even though signals are very asynchronous, libev 2094signal one or more times. Even though signals are very asynchronous, libev
1700will try it's best to deliver signals synchronously, i.e. as part of the 2095will try it's best to deliver signals synchronously, i.e. as part of the
1701normal event processing, like any other event. 2096normal event processing, like any other event.
1702 2097
1703If you want signals asynchronously, just use C<sigaction> as you would 2098If you want signals to be delivered truly asynchronously, just use
1704do without libev and forget about sharing the signal. You can even use 2099C<sigaction> as you would do without libev and forget about sharing
1705C<ev_async> from a signal handler to synchronously wake up an event loop. 2100the signal. You can even use C<ev_async> from a signal handler to
2101synchronously wake up an event loop.
1706 2102
1707You can configure as many watchers as you like per signal. Only when the 2103You can configure as many watchers as you like for the same signal, but
2104only within the same loop, i.e. you can watch for C<SIGINT> in your
2105default loop and for C<SIGIO> in another loop, but you cannot watch for
2106C<SIGINT> in both the default loop and another loop at the same time. At
2107the moment, C<SIGCHLD> is permanently tied to the default loop.
2108
1708first watcher gets started will libev actually register a signal handler 2109When the first watcher gets started will libev actually register something
1709with the kernel (thus it coexists with your own signal handlers as long as 2110with the kernel (thus it coexists with your own signal handlers as long as
1710you don't register any with libev for the same signal). Similarly, when 2111you don't register any with libev for the same signal).
1711the last signal watcher for a signal is stopped, libev will reset the
1712signal handler to SIG_DFL (regardless of what it was set to before).
1713 2112
1714If possible and supported, libev will install its handlers with 2113If possible and supported, libev will install its handlers with
1715C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2114C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
1716interrupted. If you have a problem with system calls getting interrupted by 2115not be unduly interrupted. If you have a problem with system calls getting
1717signals you can block all signals in an C<ev_check> watcher and unblock 2116interrupted by signals you can block all signals in an C<ev_check> watcher
1718them in an C<ev_prepare> watcher. 2117and unblock them in an C<ev_prepare> watcher.
2118
2119=head3 The special problem of inheritance over execve
2120
2121Both the signal mask (C<sigprocmask>) and the signal disposition
2122(C<sigaction>) are unspecified after starting a signal watcher (and after
2123stopping it again), that is, libev might or might not block the signal,
2124and might or might not set or restore the installed signal handler.
2125
2126While this does not matter for the signal disposition (libev never
2127sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2128C<execve>), this matters for the signal mask: many programs do not expect
2129certain signals to be blocked.
2130
2131This means that before calling C<exec> (from the child) you should reset
2132the signal mask to whatever "default" you expect (all clear is a good
2133choice usually).
2134
2135The simplest way to ensure that the signal mask is reset in the child is
2136to install a fork handler with C<pthread_atfork> that resets it. That will
2137catch fork calls done by libraries (such as the libc) as well.
2138
2139In current versions of libev, you can also ensure that the signal mask is
2140not blocking any signals (except temporarily, so thread users watch out)
2141by specifying the C<EVFLAG_NOSIGFD> when creating the event loop. This
2142is not guaranteed for future versions, however.
1719 2143
1720=head3 Watcher-Specific Functions and Data Members 2144=head3 Watcher-Specific Functions and Data Members
1721 2145
1722=over 4 2146=over 4
1723 2147
1755some child status changes (most typically when a child of yours dies or 2179some child status changes (most typically when a child of yours dies or
1756exits). It is permissible to install a child watcher I<after> the child 2180exits). It is permissible to install a child watcher I<after> the child
1757has been forked (which implies it might have already exited), as long 2181has been forked (which implies it might have already exited), as long
1758as the event loop isn't entered (or is continued from a watcher), i.e., 2182as the event loop isn't entered (or is continued from a watcher), i.e.,
1759forking and then immediately registering a watcher for the child is fine, 2183forking and then immediately registering a watcher for the child is fine,
1760but forking and registering a watcher a few event loop iterations later is 2184but forking and registering a watcher a few event loop iterations later or
1761not. 2185in the next callback invocation is not.
1762 2186
1763Only the default event loop is capable of handling signals, and therefore 2187Only the default event loop is capable of handling signals, and therefore
1764you can only register child watchers in the default event loop. 2188you can only register child watchers in the default event loop.
1765 2189
2190Due to some design glitches inside libev, child watchers will always be
2191handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2192libev)
2193
1766=head3 Process Interaction 2194=head3 Process Interaction
1767 2195
1768Libev grabs C<SIGCHLD> as soon as the default event loop is 2196Libev grabs C<SIGCHLD> as soon as the default event loop is
1769initialised. This is necessary to guarantee proper behaviour even if 2197initialised. This is necessary to guarantee proper behaviour even if the
1770the first child watcher is started after the child exits. The occurrence 2198first child watcher is started after the child exits. The occurrence
1771of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2199of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1772synchronously as part of the event loop processing. Libev always reaps all 2200synchronously as part of the event loop processing. Libev always reaps all
1773children, even ones not watched. 2201children, even ones not watched.
1774 2202
1775=head3 Overriding the Built-In Processing 2203=head3 Overriding the Built-In Processing
1785=head3 Stopping the Child Watcher 2213=head3 Stopping the Child Watcher
1786 2214
1787Currently, the child watcher never gets stopped, even when the 2215Currently, the child watcher never gets stopped, even when the
1788child terminates, so normally one needs to stop the watcher in the 2216child terminates, so normally one needs to stop the watcher in the
1789callback. Future versions of libev might stop the watcher automatically 2217callback. Future versions of libev might stop the watcher automatically
1790when a child exit is detected. 2218when a child exit is detected (calling C<ev_child_stop> twice is not a
2219problem).
1791 2220
1792=head3 Watcher-Specific Functions and Data Members 2221=head3 Watcher-Specific Functions and Data Members
1793 2222
1794=over 4 2223=over 4
1795 2224
1852 2281
1853 2282
1854=head2 C<ev_stat> - did the file attributes just change? 2283=head2 C<ev_stat> - did the file attributes just change?
1855 2284
1856This watches a file system path for attribute changes. That is, it calls 2285This watches a file system path for attribute changes. That is, it calls
1857C<stat> regularly (or when the OS says it changed) and sees if it changed 2286C<stat> on that path in regular intervals (or when the OS says it changed)
1858compared to the last time, invoking the callback if it did. 2287and sees if it changed compared to the last time, invoking the callback if
2288it did.
1859 2289
1860The path does not need to exist: changing from "path exists" to "path does 2290The path does not need to exist: changing from "path exists" to "path does
1861not exist" is a status change like any other. The condition "path does 2291not exist" is a status change like any other. The condition "path does not
1862not exist" is signified by the C<st_nlink> field being zero (which is 2292exist" (or more correctly "path cannot be stat'ed") is signified by the
1863otherwise always forced to be at least one) and all the other fields of 2293C<st_nlink> field being zero (which is otherwise always forced to be at
1864the stat buffer having unspecified contents. 2294least one) and all the other fields of the stat buffer having unspecified
2295contents.
1865 2296
1866The path I<should> be absolute and I<must not> end in a slash. If it is 2297The path I<must not> end in a slash or contain special components such as
2298C<.> or C<..>. The path I<should> be absolute: If it is relative and
1867relative and your working directory changes, the behaviour is undefined. 2299your working directory changes, then the behaviour is undefined.
1868 2300
1869Since there is no standard kernel interface to do this, the portable 2301Since there is no portable change notification interface available, the
1870implementation simply calls C<stat (2)> regularly on the path to see if 2302portable implementation simply calls C<stat(2)> regularly on the path
1871it changed somehow. You can specify a recommended polling interval for 2303to see if it changed somehow. You can specify a recommended polling
1872this case. If you specify a polling interval of C<0> (highly recommended!) 2304interval for this case. If you specify a polling interval of C<0> (highly
1873then a I<suitable, unspecified default> value will be used (which 2305recommended!) then a I<suitable, unspecified default> value will be used
1874you can expect to be around five seconds, although this might change 2306(which you can expect to be around five seconds, although this might
1875dynamically). Libev will also impose a minimum interval which is currently 2307change dynamically). Libev will also impose a minimum interval which is
1876around C<0.1>, but thats usually overkill. 2308currently around C<0.1>, but that's usually overkill.
1877 2309
1878This watcher type is not meant for massive numbers of stat watchers, 2310This watcher type is not meant for massive numbers of stat watchers,
1879as even with OS-supported change notifications, this can be 2311as even with OS-supported change notifications, this can be
1880resource-intensive. 2312resource-intensive.
1881 2313
1882At the time of this writing, the only OS-specific interface implemented 2314At the time of this writing, the only OS-specific interface implemented
1883is the Linux inotify interface (implementing kqueue support is left as 2315is the Linux inotify interface (implementing kqueue support is left as an
1884an exercise for the reader. Note, however, that the author sees no way 2316exercise for the reader. Note, however, that the author sees no way of
1885of implementing C<ev_stat> semantics with kqueue). 2317implementing C<ev_stat> semantics with kqueue, except as a hint).
1886 2318
1887=head3 ABI Issues (Largefile Support) 2319=head3 ABI Issues (Largefile Support)
1888 2320
1889Libev by default (unless the user overrides this) uses the default 2321Libev by default (unless the user overrides this) uses the default
1890compilation environment, which means that on systems with large file 2322compilation environment, which means that on systems with large file
1891support disabled by default, you get the 32 bit version of the stat 2323support disabled by default, you get the 32 bit version of the stat
1892structure. When using the library from programs that change the ABI to 2324structure. When using the library from programs that change the ABI to
1893use 64 bit file offsets the programs will fail. In that case you have to 2325use 64 bit file offsets the programs will fail. In that case you have to
1894compile libev with the same flags to get binary compatibility. This is 2326compile libev with the same flags to get binary compatibility. This is
1895obviously the case with any flags that change the ABI, but the problem is 2327obviously the case with any flags that change the ABI, but the problem is
1896most noticeably disabled with ev_stat and large file support. 2328most noticeably displayed with ev_stat and large file support.
1897 2329
1898The solution for this is to lobby your distribution maker to make large 2330The solution for this is to lobby your distribution maker to make large
1899file interfaces available by default (as e.g. FreeBSD does) and not 2331file interfaces available by default (as e.g. FreeBSD does) and not
1900optional. Libev cannot simply switch on large file support because it has 2332optional. Libev cannot simply switch on large file support because it has
1901to exchange stat structures with application programs compiled using the 2333to exchange stat structures with application programs compiled using the
1902default compilation environment. 2334default compilation environment.
1903 2335
1904=head3 Inotify and Kqueue 2336=head3 Inotify and Kqueue
1905 2337
1906When C<inotify (7)> support has been compiled into libev (generally 2338When C<inotify (7)> support has been compiled into libev and present at
1907only available with Linux 2.6.25 or above due to bugs in earlier 2339runtime, it will be used to speed up change detection where possible. The
1908implementations) and present at runtime, it will be used to speed up 2340inotify descriptor will be created lazily when the first C<ev_stat>
1909change detection where possible. The inotify descriptor will be created 2341watcher is being started.
1910lazily when the first C<ev_stat> watcher is being started.
1911 2342
1912Inotify presence does not change the semantics of C<ev_stat> watchers 2343Inotify presence does not change the semantics of C<ev_stat> watchers
1913except that changes might be detected earlier, and in some cases, to avoid 2344except that changes might be detected earlier, and in some cases, to avoid
1914making regular C<stat> calls. Even in the presence of inotify support 2345making regular C<stat> calls. Even in the presence of inotify support
1915there are many cases where libev has to resort to regular C<stat> polling, 2346there are many cases where libev has to resort to regular C<stat> polling,
1916but as long as the path exists, libev usually gets away without polling. 2347but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too
2348many bugs), the path exists (i.e. stat succeeds), and the path resides on
2349a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and
2350xfs are fully working) libev usually gets away without polling.
1917 2351
1918There is no support for kqueue, as apparently it cannot be used to 2352There is no support for kqueue, as apparently it cannot be used to
1919implement this functionality, due to the requirement of having a file 2353implement this functionality, due to the requirement of having a file
1920descriptor open on the object at all times, and detecting renames, unlinks 2354descriptor open on the object at all times, and detecting renames, unlinks
1921etc. is difficult. 2355etc. is difficult.
1922 2356
2357=head3 C<stat ()> is a synchronous operation
2358
2359Libev doesn't normally do any kind of I/O itself, and so is not blocking
2360the process. The exception are C<ev_stat> watchers - those call C<stat
2361()>, which is a synchronous operation.
2362
2363For local paths, this usually doesn't matter: unless the system is very
2364busy or the intervals between stat's are large, a stat call will be fast,
2365as the path data is usually in memory already (except when starting the
2366watcher).
2367
2368For networked file systems, calling C<stat ()> can block an indefinite
2369time due to network issues, and even under good conditions, a stat call
2370often takes multiple milliseconds.
2371
2372Therefore, it is best to avoid using C<ev_stat> watchers on networked
2373paths, although this is fully supported by libev.
2374
1923=head3 The special problem of stat time resolution 2375=head3 The special problem of stat time resolution
1924 2376
1925The C<stat ()> system call only supports full-second resolution portably, and 2377The C<stat ()> system call only supports full-second resolution portably,
1926even on systems where the resolution is higher, most file systems still 2378and even on systems where the resolution is higher, most file systems
1927only support whole seconds. 2379still only support whole seconds.
1928 2380
1929That means that, if the time is the only thing that changes, you can 2381That means that, if the time is the only thing that changes, you can
1930easily miss updates: on the first update, C<ev_stat> detects a change and 2382easily miss updates: on the first update, C<ev_stat> detects a change and
1931calls your callback, which does something. When there is another update 2383calls your callback, which does something. When there is another update
1932within the same second, C<ev_stat> will be unable to detect unless the 2384within the same second, C<ev_stat> will be unable to detect unless the
2075 2527
2076=head3 Watcher-Specific Functions and Data Members 2528=head3 Watcher-Specific Functions and Data Members
2077 2529
2078=over 4 2530=over 4
2079 2531
2080=item ev_idle_init (ev_signal *, callback) 2532=item ev_idle_init (ev_idle *, callback)
2081 2533
2082Initialises and configures the idle watcher - it has no parameters of any 2534Initialises and configures the idle watcher - it has no parameters of any
2083kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 2535kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
2084believe me. 2536believe me.
2085 2537
2098 // no longer anything immediate to do. 2550 // no longer anything immediate to do.
2099 } 2551 }
2100 2552
2101 ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 2553 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2102 ev_idle_init (idle_watcher, idle_cb); 2554 ev_idle_init (idle_watcher, idle_cb);
2103 ev_idle_start (loop, idle_cb); 2555 ev_idle_start (loop, idle_watcher);
2104 2556
2105 2557
2106=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2558=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2107 2559
2108Prepare and check watchers are usually (but not always) used in pairs: 2560Prepare and check watchers are usually (but not always) used in pairs:
2201 struct pollfd fds [nfd]; 2653 struct pollfd fds [nfd];
2202 // actual code will need to loop here and realloc etc. 2654 // actual code will need to loop here and realloc etc.
2203 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2655 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2204 2656
2205 /* the callback is illegal, but won't be called as we stop during check */ 2657 /* the callback is illegal, but won't be called as we stop during check */
2206 ev_timer_init (&tw, 0, timeout * 1e-3); 2658 ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
2207 ev_timer_start (loop, &tw); 2659 ev_timer_start (loop, &tw);
2208 2660
2209 // create one ev_io per pollfd 2661 // create one ev_io per pollfd
2210 for (int i = 0; i < nfd; ++i) 2662 for (int i = 0; i < nfd; ++i)
2211 { 2663 {
2324some fds have to be watched and handled very quickly (with low latency), 2776some fds have to be watched and handled very quickly (with low latency),
2325and even priorities and idle watchers might have too much overhead. In 2777and even priorities and idle watchers might have too much overhead. In
2326this case you would put all the high priority stuff in one loop and all 2778this case you would put all the high priority stuff in one loop and all
2327the rest in a second one, and embed the second one in the first. 2779the rest in a second one, and embed the second one in the first.
2328 2780
2329As long as the watcher is active, the callback will be invoked every time 2781As long as the watcher is active, the callback will be invoked every
2330there might be events pending in the embedded loop. The callback must then 2782time there might be events pending in the embedded loop. The callback
2331call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2783must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
2332their callbacks (you could also start an idle watcher to give the embedded 2784sweep and invoke their callbacks (the callback doesn't need to invoke the
2333loop strictly lower priority for example). You can also set the callback 2785C<ev_embed_sweep> function directly, it could also start an idle watcher
2334to C<0>, in which case the embed watcher will automatically execute the 2786to give the embedded loop strictly lower priority for example).
2335embedded loop sweep.
2336 2787
2337As long as the watcher is started it will automatically handle events. The 2788You can also set the callback to C<0>, in which case the embed watcher
2338callback will be invoked whenever some events have been handled. You can 2789will automatically execute the embedded loop sweep whenever necessary.
2339set the callback to C<0> to avoid having to specify one if you are not
2340interested in that.
2341 2790
2342Also, there have not currently been made special provisions for forking: 2791Fork detection will be handled transparently while the C<ev_embed> watcher
2343when you fork, you not only have to call C<ev_loop_fork> on both loops, 2792is active, i.e., the embedded loop will automatically be forked when the
2344but you will also have to stop and restart any C<ev_embed> watchers 2793embedding loop forks. In other cases, the user is responsible for calling
2345yourself - but you can use a fork watcher to handle this automatically, 2794C<ev_loop_fork> on the embedded loop.
2346and future versions of libev might do just that.
2347 2795
2348Unfortunately, not all backends are embeddable: only the ones returned by 2796Unfortunately, not all backends are embeddable: only the ones returned by
2349C<ev_embeddable_backends> are, which, unfortunately, does not include any 2797C<ev_embeddable_backends> are, which, unfortunately, does not include any
2350portable one. 2798portable one.
2351 2799
2445event loop blocks next and before C<ev_check> watchers are being called, 2893event loop blocks next and before C<ev_check> watchers are being called,
2446and only in the child after the fork. If whoever good citizen calling 2894and only in the child after the fork. If whoever good citizen calling
2447C<ev_default_fork> cheats and calls it in the wrong process, the fork 2895C<ev_default_fork> cheats and calls it in the wrong process, the fork
2448handlers will be invoked, too, of course. 2896handlers will be invoked, too, of course.
2449 2897
2898=head3 The special problem of life after fork - how is it possible?
2899
2900Most uses of C<fork()> consist of forking, then some simple calls to ste
2901up/change the process environment, followed by a call to C<exec()>. This
2902sequence should be handled by libev without any problems.
2903
2904This changes when the application actually wants to do event handling
2905in the child, or both parent in child, in effect "continuing" after the
2906fork.
2907
2908The default mode of operation (for libev, with application help to detect
2909forks) is to duplicate all the state in the child, as would be expected
2910when I<either> the parent I<or> the child process continues.
2911
2912When both processes want to continue using libev, then this is usually the
2913wrong result. In that case, usually one process (typically the parent) is
2914supposed to continue with all watchers in place as before, while the other
2915process typically wants to start fresh, i.e. without any active watchers.
2916
2917The cleanest and most efficient way to achieve that with libev is to
2918simply create a new event loop, which of course will be "empty", and
2919use that for new watchers. This has the advantage of not touching more
2920memory than necessary, and thus avoiding the copy-on-write, and the
2921disadvantage of having to use multiple event loops (which do not support
2922signal watchers).
2923
2924When this is not possible, or you want to use the default loop for
2925other reasons, then in the process that wants to start "fresh", call
2926C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
2927the default loop will "orphan" (not stop) all registered watchers, so you
2928have to be careful not to execute code that modifies those watchers. Note
2929also that in that case, you have to re-register any signal watchers.
2930
2450=head3 Watcher-Specific Functions and Data Members 2931=head3 Watcher-Specific Functions and Data Members
2451 2932
2452=over 4 2933=over 4
2453 2934
2454=item ev_fork_init (ev_signal *, callback) 2935=item ev_fork_init (ev_signal *, callback)
2571=over 4 3052=over 4
2572 3053
2573=item ev_async_init (ev_async *, callback) 3054=item ev_async_init (ev_async *, callback)
2574 3055
2575Initialises and configures the async watcher - it has no parameters of any 3056Initialises and configures the async watcher - it has no parameters of any
2576kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, 3057kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
2577trust me. 3058trust me.
2578 3059
2579=item ev_async_send (loop, ev_async *) 3060=item ev_async_send (loop, ev_async *)
2580 3061
2581Sends/signals/activates the given C<ev_async> watcher, that is, feeds 3062Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2582an C<EV_ASYNC> event on the watcher into the event loop. Unlike 3063an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2583C<ev_feed_event>, this call is safe to do from other threads, signal or 3064C<ev_feed_event>, this call is safe to do from other threads, signal or
2584similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 3065similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2585section below on what exactly this means). 3066section below on what exactly this means).
2586 3067
3068Note that, as with other watchers in libev, multiple events might get
3069compressed into a single callback invocation (another way to look at this
3070is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
3071reset when the event loop detects that).
3072
2587This call incurs the overhead of a system call only once per loop iteration, 3073This call incurs the overhead of a system call only once per event loop
2588so while the overhead might be noticeable, it doesn't apply to repeated 3074iteration, so while the overhead might be noticeable, it doesn't apply to
2589calls to C<ev_async_send>. 3075repeated calls to C<ev_async_send> for the same event loop.
2590 3076
2591=item bool = ev_async_pending (ev_async *) 3077=item bool = ev_async_pending (ev_async *)
2592 3078
2593Returns a non-zero value when C<ev_async_send> has been called on the 3079Returns a non-zero value when C<ev_async_send> has been called on the
2594watcher but the event has not yet been processed (or even noted) by the 3080watcher but the event has not yet been processed (or even noted) by the
2597C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 3083C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2598the loop iterates next and checks for the watcher to have become active, 3084the loop iterates next and checks for the watcher to have become active,
2599it will reset the flag again. C<ev_async_pending> can be used to very 3085it will reset the flag again. C<ev_async_pending> can be used to very
2600quickly check whether invoking the loop might be a good idea. 3086quickly check whether invoking the loop might be a good idea.
2601 3087
2602Not that this does I<not> check whether the watcher itself is pending, only 3088Not that this does I<not> check whether the watcher itself is pending,
2603whether it has been requested to make this watcher pending. 3089only whether it has been requested to make this watcher pending: there
3090is a time window between the event loop checking and resetting the async
3091notification, and the callback being invoked.
2604 3092
2605=back 3093=back
2606 3094
2607 3095
2608=head1 OTHER FUNCTIONS 3096=head1 OTHER FUNCTIONS
2787 3275
2788 myclass obj; 3276 myclass obj;
2789 ev::io iow; 3277 ev::io iow;
2790 iow.set <myclass, &myclass::io_cb> (&obj); 3278 iow.set <myclass, &myclass::io_cb> (&obj);
2791 3279
3280=item w->set (object *)
3281
3282This is an B<experimental> feature that might go away in a future version.
3283
3284This is a variation of a method callback - leaving out the method to call
3285will default the method to C<operator ()>, which makes it possible to use
3286functor objects without having to manually specify the C<operator ()> all
3287the time. Incidentally, you can then also leave out the template argument
3288list.
3289
3290The C<operator ()> method prototype must be C<void operator ()(watcher &w,
3291int revents)>.
3292
3293See the method-C<set> above for more details.
3294
3295Example: use a functor object as callback.
3296
3297 struct myfunctor
3298 {
3299 void operator() (ev::io &w, int revents)
3300 {
3301 ...
3302 }
3303 }
3304
3305 myfunctor f;
3306
3307 ev::io w;
3308 w.set (&f);
3309
2792=item w->set<function> (void *data = 0) 3310=item w->set<function> (void *data = 0)
2793 3311
2794Also sets a callback, but uses a static method or plain function as 3312Also sets a callback, but uses a static method or plain function as
2795callback. The optional C<data> argument will be stored in the watcher's 3313callback. The optional C<data> argument will be stored in the watcher's
2796C<data> member and is free for you to use. 3314C<data> member and is free for you to use.
2882L<http://software.schmorp.de/pkg/EV>. 3400L<http://software.schmorp.de/pkg/EV>.
2883 3401
2884=item Python 3402=item Python
2885 3403
2886Python bindings can be found at L<http://code.google.com/p/pyev/>. It 3404Python bindings can be found at L<http://code.google.com/p/pyev/>. It
2887seems to be quite complete and well-documented. Note, however, that the 3405seems to be quite complete and well-documented.
2888patch they require for libev is outright dangerous as it breaks the ABI
2889for everybody else, and therefore, should never be applied in an installed
2890libev (if python requires an incompatible ABI then it needs to embed
2891libev).
2892 3406
2893=item Ruby 3407=item Ruby
2894 3408
2895Tony Arcieri has written a ruby extension that offers access to a subset 3409Tony Arcieri has written a ruby extension that offers access to a subset
2896of the libev API and adds file handle abstractions, asynchronous DNS and 3410of the libev API and adds file handle abstractions, asynchronous DNS and
2897more on top of it. It can be found via gem servers. Its homepage is at 3411more on top of it. It can be found via gem servers. Its homepage is at
2898L<http://rev.rubyforge.org/>. 3412L<http://rev.rubyforge.org/>.
2899 3413
3414Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3415makes rev work even on mingw.
3416
3417=item Haskell
3418
3419A haskell binding to libev is available at
3420L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3421
2900=item D 3422=item D
2901 3423
2902Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 3424Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2903be found at L<http://proj.llucax.com.ar/wiki/evd>. 3425be found at L<http://proj.llucax.com.ar/wiki/evd>.
3426
3427=item Ocaml
3428
3429Erkki Seppala has written Ocaml bindings for libev, to be found at
3430L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3431
3432=item Lua
3433
3434Brian Maher has written a partial interface to libev
3435for lua (only C<ev_io> and C<ev_timer>), to be found at
3436L<http://github.com/brimworks/lua-ev>.
2904 3437
2905=back 3438=back
2906 3439
2907 3440
2908=head1 MACRO MAGIC 3441=head1 MACRO MAGIC
3009 3542
3010 #define EV_STANDALONE 1 3543 #define EV_STANDALONE 1
3011 #include "ev.h" 3544 #include "ev.h"
3012 3545
3013Both header files and implementation files can be compiled with a C++ 3546Both header files and implementation files can be compiled with a C++
3014compiler (at least, thats a stated goal, and breakage will be treated 3547compiler (at least, that's a stated goal, and breakage will be treated
3015as a bug). 3548as a bug).
3016 3549
3017You need the following files in your source tree, or in a directory 3550You need the following files in your source tree, or in a directory
3018in your include path (e.g. in libev/ when using -Ilibev): 3551in your include path (e.g. in libev/ when using -Ilibev):
3019 3552
3075keeps libev from including F<config.h>, and it also defines dummy 3608keeps libev from including F<config.h>, and it also defines dummy
3076implementations for some libevent functions (such as logging, which is not 3609implementations for some libevent functions (such as logging, which is not
3077supported). It will also not define any of the structs usually found in 3610supported). It will also not define any of the structs usually found in
3078F<event.h> that are not directly supported by the libev core alone. 3611F<event.h> that are not directly supported by the libev core alone.
3079 3612
3613In standalone mode, libev will still try to automatically deduce the
3614configuration, but has to be more conservative.
3615
3080=item EV_USE_MONOTONIC 3616=item EV_USE_MONOTONIC
3081 3617
3082If defined to be C<1>, libev will try to detect the availability of the 3618If defined to be C<1>, libev will try to detect the availability of the
3083monotonic clock option at both compile time and runtime. Otherwise no use 3619monotonic clock option at both compile time and runtime. Otherwise no
3084of the monotonic clock option will be attempted. If you enable this, you 3620use of the monotonic clock option will be attempted. If you enable this,
3085usually have to link against librt or something similar. Enabling it when 3621you usually have to link against librt or something similar. Enabling it
3086the functionality isn't available is safe, though, although you have 3622when the functionality isn't available is safe, though, although you have
3087to make sure you link against any libraries where the C<clock_gettime> 3623to make sure you link against any libraries where the C<clock_gettime>
3088function is hiding in (often F<-lrt>). 3624function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
3089 3625
3090=item EV_USE_REALTIME 3626=item EV_USE_REALTIME
3091 3627
3092If defined to be C<1>, libev will try to detect the availability of the 3628If defined to be C<1>, libev will try to detect the availability of the
3093real-time clock option at compile time (and assume its availability at 3629real-time clock option at compile time (and assume its availability
3094runtime if successful). Otherwise no use of the real-time clock option will 3630at runtime if successful). Otherwise no use of the real-time clock
3095be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3631option will be attempted. This effectively replaces C<gettimeofday>
3096(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3632by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
3097note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3633correctness. See the note about libraries in the description of
3634C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
3635C<EV_USE_CLOCK_SYSCALL>.
3636
3637=item EV_USE_CLOCK_SYSCALL
3638
3639If defined to be C<1>, libev will try to use a direct syscall instead
3640of calling the system-provided C<clock_gettime> function. This option
3641exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt>
3642unconditionally pulls in C<libpthread>, slowing down single-threaded
3643programs needlessly. Using a direct syscall is slightly slower (in
3644theory), because no optimised vdso implementation can be used, but avoids
3645the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or
3646higher, as it simplifies linking (no need for C<-lrt>).
3098 3647
3099=item EV_USE_NANOSLEEP 3648=item EV_USE_NANOSLEEP
3100 3649
3101If defined to be C<1>, libev will assume that C<nanosleep ()> is available 3650If defined to be C<1>, libev will assume that C<nanosleep ()> is available
3102and will use it for delays. Otherwise it will use C<select ()>. 3651and will use it for delays. Otherwise it will use C<select ()>.
3118 3667
3119=item EV_SELECT_USE_FD_SET 3668=item EV_SELECT_USE_FD_SET
3120 3669
3121If defined to C<1>, then the select backend will use the system C<fd_set> 3670If defined to C<1>, then the select backend will use the system C<fd_set>
3122structure. This is useful if libev doesn't compile due to a missing 3671structure. This is useful if libev doesn't compile due to a missing
3123C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout on 3672C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout
3124exotic systems. This usually limits the range of file descriptors to some 3673on exotic systems. This usually limits the range of file descriptors to
3125low limit such as 1024 or might have other limitations (winsocket only 3674some low limit such as 1024 or might have other limitations (winsocket
3126allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3675only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation,
3127influence the size of the C<fd_set> used. 3676configures the maximum size of the C<fd_set>.
3128 3677
3129=item EV_SELECT_IS_WINSOCKET 3678=item EV_SELECT_IS_WINSOCKET
3130 3679
3131When defined to C<1>, the select backend will assume that 3680When defined to C<1>, the select backend will assume that
3132select/socket/connect etc. don't understand file descriptors but 3681select/socket/connect etc. don't understand file descriptors but
3134be used is the winsock select). This means that it will call 3683be used is the winsock select). This means that it will call
3135C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3684C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3136it is assumed that all these functions actually work on fds, even 3685it is assumed that all these functions actually work on fds, even
3137on win32. Should not be defined on non-win32 platforms. 3686on win32. Should not be defined on non-win32 platforms.
3138 3687
3139=item EV_FD_TO_WIN32_HANDLE 3688=item EV_FD_TO_WIN32_HANDLE(fd)
3140 3689
3141If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3690If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3142file descriptors to socket handles. When not defining this symbol (the 3691file descriptors to socket handles. When not defining this symbol (the
3143default), then libev will call C<_get_osfhandle>, which is usually 3692default), then libev will call C<_get_osfhandle>, which is usually
3144correct. In some cases, programs use their own file descriptor management, 3693correct. In some cases, programs use their own file descriptor management,
3145in which case they can provide this function to map fds to socket handles. 3694in which case they can provide this function to map fds to socket handles.
3695
3696=item EV_WIN32_HANDLE_TO_FD(handle)
3697
3698If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3699using the standard C<_open_osfhandle> function. For programs implementing
3700their own fd to handle mapping, overwriting this function makes it easier
3701to do so. This can be done by defining this macro to an appropriate value.
3702
3703=item EV_WIN32_CLOSE_FD(fd)
3704
3705If programs implement their own fd to handle mapping on win32, then this
3706macro can be used to override the C<close> function, useful to unregister
3707file descriptors again. Note that the replacement function has to close
3708the underlying OS handle.
3146 3709
3147=item EV_USE_POLL 3710=item EV_USE_POLL
3148 3711
3149If defined to be C<1>, libev will compile in support for the C<poll>(2) 3712If defined to be C<1>, libev will compile in support for the C<poll>(2)
3150backend. Otherwise it will be enabled on non-win32 platforms. It 3713backend. Otherwise it will be enabled on non-win32 platforms. It
3282defined to be C<0>, then they are not. 3845defined to be C<0>, then they are not.
3283 3846
3284=item EV_MINIMAL 3847=item EV_MINIMAL
3285 3848
3286If you need to shave off some kilobytes of code at the expense of some 3849If you need to shave off some kilobytes of code at the expense of some
3287speed, define this symbol to C<1>. Currently this is used to override some 3850speed (but with the full API), define this symbol to C<1>. Currently this
3288inlining decisions, saves roughly 30% code size on amd64. It also selects a 3851is used to override some inlining decisions, saves roughly 30% code size
3289much smaller 2-heap for timer management over the default 4-heap. 3852on amd64. It also selects a much smaller 2-heap for timer management over
3853the default 4-heap.
3854
3855You can save even more by disabling watcher types you do not need
3856and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>
3857(C<-DNDEBUG>) will usually reduce code size a lot.
3858
3859Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
3860provide a bare-bones event library. See C<ev.h> for details on what parts
3861of the API are still available, and do not complain if this subset changes
3862over time.
3863
3864=item EV_NSIG
3865
3866The highest supported signal number, +1 (or, the number of
3867signals): Normally, libev tries to deduce the maximum number of signals
3868automatically, but sometimes this fails, in which case it can be
3869specified. Also, using a lower number than detected (C<32> should be
3870good for about any system in existance) can save some memory, as libev
3871statically allocates some 12-24 bytes per signal number.
3290 3872
3291=item EV_PID_HASHSIZE 3873=item EV_PID_HASHSIZE
3292 3874
3293C<ev_child> watchers use a small hash table to distribute workload by 3875C<ev_child> watchers use a small hash table to distribute workload by
3294pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3876pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
3480default loop and triggering an C<ev_async> watcher from the default loop 4062default loop and triggering an C<ev_async> watcher from the default loop
3481watcher callback into the event loop interested in the signal. 4063watcher callback into the event loop interested in the signal.
3482 4064
3483=back 4065=back
3484 4066
4067=head4 THREAD LOCKING EXAMPLE
4068
4069Here is a fictitious example of how to run an event loop in a different
4070thread than where callbacks are being invoked and watchers are
4071created/added/removed.
4072
4073For a real-world example, see the C<EV::Loop::Async> perl module,
4074which uses exactly this technique (which is suited for many high-level
4075languages).
4076
4077The example uses a pthread mutex to protect the loop data, a condition
4078variable to wait for callback invocations, an async watcher to notify the
4079event loop thread and an unspecified mechanism to wake up the main thread.
4080
4081First, you need to associate some data with the event loop:
4082
4083 typedef struct {
4084 mutex_t lock; /* global loop lock */
4085 ev_async async_w;
4086 thread_t tid;
4087 cond_t invoke_cv;
4088 } userdata;
4089
4090 void prepare_loop (EV_P)
4091 {
4092 // for simplicity, we use a static userdata struct.
4093 static userdata u;
4094
4095 ev_async_init (&u->async_w, async_cb);
4096 ev_async_start (EV_A_ &u->async_w);
4097
4098 pthread_mutex_init (&u->lock, 0);
4099 pthread_cond_init (&u->invoke_cv, 0);
4100
4101 // now associate this with the loop
4102 ev_set_userdata (EV_A_ u);
4103 ev_set_invoke_pending_cb (EV_A_ l_invoke);
4104 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4105
4106 // then create the thread running ev_loop
4107 pthread_create (&u->tid, 0, l_run, EV_A);
4108 }
4109
4110The callback for the C<ev_async> watcher does nothing: the watcher is used
4111solely to wake up the event loop so it takes notice of any new watchers
4112that might have been added:
4113
4114 static void
4115 async_cb (EV_P_ ev_async *w, int revents)
4116 {
4117 // just used for the side effects
4118 }
4119
4120The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4121protecting the loop data, respectively.
4122
4123 static void
4124 l_release (EV_P)
4125 {
4126 userdata *u = ev_userdata (EV_A);
4127 pthread_mutex_unlock (&u->lock);
4128 }
4129
4130 static void
4131 l_acquire (EV_P)
4132 {
4133 userdata *u = ev_userdata (EV_A);
4134 pthread_mutex_lock (&u->lock);
4135 }
4136
4137The event loop thread first acquires the mutex, and then jumps straight
4138into C<ev_loop>:
4139
4140 void *
4141 l_run (void *thr_arg)
4142 {
4143 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4144
4145 l_acquire (EV_A);
4146 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4147 ev_loop (EV_A_ 0);
4148 l_release (EV_A);
4149
4150 return 0;
4151 }
4152
4153Instead of invoking all pending watchers, the C<l_invoke> callback will
4154signal the main thread via some unspecified mechanism (signals? pipe
4155writes? C<Async::Interrupt>?) and then waits until all pending watchers
4156have been called (in a while loop because a) spurious wakeups are possible
4157and b) skipping inter-thread-communication when there are no pending
4158watchers is very beneficial):
4159
4160 static void
4161 l_invoke (EV_P)
4162 {
4163 userdata *u = ev_userdata (EV_A);
4164
4165 while (ev_pending_count (EV_A))
4166 {
4167 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4168 pthread_cond_wait (&u->invoke_cv, &u->lock);
4169 }
4170 }
4171
4172Now, whenever the main thread gets told to invoke pending watchers, it
4173will grab the lock, call C<ev_invoke_pending> and then signal the loop
4174thread to continue:
4175
4176 static void
4177 real_invoke_pending (EV_P)
4178 {
4179 userdata *u = ev_userdata (EV_A);
4180
4181 pthread_mutex_lock (&u->lock);
4182 ev_invoke_pending (EV_A);
4183 pthread_cond_signal (&u->invoke_cv);
4184 pthread_mutex_unlock (&u->lock);
4185 }
4186
4187Whenever you want to start/stop a watcher or do other modifications to an
4188event loop, you will now have to lock:
4189
4190 ev_timer timeout_watcher;
4191 userdata *u = ev_userdata (EV_A);
4192
4193 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4194
4195 pthread_mutex_lock (&u->lock);
4196 ev_timer_start (EV_A_ &timeout_watcher);
4197 ev_async_send (EV_A_ &u->async_w);
4198 pthread_mutex_unlock (&u->lock);
4199
4200Note that sending the C<ev_async> watcher is required because otherwise
4201an event loop currently blocking in the kernel will have no knowledge
4202about the newly added timer. By waking up the loop it will pick up any new
4203watchers in the next event loop iteration.
4204
3485=head3 COROUTINES 4205=head3 COROUTINES
3486 4206
3487Libev is very accommodating to coroutines ("cooperative threads"): 4207Libev is very accommodating to coroutines ("cooperative threads"):
3488libev fully supports nesting calls to its functions from different 4208libev fully supports nesting calls to its functions from different
3489coroutines (e.g. you can call C<ev_loop> on the same loop from two 4209coroutines (e.g. you can call C<ev_loop> on the same loop from two
3490different coroutines, and switch freely between both coroutines running the 4210different coroutines, and switch freely between both coroutines running
3491loop, as long as you don't confuse yourself). The only exception is that 4211the loop, as long as you don't confuse yourself). The only exception is
3492you must not do this from C<ev_periodic> reschedule callbacks. 4212that you must not do this from C<ev_periodic> reschedule callbacks.
3493 4213
3494Care has been taken to ensure that libev does not keep local state inside 4214Care has been taken to ensure that libev does not keep local state inside
3495C<ev_loop>, and other calls do not usually allow for coroutine switches as 4215C<ev_loop>, and other calls do not usually allow for coroutine switches as
3496they do not clal any callbacks. 4216they do not call any callbacks.
3497 4217
3498=head2 COMPILER WARNINGS 4218=head2 COMPILER WARNINGS
3499 4219
3500Depending on your compiler and compiler settings, you might get no or a 4220Depending on your compiler and compiler settings, you might get no or a
3501lot of warnings when compiling libev code. Some people are apparently 4221lot of warnings when compiling libev code. Some people are apparently
3535 ==2274== definitely lost: 0 bytes in 0 blocks. 4255 ==2274== definitely lost: 0 bytes in 0 blocks.
3536 ==2274== possibly lost: 0 bytes in 0 blocks. 4256 ==2274== possibly lost: 0 bytes in 0 blocks.
3537 ==2274== still reachable: 256 bytes in 1 blocks. 4257 ==2274== still reachable: 256 bytes in 1 blocks.
3538 4258
3539Then there is no memory leak, just as memory accounted to global variables 4259Then there is no memory leak, just as memory accounted to global variables
3540is not a memleak - the memory is still being refernced, and didn't leak. 4260is not a memleak - the memory is still being referenced, and didn't leak.
3541 4261
3542Similarly, under some circumstances, valgrind might report kernel bugs 4262Similarly, under some circumstances, valgrind might report kernel bugs
3543as if it were a bug in libev (e.g. in realloc or in the poll backend, 4263as if it were a bug in libev (e.g. in realloc or in the poll backend,
3544although an acceptable workaround has been found here), or it might be 4264although an acceptable workaround has been found here), or it might be
3545confused. 4265confused.
3574way (note also that glib is the slowest event library known to man). 4294way (note also that glib is the slowest event library known to man).
3575 4295
3576There is no supported compilation method available on windows except 4296There is no supported compilation method available on windows except
3577embedding it into other applications. 4297embedding it into other applications.
3578 4298
4299Sensible signal handling is officially unsupported by Microsoft - libev
4300tries its best, but under most conditions, signals will simply not work.
4301
3579Not a libev limitation but worth mentioning: windows apparently doesn't 4302Not a libev limitation but worth mentioning: windows apparently doesn't
3580accept large writes: instead of resulting in a partial write, windows will 4303accept large writes: instead of resulting in a partial write, windows will
3581either accept everything or return C<ENOBUFS> if the buffer is too large, 4304either accept everything or return C<ENOBUFS> if the buffer is too large,
3582so make sure you only write small amounts into your sockets (less than a 4305so make sure you only write small amounts into your sockets (less than a
3583megabyte seems safe, but this apparently depends on the amount of memory 4306megabyte seems safe, but this apparently depends on the amount of memory
3587the abysmal performance of winsockets, using a large number of sockets 4310the abysmal performance of winsockets, using a large number of sockets
3588is not recommended (and not reasonable). If your program needs to use 4311is not recommended (and not reasonable). If your program needs to use
3589more than a hundred or so sockets, then likely it needs to use a totally 4312more than a hundred or so sockets, then likely it needs to use a totally
3590different implementation for windows, as libev offers the POSIX readiness 4313different implementation for windows, as libev offers the POSIX readiness
3591notification model, which cannot be implemented efficiently on windows 4314notification model, which cannot be implemented efficiently on windows
3592(Microsoft monopoly games). 4315(due to Microsoft monopoly games).
3593 4316
3594A typical way to use libev under windows is to embed it (see the embedding 4317A typical way to use libev under windows is to embed it (see the embedding
3595section for details) and use the following F<evwrap.h> header file instead 4318section for details) and use the following F<evwrap.h> header file instead
3596of F<ev.h>: 4319of F<ev.h>:
3597 4320
3633 4356
3634Early versions of winsocket's select only supported waiting for a maximum 4357Early versions of winsocket's select only supported waiting for a maximum
3635of C<64> handles (probably owning to the fact that all windows kernels 4358of C<64> handles (probably owning to the fact that all windows kernels
3636can only wait for C<64> things at the same time internally; Microsoft 4359can only wait for C<64> things at the same time internally; Microsoft
3637recommends spawning a chain of threads and wait for 63 handles and the 4360recommends spawning a chain of threads and wait for 63 handles and the
3638previous thread in each. Great). 4361previous thread in each. Sounds great!).
3639 4362
3640Newer versions support more handles, but you need to define C<FD_SETSIZE> 4363Newer versions support more handles, but you need to define C<FD_SETSIZE>
3641to some high number (e.g. C<2048>) before compiling the winsocket select 4364to some high number (e.g. C<2048>) before compiling the winsocket select
3642call (which might be in libev or elsewhere, for example, perl does its own 4365call (which might be in libev or elsewhere, for example, perl and many
3643select emulation on windows). 4366other interpreters do their own select emulation on windows).
3644 4367
3645Another limit is the number of file descriptors in the Microsoft runtime 4368Another limit is the number of file descriptors in the Microsoft runtime
3646libraries, which by default is C<64> (there must be a hidden I<64> fetish 4369libraries, which by default is C<64> (there must be a hidden I<64>
3647or something like this inside Microsoft). You can increase this by calling 4370fetish or something like this inside Microsoft). You can increase this
3648C<_setmaxstdio>, which can increase this limit to C<2048> (another 4371by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3649arbitrary limit), but is broken in many versions of the Microsoft runtime 4372(another arbitrary limit), but is broken in many versions of the Microsoft
3650libraries.
3651
3652This might get you to about C<512> or C<2048> sockets (depending on 4373runtime libraries. This might get you to about C<512> or C<2048> sockets
3653windows version and/or the phase of the moon). To get more, you need to 4374(depending on windows version and/or the phase of the moon). To get more,
3654wrap all I/O functions and provide your own fd management, but the cost of 4375you need to wrap all I/O functions and provide your own fd management, but
3655calling select (O(n²)) will likely make this unworkable. 4376the cost of calling select (O(n²)) will likely make this unworkable.
3656 4377
3657=back 4378=back
3658 4379
3659=head2 PORTABILITY REQUIREMENTS 4380=head2 PORTABILITY REQUIREMENTS
3660 4381
3703=item C<double> must hold a time value in seconds with enough accuracy 4424=item C<double> must hold a time value in seconds with enough accuracy
3704 4425
3705The type C<double> is used to represent timestamps. It is required to 4426The type C<double> is used to represent timestamps. It is required to
3706have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4427have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3707enough for at least into the year 4000. This requirement is fulfilled by 4428enough for at least into the year 4000. This requirement is fulfilled by
3708implementations implementing IEEE 754 (basically all existing ones). 4429implementations implementing IEEE 754, which is basically all existing
4430ones. With IEEE 754 doubles, you get microsecond accuracy until at least
44312200.
3709 4432
3710=back 4433=back
3711 4434
3712If you know of other additional requirements drop me a note. 4435If you know of other additional requirements drop me a note.
3713 4436
3781involves iterating over all running async watchers or all signal numbers. 4504involves iterating over all running async watchers or all signal numbers.
3782 4505
3783=back 4506=back
3784 4507
3785 4508
4509=head1 GLOSSARY
4510
4511=over 4
4512
4513=item active
4514
4515A watcher is active as long as it has been started (has been attached to
4516an event loop) but not yet stopped (disassociated from the event loop).
4517
4518=item application
4519
4520In this document, an application is whatever is using libev.
4521
4522=item callback
4523
4524The address of a function that is called when some event has been
4525detected. Callbacks are being passed the event loop, the watcher that
4526received the event, and the actual event bitset.
4527
4528=item callback invocation
4529
4530The act of calling the callback associated with a watcher.
4531
4532=item event
4533
4534A change of state of some external event, such as data now being available
4535for reading on a file descriptor, time having passed or simply not having
4536any other events happening anymore.
4537
4538In libev, events are represented as single bits (such as C<EV_READ> or
4539C<EV_TIMEOUT>).
4540
4541=item event library
4542
4543A software package implementing an event model and loop.
4544
4545=item event loop
4546
4547An entity that handles and processes external events and converts them
4548into callback invocations.
4549
4550=item event model
4551
4552The model used to describe how an event loop handles and processes
4553watchers and events.
4554
4555=item pending
4556
4557A watcher is pending as soon as the corresponding event has been detected,
4558and stops being pending as soon as the watcher will be invoked or its
4559pending status is explicitly cleared by the application.
4560
4561A watcher can be pending, but not active. Stopping a watcher also clears
4562its pending status.
4563
4564=item real time
4565
4566The physical time that is observed. It is apparently strictly monotonic :)
4567
4568=item wall-clock time
4569
4570The time and date as shown on clocks. Unlike real time, it can actually
4571be wrong and jump forwards and backwards, e.g. when the you adjust your
4572clock.
4573
4574=item watcher
4575
4576A data structure that describes interest in certain events. Watchers need
4577to be started (attached to an event loop) before they can receive events.
4578
4579=item watcher invocation
4580
4581The act of calling the callback associated with a watcher.
4582
4583=back
4584
3786=head1 AUTHOR 4585=head1 AUTHOR
3787 4586
3788Marc Lehmann <libev@schmorp.de>. 4587Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3789 4588

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines