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

Comparing libev/ev.pod (file contents):
Revision 1.180 by root, Fri Sep 19 03:45:55 2008 UTC vs.
Revision 1.254 by root, Tue Jul 14 19:02:43 2009 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines