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

Comparing libev/ev.pod (file contents):
Revision 1.248 by root, Wed Jul 8 04:14:34 2009 UTC vs.
Revision 1.320 by root, Fri Oct 22 10:48:54 2010 UTC

26 puts ("stdin ready"); 26 puts ("stdin ready");
27 // for one-shot events, one must manually stop the watcher 27 // for one-shot events, one must manually stop the watcher
28 // with its corresponding stop function. 28 // with its corresponding stop function.
29 ev_io_stop (EV_A_ w); 29 ev_io_stop (EV_A_ w);
30 30
31 // this causes all nested ev_loop's to stop iterating 31 // this causes all nested ev_run's to stop iterating
32 ev_unloop (EV_A_ EVUNLOOP_ALL); 32 ev_break (EV_A_ EVBREAK_ALL);
33 } 33 }
34 34
35 // another callback, this time for a time-out 35 // another callback, this time for a time-out
36 static void 36 static void
37 timeout_cb (EV_P_ ev_timer *w, int revents) 37 timeout_cb (EV_P_ ev_timer *w, int revents)
38 { 38 {
39 puts ("timeout"); 39 puts ("timeout");
40 // this causes the innermost ev_loop to stop iterating 40 // this causes the innermost ev_run to stop iterating
41 ev_unloop (EV_A_ EVUNLOOP_ONE); 41 ev_break (EV_A_ EVBREAK_ONE);
42 } 42 }
43 43
44 int 44 int
45 main (void) 45 main (void)
46 { 46 {
56 // simple non-repeating 5.5 second timeout 56 // simple non-repeating 5.5 second timeout
57 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 57 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
58 ev_timer_start (loop, &timeout_watcher); 58 ev_timer_start (loop, &timeout_watcher);
59 59
60 // now wait for events to arrive 60 // now wait for events to arrive
61 ev_loop (loop, 0); 61 ev_run (loop, 0);
62 62
63 // unloop was called, so exit 63 // unloop was called, so exit
64 return 0; 64 return 0;
65 } 65 }
66 66
75While this document tries to be as complete as possible in documenting 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 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 77on event-based programming, nor will it introduce event-based programming
78with libev. 78with libev.
79 79
80Familarity with event based programming techniques in general is assumed 80Familiarity with event based programming techniques in general is assumed
81throughout this document. 81throughout this document.
82 82
83=head1 ABOUT LIBEV 83=head1 ABOUT LIBEV
84 84
85Libev 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
98=head2 FEATURES 98=head2 FEATURES
99 99
100Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 100Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
101BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 101BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
102for file descriptor events (C<ev_io>), the Linux C<inotify> interface 102for file descriptor events (C<ev_io>), the Linux C<inotify> interface
103(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 103(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
104with customised rescheduling (C<ev_periodic>), synchronous signals 104inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
105(C<ev_signal>), process status change events (C<ev_child>), and event 105timers (C<ev_timer>), absolute timers with customised rescheduling
106watchers dealing with the event loop mechanism itself (C<ev_idle>, 106(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
107C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 107change events (C<ev_child>), and event watchers dealing with the event
108file watchers (C<ev_stat>) and even limited support for fork events 108loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
109(C<ev_fork>). 109C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
110limited support for fork events (C<ev_fork>).
110 111
111It also is quite fast (see this 112It also is quite fast (see this
112L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 113L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
113for example). 114for example).
114 115
117Libev is very configurable. In this manual the default (and most common) 118Libev is very configurable. In this manual the default (and most common)
118configuration will be described, which supports multiple event loops. For 119configuration will be described, which supports multiple event loops. For
119more info about various configuration options please have a look at 120more info about various configuration options please have a look at
120B<EMBED> section in this manual. If libev was configured without support 121B<EMBED> section in this manual. If libev was configured without support
121for multiple event loops, then all functions taking an initial argument of 122for multiple event loops, then all functions taking an initial argument of
122name C<loop> (which is always of type C<ev_loop *>) will not have 123name C<loop> (which is always of type C<struct ev_loop *>) will not have
123this argument. 124this argument.
124 125
125=head2 TIME REPRESENTATION 126=head2 TIME REPRESENTATION
126 127
127Libev represents time as a single floating point number, representing 128Libev represents time as a single floating point number, representing
128the (fractional) number of seconds since the (POSIX) epoch (somewhere 129the (fractional) number of seconds since the (POSIX) epoch (in practice
129near the beginning of 1970, details are complicated, don't ask). This 130somewhere near the beginning of 1970, details are complicated, don't
130type is called C<ev_tstamp>, which is what you should use too. It usually 131ask). This type is called C<ev_tstamp>, which is what you should use
131aliases to the C<double> type in C. When you need to do any calculations 132too. It usually aliases to the C<double> type in C. When you need to do
132on it, you should treat it as some floating point value. Unlike the name 133any calculations on it, you should treat it as some floating point value.
134
133component C<stamp> might indicate, it is also used for time differences 135Unlike the name component C<stamp> might indicate, it is also used for
134throughout libev. 136time differences (e.g. delays) throughout libev.
135 137
136=head1 ERROR HANDLING 138=head1 ERROR HANDLING
137 139
138Libev knows three classes of errors: operating system errors, usage errors 140Libev knows three classes of errors: operating system errors, usage errors
139and internal errors (bugs). 141and internal errors (bugs).
163 165
164=item ev_tstamp ev_time () 166=item ev_tstamp ev_time ()
165 167
166Returns the current time as libev would use it. Please note that the 168Returns the current time as libev would use it. Please note that the
167C<ev_now> function is usually faster and also often returns the timestamp 169C<ev_now> function is usually faster and also often returns the timestamp
168you actually want to know. 170you actually want to know. Also interetsing is the combination of
171C<ev_update_now> and C<ev_now>.
169 172
170=item ev_sleep (ev_tstamp interval) 173=item ev_sleep (ev_tstamp interval)
171 174
172Sleep for the given interval: The current thread will be blocked until 175Sleep for the given interval: The current thread will be blocked until
173either it is interrupted or the given time interval has passed. Basically 176either it is interrupted or the given time interval has passed. Basically
190as this indicates an incompatible change. Minor versions are usually 193as this indicates an incompatible change. Minor versions are usually
191compatible to older versions, so a larger minor version alone is usually 194compatible to older versions, so a larger minor version alone is usually
192not a problem. 195not a problem.
193 196
194Example: Make sure we haven't accidentally been linked against the wrong 197Example: Make sure we haven't accidentally been linked against the wrong
195version. 198version (note, however, that this will not detect other ABI mismatches,
199such as LFS or reentrancy).
196 200
197 assert (("libev version mismatch", 201 assert (("libev version mismatch",
198 ev_version_major () == EV_VERSION_MAJOR 202 ev_version_major () == EV_VERSION_MAJOR
199 && ev_version_minor () >= EV_VERSION_MINOR)); 203 && ev_version_minor () >= EV_VERSION_MINOR));
200 204
211 assert (("sorry, no epoll, no sex", 215 assert (("sorry, no epoll, no sex",
212 ev_supported_backends () & EVBACKEND_EPOLL)); 216 ev_supported_backends () & EVBACKEND_EPOLL));
213 217
214=item unsigned int ev_recommended_backends () 218=item unsigned int ev_recommended_backends ()
215 219
216Return the set of all backends compiled into this binary of libev and also 220Return the set of all backends compiled into this binary of libev and
217recommended for this platform. This set is often smaller than the one 221also recommended for this platform, meaning it will work for most file
222descriptor types. This set is often smaller than the one returned by
218returned by C<ev_supported_backends>, as for example kqueue is broken on 223C<ev_supported_backends>, as for example kqueue is broken on most BSDs
219most BSDs and will not be auto-detected unless you explicitly request it 224and will not be auto-detected unless you explicitly request it (assuming
220(assuming you know what you are doing). This is the set of backends that 225you know what you are doing). This is the set of backends that libev will
221libev will probe for if you specify no backends explicitly. 226probe for if you specify no backends explicitly.
222 227
223=item unsigned int ev_embeddable_backends () 228=item unsigned int ev_embeddable_backends ()
224 229
225Returns the set of backends that are embeddable in other event loops. This 230Returns the set of backends that are embeddable in other event loops. This
226is the theoretical, all-platform, value. To find which backends 231value is platform-specific but can include backends not available on the
227might be supported on the current system, you would need to look at 232current system. To find which embeddable backends might be supported on
228C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 233the current system, you would need to look at C<ev_embeddable_backends ()
229recommended ones. 234& ev_supported_backends ()>, likewise for recommended ones.
230 235
231See the description of C<ev_embed> watchers for more info. 236See the description of C<ev_embed> watchers for more info.
232 237
233=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT] 238=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
234 239
290 295
291=back 296=back
292 297
293=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 298=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
294 299
295An event loop is described by a C<struct ev_loop *> (the C<struct> 300An event loop is described by a C<struct ev_loop *> (the C<struct> is
296is I<not> optional in this case, as there is also an C<ev_loop> 301I<not> optional in this case unless libev 3 compatibility is disabled, as
297I<function>). 302libev 3 had an C<ev_loop> function colliding with the struct name).
298 303
299The library knows two types of such loops, the I<default> loop, which 304The library knows two types of such loops, the I<default> loop, which
300supports signals and child events, and dynamically created loops which do 305supports signals and child events, and dynamically created event loops
301not. 306which do not.
302 307
303=over 4 308=over 4
304 309
305=item struct ev_loop *ev_default_loop (unsigned int flags) 310=item struct ev_loop *ev_default_loop (unsigned int flags)
306 311
344useful to try out specific backends to test their performance, or to work 349useful to try out specific backends to test their performance, or to work
345around bugs. 350around bugs.
346 351
347=item C<EVFLAG_FORKCHECK> 352=item C<EVFLAG_FORKCHECK>
348 353
349Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after 354Instead of calling C<ev_loop_fork> manually after a fork, you can also
350a fork, you can also make libev check for a fork in each iteration by 355make libev check for a fork in each iteration by enabling this flag.
351enabling this flag.
352 356
353This works by calling C<getpid ()> on every iteration of the loop, 357This works by calling C<getpid ()> on every iteration of the loop,
354and thus this might slow down your event loop if you do a lot of loop 358and thus this might slow down your event loop if you do a lot of loop
355iterations and little real work, but is usually not noticeable (on my 359iterations and little real work, but is usually not noticeable (on my
356GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 360GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
362flag. 366flag.
363 367
364This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 368This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
365environment variable. 369environment variable.
366 370
371=item C<EVFLAG_NOINOTIFY>
372
373When this flag is specified, then libev will not attempt to use the
374I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
375testing, this flag can be useful to conserve inotify file descriptors, as
376otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
377
378=item C<EVFLAG_SIGNALFD>
379
380When this flag is specified, then libev will attempt to use the
381I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
382delivers signals synchronously, which makes it both faster and might make
383it possible to get the queued signal data. It can also simplify signal
384handling with threads, as long as you properly block signals in your
385threads that are not interested in handling them.
386
387Signalfd will not be used by default as this changes your signal mask, and
388there are a lot of shoddy libraries and programs (glib's threadpool for
389example) that can't properly initialise their signal masks.
390
367=item C<EVBACKEND_SELECT> (value 1, portable select backend) 391=item C<EVBACKEND_SELECT> (value 1, portable select backend)
368 392
369This is your standard select(2) backend. Not I<completely> standard, as 393This is your standard select(2) backend. Not I<completely> standard, as
370libev tries to roll its own fd_set with no limits on the number of fds, 394libev tries to roll its own fd_set with no limits on the number of fds,
371but if that fails, expect a fairly low limit on the number of fds when 395but if that fails, expect a fairly low limit on the number of fds when
394 418
395This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 419This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
396C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 420C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
397 421
398=item C<EVBACKEND_EPOLL> (value 4, Linux) 422=item C<EVBACKEND_EPOLL> (value 4, Linux)
423
424Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
425kernels).
399 426
400For few fds, this backend is a bit little slower than poll and select, 427For few fds, this backend is a bit little slower than poll and select,
401but it scales phenomenally better. While poll and select usually scale 428but it scales phenomenally better. While poll and select usually scale
402like O(total_fds) where n is the total number of fds (or the highest fd), 429like O(total_fds) where n is the total number of fds (or the highest fd),
403epoll scales either O(1) or O(active_fds). 430epoll scales either O(1) or O(active_fds).
415of course I<doesn't>, and epoll just loves to report events for totally 442of course I<doesn't>, and epoll just loves to report events for totally
416I<different> file descriptors (even already closed ones, so one cannot 443I<different> file descriptors (even already closed ones, so one cannot
417even remove them from the set) than registered in the set (especially 444even remove them from the set) than registered in the set (especially
418on SMP systems). Libev tries to counter these spurious notifications by 445on SMP systems). Libev tries to counter these spurious notifications by
419employing an additional generation counter and comparing that against the 446employing an additional generation counter and comparing that against the
420events to filter out spurious ones, recreating the set when required. 447events to filter out spurious ones, recreating the set when required. Last
448not least, it also refuses to work with some file descriptors which work
449perfectly fine with C<select> (files, many character devices...).
421 450
422While stopping, setting and starting an I/O watcher in the same iteration 451While stopping, setting and starting an I/O watcher in the same iteration
423will result in some caching, there is still a system call per such 452will result in some caching, there is still a system call per such
424incident (because the same I<file descriptor> could point to a different 453incident (because the same I<file descriptor> could point to a different
425I<file description> now), so its best to avoid that. Also, C<dup ()>'ed 454I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
518 547
519It is definitely not recommended to use this flag. 548It is definitely not recommended to use this flag.
520 549
521=back 550=back
522 551
523If one or more of these are or'ed into the flags value, then only these 552If one or more of the backend flags are or'ed into the flags value,
524backends will be tried (in the reverse order as listed here). If none are 553then only these backends will be tried (in the reverse order as listed
525specified, all backends in C<ev_recommended_backends ()> will be tried. 554here). If none are specified, all backends in C<ev_recommended_backends
555()> will be tried.
526 556
527Example: This is the most typical usage. 557Example: This is the most typical usage.
528 558
529 if (!ev_default_loop (0)) 559 if (!ev_default_loop (0))
530 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 560 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
542 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 572 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
543 573
544=item struct ev_loop *ev_loop_new (unsigned int flags) 574=item struct ev_loop *ev_loop_new (unsigned int flags)
545 575
546Similar to C<ev_default_loop>, but always creates a new event loop that is 576Similar to C<ev_default_loop>, but always creates a new event loop that is
547always distinct from the default loop. Unlike the default loop, it cannot 577always distinct from the default loop.
548handle signal and child watchers, and attempts to do so will be greeted by
549undefined behaviour (or a failed assertion if assertions are enabled).
550 578
551Note that this function I<is> thread-safe, and the recommended way to use 579Note that this function I<is> thread-safe, and one common way to use
552libev with threads is indeed to create one loop per thread, and using the 580libev with threads is indeed to create one loop per thread, and using the
553default loop in the "main" or "initial" thread. 581default loop in the "main" or "initial" thread.
554 582
555Example: Try to create a event loop that uses epoll and nothing else. 583Example: Try to create a event loop that uses epoll and nothing else.
556 584
558 if (!epoller) 586 if (!epoller)
559 fatal ("no epoll found here, maybe it hides under your chair"); 587 fatal ("no epoll found here, maybe it hides under your chair");
560 588
561=item ev_default_destroy () 589=item ev_default_destroy ()
562 590
563Destroys the default loop again (frees all memory and kernel state 591Destroys the default loop (frees all memory and kernel state etc.). None
564etc.). None of the active event watchers will be stopped in the normal 592of the active event watchers will be stopped in the normal sense, so
565sense, so e.g. C<ev_is_active> might still return true. It is your 593e.g. C<ev_is_active> might still return true. It is your responsibility to
566responsibility to either stop all watchers cleanly yourself I<before> 594either stop all watchers cleanly yourself I<before> calling this function,
567calling this function, or cope with the fact afterwards (which is usually 595or cope with the fact afterwards (which is usually the easiest thing, you
568the easiest thing, you can just ignore the watchers and/or C<free ()> them 596can just ignore the watchers and/or C<free ()> them for example).
569for example).
570 597
571Note that certain global state, such as signal state (and installed signal 598Note that certain global state, such as signal state (and installed signal
572handlers), will not be freed by this function, and related watchers (such 599handlers), will not be freed by this function, and related watchers (such
573as signal and child watchers) would need to be stopped manually. 600as signal and child watchers) would need to be stopped manually.
574 601
575In general it is not advisable to call this function except in the 602In general it is not advisable to call this function except in the
576rare occasion where you really need to free e.g. the signal handling 603rare occasion where you really need to free e.g. the signal handling
577pipe fds. If you need dynamically allocated loops it is better to use 604pipe fds. If you need dynamically allocated loops it is better to use
578C<ev_loop_new> and C<ev_loop_destroy>). 605C<ev_loop_new> and C<ev_loop_destroy>.
579 606
580=item ev_loop_destroy (loop) 607=item ev_loop_destroy (loop)
581 608
582Like C<ev_default_destroy>, but destroys an event loop created by an 609Like C<ev_default_destroy>, but destroys an event loop created by an
583earlier call to C<ev_loop_new>. 610earlier call to C<ev_loop_new>.
584 611
585=item ev_default_fork () 612=item ev_default_fork ()
586 613
587This function sets a flag that causes subsequent C<ev_loop> iterations 614This function sets a flag that causes subsequent C<ev_run> iterations
588to reinitialise the kernel state for backends that have one. Despite the 615to reinitialise the kernel state for backends that have one. Despite the
589name, you can call it anytime, but it makes most sense after forking, in 616name, you can call it anytime, but it makes most sense after forking, in
590the child process (or both child and parent, but that again makes little 617the child process (or both child and parent, but that again makes little
591sense). You I<must> call it in the child before using any of the libev 618sense). You I<must> call it in the child before using any of the libev
592functions, and it will only take effect at the next C<ev_loop> iteration. 619functions, and it will only take effect at the next C<ev_run> iteration.
620
621Again, you I<have> to call it on I<any> loop that you want to re-use after
622a fork, I<even if you do not plan to use the loop in the parent>. This is
623because some kernel interfaces *cough* I<kqueue> *cough* do funny things
624during fork.
593 625
594On the other hand, you only need to call this function in the child 626On the other hand, you only need to call this function in the child
595process if and only if you want to use the event library in the child. If 627process if and only if you want to use the event loop in the child. If
596you just fork+exec, you don't have to call it at all. 628you just fork+exec or create a new loop in the child, you don't have to
629call it at all (in fact, C<epoll> is so badly broken that it makes a
630difference, but libev will usually detect this case on its own and do a
631costly reset of the backend).
597 632
598The function itself is quite fast and it's usually not a problem to call 633The function itself is quite fast and it's usually not a problem to call
599it just in case after a fork. To make this easy, the function will fit in 634it just in case after a fork. To make this easy, the function will fit in
600quite nicely into a call to C<pthread_atfork>: 635quite nicely into a call to C<pthread_atfork>:
601 636
603 638
604=item ev_loop_fork (loop) 639=item ev_loop_fork (loop)
605 640
606Like C<ev_default_fork>, but acts on an event loop created by 641Like C<ev_default_fork>, but acts on an event loop created by
607C<ev_loop_new>. Yes, you have to call this on every allocated event loop 642C<ev_loop_new>. Yes, you have to call this on every allocated event loop
608after fork that you want to re-use in the child, and how you do this is 643after fork that you want to re-use in the child, and how you keep track of
609entirely your own problem. 644them is entirely your own problem.
610 645
611=item int ev_is_default_loop (loop) 646=item int ev_is_default_loop (loop)
612 647
613Returns true when the given loop is, in fact, the default loop, and false 648Returns true when the given loop is, in fact, the default loop, and false
614otherwise. 649otherwise.
615 650
616=item unsigned int ev_loop_count (loop) 651=item unsigned int ev_iteration (loop)
617 652
618Returns the count of loop iterations for the loop, which is identical to 653Returns the current iteration count for the event loop, which is identical
619the number of times libev did poll for new events. It starts at C<0> and 654to the number of times libev did poll for new events. It starts at C<0>
620happily wraps around with enough iterations. 655and happily wraps around with enough iterations.
621 656
622This value can sometimes be useful as a generation counter of sorts (it 657This value can sometimes be useful as a generation counter of sorts (it
623"ticks" the number of loop iterations), as it roughly corresponds with 658"ticks" the number of loop iterations), as it roughly corresponds with
624C<ev_prepare> and C<ev_check> calls. 659C<ev_prepare> and C<ev_check> calls - and is incremented between the
660prepare and check phases.
625 661
626=item unsigned int ev_loop_depth (loop) 662=item unsigned int ev_depth (loop)
627 663
628Returns the number of times C<ev_loop> was entered minus the number of 664Returns the number of times C<ev_run> was entered minus the number of
629times C<ev_loop> was exited, in other words, the recursion depth. 665times C<ev_run> was exited, in other words, the recursion depth.
630 666
631Outside C<ev_loop>, this number is zero. In a callback, this number is 667Outside C<ev_run>, this number is zero. In a callback, this number is
632C<1>, unless C<ev_loop> was invoked recursively (or from another thread), 668C<1>, unless C<ev_run> was invoked recursively (or from another thread),
633in which case it is higher. 669in which case it is higher.
634 670
635Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread 671Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread
636etc.), doesn't count as exit. 672etc.), doesn't count as "exit" - consider this as a hint to avoid such
673ungentleman-like behaviour unless it's really convenient.
637 674
638=item unsigned int ev_backend (loop) 675=item unsigned int ev_backend (loop)
639 676
640Returns one of the C<EVBACKEND_*> flags indicating the event backend in 677Returns one of the C<EVBACKEND_*> flags indicating the event backend in
641use. 678use.
650 687
651=item ev_now_update (loop) 688=item ev_now_update (loop)
652 689
653Establishes the current time by querying the kernel, updating the time 690Establishes the current time by querying the kernel, updating the time
654returned by C<ev_now ()> in the progress. This is a costly operation and 691returned by C<ev_now ()> in the progress. This is a costly operation and
655is usually done automatically within C<ev_loop ()>. 692is usually done automatically within C<ev_run ()>.
656 693
657This function is rarely useful, but when some event callback runs for a 694This function is rarely useful, but when some event callback runs for a
658very long time without entering the event loop, updating libev's idea of 695very long time without entering the event loop, updating libev's idea of
659the current time is a good idea. 696the current time is a good idea.
660 697
662 699
663=item ev_suspend (loop) 700=item ev_suspend (loop)
664 701
665=item ev_resume (loop) 702=item ev_resume (loop)
666 703
667These two functions suspend and resume a loop, for use when the loop is 704These two functions suspend and resume an event loop, for use when the
668not used for a while and timeouts should not be processed. 705loop is not used for a while and timeouts should not be processed.
669 706
670A typical use case would be an interactive program such as a game: When 707A 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 708the 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 709would 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> 710the program was suspended. This can be achieved by calling C<ev_suspend>
675C<ev_resume> directly afterwards to resume timer processing. 712C<ev_resume> directly afterwards to resume timer processing.
676 713
677Effectively, all C<ev_timer> watchers will be delayed by the time spend 714Effectively, 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 715between 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 716will be rescheduled (that is, they will lose any events that would have
680occured while suspended). 717occurred while suspended).
681 718
682After calling C<ev_suspend> you B<must not> call I<any> function on the 719After 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> 720given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
684without a previous call to C<ev_suspend>. 721without a previous call to C<ev_suspend>.
685 722
686Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the 723Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
687event loop time (see C<ev_now_update>). 724event loop time (see C<ev_now_update>).
688 725
689=item ev_loop (loop, int flags) 726=item ev_run (loop, int flags)
690 727
691Finally, this is it, the event handler. This function usually is called 728Finally, this is it, the event handler. This function usually is called
692after you initialised all your watchers and you want to start handling 729after you have initialised all your watchers and you want to start
693events. 730handling events. It will ask the operating system for any new events, call
731the watcher callbacks, an then repeat the whole process indefinitely: This
732is why event loops are called I<loops>.
694 733
695If the flags argument is specified as C<0>, it will not return until 734If the flags argument is specified as C<0>, it will keep handling events
696either no event watchers are active anymore or C<ev_unloop> was called. 735until either no event watchers are active anymore or C<ev_break> was
736called.
697 737
698Please note that an explicit C<ev_unloop> is usually better than 738Please note that an explicit C<ev_break> is usually better than
699relying on all watchers to be stopped when deciding when a program has 739relying on all watchers to be stopped when deciding when a program has
700finished (especially in interactive programs), but having a program 740finished (especially in interactive programs), but having a program
701that automatically loops as long as it has to and no longer by virtue 741that automatically loops as long as it has to and no longer by virtue
702of relying on its watchers stopping correctly, that is truly a thing of 742of relying on its watchers stopping correctly, that is truly a thing of
703beauty. 743beauty.
704 744
705A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 745A flags value of C<EVRUN_NOWAIT> will look for new events, will handle
706those events and any already outstanding ones, but will not block your 746those events and any already outstanding ones, but will not wait and
707process in case there are no events and will return after one iteration of 747block your process in case there are no events and will return after one
708the loop. 748iteration of the loop. This is sometimes useful to poll and handle new
749events while doing lengthy calculations, to keep the program responsive.
709 750
710A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 751A flags value of C<EVRUN_ONCE> will look for new events (waiting if
711necessary) and will handle those and any already outstanding ones. It 752necessary) and will handle those and any already outstanding ones. It
712will block your process until at least one new event arrives (which could 753will block your process until at least one new event arrives (which could
713be an event internal to libev itself, so there is no guarantee that a 754be an event internal to libev itself, so there is no guarantee that a
714user-registered callback will be called), and will return after one 755user-registered callback will be called), and will return after one
715iteration of the loop. 756iteration of the loop.
716 757
717This is useful if you are waiting for some external event in conjunction 758This is useful if you are waiting for some external event in conjunction
718with something not expressible using other libev watchers (i.e. "roll your 759with something not expressible using other libev watchers (i.e. "roll your
719own C<ev_loop>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is 760own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
720usually a better approach for this kind of thing. 761usually a better approach for this kind of thing.
721 762
722Here are the gory details of what C<ev_loop> does: 763Here are the gory details of what C<ev_run> does:
723 764
765 - Increment loop depth.
766 - Reset the ev_break status.
724 - Before the first iteration, call any pending watchers. 767 - Before the first iteration, call any pending watchers.
768 LOOP:
725 * If EVFLAG_FORKCHECK was used, check for a fork. 769 - If EVFLAG_FORKCHECK was used, check for a fork.
726 - If a fork was detected (by any means), queue and call all fork watchers. 770 - If a fork was detected (by any means), queue and call all fork watchers.
727 - Queue and call all prepare watchers. 771 - Queue and call all prepare watchers.
772 - If ev_break was called, goto FINISH.
728 - If we have been forked, detach and recreate the kernel state 773 - If we have been forked, detach and recreate the kernel state
729 as to not disturb the other process. 774 as to not disturb the other process.
730 - Update the kernel state with all outstanding changes. 775 - Update the kernel state with all outstanding changes.
731 - Update the "event loop time" (ev_now ()). 776 - Update the "event loop time" (ev_now ()).
732 - Calculate for how long to sleep or block, if at all 777 - Calculate for how long to sleep or block, if at all
733 (active idle watchers, EVLOOP_NONBLOCK or not having 778 (active idle watchers, EVRUN_NOWAIT or not having
734 any active watchers at all will result in not sleeping). 779 any active watchers at all will result in not sleeping).
735 - Sleep if the I/O and timer collect interval say so. 780 - Sleep if the I/O and timer collect interval say so.
781 - Increment loop iteration counter.
736 - Block the process, waiting for any events. 782 - Block the process, waiting for any events.
737 - Queue all outstanding I/O (fd) events. 783 - Queue all outstanding I/O (fd) events.
738 - Update the "event loop time" (ev_now ()), and do time jump adjustments. 784 - Update the "event loop time" (ev_now ()), and do time jump adjustments.
739 - Queue all expired timers. 785 - Queue all expired timers.
740 - Queue all expired periodics. 786 - Queue all expired periodics.
741 - Unless any events are pending now, queue all idle watchers. 787 - Queue all idle watchers with priority higher than that of pending events.
742 - Queue all check watchers. 788 - Queue all check watchers.
743 - Call all queued watchers in reverse order (i.e. check watchers first). 789 - Call all queued watchers in reverse order (i.e. check watchers first).
744 Signals and child watchers are implemented as I/O watchers, and will 790 Signals and child watchers are implemented as I/O watchers, and will
745 be handled here by queueing them when their watcher gets executed. 791 be handled here by queueing them when their watcher gets executed.
746 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 792 - If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT
747 were used, or there are no active watchers, return, otherwise 793 were used, or there are no active watchers, goto FINISH, otherwise
748 continue with step *. 794 continue with step LOOP.
795 FINISH:
796 - Reset the ev_break status iff it was EVBREAK_ONE.
797 - Decrement the loop depth.
798 - Return.
749 799
750Example: Queue some jobs and then loop until no events are outstanding 800Example: Queue some jobs and then loop until no events are outstanding
751anymore. 801anymore.
752 802
753 ... queue jobs here, make sure they register event watchers as long 803 ... queue jobs here, make sure they register event watchers as long
754 ... as they still have work to do (even an idle watcher will do..) 804 ... as they still have work to do (even an idle watcher will do..)
755 ev_loop (my_loop, 0); 805 ev_run (my_loop, 0);
756 ... jobs done or somebody called unloop. yeah! 806 ... jobs done or somebody called unloop. yeah!
757 807
758=item ev_unloop (loop, how) 808=item ev_break (loop, how)
759 809
760Can be used to make a call to C<ev_loop> return early (but only after it 810Can be used to make a call to C<ev_run> return early (but only after it
761has processed all outstanding events). The C<how> argument must be either 811has processed all outstanding events). The C<how> argument must be either
762C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 812C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or
763C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 813C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return.
764 814
765This "unloop state" will be cleared when entering C<ev_loop> again. 815This "unloop state" will be cleared when entering C<ev_run> again.
766 816
767It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls. 817It is safe to call C<ev_break> from outside any C<ev_run> calls. ##TODO##
768 818
769=item ev_ref (loop) 819=item ev_ref (loop)
770 820
771=item ev_unref (loop) 821=item ev_unref (loop)
772 822
773Ref/unref can be used to add or remove a reference count on the event 823Ref/unref can be used to add or remove a reference count on the event
774loop: Every watcher keeps one reference, and as long as the reference 824loop: Every watcher keeps one reference, and as long as the reference
775count is nonzero, C<ev_loop> will not return on its own. 825count is nonzero, C<ev_run> will not return on its own.
776 826
777If you have a watcher you never unregister that should not keep C<ev_loop> 827This is useful when you have a watcher that you never intend to
778from returning, call ev_unref() after starting, and ev_ref() before 828unregister, but that nevertheless should not keep C<ev_run> from
829returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
779stopping it. 830before stopping it.
780 831
781As an example, libev itself uses this for its internal signal pipe: It 832As an example, libev itself uses this for its internal signal pipe: It
782is not visible to the libev user and should not keep C<ev_loop> from 833is not visible to the libev user and should not keep C<ev_run> from
783exiting if no event watchers registered by it are active. It is also an 834exiting if no event watchers registered by it are active. It is also an
784excellent way to do this for generic recurring timers or from within 835excellent way to do this for generic recurring timers or from within
785third-party libraries. Just remember to I<unref after start> and I<ref 836third-party libraries. Just remember to I<unref after start> and I<ref
786before stop> (but only if the watcher wasn't active before, or was active 837before stop> (but only if the watcher wasn't active before, or was active
787before, respectively. Note also that libev might stop watchers itself 838before, respectively. Note also that libev might stop watchers itself
788(e.g. non-repeating timers) in which case you have to C<ev_ref> 839(e.g. non-repeating timers) in which case you have to C<ev_ref>
789in the callback). 840in the callback).
790 841
791Example: Create a signal watcher, but keep it from keeping C<ev_loop> 842Example: Create a signal watcher, but keep it from keeping C<ev_run>
792running when nothing else is active. 843running when nothing else is active.
793 844
794 ev_signal exitsig; 845 ev_signal exitsig;
795 ev_signal_init (&exitsig, sig_cb, SIGINT); 846 ev_signal_init (&exitsig, sig_cb, SIGINT);
796 ev_signal_start (loop, &exitsig); 847 ev_signal_start (loop, &exitsig);
841usually doesn't make much sense to set it to a lower value than C<0.01>, 892usually doesn't make much sense to set it to a lower value than C<0.01>,
842as this approaches the timing granularity of most systems. Note that if 893as this approaches the timing granularity of most systems. Note that if
843you do transactions with the outside world and you can't increase the 894you do transactions with the outside world and you can't increase the
844parallelity, then this setting will limit your transaction rate (if you 895parallelity, 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, 896need 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). 897then you can't do more than 100 transactions per second).
847 898
848Setting the I<timeout collect interval> can improve the opportunity for 899Setting the I<timeout collect interval> can improve the opportunity for
849saving power, as the program will "bundle" timer callback invocations that 900saving power, as the program will "bundle" timer callback invocations that
850are "near" in time together, by delaying some, thus reducing the number of 901are "near" in time together, by delaying some, thus reducing the number of
851times the process sleeps and wakes up again. Another useful technique to 902times the process sleeps and wakes up again. Another useful technique to
856more often than 100 times per second: 907more often than 100 times per second:
857 908
858 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1); 909 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
859 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01); 910 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
860 911
912=item ev_invoke_pending (loop)
913
914This call will simply invoke all pending watchers while resetting their
915pending state. Normally, C<ev_run> does this automatically when required,
916but when overriding the invoke callback this call comes handy. This
917function can be invoked from a watcher - this can be useful for example
918when you want to do some lengthy calculation and want to pass further
919event handling to another thread (you still have to make sure only one
920thread executes within C<ev_invoke_pending> or C<ev_run> of course).
921
922=item int ev_pending_count (loop)
923
924Returns the number of pending watchers - zero indicates that no watchers
925are pending.
926
927=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
928
929This overrides the invoke pending functionality of the loop: Instead of
930invoking all pending watchers when there are any, C<ev_run> will call
931this callback instead. This is useful, for example, when you want to
932invoke the actual watchers inside another context (another thread etc.).
933
934If you want to reset the callback, use C<ev_invoke_pending> as new
935callback.
936
937=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
938
939Sometimes you want to share the same loop between multiple threads. This
940can be done relatively simply by putting mutex_lock/unlock calls around
941each call to a libev function.
942
943However, C<ev_run> can run an indefinite time, so it is not feasible
944to wait for it to return. One way around this is to wake up the event
945loop via C<ev_break> and C<av_async_send>, another way is to set these
946I<release> and I<acquire> callbacks on the loop.
947
948When set, then C<release> will be called just before the thread is
949suspended waiting for new events, and C<acquire> is called just
950afterwards.
951
952Ideally, C<release> will just call your mutex_unlock function, and
953C<acquire> will just call the mutex_lock function again.
954
955While event loop modifications are allowed between invocations of
956C<release> and C<acquire> (that's their only purpose after all), no
957modifications done will affect the event loop, i.e. adding watchers will
958have no effect on the set of file descriptors being watched, or the time
959waited. Use an C<ev_async> watcher to wake up C<ev_run> when you want it
960to take note of any changes you made.
961
962In theory, threads executing C<ev_run> will be async-cancel safe between
963invocations of C<release> and C<acquire>.
964
965See also the locking example in the C<THREADS> section later in this
966document.
967
968=item ev_set_userdata (loop, void *data)
969
970=item ev_userdata (loop)
971
972Set and retrieve a single C<void *> associated with a loop. When
973C<ev_set_userdata> has never been called, then C<ev_userdata> returns
974C<0.>
975
976These two functions can be used to associate arbitrary data with a loop,
977and are intended solely for the C<invoke_pending_cb>, C<release> and
978C<acquire> callbacks described above, but of course can be (ab-)used for
979any other purpose as well.
980
861=item ev_loop_verify (loop) 981=item ev_verify (loop)
862 982
863This function only does something when C<EV_VERIFY> support has been 983This function only does something when C<EV_VERIFY> support has been
864compiled in, which is the default for non-minimal builds. It tries to go 984compiled in, which is the default for non-minimal builds. It tries to go
865through all internal structures and checks them for validity. If anything 985through all internal structures and checks them for validity. If anything
866is found to be inconsistent, it will print an error message to standard 986is found to be inconsistent, it will print an error message to standard
877 997
878In the following description, uppercase C<TYPE> in names stands for the 998In the following description, uppercase C<TYPE> in names stands for the
879watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer 999watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
880watchers and C<ev_io_start> for I/O watchers. 1000watchers and C<ev_io_start> for I/O watchers.
881 1001
882A watcher is a structure that you create and register to record your 1002A watcher is an opaque structure that you allocate and register to record
883interest in some event. For instance, if you want to wait for STDIN to 1003your interest in some event. To make a concrete example, imagine you want
884become readable, you would create an C<ev_io> watcher for that: 1004to wait for STDIN to become readable, you would create an C<ev_io> watcher
1005for that:
885 1006
886 static void my_cb (struct ev_loop *loop, ev_io *w, int revents) 1007 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
887 { 1008 {
888 ev_io_stop (w); 1009 ev_io_stop (w);
889 ev_unloop (loop, EVUNLOOP_ALL); 1010 ev_break (loop, EVBREAK_ALL);
890 } 1011 }
891 1012
892 struct ev_loop *loop = ev_default_loop (0); 1013 struct ev_loop *loop = ev_default_loop (0);
893 1014
894 ev_io stdin_watcher; 1015 ev_io stdin_watcher;
895 1016
896 ev_init (&stdin_watcher, my_cb); 1017 ev_init (&stdin_watcher, my_cb);
897 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 1018 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
898 ev_io_start (loop, &stdin_watcher); 1019 ev_io_start (loop, &stdin_watcher);
899 1020
900 ev_loop (loop, 0); 1021 ev_run (loop, 0);
901 1022
902As you can see, you are responsible for allocating the memory for your 1023As you can see, you are responsible for allocating the memory for your
903watcher structures (and it is I<usually> a bad idea to do this on the 1024watcher structures (and it is I<usually> a bad idea to do this on the
904stack). 1025stack).
905 1026
906Each watcher has an associated watcher structure (called C<struct ev_TYPE> 1027Each watcher has an associated watcher structure (called C<struct ev_TYPE>
907or simply C<ev_TYPE>, as typedefs are provided for all watcher structs). 1028or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
908 1029
909Each watcher structure must be initialised by a call to C<ev_init 1030Each watcher structure must be initialised by a call to C<ev_init (watcher
910(watcher *, callback)>, which expects a callback to be provided. This 1031*, callback)>, which expects a callback to be provided. This callback is
911callback gets invoked each time the event occurs (or, in the case of I/O 1032invoked each time the event occurs (or, in the case of I/O watchers, each
912watchers, each time the event loop detects that the file descriptor given 1033time the event loop detects that the file descriptor given is readable
913is readable and/or writable). 1034and/or writable).
914 1035
915Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >> 1036Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
916macro to configure it, with arguments specific to the watcher type. There 1037macro to configure it, with arguments specific to the watcher type. There
917is also a macro to combine initialisation and setting in one call: C<< 1038is also a macro to combine initialisation and setting in one call: C<<
918ev_TYPE_init (watcher *, callback, ...) >>. 1039ev_TYPE_init (watcher *, callback, ...) >>.
941=item C<EV_WRITE> 1062=item C<EV_WRITE>
942 1063
943The file descriptor in the C<ev_io> watcher has become readable and/or 1064The file descriptor in the C<ev_io> watcher has become readable and/or
944writable. 1065writable.
945 1066
946=item C<EV_TIMEOUT> 1067=item C<EV_TIMER>
947 1068
948The C<ev_timer> watcher has timed out. 1069The C<ev_timer> watcher has timed out.
949 1070
950=item C<EV_PERIODIC> 1071=item C<EV_PERIODIC>
951 1072
969 1090
970=item C<EV_PREPARE> 1091=item C<EV_PREPARE>
971 1092
972=item C<EV_CHECK> 1093=item C<EV_CHECK>
973 1094
974All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts 1095All C<ev_prepare> watchers are invoked just I<before> C<ev_run> starts
975to gather new events, and all C<ev_check> watchers are invoked just after 1096to gather new events, and all C<ev_check> watchers are invoked just after
976C<ev_loop> has gathered them, but before it invokes any callbacks for any 1097C<ev_run> has gathered them, but before it invokes any callbacks for any
977received events. Callbacks of both watcher types can start and stop as 1098received events. Callbacks of both watcher types can start and stop as
978many watchers as they want, and all of them will be taken into account 1099many watchers as they want, and all of them will be taken into account
979(for example, a C<ev_prepare> watcher might start an idle watcher to keep 1100(for example, a C<ev_prepare> watcher might start an idle watcher to keep
980C<ev_loop> from blocking). 1101C<ev_run> from blocking).
981 1102
982=item C<EV_EMBED> 1103=item C<EV_EMBED>
983 1104
984The embedded event loop specified in the C<ev_embed> watcher needs attention. 1105The embedded event loop specified in the C<ev_embed> watcher needs attention.
985 1106
1016programs, though, as the fd could already be closed and reused for another 1137programs, though, as the fd could already be closed and reused for another
1017thing, so beware. 1138thing, so beware.
1018 1139
1019=back 1140=back
1020 1141
1142=head2 WATCHER STATES
1143
1144There are various watcher states mentioned throughout this manual -
1145active, pending and so on. In this section these states and the rules to
1146transition between them will be described in more detail - and while these
1147rules might look complicated, they usually do "the right thing".
1148
1149=over 4
1150
1151=item initialiased
1152
1153Before a watcher can be registered with the event looop it has to be
1154initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
1155C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1156
1157In this state it is simply some block of memory that is suitable for use
1158in an event loop. It can be moved around, freed, reused etc. at will.
1159
1160=item started/running/active
1161
1162Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
1163property of the event loop, and is actively waiting for events. While in
1164this state it cannot be accessed (except in a few documented ways), moved,
1165freed or anything else - the only legal thing is to keep a pointer to it,
1166and call libev functions on it that are documented to work on active watchers.
1167
1168=item pending
1169
1170If a watcher is active and libev determines that an event it is interested
1171in has occurred (such as a timer expiring), it will become pending. It will
1172stay in this pending state until either it is stopped or its callback is
1173about to be invoked, so it is not normally pending inside the watcher
1174callback.
1175
1176The watcher might or might not be active while it is pending (for example,
1177an expired non-repeating timer can be pending but no longer active). If it
1178is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
1179but it is still property of the event loop at this time, so cannot be
1180moved, freed or reused. And if it is active the rules described in the
1181previous item still apply.
1182
1183It is also possible to feed an event on a watcher that is not active (e.g.
1184via C<ev_feed_event>), in which case it becomes pending without being
1185active.
1186
1187=item stopped
1188
1189A watcher can be stopped implicitly by libev (in which case it might still
1190be pending), or explicitly by calling its C<ev_TYPE_stop> function. The
1191latter will clear any pending state the watcher might be in, regardless
1192of whether it was active or not, so stopping a watcher explicitly before
1193freeing it is often a good idea.
1194
1195While stopped (and not pending) the watcher is essentially in the
1196initialised state, that is it can be reused, moved, modified in any way
1197you wish.
1198
1199=back
1200
1021=head2 GENERIC WATCHER FUNCTIONS 1201=head2 GENERIC WATCHER FUNCTIONS
1022 1202
1023=over 4 1203=over 4
1024 1204
1025=item C<ev_init> (ev_TYPE *watcher, callback) 1205=item C<ev_init> (ev_TYPE *watcher, callback)
1041 1221
1042 ev_io w; 1222 ev_io w;
1043 ev_init (&w, my_cb); 1223 ev_init (&w, my_cb);
1044 ev_io_set (&w, STDIN_FILENO, EV_READ); 1224 ev_io_set (&w, STDIN_FILENO, EV_READ);
1045 1225
1046=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1226=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1047 1227
1048This macro initialises the type-specific parts of a watcher. You need to 1228This macro initialises the type-specific parts of a watcher. You need to
1049call C<ev_init> at least once before you call this macro, but you can 1229call C<ev_init> at least once before you call this macro, but you can
1050call C<ev_TYPE_set> any number of times. You must not, however, call this 1230call C<ev_TYPE_set> any number of times. You must not, however, call this
1051macro on a watcher that is active (it can be pending, however, which is a 1231macro on a watcher that is active (it can be pending, however, which is a
1064 1244
1065Example: Initialise and set an C<ev_io> watcher in one step. 1245Example: Initialise and set an C<ev_io> watcher in one step.
1066 1246
1067 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1247 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1068 1248
1069=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1249=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1070 1250
1071Starts (activates) the given watcher. Only active watchers will receive 1251Starts (activates) the given watcher. Only active watchers will receive
1072events. If the watcher is already active nothing will happen. 1252events. If the watcher is already active nothing will happen.
1073 1253
1074Example: Start the C<ev_io> watcher that is being abused as example in this 1254Example: Start the C<ev_io> watcher that is being abused as example in this
1075whole section. 1255whole section.
1076 1256
1077 ev_io_start (EV_DEFAULT_UC, &w); 1257 ev_io_start (EV_DEFAULT_UC, &w);
1078 1258
1079=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1259=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1080 1260
1081Stops the given watcher if active, and clears the pending status (whether 1261Stops the given watcher if active, and clears the pending status (whether
1082the watcher was active or not). 1262the watcher was active or not).
1083 1263
1084It is possible that stopped watchers are pending - for example, 1264It is possible that stopped watchers are pending - for example,
1109=item ev_cb_set (ev_TYPE *watcher, callback) 1289=item ev_cb_set (ev_TYPE *watcher, callback)
1110 1290
1111Change the callback. You can change the callback at virtually any time 1291Change the callback. You can change the callback at virtually any time
1112(modulo threads). 1292(modulo threads).
1113 1293
1114=item ev_set_priority (ev_TYPE *watcher, priority) 1294=item ev_set_priority (ev_TYPE *watcher, int priority)
1115 1295
1116=item int ev_priority (ev_TYPE *watcher) 1296=item int ev_priority (ev_TYPE *watcher)
1117 1297
1118Set and query the priority of the watcher. The priority is a small 1298Set and query the priority of the watcher. The priority is a small
1119integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1299integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1150returns its C<revents> bitset (as if its callback was invoked). If the 1330returns its C<revents> bitset (as if its callback was invoked). If the
1151watcher isn't pending it does nothing and returns C<0>. 1331watcher isn't pending it does nothing and returns C<0>.
1152 1332
1153Sometimes it can be useful to "poll" a watcher instead of waiting for its 1333Sometimes it can be useful to "poll" a watcher instead of waiting for its
1154callback to be invoked, which can be accomplished with this function. 1334callback to be invoked, which can be accomplished with this function.
1335
1336=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1337
1338Feeds the given event set into the event loop, as if the specified event
1339had happened for the specified watcher (which must be a pointer to an
1340initialised but not necessarily started event watcher). Obviously you must
1341not free the watcher as long as it has pending events.
1342
1343Stopping the watcher, letting libev invoke it, or calling
1344C<ev_clear_pending> will clear the pending event, even if the watcher was
1345not started in the first place.
1346
1347See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1348functions that do not need a watcher.
1155 1349
1156=back 1350=back
1157 1351
1158 1352
1159=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1353=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1270 1464
1271For example, to emulate how many other event libraries handle priorities, 1465For example, to emulate how many other event libraries handle priorities,
1272you can associate an C<ev_idle> watcher to each such watcher, and in 1466you can associate an C<ev_idle> watcher to each such watcher, and in
1273the normal watcher callback, you just start the idle watcher. The real 1467the normal watcher callback, you just start the idle watcher. The real
1274processing is done in the idle watcher callback. This causes libev to 1468processing is done in the idle watcher callback. This causes libev to
1275continously poll and process kernel event data for the watcher, but when 1469continuously poll and process kernel event data for the watcher, but when
1276the lock-out case is known to be rare (which in turn is rare :), this is 1470the lock-out case is known to be rare (which in turn is rare :), this is
1277workable. 1471workable.
1278 1472
1279Usually, however, the lock-out model implemented that way will perform 1473Usually, however, the lock-out model implemented that way will perform
1280miserably under the type of load it was designed to handle. In that case, 1474miserably under the type of load it was designed to handle. In that case,
1294 { 1488 {
1295 // stop the I/O watcher, we received the event, but 1489 // stop the I/O watcher, we received the event, but
1296 // are not yet ready to handle it. 1490 // are not yet ready to handle it.
1297 ev_io_stop (EV_A_ w); 1491 ev_io_stop (EV_A_ w);
1298 1492
1299 // start the idle watcher to ahndle the actual event. 1493 // start the idle watcher to handle the actual event.
1300 // it will not be executed as long as other watchers 1494 // it will not be executed as long as other watchers
1301 // with the default priority are receiving events. 1495 // with the default priority are receiving events.
1302 ev_idle_start (EV_A_ &idle); 1496 ev_idle_start (EV_A_ &idle);
1303 } 1497 }
1304 1498
1358 1552
1359If you cannot use non-blocking mode, then force the use of a 1553If you cannot use non-blocking mode, then force the use of a
1360known-to-be-good backend (at the time of this writing, this includes only 1554known-to-be-good backend (at the time of this writing, this includes only
1361C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file 1555C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1362descriptors for which non-blocking operation makes no sense (such as 1556descriptors for which non-blocking operation makes no sense (such as
1363files) - libev doesn't guarentee any specific behaviour in that case. 1557files) - libev doesn't guarantee any specific behaviour in that case.
1364 1558
1365Another thing you have to watch out for is that it is quite easy to 1559Another thing you have to watch out for is that it is quite easy to
1366receive "spurious" readiness notifications, that is your callback might 1560receive "spurious" readiness notifications, that is your callback might
1367be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1561be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1368because there is no data. Not only are some backends known to create a 1562because there is no data. Not only are some backends known to create a
1433 1627
1434So when you encounter spurious, unexplained daemon exits, make sure you 1628So when you encounter spurious, unexplained daemon exits, make sure you
1435ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1629ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1436somewhere, as that would have given you a big clue). 1630somewhere, as that would have given you a big clue).
1437 1631
1632=head3 The special problem of accept()ing when you can't
1633
1634Many implementations of the POSIX C<accept> function (for example,
1635found in post-2004 Linux) have the peculiar behaviour of not removing a
1636connection from the pending queue in all error cases.
1637
1638For example, larger servers often run out of file descriptors (because
1639of resource limits), causing C<accept> to fail with C<ENFILE> but not
1640rejecting the connection, leading to libev signalling readiness on
1641the next iteration again (the connection still exists after all), and
1642typically causing the program to loop at 100% CPU usage.
1643
1644Unfortunately, the set of errors that cause this issue differs between
1645operating systems, there is usually little the app can do to remedy the
1646situation, and no known thread-safe method of removing the connection to
1647cope with overload is known (to me).
1648
1649One of the easiest ways to handle this situation is to just ignore it
1650- when the program encounters an overload, it will just loop until the
1651situation is over. While this is a form of busy waiting, no OS offers an
1652event-based way to handle this situation, so it's the best one can do.
1653
1654A better way to handle the situation is to log any errors other than
1655C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1656messages, and continue as usual, which at least gives the user an idea of
1657what could be wrong ("raise the ulimit!"). For extra points one could stop
1658the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1659usage.
1660
1661If your program is single-threaded, then you could also keep a dummy file
1662descriptor for overload situations (e.g. by opening F</dev/null>), and
1663when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1664close that fd, and create a new dummy fd. This will gracefully refuse
1665clients under typical overload conditions.
1666
1667The last way to handle it is to simply log the error and C<exit>, as
1668is often done with C<malloc> failures, but this results in an easy
1669opportunity for a DoS attack.
1438 1670
1439=head3 Watcher-Specific Functions 1671=head3 Watcher-Specific Functions
1440 1672
1441=over 4 1673=over 4
1442 1674
1474 ... 1706 ...
1475 struct ev_loop *loop = ev_default_init (0); 1707 struct ev_loop *loop = ev_default_init (0);
1476 ev_io stdin_readable; 1708 ev_io stdin_readable;
1477 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1709 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1478 ev_io_start (loop, &stdin_readable); 1710 ev_io_start (loop, &stdin_readable);
1479 ev_loop (loop, 0); 1711 ev_run (loop, 0);
1480 1712
1481 1713
1482=head2 C<ev_timer> - relative and optionally repeating timeouts 1714=head2 C<ev_timer> - relative and optionally repeating timeouts
1483 1715
1484Timer watchers are simple relative timers that generate an event after a 1716Timer watchers are simple relative timers that generate an event after a
1493The callback is guaranteed to be invoked only I<after> its timeout has 1725The callback is guaranteed to be invoked only I<after> its timeout has
1494passed (not I<at>, so on systems with very low-resolution clocks this 1726passed (not I<at>, so on systems with very low-resolution clocks this
1495might introduce a small delay). If multiple timers become ready during the 1727might introduce a small delay). If multiple timers become ready during the
1496same loop iteration then the ones with earlier time-out values are invoked 1728same loop iteration then the ones with earlier time-out values are invoked
1497before ones of the same priority with later time-out values (but this is 1729before ones of the same priority with later time-out values (but this is
1498no longer true when a callback calls C<ev_loop> recursively). 1730no longer true when a callback calls C<ev_run> recursively).
1499 1731
1500=head3 Be smart about timeouts 1732=head3 Be smart about timeouts
1501 1733
1502Many real-world problems involve some kind of timeout, usually for error 1734Many real-world problems involve some kind of timeout, usually for error
1503recovery. A typical example is an HTTP request - if the other side hangs, 1735recovery. A typical example is an HTTP request - if the other side hangs,
1589 ev_tstamp timeout = last_activity + 60.; 1821 ev_tstamp timeout = last_activity + 60.;
1590 1822
1591 // if last_activity + 60. is older than now, we did time out 1823 // if last_activity + 60. is older than now, we did time out
1592 if (timeout < now) 1824 if (timeout < now)
1593 { 1825 {
1594 // timeout occured, take action 1826 // timeout occurred, take action
1595 } 1827 }
1596 else 1828 else
1597 { 1829 {
1598 // callback was invoked, but there was some activity, re-arm 1830 // callback was invoked, but there was some activity, re-arm
1599 // the watcher to fire in last_activity + 60, which is 1831 // the watcher to fire in last_activity + 60, which is
1621to the current time (meaning we just have some activity :), then call the 1853to the current time (meaning we just have some activity :), then call the
1622callback, which will "do the right thing" and start the timer: 1854callback, which will "do the right thing" and start the timer:
1623 1855
1624 ev_init (timer, callback); 1856 ev_init (timer, callback);
1625 last_activity = ev_now (loop); 1857 last_activity = ev_now (loop);
1626 callback (loop, timer, EV_TIMEOUT); 1858 callback (loop, timer, EV_TIMER);
1627 1859
1628And when there is some activity, simply store the current time in 1860And when there is some activity, simply store the current time in
1629C<last_activity>, no libev calls at all: 1861C<last_activity>, no libev calls at all:
1630 1862
1631 last_actiivty = ev_now (loop); 1863 last_activity = ev_now (loop);
1632 1864
1633This technique is slightly more complex, but in most cases where the 1865This technique is slightly more complex, but in most cases where the
1634time-out is unlikely to be triggered, much more efficient. 1866time-out is unlikely to be triggered, much more efficient.
1635 1867
1636Changing the timeout is trivial as well (if it isn't hard-coded in the 1868Changing the timeout is trivial as well (if it isn't hard-coded in the
1674 1906
1675=head3 The special problem of time updates 1907=head3 The special problem of time updates
1676 1908
1677Establishing the current time is a costly operation (it usually takes at 1909Establishing the current time is a costly operation (it usually takes at
1678least two system calls): EV therefore updates its idea of the current 1910least two system calls): EV therefore updates its idea of the current
1679time only before and after C<ev_loop> collects new events, which causes a 1911time only before and after C<ev_run> collects new events, which causes a
1680growing difference between C<ev_now ()> and C<ev_time ()> when handling 1912growing difference between C<ev_now ()> and C<ev_time ()> when handling
1681lots of events in one iteration. 1913lots of events in one iteration.
1682 1914
1683The relative timeouts are calculated relative to the C<ev_now ()> 1915The relative timeouts are calculated relative to the C<ev_now ()>
1684time. This is usually the right thing as this timestamp refers to the time 1916time. This is usually the right thing as this timestamp refers to the time
1690 1922
1691If the event loop is suspended for a long time, you can also force an 1923If the event loop is suspended for a long time, you can also force an
1692update of the time returned by C<ev_now ()> by calling C<ev_now_update 1924update of the time returned by C<ev_now ()> by calling C<ev_now_update
1693()>. 1925()>.
1694 1926
1927=head3 The special problems of suspended animation
1928
1929When you leave the server world it is quite customary to hit machines that
1930can suspend/hibernate - what happens to the clocks during such a suspend?
1931
1932Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
1933all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
1934to run until the system is suspended, but they will not advance while the
1935system is suspended. That means, on resume, it will be as if the program
1936was frozen for a few seconds, but the suspend time will not be counted
1937towards C<ev_timer> when a monotonic clock source is used. The real time
1938clock advanced as expected, but if it is used as sole clocksource, then a
1939long suspend would be detected as a time jump by libev, and timers would
1940be adjusted accordingly.
1941
1942I would not be surprised to see different behaviour in different between
1943operating systems, OS versions or even different hardware.
1944
1945The other form of suspend (job control, or sending a SIGSTOP) will see a
1946time jump in the monotonic clocks and the realtime clock. If the program
1947is suspended for a very long time, and monotonic clock sources are in use,
1948then you can expect C<ev_timer>s to expire as the full suspension time
1949will be counted towards the timers. When no monotonic clock source is in
1950use, then libev will again assume a timejump and adjust accordingly.
1951
1952It might be beneficial for this latter case to call C<ev_suspend>
1953and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
1954deterministic behaviour in this case (you can do nothing against
1955C<SIGSTOP>).
1956
1695=head3 Watcher-Specific Functions and Data Members 1957=head3 Watcher-Specific Functions and Data Members
1696 1958
1697=over 4 1959=over 4
1698 1960
1699=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1961=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1725C<repeat> value), or reset the running timer to the C<repeat> value. 1987C<repeat> value), or reset the running timer to the C<repeat> value.
1726 1988
1727This sounds a bit complicated, see L<Be smart about timeouts>, above, for a 1989This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1728usage example. 1990usage example.
1729 1991
1992=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1993
1994Returns the remaining time until a timer fires. If the timer is active,
1995then this time is relative to the current event loop time, otherwise it's
1996the timeout value currently configured.
1997
1998That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1999C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
2000will return C<4>. When the timer expires and is restarted, it will return
2001roughly C<7> (likely slightly less as callback invocation takes some time,
2002too), and so on.
2003
1730=item ev_tstamp repeat [read-write] 2004=item ev_tstamp repeat [read-write]
1731 2005
1732The current C<repeat> value. Will be used each time the watcher times out 2006The current C<repeat> value. Will be used each time the watcher times out
1733or C<ev_timer_again> is called, and determines the next timeout (if any), 2007or C<ev_timer_again> is called, and determines the next timeout (if any),
1734which is also when any modifications are taken into account. 2008which is also when any modifications are taken into account.
1759 } 2033 }
1760 2034
1761 ev_timer mytimer; 2035 ev_timer mytimer;
1762 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 2036 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1763 ev_timer_again (&mytimer); /* start timer */ 2037 ev_timer_again (&mytimer); /* start timer */
1764 ev_loop (loop, 0); 2038 ev_run (loop, 0);
1765 2039
1766 // and in some piece of code that gets executed on any "activity": 2040 // and in some piece of code that gets executed on any "activity":
1767 // reset the timeout to start ticking again at 10 seconds 2041 // reset the timeout to start ticking again at 10 seconds
1768 ev_timer_again (&mytimer); 2042 ev_timer_again (&mytimer);
1769 2043
1795 2069
1796As with timers, the callback is guaranteed to be invoked only when the 2070As with timers, the callback is guaranteed to be invoked only when the
1797point in time where it is supposed to trigger has passed. If multiple 2071point in time where it is supposed to trigger has passed. If multiple
1798timers become ready during the same loop iteration then the ones with 2072timers become ready during the same loop iteration then the ones with
1799earlier time-out values are invoked before ones with later time-out values 2073earlier time-out values are invoked before ones with later time-out values
1800(but this is no longer true when a callback calls C<ev_loop> recursively). 2074(but this is no longer true when a callback calls C<ev_run> recursively).
1801 2075
1802=head3 Watcher-Specific Functions and Data Members 2076=head3 Watcher-Specific Functions and Data Members
1803 2077
1804=over 4 2078=over 4
1805 2079
1933Example: Call a callback every hour, or, more precisely, whenever the 2207Example: Call a callback every hour, or, more precisely, whenever the
1934system time is divisible by 3600. The callback invocation times have 2208system time is divisible by 3600. The callback invocation times have
1935potentially a lot of jitter, but good long-term stability. 2209potentially a lot of jitter, but good long-term stability.
1936 2210
1937 static void 2211 static void
1938 clock_cb (struct ev_loop *loop, ev_io *w, int revents) 2212 clock_cb (struct ev_loop *loop, ev_periodic *w, int revents)
1939 { 2213 {
1940 ... its now a full hour (UTC, or TAI or whatever your clock follows) 2214 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1941 } 2215 }
1942 2216
1943 ev_periodic hourly_tick; 2217 ev_periodic hourly_tick;
1969Signal watchers will trigger an event when the process receives a specific 2243Signal watchers will trigger an event when the process receives a specific
1970signal one or more times. Even though signals are very asynchronous, libev 2244signal one or more times. Even though signals are very asynchronous, libev
1971will try it's best to deliver signals synchronously, i.e. as part of the 2245will try it's best to deliver signals synchronously, i.e. as part of the
1972normal event processing, like any other event. 2246normal event processing, like any other event.
1973 2247
1974If you want signals asynchronously, just use C<sigaction> as you would 2248If you want signals to be delivered truly asynchronously, just use
1975do without libev and forget about sharing the signal. You can even use 2249C<sigaction> as you would do without libev and forget about sharing
1976C<ev_async> from a signal handler to synchronously wake up an event loop. 2250the signal. You can even use C<ev_async> from a signal handler to
2251synchronously wake up an event loop.
1977 2252
1978You can configure as many watchers as you like per signal. Only when the 2253You can configure as many watchers as you like for the same signal, but
2254only within the same loop, i.e. you can watch for C<SIGINT> in your
2255default loop and for C<SIGIO> in another loop, but you cannot watch for
2256C<SIGINT> in both the default loop and another loop at the same time. At
2257the moment, C<SIGCHLD> is permanently tied to the default loop.
2258
1979first watcher gets started will libev actually register a signal handler 2259When the first watcher gets started will libev actually register something
1980with the kernel (thus it coexists with your own signal handlers as long as 2260with the kernel (thus it coexists with your own signal handlers as long as
1981you don't register any with libev for the same signal). Similarly, when 2261you don't register any with libev for the same signal).
1982the last signal watcher for a signal is stopped, libev will reset the
1983signal handler to SIG_DFL (regardless of what it was set to before).
1984 2262
1985If possible and supported, libev will install its handlers with 2263If possible and supported, libev will install its handlers with
1986C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2264C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
1987interrupted. If you have a problem with system calls getting interrupted by 2265not be unduly interrupted. If you have a problem with system calls getting
1988signals you can block all signals in an C<ev_check> watcher and unblock 2266interrupted by signals you can block all signals in an C<ev_check> watcher
1989them in an C<ev_prepare> watcher. 2267and unblock them in an C<ev_prepare> watcher.
2268
2269=head3 The special problem of inheritance over fork/execve/pthread_create
2270
2271Both the signal mask (C<sigprocmask>) and the signal disposition
2272(C<sigaction>) are unspecified after starting a signal watcher (and after
2273stopping it again), that is, libev might or might not block the signal,
2274and might or might not set or restore the installed signal handler.
2275
2276While this does not matter for the signal disposition (libev never
2277sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2278C<execve>), this matters for the signal mask: many programs do not expect
2279certain signals to be blocked.
2280
2281This means that before calling C<exec> (from the child) you should reset
2282the signal mask to whatever "default" you expect (all clear is a good
2283choice usually).
2284
2285The simplest way to ensure that the signal mask is reset in the child is
2286to install a fork handler with C<pthread_atfork> that resets it. That will
2287catch fork calls done by libraries (such as the libc) as well.
2288
2289In current versions of libev, the signal will not be blocked indefinitely
2290unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2291the window of opportunity for problems, it will not go away, as libev
2292I<has> to modify the signal mask, at least temporarily.
2293
2294So I can't stress this enough: I<If you do not reset your signal mask when
2295you expect it to be empty, you have a race condition in your code>. This
2296is not a libev-specific thing, this is true for most event libraries.
1990 2297
1991=head3 Watcher-Specific Functions and Data Members 2298=head3 Watcher-Specific Functions and Data Members
1992 2299
1993=over 4 2300=over 4
1994 2301
2010Example: Try to exit cleanly on SIGINT. 2317Example: Try to exit cleanly on SIGINT.
2011 2318
2012 static void 2319 static void
2013 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) 2320 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
2014 { 2321 {
2015 ev_unloop (loop, EVUNLOOP_ALL); 2322 ev_break (loop, EVBREAK_ALL);
2016 } 2323 }
2017 2324
2018 ev_signal signal_watcher; 2325 ev_signal signal_watcher;
2019 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 2326 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
2020 ev_signal_start (loop, &signal_watcher); 2327 ev_signal_start (loop, &signal_watcher);
2033 2340
2034Only the default event loop is capable of handling signals, and therefore 2341Only the default event loop is capable of handling signals, and therefore
2035you can only register child watchers in the default event loop. 2342you can only register child watchers in the default event loop.
2036 2343
2037Due to some design glitches inside libev, child watchers will always be 2344Due to some design glitches inside libev, child watchers will always be
2038handled at maximum priority (their priority is set to EV_MAXPRI by libev) 2345handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2346libev)
2039 2347
2040=head3 Process Interaction 2348=head3 Process Interaction
2041 2349
2042Libev grabs C<SIGCHLD> as soon as the default event loop is 2350Libev grabs C<SIGCHLD> as soon as the default event loop is
2043initialised. This is necessary to guarantee proper behaviour even if 2351initialised. This is necessary to guarantee proper behaviour even if the
2044the first child watcher is started after the child exits. The occurrence 2352first child watcher is started after the child exits. The occurrence
2045of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2353of C<SIGCHLD> is recorded asynchronously, but child reaping is done
2046synchronously as part of the event loop processing. Libev always reaps all 2354synchronously as part of the event loop processing. Libev always reaps all
2047children, even ones not watched. 2355children, even ones not watched.
2048 2356
2049=head3 Overriding the Built-In Processing 2357=head3 Overriding the Built-In Processing
2059=head3 Stopping the Child Watcher 2367=head3 Stopping the Child Watcher
2060 2368
2061Currently, the child watcher never gets stopped, even when the 2369Currently, the child watcher never gets stopped, even when the
2062child terminates, so normally one needs to stop the watcher in the 2370child terminates, so normally one needs to stop the watcher in the
2063callback. Future versions of libev might stop the watcher automatically 2371callback. Future versions of libev might stop the watcher automatically
2064when a child exit is detected. 2372when a child exit is detected (calling C<ev_child_stop> twice is not a
2373problem).
2065 2374
2066=head3 Watcher-Specific Functions and Data Members 2375=head3 Watcher-Specific Functions and Data Members
2067 2376
2068=over 4 2377=over 4
2069 2378
2404 2713
2405Prepare and check watchers are usually (but not always) used in pairs: 2714Prepare and check watchers are usually (but not always) used in pairs:
2406prepare watchers get invoked before the process blocks and check watchers 2715prepare watchers get invoked before the process blocks and check watchers
2407afterwards. 2716afterwards.
2408 2717
2409You I<must not> call C<ev_loop> or similar functions that enter 2718You I<must not> call C<ev_run> or similar functions that enter
2410the current event loop from either C<ev_prepare> or C<ev_check> 2719the current event loop from either C<ev_prepare> or C<ev_check>
2411watchers. Other loops than the current one are fine, however. The 2720watchers. Other loops than the current one are fine, however. The
2412rationale behind this is that you do not need to check for recursion in 2721rationale behind this is that you do not need to check for recursion in
2413those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 2722those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
2414C<ev_check> so if you have one watcher of each kind they will always be 2723C<ev_check> so if you have one watcher of each kind they will always be
2582 2891
2583 if (timeout >= 0) 2892 if (timeout >= 0)
2584 // create/start timer 2893 // create/start timer
2585 2894
2586 // poll 2895 // poll
2587 ev_loop (EV_A_ 0); 2896 ev_run (EV_A_ 0);
2588 2897
2589 // stop timer again 2898 // stop timer again
2590 if (timeout >= 0) 2899 if (timeout >= 0)
2591 ev_timer_stop (EV_A_ &to); 2900 ev_timer_stop (EV_A_ &to);
2592 2901
2670if you do not want that, you need to temporarily stop the embed watcher). 2979if you do not want that, you need to temporarily stop the embed watcher).
2671 2980
2672=item ev_embed_sweep (loop, ev_embed *) 2981=item ev_embed_sweep (loop, ev_embed *)
2673 2982
2674Make a single, non-blocking sweep over the embedded loop. This works 2983Make a single, non-blocking sweep over the embedded loop. This works
2675similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 2984similarly to C<ev_run (embedded_loop, EVRUN_NOWAIT)>, but in the most
2676appropriate way for embedded loops. 2985appropriate way for embedded loops.
2677 2986
2678=item struct ev_loop *other [read-only] 2987=item struct ev_loop *other [read-only]
2679 2988
2680The embedded event loop. 2989The embedded event loop.
2740C<ev_default_fork> cheats and calls it in the wrong process, the fork 3049C<ev_default_fork> cheats and calls it in the wrong process, the fork
2741handlers will be invoked, too, of course. 3050handlers will be invoked, too, of course.
2742 3051
2743=head3 The special problem of life after fork - how is it possible? 3052=head3 The special problem of life after fork - how is it possible?
2744 3053
2745Most uses of C<fork()> consist of forking, then some simple calls to ste 3054Most uses of C<fork()> consist of forking, then some simple calls to set
2746up/change the process environment, followed by a call to C<exec()>. This 3055up/change the process environment, followed by a call to C<exec()>. This
2747sequence should be handled by libev without any problems. 3056sequence should be handled by libev without any problems.
2748 3057
2749This changes when the application actually wants to do event handling 3058This changes when the application actually wants to do event handling
2750in the child, or both parent in child, in effect "continuing" after the 3059in the child, or both parent in child, in effect "continuing" after the
2784believe me. 3093believe me.
2785 3094
2786=back 3095=back
2787 3096
2788 3097
2789=head2 C<ev_async> - how to wake up another event loop 3098=head2 C<ev_async> - how to wake up an event loop
2790 3099
2791In general, you cannot use an C<ev_loop> from multiple threads or other 3100In general, you cannot use an C<ev_run> from multiple threads or other
2792asynchronous sources such as signal handlers (as opposed to multiple event 3101asynchronous sources such as signal handlers (as opposed to multiple event
2793loops - those are of course safe to use in different threads). 3102loops - those are of course safe to use in different threads).
2794 3103
2795Sometimes, however, you need to wake up another event loop you do not 3104Sometimes, however, you need to wake up an event loop you do not control,
2796control, for example because it belongs to another thread. This is what 3105for example because it belongs to another thread. This is what C<ev_async>
2797C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you 3106watchers do: as long as the C<ev_async> watcher is active, you can signal
2798can signal it by calling C<ev_async_send>, which is thread- and signal 3107it by calling C<ev_async_send>, which is thread- and signal safe.
2799safe.
2800 3108
2801This functionality is very similar to C<ev_signal> watchers, as signals, 3109This functionality is very similar to C<ev_signal> watchers, as signals,
2802too, are asynchronous in nature, and signals, too, will be compressed 3110too, are asynchronous in nature, and signals, too, will be compressed
2803(i.e. the number of callback invocations may be less than the number of 3111(i.e. the number of callback invocations may be less than the number of
2804C<ev_async_sent> calls). 3112C<ev_async_sent> calls).
2809=head3 Queueing 3117=head3 Queueing
2810 3118
2811C<ev_async> does not support queueing of data in any way. The reason 3119C<ev_async> does not support queueing of data in any way. The reason
2812is that the author does not know of a simple (or any) algorithm for a 3120is that the author does not know of a simple (or any) algorithm for a
2813multiple-writer-single-reader queue that works in all cases and doesn't 3121multiple-writer-single-reader queue that works in all cases and doesn't
2814need elaborate support such as pthreads. 3122need elaborate support such as pthreads or unportable memory access
3123semantics.
2815 3124
2816That means that if you want to queue data, you have to provide your own 3125That means that if you want to queue data, you have to provide your own
2817queue. But at least I can tell you how to implement locking around your 3126queue. But at least I can tell you how to implement locking around your
2818queue: 3127queue:
2819 3128
2958 3267
2959If C<timeout> is less than 0, then no timeout watcher will be 3268If C<timeout> is less than 0, then no timeout watcher will be
2960started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3269started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2961repeat = 0) will be started. C<0> is a valid timeout. 3270repeat = 0) will be started. C<0> is a valid timeout.
2962 3271
2963The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3272The callback has the type C<void (*cb)(int revents, void *arg)> and is
2964passed an C<revents> set like normal event callbacks (a combination of 3273passed an C<revents> set like normal event callbacks (a combination of
2965C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3274C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
2966value passed to C<ev_once>. Note that it is possible to receive I<both> 3275value passed to C<ev_once>. Note that it is possible to receive I<both>
2967a timeout and an io event at the same time - you probably should give io 3276a timeout and an io event at the same time - you probably should give io
2968events precedence. 3277events precedence.
2969 3278
2970Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3279Example: wait up to ten seconds for data to appear on STDIN_FILENO.
2971 3280
2972 static void stdin_ready (int revents, void *arg) 3281 static void stdin_ready (int revents, void *arg)
2973 { 3282 {
2974 if (revents & EV_READ) 3283 if (revents & EV_READ)
2975 /* stdin might have data for us, joy! */; 3284 /* stdin might have data for us, joy! */;
2976 else if (revents & EV_TIMEOUT) 3285 else if (revents & EV_TIMER)
2977 /* doh, nothing entered */; 3286 /* doh, nothing entered */;
2978 } 3287 }
2979 3288
2980 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3289 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2981 3290
2982=item ev_feed_event (struct ev_loop *, watcher *, int revents)
2983
2984Feeds the given event set into the event loop, as if the specified event
2985had happened for the specified watcher (which must be a pointer to an
2986initialised but not necessarily started event watcher).
2987
2988=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3291=item ev_feed_fd_event (loop, int fd, int revents)
2989 3292
2990Feed an event on the given fd, as if a file descriptor backend detected 3293Feed an event on the given fd, as if a file descriptor backend detected
2991the given events it. 3294the given events it.
2992 3295
2993=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3296=item ev_feed_signal_event (loop, int signum)
2994 3297
2995Feed an event as if the given signal occurred (C<loop> must be the default 3298Feed an event as if the given signal occurred (C<loop> must be the default
2996loop!). 3299loop!).
2997 3300
2998=back 3301=back
3078 3381
3079=over 4 3382=over 4
3080 3383
3081=item ev::TYPE::TYPE () 3384=item ev::TYPE::TYPE ()
3082 3385
3083=item ev::TYPE::TYPE (struct ev_loop *) 3386=item ev::TYPE::TYPE (loop)
3084 3387
3085=item ev::TYPE::~TYPE 3388=item ev::TYPE::~TYPE
3086 3389
3087The constructor (optionally) takes an event loop to associate the watcher 3390The constructor (optionally) takes an event loop to associate the watcher
3088with. If it is omitted, it will use C<EV_DEFAULT>. 3391with. If it is omitted, it will use C<EV_DEFAULT>.
3121 myclass obj; 3424 myclass obj;
3122 ev::io iow; 3425 ev::io iow;
3123 iow.set <myclass, &myclass::io_cb> (&obj); 3426 iow.set <myclass, &myclass::io_cb> (&obj);
3124 3427
3125=item w->set (object *) 3428=item w->set (object *)
3126
3127This is an B<experimental> feature that might go away in a future version.
3128 3429
3129This is a variation of a method callback - leaving out the method to call 3430This is a variation of a method callback - leaving out the method to call
3130will default the method to C<operator ()>, which makes it possible to use 3431will default the method to C<operator ()>, which makes it possible to use
3131functor objects without having to manually specify the C<operator ()> all 3432functor objects without having to manually specify the C<operator ()> all
3132the time. Incidentally, you can then also leave out the template argument 3433the time. Incidentally, you can then also leave out the template argument
3165Example: Use a plain function as callback. 3466Example: Use a plain function as callback.
3166 3467
3167 static void io_cb (ev::io &w, int revents) { } 3468 static void io_cb (ev::io &w, int revents) { }
3168 iow.set <io_cb> (); 3469 iow.set <io_cb> ();
3169 3470
3170=item w->set (struct ev_loop *) 3471=item w->set (loop)
3171 3472
3172Associates a different C<struct ev_loop> with this watcher. You can only 3473Associates a different C<struct ev_loop> with this watcher. You can only
3173do this when the watcher is inactive (and not pending either). 3474do this when the watcher is inactive (and not pending either).
3174 3475
3175=item w->set ([arguments]) 3476=item w->set ([arguments])
3176 3477
3177Basically the same as C<ev_TYPE_set>, with the same arguments. Must be 3478Basically the same as C<ev_TYPE_set>, with the same arguments. Either this
3178called at least once. Unlike the C counterpart, an active watcher gets 3479method or a suitable start method must be called at least once. Unlike the
3179automatically stopped and restarted when reconfiguring it with this 3480C counterpart, an active watcher gets automatically stopped and restarted
3180method. 3481when reconfiguring it with this method.
3181 3482
3182=item w->start () 3483=item w->start ()
3183 3484
3184Starts the watcher. Note that there is no C<loop> argument, as the 3485Starts the watcher. Note that there is no C<loop> argument, as the
3185constructor already stores the event loop. 3486constructor already stores the event loop.
3186 3487
3488=item w->start ([arguments])
3489
3490Instead of calling C<set> and C<start> methods separately, it is often
3491convenient to wrap them in one call. Uses the same type of arguments as
3492the configure C<set> method of the watcher.
3493
3187=item w->stop () 3494=item w->stop ()
3188 3495
3189Stops the watcher if it is active. Again, no C<loop> argument. 3496Stops the watcher if it is active. Again, no C<loop> argument.
3190 3497
3191=item w->again () (C<ev::timer>, C<ev::periodic> only) 3498=item w->again () (C<ev::timer>, C<ev::periodic> only)
3203 3510
3204=back 3511=back
3205 3512
3206=back 3513=back
3207 3514
3208Example: Define a class with an IO and idle watcher, start one of them in 3515Example: Define a class with two I/O and idle watchers, start the I/O
3209the constructor. 3516watchers in the constructor.
3210 3517
3211 class myclass 3518 class myclass
3212 { 3519 {
3213 ev::io io ; void io_cb (ev::io &w, int revents); 3520 ev::io io ; void io_cb (ev::io &w, int revents);
3521 ev::io2 io2 ; void io2_cb (ev::io &w, int revents);
3214 ev::idle idle; void idle_cb (ev::idle &w, int revents); 3522 ev::idle idle; void idle_cb (ev::idle &w, int revents);
3215 3523
3216 myclass (int fd) 3524 myclass (int fd)
3217 { 3525 {
3218 io .set <myclass, &myclass::io_cb > (this); 3526 io .set <myclass, &myclass::io_cb > (this);
3527 io2 .set <myclass, &myclass::io2_cb > (this);
3219 idle.set <myclass, &myclass::idle_cb> (this); 3528 idle.set <myclass, &myclass::idle_cb> (this);
3220 3529
3221 io.start (fd, ev::READ); 3530 io.set (fd, ev::WRITE); // configure the watcher
3531 io.start (); // start it whenever convenient
3532
3533 io2.start (fd, ev::READ); // set + start in one call
3222 } 3534 }
3223 }; 3535 };
3224 3536
3225 3537
3226=head1 OTHER LANGUAGE BINDINGS 3538=head1 OTHER LANGUAGE BINDINGS
3272=item Ocaml 3584=item Ocaml
3273 3585
3274Erkki Seppala has written Ocaml bindings for libev, to be found at 3586Erkki Seppala has written Ocaml bindings for libev, to be found at
3275L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3587L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3276 3588
3589=item Lua
3590
3591Brian Maher has written a partial interface to libev for lua (at the
3592time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3593L<http://github.com/brimworks/lua-ev>.
3594
3277=back 3595=back
3278 3596
3279 3597
3280=head1 MACRO MAGIC 3598=head1 MACRO MAGIC
3281 3599
3294loop argument"). The C<EV_A> form is used when this is the sole argument, 3612loop argument"). The C<EV_A> form is used when this is the sole argument,
3295C<EV_A_> is used when other arguments are following. Example: 3613C<EV_A_> is used when other arguments are following. Example:
3296 3614
3297 ev_unref (EV_A); 3615 ev_unref (EV_A);
3298 ev_timer_add (EV_A_ watcher); 3616 ev_timer_add (EV_A_ watcher);
3299 ev_loop (EV_A_ 0); 3617 ev_run (EV_A_ 0);
3300 3618
3301It assumes the variable C<loop> of type C<struct ev_loop *> is in scope, 3619It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
3302which is often provided by the following macro. 3620which is often provided by the following macro.
3303 3621
3304=item C<EV_P>, C<EV_P_> 3622=item C<EV_P>, C<EV_P_>
3344 } 3662 }
3345 3663
3346 ev_check check; 3664 ev_check check;
3347 ev_check_init (&check, check_cb); 3665 ev_check_init (&check, check_cb);
3348 ev_check_start (EV_DEFAULT_ &check); 3666 ev_check_start (EV_DEFAULT_ &check);
3349 ev_loop (EV_DEFAULT_ 0); 3667 ev_run (EV_DEFAULT_ 0);
3350 3668
3351=head1 EMBEDDING 3669=head1 EMBEDDING
3352 3670
3353Libev can (and often is) directly embedded into host 3671Libev can (and often is) directly embedded into host
3354applications. Examples of applications that embed it include the Deliantra 3672applications. Examples of applications that embed it include the Deliantra
3434 libev.m4 3752 libev.m4
3435 3753
3436=head2 PREPROCESSOR SYMBOLS/MACROS 3754=head2 PREPROCESSOR SYMBOLS/MACROS
3437 3755
3438Libev can be configured via a variety of preprocessor symbols you have to 3756Libev can be configured via a variety of preprocessor symbols you have to
3439define before including any of its files. The default in the absence of 3757define before including (or compiling) any of its files. The default in
3440autoconf is documented for every option. 3758the absence of autoconf is documented for every option.
3759
3760Symbols marked with "(h)" do not change the ABI, and can have different
3761values when compiling libev vs. including F<ev.h>, so it is permissible
3762to redefine them before including F<ev.h> without breaking compatibility
3763to a compiled library. All other symbols change the ABI, which means all
3764users of libev and the libev code itself must be compiled with compatible
3765settings.
3441 3766
3442=over 4 3767=over 4
3443 3768
3769=item EV_COMPAT3 (h)
3770
3771Backwards compatibility is a major concern for libev. This is why this
3772release of libev comes with wrappers for the functions and symbols that
3773have been renamed between libev version 3 and 4.
3774
3775You can disable these wrappers (to test compatibility with future
3776versions) by defining C<EV_COMPAT3> to C<0> when compiling your
3777sources. This has the additional advantage that you can drop the C<struct>
3778from C<struct ev_loop> declarations, as libev will provide an C<ev_loop>
3779typedef in that case.
3780
3781In some future version, the default for C<EV_COMPAT3> will become C<0>,
3782and in some even more future version the compatibility code will be
3783removed completely.
3784
3444=item EV_STANDALONE 3785=item EV_STANDALONE (h)
3445 3786
3446Must always be C<1> if you do not use autoconf configuration, which 3787Must always be C<1> if you do not use autoconf configuration, which
3447keeps libev from including F<config.h>, and it also defines dummy 3788keeps libev from including F<config.h>, and it also defines dummy
3448implementations for some libevent functions (such as logging, which is not 3789implementations for some libevent functions (such as logging, which is not
3449supported). It will also not define any of the structs usually found in 3790supported). It will also not define any of the structs usually found in
3450F<event.h> that are not directly supported by the libev core alone. 3791F<event.h> that are not directly supported by the libev core alone.
3451 3792
3452In stanbdalone mode, libev will still try to automatically deduce the 3793In standalone mode, libev will still try to automatically deduce the
3453configuration, but has to be more conservative. 3794configuration, but has to be more conservative.
3454 3795
3455=item EV_USE_MONOTONIC 3796=item EV_USE_MONOTONIC
3456 3797
3457If defined to be C<1>, libev will try to detect the availability of the 3798If defined to be C<1>, libev will try to detect the availability of the
3522be used is the winsock select). This means that it will call 3863be used is the winsock select). This means that it will call
3523C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3864C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3524it is assumed that all these functions actually work on fds, even 3865it is assumed that all these functions actually work on fds, even
3525on win32. Should not be defined on non-win32 platforms. 3866on win32. Should not be defined on non-win32 platforms.
3526 3867
3527=item EV_FD_TO_WIN32_HANDLE 3868=item EV_FD_TO_WIN32_HANDLE(fd)
3528 3869
3529If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3870If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3530file descriptors to socket handles. When not defining this symbol (the 3871file descriptors to socket handles. When not defining this symbol (the
3531default), then libev will call C<_get_osfhandle>, which is usually 3872default), then libev will call C<_get_osfhandle>, which is usually
3532correct. In some cases, programs use their own file descriptor management, 3873correct. In some cases, programs use their own file descriptor management,
3533in which case they can provide this function to map fds to socket handles. 3874in which case they can provide this function to map fds to socket handles.
3875
3876=item EV_WIN32_HANDLE_TO_FD(handle)
3877
3878If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3879using the standard C<_open_osfhandle> function. For programs implementing
3880their own fd to handle mapping, overwriting this function makes it easier
3881to do so. This can be done by defining this macro to an appropriate value.
3882
3883=item EV_WIN32_CLOSE_FD(fd)
3884
3885If programs implement their own fd to handle mapping on win32, then this
3886macro can be used to override the C<close> function, useful to unregister
3887file descriptors again. Note that the replacement function has to close
3888the underlying OS handle.
3534 3889
3535=item EV_USE_POLL 3890=item EV_USE_POLL
3536 3891
3537If defined to be C<1>, libev will compile in support for the C<poll>(2) 3892If defined to be C<1>, libev will compile in support for the C<poll>(2)
3538backend. Otherwise it will be enabled on non-win32 platforms. It 3893backend. Otherwise it will be enabled on non-win32 platforms. It
3585as well as for signal and thread safety in C<ev_async> watchers. 3940as well as for signal and thread safety in C<ev_async> watchers.
3586 3941
3587In the absence of this define, libev will use C<sig_atomic_t volatile> 3942In the absence of this define, libev will use C<sig_atomic_t volatile>
3588(from F<signal.h>), which is usually good enough on most platforms. 3943(from F<signal.h>), which is usually good enough on most platforms.
3589 3944
3590=item EV_H 3945=item EV_H (h)
3591 3946
3592The name of the F<ev.h> header file used to include it. The default if 3947The name of the F<ev.h> header file used to include it. The default if
3593undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 3948undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3594used to virtually rename the F<ev.h> header file in case of conflicts. 3949used to virtually rename the F<ev.h> header file in case of conflicts.
3595 3950
3596=item EV_CONFIG_H 3951=item EV_CONFIG_H (h)
3597 3952
3598If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3953If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3599F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3954F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3600C<EV_H>, above. 3955C<EV_H>, above.
3601 3956
3602=item EV_EVENT_H 3957=item EV_EVENT_H (h)
3603 3958
3604Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3959Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3605of how the F<event.h> header can be found, the default is C<"event.h">. 3960of how the F<event.h> header can be found, the default is C<"event.h">.
3606 3961
3607=item EV_PROTOTYPES 3962=item EV_PROTOTYPES (h)
3608 3963
3609If defined to be C<0>, then F<ev.h> will not define any function 3964If defined to be C<0>, then F<ev.h> will not define any function
3610prototypes, but still define all the structs and other symbols. This is 3965prototypes, but still define all the structs and other symbols. This is
3611occasionally useful if you want to provide your own wrapper functions 3966occasionally useful if you want to provide your own wrapper functions
3612around libev functions. 3967around libev functions.
3634fine. 3989fine.
3635 3990
3636If your embedding application does not need any priorities, defining these 3991If your embedding application does not need any priorities, defining these
3637both to C<0> will save some memory and CPU. 3992both to C<0> will save some memory and CPU.
3638 3993
3639=item EV_PERIODIC_ENABLE 3994=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3995EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3996EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3640 3997
3641If undefined or defined to be C<1>, then periodic timers are supported. If 3998If undefined or defined to be C<1> (and the platform supports it), then
3642defined to be C<0>, then they are not. Disabling them saves a few kB of 3999the respective watcher type is supported. If defined to be C<0>, then it
3643code. 4000is not. Disabling watcher types mainly saves code size.
3644 4001
3645=item EV_IDLE_ENABLE 4002=item EV_FEATURES
3646
3647If undefined or defined to be C<1>, then idle watchers are supported. If
3648defined to be C<0>, then they are not. Disabling them saves a few kB of
3649code.
3650
3651=item EV_EMBED_ENABLE
3652
3653If undefined or defined to be C<1>, then embed watchers are supported. If
3654defined to be C<0>, then they are not. Embed watchers rely on most other
3655watcher types, which therefore must not be disabled.
3656
3657=item EV_STAT_ENABLE
3658
3659If undefined or defined to be C<1>, then stat watchers are supported. If
3660defined to be C<0>, then they are not.
3661
3662=item EV_FORK_ENABLE
3663
3664If undefined or defined to be C<1>, then fork watchers are supported. If
3665defined to be C<0>, then they are not.
3666
3667=item EV_ASYNC_ENABLE
3668
3669If undefined or defined to be C<1>, then async watchers are supported. If
3670defined to be C<0>, then they are not.
3671
3672=item EV_MINIMAL
3673 4003
3674If you need to shave off some kilobytes of code at the expense of some 4004If you need to shave off some kilobytes of code at the expense of some
3675speed, define this symbol to C<1>. Currently this is used to override some 4005speed (but with the full API), you can define this symbol to request
3676inlining decisions, saves roughly 30% code size on amd64. It also selects a 4006certain subsets of functionality. The default is to enable all features
3677much smaller 2-heap for timer management over the default 4-heap. 4007that can be enabled on the platform.
4008
4009A typical way to use this symbol is to define it to C<0> (or to a bitset
4010with some broad features you want) and then selectively re-enable
4011additional parts you want, for example if you want everything minimal,
4012but multiple event loop support, async and child watchers and the poll
4013backend, use this:
4014
4015 #define EV_FEATURES 0
4016 #define EV_MULTIPLICITY 1
4017 #define EV_USE_POLL 1
4018 #define EV_CHILD_ENABLE 1
4019 #define EV_ASYNC_ENABLE 1
4020
4021The actual value is a bitset, it can be a combination of the following
4022values:
4023
4024=over 4
4025
4026=item C<1> - faster/larger code
4027
4028Use larger code to speed up some operations.
4029
4030Currently this is used to override some inlining decisions (enlarging the
4031code size by roughly 30% on amd64).
4032
4033When optimising for size, use of compiler flags such as C<-Os> with
4034gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
4035assertions.
4036
4037=item C<2> - faster/larger data structures
4038
4039Replaces the small 2-heap for timer management by a faster 4-heap, larger
4040hash table sizes and so on. This will usually further increase code size
4041and can additionally have an effect on the size of data structures at
4042runtime.
4043
4044=item C<4> - full API configuration
4045
4046This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
4047enables multiplicity (C<EV_MULTIPLICITY>=1).
4048
4049=item C<8> - full API
4050
4051This enables a lot of the "lesser used" API functions. See C<ev.h> for
4052details on which parts of the API are still available without this
4053feature, and do not complain if this subset changes over time.
4054
4055=item C<16> - enable all optional watcher types
4056
4057Enables all optional watcher types. If you want to selectively enable
4058only some watcher types other than I/O and timers (e.g. prepare,
4059embed, async, child...) you can enable them manually by defining
4060C<EV_watchertype_ENABLE> to C<1> instead.
4061
4062=item C<32> - enable all backends
4063
4064This enables all backends - without this feature, you need to enable at
4065least one backend manually (C<EV_USE_SELECT> is a good choice).
4066
4067=item C<64> - enable OS-specific "helper" APIs
4068
4069Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
4070default.
4071
4072=back
4073
4074Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
4075reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
4076code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
4077watchers, timers and monotonic clock support.
4078
4079With an intelligent-enough linker (gcc+binutils are intelligent enough
4080when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
4081your program might be left out as well - a binary starting a timer and an
4082I/O watcher then might come out at only 5Kb.
4083
4084=item EV_AVOID_STDIO
4085
4086If this is set to C<1> at compiletime, then libev will avoid using stdio
4087functions (printf, scanf, perror etc.). This will increase the code size
4088somewhat, but if your program doesn't otherwise depend on stdio and your
4089libc allows it, this avoids linking in the stdio library which is quite
4090big.
4091
4092Note that error messages might become less precise when this option is
4093enabled.
4094
4095=item EV_NSIG
4096
4097The highest supported signal number, +1 (or, the number of
4098signals): Normally, libev tries to deduce the maximum number of signals
4099automatically, but sometimes this fails, in which case it can be
4100specified. Also, using a lower number than detected (C<32> should be
4101good for about any system in existence) can save some memory, as libev
4102statically allocates some 12-24 bytes per signal number.
3678 4103
3679=item EV_PID_HASHSIZE 4104=item EV_PID_HASHSIZE
3680 4105
3681C<ev_child> watchers use a small hash table to distribute workload by 4106C<ev_child> watchers use a small hash table to distribute workload by
3682pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 4107pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3683than enough. If you need to manage thousands of children you might want to 4108usually more than enough. If you need to manage thousands of children you
3684increase this value (I<must> be a power of two). 4109might want to increase this value (I<must> be a power of two).
3685 4110
3686=item EV_INOTIFY_HASHSIZE 4111=item EV_INOTIFY_HASHSIZE
3687 4112
3688C<ev_stat> watchers use a small hash table to distribute workload by 4113C<ev_stat> watchers use a small hash table to distribute workload by
3689inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4114inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3690usually more than enough. If you need to manage thousands of C<ev_stat> 4115disabled), usually more than enough. If you need to manage thousands of
3691watchers you might want to increase this value (I<must> be a power of 4116C<ev_stat> watchers you might want to increase this value (I<must> be a
3692two). 4117power of two).
3693 4118
3694=item EV_USE_4HEAP 4119=item EV_USE_4HEAP
3695 4120
3696Heaps are not very cache-efficient. To improve the cache-efficiency of the 4121Heaps are not very cache-efficient. To improve the cache-efficiency of the
3697timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4122timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3698to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4123to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3699faster performance with many (thousands) of watchers. 4124faster performance with many (thousands) of watchers.
3700 4125
3701The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4126The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3702(disabled). 4127will be C<0>.
3703 4128
3704=item EV_HEAP_CACHE_AT 4129=item EV_HEAP_CACHE_AT
3705 4130
3706Heaps are not very cache-efficient. To improve the cache-efficiency of the 4131Heaps are not very cache-efficient. To improve the cache-efficiency of the
3707timer and periodics heaps, libev can cache the timestamp (I<at>) within 4132timer and periodics heaps, libev can cache the timestamp (I<at>) within
3708the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4133the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3709which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4134which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3710but avoids random read accesses on heap changes. This improves performance 4135but avoids random read accesses on heap changes. This improves performance
3711noticeably with many (hundreds) of watchers. 4136noticeably with many (hundreds) of watchers.
3712 4137
3713The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4138The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3714(disabled). 4139will be C<0>.
3715 4140
3716=item EV_VERIFY 4141=item EV_VERIFY
3717 4142
3718Controls how much internal verification (see C<ev_loop_verify ()>) will 4143Controls how much internal verification (see C<ev_verify ()>) will
3719be done: If set to C<0>, no internal verification code will be compiled 4144be done: If set to C<0>, no internal verification code will be compiled
3720in. If set to C<1>, then verification code will be compiled in, but not 4145in. If set to C<1>, then verification code will be compiled in, but not
3721called. If set to C<2>, then the internal verification code will be 4146called. If set to C<2>, then the internal verification code will be
3722called once per loop, which can slow down libev. If set to C<3>, then the 4147called once per loop, which can slow down libev. If set to C<3>, then the
3723verification code will be called very frequently, which will slow down 4148verification code will be called very frequently, which will slow down
3724libev considerably. 4149libev considerably.
3725 4150
3726The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4151The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3727C<0>. 4152will be C<0>.
3728 4153
3729=item EV_COMMON 4154=item EV_COMMON
3730 4155
3731By default, all watchers have a C<void *data> member. By redefining 4156By default, all watchers have a C<void *data> member. By redefining
3732this macro to a something else you can include more and other types of 4157this macro to something else you can include more and other types of
3733members. You have to define it each time you include one of the files, 4158members. You have to define it each time you include one of the files,
3734though, and it must be identical each time. 4159though, and it must be identical each time.
3735 4160
3736For example, the perl EV module uses something like this: 4161For example, the perl EV module uses something like this:
3737 4162
3790file. 4215file.
3791 4216
3792The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4217The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3793that everybody includes and which overrides some configure choices: 4218that everybody includes and which overrides some configure choices:
3794 4219
3795 #define EV_MINIMAL 1 4220 #define EV_FEATURES 8
3796 #define EV_USE_POLL 0 4221 #define EV_USE_SELECT 1
3797 #define EV_MULTIPLICITY 0
3798 #define EV_PERIODIC_ENABLE 0 4222 #define EV_PREPARE_ENABLE 1
4223 #define EV_IDLE_ENABLE 1
3799 #define EV_STAT_ENABLE 0 4224 #define EV_SIGNAL_ENABLE 1
3800 #define EV_FORK_ENABLE 0 4225 #define EV_CHILD_ENABLE 1
4226 #define EV_USE_STDEXCEPT 0
3801 #define EV_CONFIG_H <config.h> 4227 #define EV_CONFIG_H <config.h>
3802 #define EV_MINPRI 0
3803 #define EV_MAXPRI 0
3804 4228
3805 #include "ev++.h" 4229 #include "ev++.h"
3806 4230
3807And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4231And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3808 4232
3868default loop and triggering an C<ev_async> watcher from the default loop 4292default loop and triggering an C<ev_async> watcher from the default loop
3869watcher callback into the event loop interested in the signal. 4293watcher callback into the event loop interested in the signal.
3870 4294
3871=back 4295=back
3872 4296
4297=head4 THREAD LOCKING EXAMPLE
4298
4299Here is a fictitious example of how to run an event loop in a different
4300thread than where callbacks are being invoked and watchers are
4301created/added/removed.
4302
4303For a real-world example, see the C<EV::Loop::Async> perl module,
4304which uses exactly this technique (which is suited for many high-level
4305languages).
4306
4307The example uses a pthread mutex to protect the loop data, a condition
4308variable to wait for callback invocations, an async watcher to notify the
4309event loop thread and an unspecified mechanism to wake up the main thread.
4310
4311First, you need to associate some data with the event loop:
4312
4313 typedef struct {
4314 mutex_t lock; /* global loop lock */
4315 ev_async async_w;
4316 thread_t tid;
4317 cond_t invoke_cv;
4318 } userdata;
4319
4320 void prepare_loop (EV_P)
4321 {
4322 // for simplicity, we use a static userdata struct.
4323 static userdata u;
4324
4325 ev_async_init (&u->async_w, async_cb);
4326 ev_async_start (EV_A_ &u->async_w);
4327
4328 pthread_mutex_init (&u->lock, 0);
4329 pthread_cond_init (&u->invoke_cv, 0);
4330
4331 // now associate this with the loop
4332 ev_set_userdata (EV_A_ u);
4333 ev_set_invoke_pending_cb (EV_A_ l_invoke);
4334 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4335
4336 // then create the thread running ev_loop
4337 pthread_create (&u->tid, 0, l_run, EV_A);
4338 }
4339
4340The callback for the C<ev_async> watcher does nothing: the watcher is used
4341solely to wake up the event loop so it takes notice of any new watchers
4342that might have been added:
4343
4344 static void
4345 async_cb (EV_P_ ev_async *w, int revents)
4346 {
4347 // just used for the side effects
4348 }
4349
4350The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4351protecting the loop data, respectively.
4352
4353 static void
4354 l_release (EV_P)
4355 {
4356 userdata *u = ev_userdata (EV_A);
4357 pthread_mutex_unlock (&u->lock);
4358 }
4359
4360 static void
4361 l_acquire (EV_P)
4362 {
4363 userdata *u = ev_userdata (EV_A);
4364 pthread_mutex_lock (&u->lock);
4365 }
4366
4367The event loop thread first acquires the mutex, and then jumps straight
4368into C<ev_run>:
4369
4370 void *
4371 l_run (void *thr_arg)
4372 {
4373 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4374
4375 l_acquire (EV_A);
4376 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4377 ev_run (EV_A_ 0);
4378 l_release (EV_A);
4379
4380 return 0;
4381 }
4382
4383Instead of invoking all pending watchers, the C<l_invoke> callback will
4384signal the main thread via some unspecified mechanism (signals? pipe
4385writes? C<Async::Interrupt>?) and then waits until all pending watchers
4386have been called (in a while loop because a) spurious wakeups are possible
4387and b) skipping inter-thread-communication when there are no pending
4388watchers is very beneficial):
4389
4390 static void
4391 l_invoke (EV_P)
4392 {
4393 userdata *u = ev_userdata (EV_A);
4394
4395 while (ev_pending_count (EV_A))
4396 {
4397 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4398 pthread_cond_wait (&u->invoke_cv, &u->lock);
4399 }
4400 }
4401
4402Now, whenever the main thread gets told to invoke pending watchers, it
4403will grab the lock, call C<ev_invoke_pending> and then signal the loop
4404thread to continue:
4405
4406 static void
4407 real_invoke_pending (EV_P)
4408 {
4409 userdata *u = ev_userdata (EV_A);
4410
4411 pthread_mutex_lock (&u->lock);
4412 ev_invoke_pending (EV_A);
4413 pthread_cond_signal (&u->invoke_cv);
4414 pthread_mutex_unlock (&u->lock);
4415 }
4416
4417Whenever you want to start/stop a watcher or do other modifications to an
4418event loop, you will now have to lock:
4419
4420 ev_timer timeout_watcher;
4421 userdata *u = ev_userdata (EV_A);
4422
4423 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4424
4425 pthread_mutex_lock (&u->lock);
4426 ev_timer_start (EV_A_ &timeout_watcher);
4427 ev_async_send (EV_A_ &u->async_w);
4428 pthread_mutex_unlock (&u->lock);
4429
4430Note that sending the C<ev_async> watcher is required because otherwise
4431an event loop currently blocking in the kernel will have no knowledge
4432about the newly added timer. By waking up the loop it will pick up any new
4433watchers in the next event loop iteration.
4434
3873=head3 COROUTINES 4435=head3 COROUTINES
3874 4436
3875Libev is very accommodating to coroutines ("cooperative threads"): 4437Libev is very accommodating to coroutines ("cooperative threads"):
3876libev fully supports nesting calls to its functions from different 4438libev fully supports nesting calls to its functions from different
3877coroutines (e.g. you can call C<ev_loop> on the same loop from two 4439coroutines (e.g. you can call C<ev_run> on the same loop from two
3878different coroutines, and switch freely between both coroutines running the 4440different coroutines, and switch freely between both coroutines running
3879loop, as long as you don't confuse yourself). The only exception is that 4441the loop, as long as you don't confuse yourself). The only exception is
3880you must not do this from C<ev_periodic> reschedule callbacks. 4442that you must not do this from C<ev_periodic> reschedule callbacks.
3881 4443
3882Care has been taken to ensure that libev does not keep local state inside 4444Care has been taken to ensure that libev does not keep local state inside
3883C<ev_loop>, and other calls do not usually allow for coroutine switches as 4445C<ev_run>, and other calls do not usually allow for coroutine switches as
3884they do not call any callbacks. 4446they do not call any callbacks.
3885 4447
3886=head2 COMPILER WARNINGS 4448=head2 COMPILER WARNINGS
3887 4449
3888Depending on your compiler and compiler settings, you might get no or a 4450Depending on your compiler and compiler settings, you might get no or a
3899maintainable. 4461maintainable.
3900 4462
3901And of course, some compiler warnings are just plain stupid, or simply 4463And of course, some compiler warnings are just plain stupid, or simply
3902wrong (because they don't actually warn about the condition their message 4464wrong (because they don't actually warn about the condition their message
3903seems to warn about). For example, certain older gcc versions had some 4465seems to warn about). For example, certain older gcc versions had some
3904warnings that resulted an extreme number of false positives. These have 4466warnings that resulted in an extreme number of false positives. These have
3905been fixed, but some people still insist on making code warn-free with 4467been fixed, but some people still insist on making code warn-free with
3906such buggy versions. 4468such buggy versions.
3907 4469
3908While libev is written to generate as few warnings as possible, 4470While libev is written to generate as few warnings as possible,
3909"warn-free" code is not a goal, and it is recommended not to build libev 4471"warn-free" code is not a goal, and it is recommended not to build libev
3945I suggest using suppression lists. 4507I suggest using suppression lists.
3946 4508
3947 4509
3948=head1 PORTABILITY NOTES 4510=head1 PORTABILITY NOTES
3949 4511
4512=head2 GNU/LINUX 32 BIT LIMITATIONS
4513
4514GNU/Linux is the only common platform that supports 64 bit file/large file
4515interfaces but I<disables> them by default.
4516
4517That means that libev compiled in the default environment doesn't support
4518files larger than 2GiB or so, which mainly affects C<ev_stat> watchers.
4519
4520Unfortunately, many programs try to work around this GNU/Linux issue
4521by enabling the large file API, which makes them incompatible with the
4522standard libev compiled for their system.
4523
4524Likewise, libev cannot enable the large file API itself as this would
4525suddenly make it incompatible to the default compile time environment,
4526i.e. all programs not using special compile switches.
4527
4528=head2 OS/X AND DARWIN BUGS
4529
4530The whole thing is a bug if you ask me - basically any system interface
4531you touch is broken, whether it is locales, poll, kqueue or even the
4532OpenGL drivers.
4533
4534=head3 C<kqueue> is buggy
4535
4536The kqueue syscall is broken in all known versions - most versions support
4537only sockets, many support pipes.
4538
4539Libev tries to work around this by not using C<kqueue> by default on this
4540rotten platform, but of course you can still ask for it when creating a
4541loop - embedding a socket-only kqueue loop into a select-based one is
4542probably going to work well.
4543
4544=head3 C<poll> is buggy
4545
4546Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
4547implementation by something calling C<kqueue> internally around the 10.5.6
4548release, so now C<kqueue> I<and> C<poll> are broken.
4549
4550Libev tries to work around this by not using C<poll> by default on
4551this rotten platform, but of course you can still ask for it when creating
4552a loop.
4553
4554=head3 C<select> is buggy
4555
4556All that's left is C<select>, and of course Apple found a way to fuck this
4557one up as well: On OS/X, C<select> actively limits the number of file
4558descriptors you can pass in to 1024 - your program suddenly crashes when
4559you use more.
4560
4561There is an undocumented "workaround" for this - defining
4562C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
4563work on OS/X.
4564
4565=head2 SOLARIS PROBLEMS AND WORKAROUNDS
4566
4567=head3 C<errno> reentrancy
4568
4569The default compile environment on Solaris is unfortunately so
4570thread-unsafe that you can't even use components/libraries compiled
4571without C<-D_REENTRANT> in a threaded program, which, of course, isn't
4572defined by default. A valid, if stupid, implementation choice.
4573
4574If you want to use libev in threaded environments you have to make sure
4575it's compiled with C<_REENTRANT> defined.
4576
4577=head3 Event port backend
4578
4579The scalable event interface for Solaris is called "event
4580ports". Unfortunately, this mechanism is very buggy in all major
4581releases. If you run into high CPU usage, your program freezes or you get
4582a large number of spurious wakeups, make sure you have all the relevant
4583and latest kernel patches applied. No, I don't know which ones, but there
4584are multiple ones to apply, and afterwards, event ports actually work
4585great.
4586
4587If you can't get it to work, you can try running the program by setting
4588the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and
4589C<select> backends.
4590
4591=head2 AIX POLL BUG
4592
4593AIX unfortunately has a broken C<poll.h> header. Libev works around
4594this by trying to avoid the poll backend altogether (i.e. it's not even
4595compiled in), which normally isn't a big problem as C<select> works fine
4596with large bitsets on AIX, and AIX is dead anyway.
4597
3950=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 4598=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
4599
4600=head3 General issues
3951 4601
3952Win32 doesn't support any of the standards (e.g. POSIX) that libev 4602Win32 doesn't support any of the standards (e.g. POSIX) that libev
3953requires, and its I/O model is fundamentally incompatible with the POSIX 4603requires, and its I/O model is fundamentally incompatible with the POSIX
3954model. Libev still offers limited functionality on this platform in 4604model. Libev still offers limited functionality on this platform in
3955the form of the C<EVBACKEND_SELECT> backend, and only supports socket 4605the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3956descriptors. This only applies when using Win32 natively, not when using 4606descriptors. This only applies when using Win32 natively, not when using
3957e.g. cygwin. 4607e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4608as every compielr comes with a slightly differently broken/incompatible
4609environment.
3958 4610
3959Lifting these limitations would basically require the full 4611Lifting these limitations would basically require the full
3960re-implementation of the I/O system. If you are into these kinds of 4612re-implementation of the I/O system. If you are into this kind of thing,
3961things, then note that glib does exactly that for you in a very portable 4613then note that glib does exactly that for you in a very portable way (note
3962way (note also that glib is the slowest event library known to man). 4614also that glib is the slowest event library known to man).
3963 4615
3964There is no supported compilation method available on windows except 4616There is no supported compilation method available on windows except
3965embedding it into other applications. 4617embedding it into other applications.
3966 4618
3967Sensible signal handling is officially unsupported by Microsoft - libev 4619Sensible signal handling is officially unsupported by Microsoft - libev
3995you do I<not> compile the F<ev.c> or any other embedded source files!): 4647you do I<not> compile the F<ev.c> or any other embedded source files!):
3996 4648
3997 #include "evwrap.h" 4649 #include "evwrap.h"
3998 #include "ev.c" 4650 #include "ev.c"
3999 4651
4000=over 4
4001
4002=item The winsocket select function 4652=head3 The winsocket C<select> function
4003 4653
4004The winsocket C<select> function doesn't follow POSIX in that it 4654The winsocket C<select> function doesn't follow POSIX in that it
4005requires socket I<handles> and not socket I<file descriptors> (it is 4655requires socket I<handles> and not socket I<file descriptors> (it is
4006also extremely buggy). This makes select very inefficient, and also 4656also extremely buggy). This makes select very inefficient, and also
4007requires a mapping from file descriptors to socket handles (the Microsoft 4657requires a mapping from file descriptors to socket handles (the Microsoft
4016 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 4666 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
4017 4667
4018Note that winsockets handling of fd sets is O(n), so you can easily get a 4668Note that winsockets handling of fd sets is O(n), so you can easily get a
4019complexity in the O(n²) range when using win32. 4669complexity in the O(n²) range when using win32.
4020 4670
4021=item Limited number of file descriptors 4671=head3 Limited number of file descriptors
4022 4672
4023Windows has numerous arbitrary (and low) limits on things. 4673Windows has numerous arbitrary (and low) limits on things.
4024 4674
4025Early versions of winsocket's select only supported waiting for a maximum 4675Early versions of winsocket's select only supported waiting for a maximum
4026of C<64> handles (probably owning to the fact that all windows kernels 4676of C<64> handles (probably owning to the fact that all windows kernels
4041runtime libraries. This might get you to about C<512> or C<2048> sockets 4691runtime libraries. This might get you to about C<512> or C<2048> sockets
4042(depending on windows version and/or the phase of the moon). To get more, 4692(depending on windows version and/or the phase of the moon). To get more,
4043you need to wrap all I/O functions and provide your own fd management, but 4693you need to wrap all I/O functions and provide your own fd management, but
4044the cost of calling select (O(n²)) will likely make this unworkable. 4694the cost of calling select (O(n²)) will likely make this unworkable.
4045 4695
4046=back
4047
4048=head2 PORTABILITY REQUIREMENTS 4696=head2 PORTABILITY REQUIREMENTS
4049 4697
4050In addition to a working ISO-C implementation and of course the 4698In addition to a working ISO-C implementation and of course the
4051backend-specific APIs, libev relies on a few additional extensions: 4699backend-specific APIs, libev relies on a few additional extensions:
4052 4700
4090watchers. 4738watchers.
4091 4739
4092=item C<double> must hold a time value in seconds with enough accuracy 4740=item C<double> must hold a time value in seconds with enough accuracy
4093 4741
4094The type C<double> is used to represent timestamps. It is required to 4742The type C<double> is used to represent timestamps. It is required to
4095have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4743have at least 51 bits of mantissa (and 9 bits of exponent), which is
4096enough for at least into the year 4000. This requirement is fulfilled by 4744good enough for at least into the year 4000 with millisecond accuracy
4745(the design goal for libev). This requirement is overfulfilled by
4097implementations implementing IEEE 754, which is basically all existing 4746implementations using IEEE 754, which is basically all existing ones. With
4098ones. With IEEE 754 doubles, you get microsecond accuracy until at least 4747IEEE 754 doubles, you get microsecond accuracy until at least 2200.
40992200.
4100 4748
4101=back 4749=back
4102 4750
4103If you know of other additional requirements drop me a note. 4751If you know of other additional requirements drop me a note.
4104 4752
4172involves iterating over all running async watchers or all signal numbers. 4820involves iterating over all running async watchers or all signal numbers.
4173 4821
4174=back 4822=back
4175 4823
4176 4824
4825=head1 PORTING FROM LIBEV 3.X TO 4.X
4826
4827The major version 4 introduced some minor incompatible changes to the API.
4828
4829At the moment, the C<ev.h> header file tries to implement superficial
4830compatibility, so most programs should still compile. Those might be
4831removed in later versions of libev, so better update early than late.
4832
4833=over 4
4834
4835=item function/symbol renames
4836
4837A number of functions and symbols have been renamed:
4838
4839 ev_loop => ev_run
4840 EVLOOP_NONBLOCK => EVRUN_NOWAIT
4841 EVLOOP_ONESHOT => EVRUN_ONCE
4842
4843 ev_unloop => ev_break
4844 EVUNLOOP_CANCEL => EVBREAK_CANCEL
4845 EVUNLOOP_ONE => EVBREAK_ONE
4846 EVUNLOOP_ALL => EVBREAK_ALL
4847
4848 EV_TIMEOUT => EV_TIMER
4849
4850 ev_loop_count => ev_iteration
4851 ev_loop_depth => ev_depth
4852 ev_loop_verify => ev_verify
4853
4854Most functions working on C<struct ev_loop> objects don't have an
4855C<ev_loop_> prefix, so it was removed; C<ev_loop>, C<ev_unloop> and
4856associated constants have been renamed to not collide with the C<struct
4857ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme
4858as all other watcher types. Note that C<ev_loop_fork> is still called
4859C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
4860typedef.
4861
4862=item C<EV_COMPAT3> backwards compatibility mechanism
4863
4864The backward compatibility mechanism can be controlled by
4865C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
4866section.
4867
4868=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4869
4870The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4871mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4872and work, but the library code will of course be larger.
4873
4874=back
4875
4876
4177=head1 GLOSSARY 4877=head1 GLOSSARY
4178 4878
4179=over 4 4879=over 4
4180 4880
4181=item active 4881=item active
4182 4882
4183A watcher is active as long as it has been started (has been attached to 4883A watcher is active as long as it has been started and not yet stopped.
4184an event loop) but not yet stopped (disassociated from the event loop). 4884See L<WATCHER STATES> for details.
4185 4885
4186=item application 4886=item application
4187 4887
4188In this document, an application is whatever is using libev. 4888In this document, an application is whatever is using libev.
4889
4890=item backend
4891
4892The part of the code dealing with the operating system interfaces.
4189 4893
4190=item callback 4894=item callback
4191 4895
4192The address of a function that is called when some event has been 4896The address of a function that is called when some event has been
4193detected. Callbacks are being passed the event loop, the watcher that 4897detected. Callbacks are being passed the event loop, the watcher that
4194received the event, and the actual event bitset. 4898received the event, and the actual event bitset.
4195 4899
4196=item callback invocation 4900=item callback/watcher invocation
4197 4901
4198The act of calling the callback associated with a watcher. 4902The act of calling the callback associated with a watcher.
4199 4903
4200=item event 4904=item event
4201 4905
4202A change of state of some external event, such as data now being available 4906A change of state of some external event, such as data now being available
4203for reading on a file descriptor, time having passed or simply not having 4907for reading on a file descriptor, time having passed or simply not having
4204any other events happening anymore. 4908any other events happening anymore.
4205 4909
4206In libev, events are represented as single bits (such as C<EV_READ> or 4910In libev, events are represented as single bits (such as C<EV_READ> or
4207C<EV_TIMEOUT>). 4911C<EV_TIMER>).
4208 4912
4209=item event library 4913=item event library
4210 4914
4211A software package implementing an event model and loop. 4915A software package implementing an event model and loop.
4212 4916
4220The model used to describe how an event loop handles and processes 4924The model used to describe how an event loop handles and processes
4221watchers and events. 4925watchers and events.
4222 4926
4223=item pending 4927=item pending
4224 4928
4225A watcher is pending as soon as the corresponding event has been detected, 4929A watcher is pending as soon as the corresponding event has been
4226and stops being pending as soon as the watcher will be invoked or its 4930detected. See L<WATCHER STATES> for details.
4227pending status is explicitly cleared by the application.
4228
4229A watcher can be pending, but not active. Stopping a watcher also clears
4230its pending status.
4231 4931
4232=item real time 4932=item real time
4233 4933
4234The physical time that is observed. It is apparently strictly monotonic :) 4934The physical time that is observed. It is apparently strictly monotonic :)
4235 4935
4242=item watcher 4942=item watcher
4243 4943
4244A data structure that describes interest in certain events. Watchers need 4944A data structure that describes interest in certain events. Watchers need
4245to be started (attached to an event loop) before they can receive events. 4945to be started (attached to an event loop) before they can receive events.
4246 4946
4247=item watcher invocation
4248
4249The act of calling the callback associated with a watcher.
4250
4251=back 4947=back
4252 4948
4253=head1 AUTHOR 4949=head1 AUTHOR
4254 4950
4255Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 4951Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines