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

Comparing libev/ev.pod (file contents):
Revision 1.262 by root, Sat Jul 25 10:14:34 2009 UTC vs.
Revision 1.337 by root, Sun Oct 31 20:20:20 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 {
47 // use the default event loop unless you have special needs 47 // use the default event loop unless you have special needs
48 struct ev_loop *loop = ev_default_loop (0); 48 struct ev_loop *loop = EV_DEFAULT;
49 49
50 // initialise an io watcher, then start it 50 // initialise an io watcher, then start it
51 // this one will watch for stdin to become readable 51 // this one will watch for stdin to become readable
52 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 52 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
53 ev_io_start (loop, &stdin_watcher); 53 ev_io_start (loop, &stdin_watcher);
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
83=head1 WHAT TO READ WHEN IN A HURRY
84
85This manual tries to be very detailed, but unfortunately, this also makes
86it very long. If you just want to know the basics of libev, I suggest
87reading L<ANATOMY OF A WATCHER>, then the L<EXAMPLE PROGRAM> above and
88look up the missing functions in L<GLOBAL FUNCTIONS> and the C<ev_io> and
89C<ev_timer> sections in L<WATCHER TYPES>.
82 90
83=head1 ABOUT LIBEV 91=head1 ABOUT LIBEV
84 92
85Libev is an event loop: you register interest in certain events (such as a 93Libev is an event loop: you register interest in certain events (such as a
86file descriptor being readable or a timeout occurring), and it will manage 94file descriptor being readable or a timeout occurring), and it will manage
118Libev is very configurable. In this manual the default (and most common) 126Libev is very configurable. In this manual the default (and most common)
119configuration will be described, which supports multiple event loops. For 127configuration will be described, which supports multiple event loops. For
120more info about various configuration options please have a look at 128more info about various configuration options please have a look at
121B<EMBED> section in this manual. If libev was configured without support 129B<EMBED> section in this manual. If libev was configured without support
122for multiple event loops, then all functions taking an initial argument of 130for multiple event loops, then all functions taking an initial argument of
123name C<loop> (which is always of type C<ev_loop *>) will not have 131name C<loop> (which is always of type C<struct ev_loop *>) will not have
124this argument. 132this argument.
125 133
126=head2 TIME REPRESENTATION 134=head2 TIME REPRESENTATION
127 135
128Libev represents time as a single floating point number, representing 136Libev represents time as a single floating point number, representing
129the (fractional) number of seconds since the (POSIX) epoch (somewhere 137the (fractional) number of seconds since the (POSIX) epoch (in practice
130near the beginning of 1970, details are complicated, don't ask). This 138somewhere near the beginning of 1970, details are complicated, don't
131type is called C<ev_tstamp>, which is what you should use too. It usually 139ask). This type is called C<ev_tstamp>, which is what you should use
132aliases to the C<double> type in C. When you need to do any calculations 140too. It usually aliases to the C<double> type in C. When you need to do
133on it, you should treat it as some floating point value. Unlike the name 141any calculations on it, you should treat it as some floating point value.
142
134component C<stamp> might indicate, it is also used for time differences 143Unlike the name component C<stamp> might indicate, it is also used for
135throughout libev. 144time differences (e.g. delays) throughout libev.
136 145
137=head1 ERROR HANDLING 146=head1 ERROR HANDLING
138 147
139Libev knows three classes of errors: operating system errors, usage errors 148Libev knows three classes of errors: operating system errors, usage errors
140and internal errors (bugs). 149and internal errors (bugs).
164 173
165=item ev_tstamp ev_time () 174=item ev_tstamp ev_time ()
166 175
167Returns the current time as libev would use it. Please note that the 176Returns the current time as libev would use it. Please note that the
168C<ev_now> function is usually faster and also often returns the timestamp 177C<ev_now> function is usually faster and also often returns the timestamp
169you actually want to know. 178you actually want to know. Also interesting is the combination of
179C<ev_update_now> and C<ev_now>.
170 180
171=item ev_sleep (ev_tstamp interval) 181=item ev_sleep (ev_tstamp interval)
172 182
173Sleep for the given interval: The current thread will be blocked until 183Sleep for the given interval: The current thread will be blocked until
174either it is interrupted or the given time interval has passed. Basically 184either it is interrupted or the given time interval has passed. Basically
191as this indicates an incompatible change. Minor versions are usually 201as this indicates an incompatible change. Minor versions are usually
192compatible to older versions, so a larger minor version alone is usually 202compatible to older versions, so a larger minor version alone is usually
193not a problem. 203not a problem.
194 204
195Example: Make sure we haven't accidentally been linked against the wrong 205Example: Make sure we haven't accidentally been linked against the wrong
196version. 206version (note, however, that this will not detect other ABI mismatches,
207such as LFS or reentrancy).
197 208
198 assert (("libev version mismatch", 209 assert (("libev version mismatch",
199 ev_version_major () == EV_VERSION_MAJOR 210 ev_version_major () == EV_VERSION_MAJOR
200 && ev_version_minor () >= EV_VERSION_MINOR)); 211 && ev_version_minor () >= EV_VERSION_MINOR));
201 212
212 assert (("sorry, no epoll, no sex", 223 assert (("sorry, no epoll, no sex",
213 ev_supported_backends () & EVBACKEND_EPOLL)); 224 ev_supported_backends () & EVBACKEND_EPOLL));
214 225
215=item unsigned int ev_recommended_backends () 226=item unsigned int ev_recommended_backends ()
216 227
217Return the set of all backends compiled into this binary of libev and also 228Return the set of all backends compiled into this binary of libev and
218recommended for this platform. This set is often smaller than the one 229also recommended for this platform, meaning it will work for most file
230descriptor types. This set is often smaller than the one returned by
219returned by C<ev_supported_backends>, as for example kqueue is broken on 231C<ev_supported_backends>, as for example kqueue is broken on most BSDs
220most BSDs and will not be auto-detected unless you explicitly request it 232and will not be auto-detected unless you explicitly request it (assuming
221(assuming you know what you are doing). This is the set of backends that 233you know what you are doing). This is the set of backends that libev will
222libev will probe for if you specify no backends explicitly. 234probe for if you specify no backends explicitly.
223 235
224=item unsigned int ev_embeddable_backends () 236=item unsigned int ev_embeddable_backends ()
225 237
226Returns the set of backends that are embeddable in other event loops. This 238Returns the set of backends that are embeddable in other event loops. This
227is the theoretical, all-platform, value. To find which backends 239value is platform-specific but can include backends not available on the
228might be supported on the current system, you would need to look at 240current system. To find which embeddable backends might be supported on
229C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 241the current system, you would need to look at C<ev_embeddable_backends ()
230recommended ones. 242& ev_supported_backends ()>, likewise for recommended ones.
231 243
232See the description of C<ev_embed> watchers for more info. 244See the description of C<ev_embed> watchers for more info.
233 245
234=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT] 246=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
235 247
289 ... 301 ...
290 ev_set_syserr_cb (fatal_error); 302 ev_set_syserr_cb (fatal_error);
291 303
292=back 304=back
293 305
294=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 306=head1 FUNCTIONS CONTROLLING EVENT LOOPS
295 307
296An event loop is described by a C<struct ev_loop *> (the C<struct> 308An event loop is described by a C<struct ev_loop *> (the C<struct> is
297is I<not> optional in this case, as there is also an C<ev_loop> 309I<not> optional in this case unless libev 3 compatibility is disabled, as
298I<function>). 310libev 3 had an C<ev_loop> function colliding with the struct name).
299 311
300The library knows two types of such loops, the I<default> loop, which 312The library knows two types of such loops, the I<default> loop, which
301supports signals and child events, and dynamically created loops which do 313supports child process events, and dynamically created event loops which
302not. 314do not.
303 315
304=over 4 316=over 4
305 317
306=item struct ev_loop *ev_default_loop (unsigned int flags) 318=item struct ev_loop *ev_default_loop (unsigned int flags)
307 319
308This will initialise the default event loop if it hasn't been initialised 320This returns the "default" event loop object, which is what you should
309yet and return it. If the default loop could not be initialised, returns 321normally use when you just need "the event loop". Event loop objects and
310false. If it already was initialised it simply returns it (and ignores the 322the C<flags> parameter are described in more detail in the entry for
311flags. If that is troubling you, check C<ev_backend ()> afterwards). 323C<ev_loop_new>.
324
325If the default loop is already initialised then this function simply
326returns it (and ignores the flags. If that is troubling you, check
327C<ev_backend ()> afterwards). Otherwise it will create it with the given
328flags, which should almost always be C<0>, unless the caller is also the
329one calling C<ev_run> or otherwise qualifies as "the main program".
312 330
313If you don't know what event loop to use, use the one returned from this 331If you don't know what event loop to use, use the one returned from this
314function. 332function (or via the C<EV_DEFAULT> macro).
315 333
316Note that this function is I<not> thread-safe, so if you want to use it 334Note that this function is I<not> thread-safe, so if you want to use it
317from multiple threads, you have to lock (note also that this is unlikely, 335from multiple threads, you have to employ some kind of mutex (note also
318as loops cannot be shared easily between threads anyway). 336that this case is unlikely, as loops cannot be shared easily between
337threads anyway).
319 338
320The default loop is the only loop that can handle C<ev_signal> and 339The default loop is the only loop that can handle C<ev_child> watchers,
321C<ev_child> watchers, and to do this, it always registers a handler 340and to do this, it always registers a handler for C<SIGCHLD>. If this is
322for C<SIGCHLD>. If this is a problem for your application you can either 341a problem for your application you can either create a dynamic loop with
323create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 342C<ev_loop_new> which doesn't do that, or you can simply overwrite the
324can simply overwrite the C<SIGCHLD> signal handler I<after> calling 343C<SIGCHLD> signal handler I<after> calling C<ev_default_init>.
325C<ev_default_init>. 344
345Example: This is the most typical usage.
346
347 if (!ev_default_loop (0))
348 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
349
350Example: Restrict libev to the select and poll backends, and do not allow
351environment settings to be taken into account:
352
353 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
354
355=item struct ev_loop *ev_loop_new (unsigned int flags)
356
357This will create and initialise a new event loop object. If the loop
358could not be initialised, returns false.
359
360Note that this function I<is> thread-safe, and one common way to use
361libev with threads is indeed to create one loop per thread, and using the
362default loop in the "main" or "initial" thread.
326 363
327The flags argument can be used to specify special behaviour or specific 364The flags argument can be used to specify special behaviour or specific
328backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>). 365backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
329 366
330The following flags are supported: 367The following flags are supported:
345useful to try out specific backends to test their performance, or to work 382useful to try out specific backends to test their performance, or to work
346around bugs. 383around bugs.
347 384
348=item C<EVFLAG_FORKCHECK> 385=item C<EVFLAG_FORKCHECK>
349 386
350Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after 387Instead of calling C<ev_loop_fork> manually after a fork, you can also
351a fork, you can also make libev check for a fork in each iteration by 388make libev check for a fork in each iteration by enabling this flag.
352enabling this flag.
353 389
354This works by calling C<getpid ()> on every iteration of the loop, 390This works by calling C<getpid ()> on every iteration of the loop,
355and thus this might slow down your event loop if you do a lot of loop 391and thus this might slow down your event loop if you do a lot of loop
356iterations and little real work, but is usually not noticeable (on my 392iterations and little real work, but is usually not noticeable (on my
357GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 393GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
370When this flag is specified, then libev will not attempt to use the 406When this flag is specified, then libev will not attempt to use the
371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and 407I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372testing, this flag can be useful to conserve inotify file descriptors, as 408testing, this flag can be useful to conserve inotify file descriptors, as
373otherwise each loop using C<ev_stat> watchers consumes one inotify handle. 409otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374 410
375=item C<EVFLAG_NOSIGNALFD> 411=item C<EVFLAG_SIGNALFD>
376 412
377When this flag is specified, then libev will not attempt to use the 413When this flag is specified, then libev will attempt to use the
378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is 414I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
379probably only useful to work around any bugs in libev. Consequently, this 415delivers signals synchronously, which makes it both faster and might make
380flag might go away once the signalfd functionality is considered stable, 416it possible to get the queued signal data. It can also simplify signal
381so it's useful mostly in environment variables and not in program code. 417handling with threads, as long as you properly block signals in your
418threads that are not interested in handling them.
419
420Signalfd will not be used by default as this changes your signal mask, and
421there are a lot of shoddy libraries and programs (glib's threadpool for
422example) that can't properly initialise their signal masks.
382 423
383=item C<EVBACKEND_SELECT> (value 1, portable select backend) 424=item C<EVBACKEND_SELECT> (value 1, portable select backend)
384 425
385This is your standard select(2) backend. Not I<completely> standard, as 426This is your standard select(2) backend. Not I<completely> standard, as
386libev tries to roll its own fd_set with no limits on the number of fds, 427libev tries to roll its own fd_set with no limits on the number of fds,
411This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 452This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
412C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 453C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
413 454
414=item C<EVBACKEND_EPOLL> (value 4, Linux) 455=item C<EVBACKEND_EPOLL> (value 4, Linux)
415 456
457Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
458kernels).
459
416For few fds, this backend is a bit little slower than poll and select, 460For few fds, this backend is a bit little slower than poll and select,
417but it scales phenomenally better. While poll and select usually scale 461but it scales phenomenally better. While poll and select usually scale
418like O(total_fds) where n is the total number of fds (or the highest fd), 462like O(total_fds) where n is the total number of fds (or the highest fd),
419epoll scales either O(1) or O(active_fds). 463epoll scales either O(1) or O(active_fds).
420 464
421The epoll mechanism deserves honorable mention as the most misdesigned 465The epoll mechanism deserves honorable mention as the most misdesigned
422of the more advanced event mechanisms: mere annoyances include silently 466of the more advanced event mechanisms: mere annoyances include silently
423dropping file descriptors, requiring a system call per change per file 467dropping file descriptors, requiring a system call per change per file
424descriptor (and unnecessary guessing of parameters), problems with dup and 468descriptor (and unnecessary guessing of parameters), problems with dup,
469returning before the timeout value requiring additional iterations and so
425so on. The biggest issue is fork races, however - if a program forks then 470on. The biggest issue is fork races, however - if a program forks then
426I<both> parent and child process have to recreate the epoll set, which can 471I<both> parent and child process have to recreate the epoll set, which can
427take considerable time (one syscall per file descriptor) and is of course 472take considerable time (one syscall per file descriptor) and is of course
428hard to detect. 473hard to detect.
429 474
430Epoll is also notoriously buggy - embedding epoll fds I<should> work, but 475Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
431of course I<doesn't>, and epoll just loves to report events for totally 476of course I<doesn't>, and epoll just loves to report events for totally
432I<different> file descriptors (even already closed ones, so one cannot 477I<different> file descriptors (even already closed ones, so one cannot
433even remove them from the set) than registered in the set (especially 478even remove them from the set) than registered in the set (especially
434on SMP systems). Libev tries to counter these spurious notifications by 479on SMP systems). Libev tries to counter these spurious notifications by
435employing an additional generation counter and comparing that against the 480employing an additional generation counter and comparing that against the
436events to filter out spurious ones, recreating the set when required. 481events to filter out spurious ones, recreating the set when required. Last
482not least, it also refuses to work with some file descriptors which work
483perfectly fine with C<select> (files, many character devices...).
437 484
438While stopping, setting and starting an I/O watcher in the same iteration 485While stopping, setting and starting an I/O watcher in the same iteration
439will result in some caching, there is still a system call per such 486will result in some caching, there is still a system call per such
440incident (because the same I<file descriptor> could point to a different 487incident (because the same I<file descriptor> could point to a different
441I<file description> now), so its best to avoid that. Also, C<dup ()>'ed 488I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
539If one or more of the backend flags are or'ed into the flags value, 586If one or more of the backend flags are or'ed into the flags value,
540then only these backends will be tried (in the reverse order as listed 587then only these backends will be tried (in the reverse order as listed
541here). If none are specified, all backends in C<ev_recommended_backends 588here). If none are specified, all backends in C<ev_recommended_backends
542()> will be tried. 589()> will be tried.
543 590
544Example: This is the most typical usage.
545
546 if (!ev_default_loop (0))
547 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
548
549Example: Restrict libev to the select and poll backends, and do not allow
550environment settings to be taken into account:
551
552 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
553
554Example: Use whatever libev has to offer, but make sure that kqueue is
555used if available (warning, breaks stuff, best use only with your own
556private event loop and only if you know the OS supports your types of
557fds):
558
559 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
560
561=item struct ev_loop *ev_loop_new (unsigned int flags)
562
563Similar to C<ev_default_loop>, but always creates a new event loop that is
564always distinct from the default loop. Unlike the default loop, it cannot
565handle signal and child watchers, and attempts to do so will be greeted by
566undefined behaviour (or a failed assertion if assertions are enabled).
567
568Note that this function I<is> thread-safe, and the recommended way to use
569libev with threads is indeed to create one loop per thread, and using the
570default loop in the "main" or "initial" thread.
571
572Example: Try to create a event loop that uses epoll and nothing else. 591Example: Try to create a event loop that uses epoll and nothing else.
573 592
574 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 593 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
575 if (!epoller) 594 if (!epoller)
576 fatal ("no epoll found here, maybe it hides under your chair"); 595 fatal ("no epoll found here, maybe it hides under your chair");
577 596
597Example: Use whatever libev has to offer, but make sure that kqueue is
598used if available.
599
600 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
601
578=item ev_default_destroy () 602=item ev_loop_destroy (loop)
579 603
580Destroys the default loop again (frees all memory and kernel state 604Destroys an event loop object (frees all memory and kernel state
581etc.). None of the active event watchers will be stopped in the normal 605etc.). None of the active event watchers will be stopped in the normal
582sense, so e.g. C<ev_is_active> might still return true. It is your 606sense, so e.g. C<ev_is_active> might still return true. It is your
583responsibility to either stop all watchers cleanly yourself I<before> 607responsibility to either stop all watchers cleanly yourself I<before>
584calling this function, or cope with the fact afterwards (which is usually 608calling this function, or cope with the fact afterwards (which is usually
585the easiest thing, you can just ignore the watchers and/or C<free ()> them 609the easiest thing, you can just ignore the watchers and/or C<free ()> them
587 611
588Note that certain global state, such as signal state (and installed signal 612Note that certain global state, such as signal state (and installed signal
589handlers), will not be freed by this function, and related watchers (such 613handlers), will not be freed by this function, and related watchers (such
590as signal and child watchers) would need to be stopped manually. 614as signal and child watchers) would need to be stopped manually.
591 615
592In general it is not advisable to call this function except in the 616This function is normally used on loop objects allocated by
593rare occasion where you really need to free e.g. the signal handling 617C<ev_loop_new>, but it can also be used on the default loop returned by
618C<ev_default_loop>, in which case it is not thread-safe.
619
620Note that it is not advisable to call this function on the default loop
621except in the rare occasion where you really need to free it's resources.
594pipe fds. If you need dynamically allocated loops it is better to use 622If you need dynamically allocated loops it is better to use C<ev_loop_new>
595C<ev_loop_new> and C<ev_loop_destroy>). 623and C<ev_loop_destroy>.
596 624
597=item ev_loop_destroy (loop) 625=item ev_loop_fork (loop)
598 626
599Like C<ev_default_destroy>, but destroys an event loop created by an
600earlier call to C<ev_loop_new>.
601
602=item ev_default_fork ()
603
604This function sets a flag that causes subsequent C<ev_loop> iterations 627This function sets a flag that causes subsequent C<ev_run> iterations to
605to reinitialise the kernel state for backends that have one. Despite the 628reinitialise the kernel state for backends that have one. Despite the
606name, you can call it anytime, but it makes most sense after forking, in 629name, you can call it anytime, but it makes most sense after forking, in
607the child process (or both child and parent, but that again makes little 630the child process. You I<must> call it (or use C<EVFLAG_FORKCHECK>) in the
608sense). You I<must> call it in the child before using any of the libev 631child before resuming or calling C<ev_run>.
609functions, and it will only take effect at the next C<ev_loop> iteration. 632
633Again, you I<have> to call it on I<any> loop that you want to re-use after
634a fork, I<even if you do not plan to use the loop in the parent>. This is
635because some kernel interfaces *cough* I<kqueue> *cough* do funny things
636during fork.
610 637
611On the other hand, you only need to call this function in the child 638On the other hand, you only need to call this function in the child
612process if and only if you want to use the event library in the child. If 639process if and only if you want to use the event loop in the child. If
613you just fork+exec, you don't have to call it at all. 640you just fork+exec or create a new loop in the child, you don't have to
641call it at all (in fact, C<epoll> is so badly broken that it makes a
642difference, but libev will usually detect this case on its own and do a
643costly reset of the backend).
614 644
615The function itself is quite fast and it's usually not a problem to call 645The function itself is quite fast and it's usually not a problem to call
616it just in case after a fork. To make this easy, the function will fit in 646it just in case after a fork.
617quite nicely into a call to C<pthread_atfork>:
618 647
648Example: Automate calling C<ev_loop_fork> on the default loop when
649using pthreads.
650
651 static void
652 post_fork_child (void)
653 {
654 ev_loop_fork (EV_DEFAULT);
655 }
656
657 ...
619 pthread_atfork (0, 0, ev_default_fork); 658 pthread_atfork (0, 0, post_fork_child);
620
621=item ev_loop_fork (loop)
622
623Like C<ev_default_fork>, but acts on an event loop created by
624C<ev_loop_new>. Yes, you have to call this on every allocated event loop
625after fork that you want to re-use in the child, and how you do this is
626entirely your own problem.
627 659
628=item int ev_is_default_loop (loop) 660=item int ev_is_default_loop (loop)
629 661
630Returns true when the given loop is, in fact, the default loop, and false 662Returns true when the given loop is, in fact, the default loop, and false
631otherwise. 663otherwise.
632 664
633=item unsigned int ev_loop_count (loop) 665=item unsigned int ev_iteration (loop)
634 666
635Returns the count of loop iterations for the loop, which is identical to 667Returns the current iteration count for the event loop, which is identical
636the number of times libev did poll for new events. It starts at C<0> and 668to the number of times libev did poll for new events. It starts at C<0>
637happily wraps around with enough iterations. 669and happily wraps around with enough iterations.
638 670
639This value can sometimes be useful as a generation counter of sorts (it 671This value can sometimes be useful as a generation counter of sorts (it
640"ticks" the number of loop iterations), as it roughly corresponds with 672"ticks" the number of loop iterations), as it roughly corresponds with
641C<ev_prepare> and C<ev_check> calls. 673C<ev_prepare> and C<ev_check> calls - and is incremented between the
674prepare and check phases.
642 675
643=item unsigned int ev_loop_depth (loop) 676=item unsigned int ev_depth (loop)
644 677
645Returns the number of times C<ev_loop> was entered minus the number of 678Returns the number of times C<ev_run> was entered minus the number of
646times C<ev_loop> was exited, in other words, the recursion depth. 679times C<ev_run> was exited, in other words, the recursion depth.
647 680
648Outside C<ev_loop>, this number is zero. In a callback, this number is 681Outside C<ev_run>, this number is zero. In a callback, this number is
649C<1>, unless C<ev_loop> was invoked recursively (or from another thread), 682C<1>, unless C<ev_run> was invoked recursively (or from another thread),
650in which case it is higher. 683in which case it is higher.
651 684
652Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread 685Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread
653etc.), doesn't count as exit. 686etc.), doesn't count as "exit" - consider this as a hint to avoid such
687ungentleman-like behaviour unless it's really convenient.
654 688
655=item unsigned int ev_backend (loop) 689=item unsigned int ev_backend (loop)
656 690
657Returns one of the C<EVBACKEND_*> flags indicating the event backend in 691Returns one of the C<EVBACKEND_*> flags indicating the event backend in
658use. 692use.
667 701
668=item ev_now_update (loop) 702=item ev_now_update (loop)
669 703
670Establishes the current time by querying the kernel, updating the time 704Establishes the current time by querying the kernel, updating the time
671returned by C<ev_now ()> in the progress. This is a costly operation and 705returned by C<ev_now ()> in the progress. This is a costly operation and
672is usually done automatically within C<ev_loop ()>. 706is usually done automatically within C<ev_run ()>.
673 707
674This function is rarely useful, but when some event callback runs for a 708This function is rarely useful, but when some event callback runs for a
675very long time without entering the event loop, updating libev's idea of 709very long time without entering the event loop, updating libev's idea of
676the current time is a good idea. 710the current time is a good idea.
677 711
679 713
680=item ev_suspend (loop) 714=item ev_suspend (loop)
681 715
682=item ev_resume (loop) 716=item ev_resume (loop)
683 717
684These two functions suspend and resume a loop, for use when the loop is 718These two functions suspend and resume an event loop, for use when the
685not used for a while and timeouts should not be processed. 719loop is not used for a while and timeouts should not be processed.
686 720
687A typical use case would be an interactive program such as a game: When 721A typical use case would be an interactive program such as a game: When
688the user presses C<^Z> to suspend the game and resumes it an hour later it 722the user presses C<^Z> to suspend the game and resumes it an hour later it
689would be best to handle timeouts as if no time had actually passed while 723would be best to handle timeouts as if no time had actually passed while
690the program was suspended. This can be achieved by calling C<ev_suspend> 724the program was suspended. This can be achieved by calling C<ev_suspend>
692C<ev_resume> directly afterwards to resume timer processing. 726C<ev_resume> directly afterwards to resume timer processing.
693 727
694Effectively, all C<ev_timer> watchers will be delayed by the time spend 728Effectively, all C<ev_timer> watchers will be delayed by the time spend
695between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers 729between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
696will be rescheduled (that is, they will lose any events that would have 730will be rescheduled (that is, they will lose any events that would have
697occured while suspended). 731occurred while suspended).
698 732
699After calling C<ev_suspend> you B<must not> call I<any> function on the 733After calling C<ev_suspend> you B<must not> call I<any> function on the
700given loop other than C<ev_resume>, and you B<must not> call C<ev_resume> 734given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
701without a previous call to C<ev_suspend>. 735without a previous call to C<ev_suspend>.
702 736
703Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the 737Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
704event loop time (see C<ev_now_update>). 738event loop time (see C<ev_now_update>).
705 739
706=item ev_loop (loop, int flags) 740=item ev_run (loop, int flags)
707 741
708Finally, this is it, the event handler. This function usually is called 742Finally, this is it, the event handler. This function usually is called
709after you initialised all your watchers and you want to start handling 743after you have initialised all your watchers and you want to start
710events. 744handling events. It will ask the operating system for any new events, call
745the watcher callbacks, an then repeat the whole process indefinitely: This
746is why event loops are called I<loops>.
711 747
712If the flags argument is specified as C<0>, it will not return until 748If the flags argument is specified as C<0>, it will keep handling events
713either no event watchers are active anymore or C<ev_unloop> was called. 749until either no event watchers are active anymore or C<ev_break> was
750called.
714 751
715Please note that an explicit C<ev_unloop> is usually better than 752Please note that an explicit C<ev_break> is usually better than
716relying on all watchers to be stopped when deciding when a program has 753relying on all watchers to be stopped when deciding when a program has
717finished (especially in interactive programs), but having a program 754finished (especially in interactive programs), but having a program
718that automatically loops as long as it has to and no longer by virtue 755that automatically loops as long as it has to and no longer by virtue
719of relying on its watchers stopping correctly, that is truly a thing of 756of relying on its watchers stopping correctly, that is truly a thing of
720beauty. 757beauty.
721 758
722A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 759A flags value of C<EVRUN_NOWAIT> will look for new events, will handle
723those events and any already outstanding ones, but will not block your 760those events and any already outstanding ones, but will not wait and
724process in case there are no events and will return after one iteration of 761block your process in case there are no events and will return after one
725the loop. 762iteration of the loop. This is sometimes useful to poll and handle new
763events while doing lengthy calculations, to keep the program responsive.
726 764
727A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 765A flags value of C<EVRUN_ONCE> will look for new events (waiting if
728necessary) and will handle those and any already outstanding ones. It 766necessary) and will handle those and any already outstanding ones. It
729will block your process until at least one new event arrives (which could 767will block your process until at least one new event arrives (which could
730be an event internal to libev itself, so there is no guarantee that a 768be an event internal to libev itself, so there is no guarantee that a
731user-registered callback will be called), and will return after one 769user-registered callback will be called), and will return after one
732iteration of the loop. 770iteration of the loop.
733 771
734This is useful if you are waiting for some external event in conjunction 772This is useful if you are waiting for some external event in conjunction
735with something not expressible using other libev watchers (i.e. "roll your 773with something not expressible using other libev watchers (i.e. "roll your
736own C<ev_loop>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is 774own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
737usually a better approach for this kind of thing. 775usually a better approach for this kind of thing.
738 776
739Here are the gory details of what C<ev_loop> does: 777Here are the gory details of what C<ev_run> does:
740 778
779 - Increment loop depth.
780 - Reset the ev_break status.
741 - Before the first iteration, call any pending watchers. 781 - Before the first iteration, call any pending watchers.
782 LOOP:
742 * If EVFLAG_FORKCHECK was used, check for a fork. 783 - If EVFLAG_FORKCHECK was used, check for a fork.
743 - If a fork was detected (by any means), queue and call all fork watchers. 784 - If a fork was detected (by any means), queue and call all fork watchers.
744 - Queue and call all prepare watchers. 785 - Queue and call all prepare watchers.
786 - If ev_break was called, goto FINISH.
745 - If we have been forked, detach and recreate the kernel state 787 - If we have been forked, detach and recreate the kernel state
746 as to not disturb the other process. 788 as to not disturb the other process.
747 - Update the kernel state with all outstanding changes. 789 - Update the kernel state with all outstanding changes.
748 - Update the "event loop time" (ev_now ()). 790 - Update the "event loop time" (ev_now ()).
749 - Calculate for how long to sleep or block, if at all 791 - Calculate for how long to sleep or block, if at all
750 (active idle watchers, EVLOOP_NONBLOCK or not having 792 (active idle watchers, EVRUN_NOWAIT or not having
751 any active watchers at all will result in not sleeping). 793 any active watchers at all will result in not sleeping).
752 - Sleep if the I/O and timer collect interval say so. 794 - Sleep if the I/O and timer collect interval say so.
795 - Increment loop iteration counter.
753 - Block the process, waiting for any events. 796 - Block the process, waiting for any events.
754 - Queue all outstanding I/O (fd) events. 797 - Queue all outstanding I/O (fd) events.
755 - Update the "event loop time" (ev_now ()), and do time jump adjustments. 798 - Update the "event loop time" (ev_now ()), and do time jump adjustments.
756 - Queue all expired timers. 799 - Queue all expired timers.
757 - Queue all expired periodics. 800 - Queue all expired periodics.
758 - Unless any events are pending now, queue all idle watchers. 801 - Queue all idle watchers with priority higher than that of pending events.
759 - Queue all check watchers. 802 - Queue all check watchers.
760 - Call all queued watchers in reverse order (i.e. check watchers first). 803 - Call all queued watchers in reverse order (i.e. check watchers first).
761 Signals and child watchers are implemented as I/O watchers, and will 804 Signals and child watchers are implemented as I/O watchers, and will
762 be handled here by queueing them when their watcher gets executed. 805 be handled here by queueing them when their watcher gets executed.
763 - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 806 - If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT
764 were used, or there are no active watchers, return, otherwise 807 were used, or there are no active watchers, goto FINISH, otherwise
765 continue with step *. 808 continue with step LOOP.
809 FINISH:
810 - Reset the ev_break status iff it was EVBREAK_ONE.
811 - Decrement the loop depth.
812 - Return.
766 813
767Example: Queue some jobs and then loop until no events are outstanding 814Example: Queue some jobs and then loop until no events are outstanding
768anymore. 815anymore.
769 816
770 ... queue jobs here, make sure they register event watchers as long 817 ... queue jobs here, make sure they register event watchers as long
771 ... as they still have work to do (even an idle watcher will do..) 818 ... as they still have work to do (even an idle watcher will do..)
772 ev_loop (my_loop, 0); 819 ev_run (my_loop, 0);
773 ... jobs done or somebody called unloop. yeah! 820 ... jobs done or somebody called unloop. yeah!
774 821
775=item ev_unloop (loop, how) 822=item ev_break (loop, how)
776 823
777Can be used to make a call to C<ev_loop> return early (but only after it 824Can be used to make a call to C<ev_run> return early (but only after it
778has processed all outstanding events). The C<how> argument must be either 825has processed all outstanding events). The C<how> argument must be either
779C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 826C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or
780C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 827C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return.
781 828
782This "unloop state" will be cleared when entering C<ev_loop> again. 829This "break state" will be cleared when entering C<ev_run> again.
783 830
784It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls. 831It is safe to call C<ev_break> from outside any C<ev_run> calls, too.
785 832
786=item ev_ref (loop) 833=item ev_ref (loop)
787 834
788=item ev_unref (loop) 835=item ev_unref (loop)
789 836
790Ref/unref can be used to add or remove a reference count on the event 837Ref/unref can be used to add or remove a reference count on the event
791loop: Every watcher keeps one reference, and as long as the reference 838loop: Every watcher keeps one reference, and as long as the reference
792count is nonzero, C<ev_loop> will not return on its own. 839count is nonzero, C<ev_run> will not return on its own.
793 840
794If you have a watcher you never unregister that should not keep C<ev_loop> 841This is useful when you have a watcher that you never intend to
795from returning, call ev_unref() after starting, and ev_ref() before 842unregister, but that nevertheless should not keep C<ev_run> from
843returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
796stopping it. 844before stopping it.
797 845
798As an example, libev itself uses this for its internal signal pipe: It 846As an example, libev itself uses this for its internal signal pipe: It
799is not visible to the libev user and should not keep C<ev_loop> from 847is not visible to the libev user and should not keep C<ev_run> from
800exiting if no event watchers registered by it are active. It is also an 848exiting if no event watchers registered by it are active. It is also an
801excellent way to do this for generic recurring timers or from within 849excellent way to do this for generic recurring timers or from within
802third-party libraries. Just remember to I<unref after start> and I<ref 850third-party libraries. Just remember to I<unref after start> and I<ref
803before stop> (but only if the watcher wasn't active before, or was active 851before stop> (but only if the watcher wasn't active before, or was active
804before, respectively. Note also that libev might stop watchers itself 852before, respectively. Note also that libev might stop watchers itself
805(e.g. non-repeating timers) in which case you have to C<ev_ref> 853(e.g. non-repeating timers) in which case you have to C<ev_ref>
806in the callback). 854in the callback).
807 855
808Example: Create a signal watcher, but keep it from keeping C<ev_loop> 856Example: Create a signal watcher, but keep it from keeping C<ev_run>
809running when nothing else is active. 857running when nothing else is active.
810 858
811 ev_signal exitsig; 859 ev_signal exitsig;
812 ev_signal_init (&exitsig, sig_cb, SIGINT); 860 ev_signal_init (&exitsig, sig_cb, SIGINT);
813 ev_signal_start (loop, &exitsig); 861 ev_signal_start (loop, &exitsig);
858usually doesn't make much sense to set it to a lower value than C<0.01>, 906usually doesn't make much sense to set it to a lower value than C<0.01>,
859as this approaches the timing granularity of most systems. Note that if 907as this approaches the timing granularity of most systems. Note that if
860you do transactions with the outside world and you can't increase the 908you do transactions with the outside world and you can't increase the
861parallelity, then this setting will limit your transaction rate (if you 909parallelity, then this setting will limit your transaction rate (if you
862need to poll once per transaction and the I/O collect interval is 0.01, 910need to poll once per transaction and the I/O collect interval is 0.01,
863then you can't do more than 100 transations per second). 911then you can't do more than 100 transactions per second).
864 912
865Setting the I<timeout collect interval> can improve the opportunity for 913Setting the I<timeout collect interval> can improve the opportunity for
866saving power, as the program will "bundle" timer callback invocations that 914saving power, as the program will "bundle" timer callback invocations that
867are "near" in time together, by delaying some, thus reducing the number of 915are "near" in time together, by delaying some, thus reducing the number of
868times the process sleeps and wakes up again. Another useful technique to 916times the process sleeps and wakes up again. Another useful technique to
876 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01); 924 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
877 925
878=item ev_invoke_pending (loop) 926=item ev_invoke_pending (loop)
879 927
880This call will simply invoke all pending watchers while resetting their 928This call will simply invoke all pending watchers while resetting their
881pending state. Normally, C<ev_loop> does this automatically when required, 929pending state. Normally, C<ev_run> does this automatically when required,
882but when overriding the invoke callback this call comes handy. 930but when overriding the invoke callback this call comes handy. This
931function can be invoked from a watcher - this can be useful for example
932when you want to do some lengthy calculation and want to pass further
933event handling to another thread (you still have to make sure only one
934thread executes within C<ev_invoke_pending> or C<ev_run> of course).
883 935
884=item int ev_pending_count (loop) 936=item int ev_pending_count (loop)
885 937
886Returns the number of pending watchers - zero indicates that no watchers 938Returns the number of pending watchers - zero indicates that no watchers
887are pending. 939are pending.
888 940
889=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P)) 941=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
890 942
891This overrides the invoke pending functionality of the loop: Instead of 943This overrides the invoke pending functionality of the loop: Instead of
892invoking all pending watchers when there are any, C<ev_loop> will call 944invoking all pending watchers when there are any, C<ev_run> will call
893this callback instead. This is useful, for example, when you want to 945this callback instead. This is useful, for example, when you want to
894invoke the actual watchers inside another context (another thread etc.). 946invoke the actual watchers inside another context (another thread etc.).
895 947
896If you want to reset the callback, use C<ev_invoke_pending> as new 948If you want to reset the callback, use C<ev_invoke_pending> as new
897callback. 949callback.
900 952
901Sometimes you want to share the same loop between multiple threads. This 953Sometimes you want to share the same loop between multiple threads. This
902can be done relatively simply by putting mutex_lock/unlock calls around 954can be done relatively simply by putting mutex_lock/unlock calls around
903each call to a libev function. 955each call to a libev function.
904 956
905However, C<ev_loop> can run an indefinite time, so it is not feasible to 957However, C<ev_run> can run an indefinite time, so it is not feasible
906wait for it to return. One way around this is to wake up the loop via 958to wait for it to return. One way around this is to wake up the event
907C<ev_unloop> and C<av_async_send>, another way is to set these I<release> 959loop via C<ev_break> and C<av_async_send>, another way is to set these
908and I<acquire> callbacks on the loop. 960I<release> and I<acquire> callbacks on the loop.
909 961
910When set, then C<release> will be called just before the thread is 962When set, then C<release> will be called just before the thread is
911suspended waiting for new events, and C<acquire> is called just 963suspended waiting for new events, and C<acquire> is called just
912afterwards. 964afterwards.
913 965
916 968
917While event loop modifications are allowed between invocations of 969While event loop modifications are allowed between invocations of
918C<release> and C<acquire> (that's their only purpose after all), no 970C<release> and C<acquire> (that's their only purpose after all), no
919modifications done will affect the event loop, i.e. adding watchers will 971modifications done will affect the event loop, i.e. adding watchers will
920have no effect on the set of file descriptors being watched, or the time 972have no effect on the set of file descriptors being watched, or the time
921waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it 973waited. Use an C<ev_async> watcher to wake up C<ev_run> when you want it
922to take note of any changes you made. 974to take note of any changes you made.
923 975
924In theory, threads executing C<ev_loop> will be async-cancel safe between 976In theory, threads executing C<ev_run> will be async-cancel safe between
925invocations of C<release> and C<acquire>. 977invocations of C<release> and C<acquire>.
926 978
927See also the locking example in the C<THREADS> section later in this 979See also the locking example in the C<THREADS> section later in this
928document. 980document.
929 981
938These two functions can be used to associate arbitrary data with a loop, 990These two functions can be used to associate arbitrary data with a loop,
939and are intended solely for the C<invoke_pending_cb>, C<release> and 991and are intended solely for the C<invoke_pending_cb>, C<release> and
940C<acquire> callbacks described above, but of course can be (ab-)used for 992C<acquire> callbacks described above, but of course can be (ab-)used for
941any other purpose as well. 993any other purpose as well.
942 994
943=item ev_loop_verify (loop) 995=item ev_verify (loop)
944 996
945This function only does something when C<EV_VERIFY> support has been 997This function only does something when C<EV_VERIFY> support has been
946compiled in, which is the default for non-minimal builds. It tries to go 998compiled in, which is the default for non-minimal builds. It tries to go
947through all internal structures and checks them for validity. If anything 999through all internal structures and checks them for validity. If anything
948is found to be inconsistent, it will print an error message to standard 1000is found to be inconsistent, it will print an error message to standard
959 1011
960In the following description, uppercase C<TYPE> in names stands for the 1012In the following description, uppercase C<TYPE> in names stands for the
961watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer 1013watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
962watchers and C<ev_io_start> for I/O watchers. 1014watchers and C<ev_io_start> for I/O watchers.
963 1015
964A watcher is a structure that you create and register to record your 1016A watcher is an opaque structure that you allocate and register to record
965interest in some event. For instance, if you want to wait for STDIN to 1017your interest in some event. To make a concrete example, imagine you want
966become readable, you would create an C<ev_io> watcher for that: 1018to wait for STDIN to become readable, you would create an C<ev_io> watcher
1019for that:
967 1020
968 static void my_cb (struct ev_loop *loop, ev_io *w, int revents) 1021 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
969 { 1022 {
970 ev_io_stop (w); 1023 ev_io_stop (w);
971 ev_unloop (loop, EVUNLOOP_ALL); 1024 ev_break (loop, EVBREAK_ALL);
972 } 1025 }
973 1026
974 struct ev_loop *loop = ev_default_loop (0); 1027 struct ev_loop *loop = ev_default_loop (0);
975 1028
976 ev_io stdin_watcher; 1029 ev_io stdin_watcher;
977 1030
978 ev_init (&stdin_watcher, my_cb); 1031 ev_init (&stdin_watcher, my_cb);
979 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 1032 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
980 ev_io_start (loop, &stdin_watcher); 1033 ev_io_start (loop, &stdin_watcher);
981 1034
982 ev_loop (loop, 0); 1035 ev_run (loop, 0);
983 1036
984As you can see, you are responsible for allocating the memory for your 1037As you can see, you are responsible for allocating the memory for your
985watcher structures (and it is I<usually> a bad idea to do this on the 1038watcher structures (and it is I<usually> a bad idea to do this on the
986stack). 1039stack).
987 1040
988Each watcher has an associated watcher structure (called C<struct ev_TYPE> 1041Each watcher has an associated watcher structure (called C<struct ev_TYPE>
989or simply C<ev_TYPE>, as typedefs are provided for all watcher structs). 1042or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
990 1043
991Each watcher structure must be initialised by a call to C<ev_init 1044Each watcher structure must be initialised by a call to C<ev_init (watcher
992(watcher *, callback)>, which expects a callback to be provided. This 1045*, callback)>, which expects a callback to be provided. This callback is
993callback gets invoked each time the event occurs (or, in the case of I/O 1046invoked each time the event occurs (or, in the case of I/O watchers, each
994watchers, each time the event loop detects that the file descriptor given 1047time the event loop detects that the file descriptor given is readable
995is readable and/or writable). 1048and/or writable).
996 1049
997Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >> 1050Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
998macro to configure it, with arguments specific to the watcher type. There 1051macro to configure it, with arguments specific to the watcher type. There
999is also a macro to combine initialisation and setting in one call: C<< 1052is also a macro to combine initialisation and setting in one call: C<<
1000ev_TYPE_init (watcher *, callback, ...) >>. 1053ev_TYPE_init (watcher *, callback, ...) >>.
1023=item C<EV_WRITE> 1076=item C<EV_WRITE>
1024 1077
1025The file descriptor in the C<ev_io> watcher has become readable and/or 1078The file descriptor in the C<ev_io> watcher has become readable and/or
1026writable. 1079writable.
1027 1080
1028=item C<EV_TIMEOUT> 1081=item C<EV_TIMER>
1029 1082
1030The C<ev_timer> watcher has timed out. 1083The C<ev_timer> watcher has timed out.
1031 1084
1032=item C<EV_PERIODIC> 1085=item C<EV_PERIODIC>
1033 1086
1051 1104
1052=item C<EV_PREPARE> 1105=item C<EV_PREPARE>
1053 1106
1054=item C<EV_CHECK> 1107=item C<EV_CHECK>
1055 1108
1056All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts 1109All C<ev_prepare> watchers are invoked just I<before> C<ev_run> starts
1057to gather new events, and all C<ev_check> watchers are invoked just after 1110to gather new events, and all C<ev_check> watchers are invoked just after
1058C<ev_loop> has gathered them, but before it invokes any callbacks for any 1111C<ev_run> has gathered them, but before it invokes any callbacks for any
1059received events. Callbacks of both watcher types can start and stop as 1112received events. Callbacks of both watcher types can start and stop as
1060many watchers as they want, and all of them will be taken into account 1113many watchers as they want, and all of them will be taken into account
1061(for example, a C<ev_prepare> watcher might start an idle watcher to keep 1114(for example, a C<ev_prepare> watcher might start an idle watcher to keep
1062C<ev_loop> from blocking). 1115C<ev_run> from blocking).
1063 1116
1064=item C<EV_EMBED> 1117=item C<EV_EMBED>
1065 1118
1066The embedded event loop specified in the C<ev_embed> watcher needs attention. 1119The embedded event loop specified in the C<ev_embed> watcher needs attention.
1067 1120
1068=item C<EV_FORK> 1121=item C<EV_FORK>
1069 1122
1070The event loop has been resumed in the child process after fork (see 1123The event loop has been resumed in the child process after fork (see
1071C<ev_fork>). 1124C<ev_fork>).
1125
1126=item C<EV_CLEANUP>
1127
1128The event loop is about to be destroyed (see C<ev_cleanup>).
1072 1129
1073=item C<EV_ASYNC> 1130=item C<EV_ASYNC>
1074 1131
1075The given async watcher has been asynchronously notified (see C<ev_async>). 1132The given async watcher has been asynchronously notified (see C<ev_async>).
1076 1133
1123 1180
1124 ev_io w; 1181 ev_io w;
1125 ev_init (&w, my_cb); 1182 ev_init (&w, my_cb);
1126 ev_io_set (&w, STDIN_FILENO, EV_READ); 1183 ev_io_set (&w, STDIN_FILENO, EV_READ);
1127 1184
1128=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1185=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1129 1186
1130This macro initialises the type-specific parts of a watcher. You need to 1187This macro initialises the type-specific parts of a watcher. You need to
1131call C<ev_init> at least once before you call this macro, but you can 1188call C<ev_init> at least once before you call this macro, but you can
1132call C<ev_TYPE_set> any number of times. You must not, however, call this 1189call C<ev_TYPE_set> any number of times. You must not, however, call this
1133macro on a watcher that is active (it can be pending, however, which is a 1190macro on a watcher that is active (it can be pending, however, which is a
1146 1203
1147Example: Initialise and set an C<ev_io> watcher in one step. 1204Example: Initialise and set an C<ev_io> watcher in one step.
1148 1205
1149 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1206 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1150 1207
1151=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1208=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1152 1209
1153Starts (activates) the given watcher. Only active watchers will receive 1210Starts (activates) the given watcher. Only active watchers will receive
1154events. If the watcher is already active nothing will happen. 1211events. If the watcher is already active nothing will happen.
1155 1212
1156Example: Start the C<ev_io> watcher that is being abused as example in this 1213Example: Start the C<ev_io> watcher that is being abused as example in this
1157whole section. 1214whole section.
1158 1215
1159 ev_io_start (EV_DEFAULT_UC, &w); 1216 ev_io_start (EV_DEFAULT_UC, &w);
1160 1217
1161=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1218=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1162 1219
1163Stops the given watcher if active, and clears the pending status (whether 1220Stops the given watcher if active, and clears the pending status (whether
1164the watcher was active or not). 1221the watcher was active or not).
1165 1222
1166It is possible that stopped watchers are pending - for example, 1223It is possible that stopped watchers are pending - for example,
1191=item ev_cb_set (ev_TYPE *watcher, callback) 1248=item ev_cb_set (ev_TYPE *watcher, callback)
1192 1249
1193Change the callback. You can change the callback at virtually any time 1250Change the callback. You can change the callback at virtually any time
1194(modulo threads). 1251(modulo threads).
1195 1252
1196=item ev_set_priority (ev_TYPE *watcher, priority) 1253=item ev_set_priority (ev_TYPE *watcher, int priority)
1197 1254
1198=item int ev_priority (ev_TYPE *watcher) 1255=item int ev_priority (ev_TYPE *watcher)
1199 1256
1200Set and query the priority of the watcher. The priority is a small 1257Set and query the priority of the watcher. The priority is a small
1201integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1258integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1233watcher isn't pending it does nothing and returns C<0>. 1290watcher isn't pending it does nothing and returns C<0>.
1234 1291
1235Sometimes it can be useful to "poll" a watcher instead of waiting for its 1292Sometimes it can be useful to "poll" a watcher instead of waiting for its
1236callback to be invoked, which can be accomplished with this function. 1293callback to be invoked, which can be accomplished with this function.
1237 1294
1295=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1296
1297Feeds the given event set into the event loop, as if the specified event
1298had happened for the specified watcher (which must be a pointer to an
1299initialised but not necessarily started event watcher). Obviously you must
1300not free the watcher as long as it has pending events.
1301
1302Stopping the watcher, letting libev invoke it, or calling
1303C<ev_clear_pending> will clear the pending event, even if the watcher was
1304not started in the first place.
1305
1306See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1307functions that do not need a watcher.
1308
1238=back 1309=back
1239
1240 1310
1241=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1311=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1242 1312
1243Each watcher has, by default, a member C<void *data> that you can change 1313Each watcher has, by default, a member C<void *data> that you can change
1244and read at any time: libev will completely ignore it. This can be used 1314and read at any time: libev will completely ignore it. This can be used
1300 t2_cb (EV_P_ ev_timer *w, int revents) 1370 t2_cb (EV_P_ ev_timer *w, int revents)
1301 { 1371 {
1302 struct my_biggy big = (struct my_biggy *) 1372 struct my_biggy big = (struct my_biggy *)
1303 (((char *)w) - offsetof (struct my_biggy, t2)); 1373 (((char *)w) - offsetof (struct my_biggy, t2));
1304 } 1374 }
1375
1376=head2 WATCHER STATES
1377
1378There are various watcher states mentioned throughout this manual -
1379active, pending and so on. In this section these states and the rules to
1380transition between them will be described in more detail - and while these
1381rules might look complicated, they usually do "the right thing".
1382
1383=over 4
1384
1385=item initialiased
1386
1387Before a watcher can be registered with the event looop it has to be
1388initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
1389C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1390
1391In this state it is simply some block of memory that is suitable for use
1392in an event loop. It can be moved around, freed, reused etc. at will.
1393
1394=item started/running/active
1395
1396Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
1397property of the event loop, and is actively waiting for events. While in
1398this state it cannot be accessed (except in a few documented ways), moved,
1399freed or anything else - the only legal thing is to keep a pointer to it,
1400and call libev functions on it that are documented to work on active watchers.
1401
1402=item pending
1403
1404If a watcher is active and libev determines that an event it is interested
1405in has occurred (such as a timer expiring), it will become pending. It will
1406stay in this pending state until either it is stopped or its callback is
1407about to be invoked, so it is not normally pending inside the watcher
1408callback.
1409
1410The watcher might or might not be active while it is pending (for example,
1411an expired non-repeating timer can be pending but no longer active). If it
1412is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
1413but it is still property of the event loop at this time, so cannot be
1414moved, freed or reused. And if it is active the rules described in the
1415previous item still apply.
1416
1417It is also possible to feed an event on a watcher that is not active (e.g.
1418via C<ev_feed_event>), in which case it becomes pending without being
1419active.
1420
1421=item stopped
1422
1423A watcher can be stopped implicitly by libev (in which case it might still
1424be pending), or explicitly by calling its C<ev_TYPE_stop> function. The
1425latter will clear any pending state the watcher might be in, regardless
1426of whether it was active or not, so stopping a watcher explicitly before
1427freeing it is often a good idea.
1428
1429While stopped (and not pending) the watcher is essentially in the
1430initialised state, that is it can be reused, moved, modified in any way
1431you wish.
1432
1433=back
1305 1434
1306=head2 WATCHER PRIORITY MODELS 1435=head2 WATCHER PRIORITY MODELS
1307 1436
1308Many event loops support I<watcher priorities>, which are usually small 1437Many event loops support I<watcher priorities>, which are usually small
1309integers that influence the ordering of event callback invocation 1438integers that influence the ordering of event callback invocation
1352 1481
1353For example, to emulate how many other event libraries handle priorities, 1482For example, to emulate how many other event libraries handle priorities,
1354you can associate an C<ev_idle> watcher to each such watcher, and in 1483you can associate an C<ev_idle> watcher to each such watcher, and in
1355the normal watcher callback, you just start the idle watcher. The real 1484the normal watcher callback, you just start the idle watcher. The real
1356processing is done in the idle watcher callback. This causes libev to 1485processing is done in the idle watcher callback. This causes libev to
1357continously poll and process kernel event data for the watcher, but when 1486continuously poll and process kernel event data for the watcher, but when
1358the lock-out case is known to be rare (which in turn is rare :), this is 1487the lock-out case is known to be rare (which in turn is rare :), this is
1359workable. 1488workable.
1360 1489
1361Usually, however, the lock-out model implemented that way will perform 1490Usually, however, the lock-out model implemented that way will perform
1362miserably under the type of load it was designed to handle. In that case, 1491miserably under the type of load it was designed to handle. In that case,
1376 { 1505 {
1377 // stop the I/O watcher, we received the event, but 1506 // stop the I/O watcher, we received the event, but
1378 // are not yet ready to handle it. 1507 // are not yet ready to handle it.
1379 ev_io_stop (EV_A_ w); 1508 ev_io_stop (EV_A_ w);
1380 1509
1381 // start the idle watcher to ahndle the actual event. 1510 // start the idle watcher to handle the actual event.
1382 // it will not be executed as long as other watchers 1511 // it will not be executed as long as other watchers
1383 // with the default priority are receiving events. 1512 // with the default priority are receiving events.
1384 ev_idle_start (EV_A_ &idle); 1513 ev_idle_start (EV_A_ &idle);
1385 } 1514 }
1386 1515
1440 1569
1441If you cannot use non-blocking mode, then force the use of a 1570If you cannot use non-blocking mode, then force the use of a
1442known-to-be-good backend (at the time of this writing, this includes only 1571known-to-be-good backend (at the time of this writing, this includes only
1443C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file 1572C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1444descriptors for which non-blocking operation makes no sense (such as 1573descriptors for which non-blocking operation makes no sense (such as
1445files) - libev doesn't guarentee any specific behaviour in that case. 1574files) - libev doesn't guarantee any specific behaviour in that case.
1446 1575
1447Another thing you have to watch out for is that it is quite easy to 1576Another thing you have to watch out for is that it is quite easy to
1448receive "spurious" readiness notifications, that is your callback might 1577receive "spurious" readiness notifications, that is your callback might
1449be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1578be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1450because there is no data. Not only are some backends known to create a 1579because there is no data. Not only are some backends known to create a
1515 1644
1516So when you encounter spurious, unexplained daemon exits, make sure you 1645So when you encounter spurious, unexplained daemon exits, make sure you
1517ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1646ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1518somewhere, as that would have given you a big clue). 1647somewhere, as that would have given you a big clue).
1519 1648
1649=head3 The special problem of accept()ing when you can't
1650
1651Many implementations of the POSIX C<accept> function (for example,
1652found in post-2004 Linux) have the peculiar behaviour of not removing a
1653connection from the pending queue in all error cases.
1654
1655For example, larger servers often run out of file descriptors (because
1656of resource limits), causing C<accept> to fail with C<ENFILE> but not
1657rejecting the connection, leading to libev signalling readiness on
1658the next iteration again (the connection still exists after all), and
1659typically causing the program to loop at 100% CPU usage.
1660
1661Unfortunately, the set of errors that cause this issue differs between
1662operating systems, there is usually little the app can do to remedy the
1663situation, and no known thread-safe method of removing the connection to
1664cope with overload is known (to me).
1665
1666One of the easiest ways to handle this situation is to just ignore it
1667- when the program encounters an overload, it will just loop until the
1668situation is over. While this is a form of busy waiting, no OS offers an
1669event-based way to handle this situation, so it's the best one can do.
1670
1671A better way to handle the situation is to log any errors other than
1672C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1673messages, and continue as usual, which at least gives the user an idea of
1674what could be wrong ("raise the ulimit!"). For extra points one could stop
1675the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1676usage.
1677
1678If your program is single-threaded, then you could also keep a dummy file
1679descriptor for overload situations (e.g. by opening F</dev/null>), and
1680when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1681close that fd, and create a new dummy fd. This will gracefully refuse
1682clients under typical overload conditions.
1683
1684The last way to handle it is to simply log the error and C<exit>, as
1685is often done with C<malloc> failures, but this results in an easy
1686opportunity for a DoS attack.
1520 1687
1521=head3 Watcher-Specific Functions 1688=head3 Watcher-Specific Functions
1522 1689
1523=over 4 1690=over 4
1524 1691
1556 ... 1723 ...
1557 struct ev_loop *loop = ev_default_init (0); 1724 struct ev_loop *loop = ev_default_init (0);
1558 ev_io stdin_readable; 1725 ev_io stdin_readable;
1559 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1726 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1560 ev_io_start (loop, &stdin_readable); 1727 ev_io_start (loop, &stdin_readable);
1561 ev_loop (loop, 0); 1728 ev_run (loop, 0);
1562 1729
1563 1730
1564=head2 C<ev_timer> - relative and optionally repeating timeouts 1731=head2 C<ev_timer> - relative and optionally repeating timeouts
1565 1732
1566Timer watchers are simple relative timers that generate an event after a 1733Timer watchers are simple relative timers that generate an event after a
1575The callback is guaranteed to be invoked only I<after> its timeout has 1742The callback is guaranteed to be invoked only I<after> its timeout has
1576passed (not I<at>, so on systems with very low-resolution clocks this 1743passed (not I<at>, so on systems with very low-resolution clocks this
1577might introduce a small delay). If multiple timers become ready during the 1744might introduce a small delay). If multiple timers become ready during the
1578same loop iteration then the ones with earlier time-out values are invoked 1745same loop iteration then the ones with earlier time-out values are invoked
1579before ones of the same priority with later time-out values (but this is 1746before ones of the same priority with later time-out values (but this is
1580no longer true when a callback calls C<ev_loop> recursively). 1747no longer true when a callback calls C<ev_run> recursively).
1581 1748
1582=head3 Be smart about timeouts 1749=head3 Be smart about timeouts
1583 1750
1584Many real-world problems involve some kind of timeout, usually for error 1751Many real-world problems involve some kind of timeout, usually for error
1585recovery. A typical example is an HTTP request - if the other side hangs, 1752recovery. A typical example is an HTTP request - if the other side hangs,
1671 ev_tstamp timeout = last_activity + 60.; 1838 ev_tstamp timeout = last_activity + 60.;
1672 1839
1673 // if last_activity + 60. is older than now, we did time out 1840 // if last_activity + 60. is older than now, we did time out
1674 if (timeout < now) 1841 if (timeout < now)
1675 { 1842 {
1676 // timeout occured, take action 1843 // timeout occurred, take action
1677 } 1844 }
1678 else 1845 else
1679 { 1846 {
1680 // callback was invoked, but there was some activity, re-arm 1847 // callback was invoked, but there was some activity, re-arm
1681 // the watcher to fire in last_activity + 60, which is 1848 // the watcher to fire in last_activity + 60, which is
1703to the current time (meaning we just have some activity :), then call the 1870to the current time (meaning we just have some activity :), then call the
1704callback, which will "do the right thing" and start the timer: 1871callback, which will "do the right thing" and start the timer:
1705 1872
1706 ev_init (timer, callback); 1873 ev_init (timer, callback);
1707 last_activity = ev_now (loop); 1874 last_activity = ev_now (loop);
1708 callback (loop, timer, EV_TIMEOUT); 1875 callback (loop, timer, EV_TIMER);
1709 1876
1710And when there is some activity, simply store the current time in 1877And when there is some activity, simply store the current time in
1711C<last_activity>, no libev calls at all: 1878C<last_activity>, no libev calls at all:
1712 1879
1713 last_actiivty = ev_now (loop); 1880 last_activity = ev_now (loop);
1714 1881
1715This technique is slightly more complex, but in most cases where the 1882This technique is slightly more complex, but in most cases where the
1716time-out is unlikely to be triggered, much more efficient. 1883time-out is unlikely to be triggered, much more efficient.
1717 1884
1718Changing the timeout is trivial as well (if it isn't hard-coded in the 1885Changing the timeout is trivial as well (if it isn't hard-coded in the
1756 1923
1757=head3 The special problem of time updates 1924=head3 The special problem of time updates
1758 1925
1759Establishing the current time is a costly operation (it usually takes at 1926Establishing the current time is a costly operation (it usually takes at
1760least two system calls): EV therefore updates its idea of the current 1927least two system calls): EV therefore updates its idea of the current
1761time only before and after C<ev_loop> collects new events, which causes a 1928time only before and after C<ev_run> collects new events, which causes a
1762growing difference between C<ev_now ()> and C<ev_time ()> when handling 1929growing difference between C<ev_now ()> and C<ev_time ()> when handling
1763lots of events in one iteration. 1930lots of events in one iteration.
1764 1931
1765The relative timeouts are calculated relative to the C<ev_now ()> 1932The relative timeouts are calculated relative to the C<ev_now ()>
1766time. This is usually the right thing as this timestamp refers to the time 1933time. This is usually the right thing as this timestamp refers to the time
1837C<repeat> value), or reset the running timer to the C<repeat> value. 2004C<repeat> value), or reset the running timer to the C<repeat> value.
1838 2005
1839This sounds a bit complicated, see L<Be smart about timeouts>, above, for a 2006This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1840usage example. 2007usage example.
1841 2008
1842=item ev_timer_remaining (loop, ev_timer *) 2009=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1843 2010
1844Returns the remaining time until a timer fires. If the timer is active, 2011Returns the remaining time until a timer fires. If the timer is active,
1845then this time is relative to the current event loop time, otherwise it's 2012then this time is relative to the current event loop time, otherwise it's
1846the timeout value currently configured. 2013the timeout value currently configured.
1847 2014
1848That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns 2015That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1849C<5>. When the timer is started and one second passes, C<ev_timer_remain> 2016C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
1850will return C<4>. When the timer expires and is restarted, it will return 2017will return C<4>. When the timer expires and is restarted, it will return
1851roughly C<7> (likely slightly less as callback invocation takes some time, 2018roughly C<7> (likely slightly less as callback invocation takes some time,
1852too), and so on. 2019too), and so on.
1853 2020
1854=item ev_tstamp repeat [read-write] 2021=item ev_tstamp repeat [read-write]
1883 } 2050 }
1884 2051
1885 ev_timer mytimer; 2052 ev_timer mytimer;
1886 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 2053 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1887 ev_timer_again (&mytimer); /* start timer */ 2054 ev_timer_again (&mytimer); /* start timer */
1888 ev_loop (loop, 0); 2055 ev_run (loop, 0);
1889 2056
1890 // and in some piece of code that gets executed on any "activity": 2057 // and in some piece of code that gets executed on any "activity":
1891 // reset the timeout to start ticking again at 10 seconds 2058 // reset the timeout to start ticking again at 10 seconds
1892 ev_timer_again (&mytimer); 2059 ev_timer_again (&mytimer);
1893 2060
1919 2086
1920As with timers, the callback is guaranteed to be invoked only when the 2087As with timers, the callback is guaranteed to be invoked only when the
1921point in time where it is supposed to trigger has passed. If multiple 2088point in time where it is supposed to trigger has passed. If multiple
1922timers become ready during the same loop iteration then the ones with 2089timers become ready during the same loop iteration then the ones with
1923earlier time-out values are invoked before ones with later time-out values 2090earlier time-out values are invoked before ones with later time-out values
1924(but this is no longer true when a callback calls C<ev_loop> recursively). 2091(but this is no longer true when a callback calls C<ev_run> recursively).
1925 2092
1926=head3 Watcher-Specific Functions and Data Members 2093=head3 Watcher-Specific Functions and Data Members
1927 2094
1928=over 4 2095=over 4
1929 2096
2057Example: Call a callback every hour, or, more precisely, whenever the 2224Example: Call a callback every hour, or, more precisely, whenever the
2058system time is divisible by 3600. The callback invocation times have 2225system time is divisible by 3600. The callback invocation times have
2059potentially a lot of jitter, but good long-term stability. 2226potentially a lot of jitter, but good long-term stability.
2060 2227
2061 static void 2228 static void
2062 clock_cb (struct ev_loop *loop, ev_io *w, int revents) 2229 clock_cb (struct ev_loop *loop, ev_periodic *w, int revents)
2063 { 2230 {
2064 ... its now a full hour (UTC, or TAI or whatever your clock follows) 2231 ... its now a full hour (UTC, or TAI or whatever your clock follows)
2065 } 2232 }
2066 2233
2067 ev_periodic hourly_tick; 2234 ev_periodic hourly_tick;
2108 2275
2109When the first watcher gets started will libev actually register something 2276When the first watcher gets started will libev actually register something
2110with the kernel (thus it coexists with your own signal handlers as long as 2277with the kernel (thus it coexists with your own signal handlers as long as
2111you don't register any with libev for the same signal). 2278you don't register any with libev for the same signal).
2112 2279
2113Both the signal mask state (C<sigprocmask>) and the signal handler state
2114(C<sigaction>) are unspecified after starting a signal watcher (and after
2115sotpping it again), that is, libev might or might not block the signal,
2116and might or might not set or restore the installed signal handler.
2117
2118If possible and supported, libev will install its handlers with 2280If possible and supported, libev will install its handlers with
2119C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2281C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2120not be unduly interrupted. If you have a problem with system calls getting 2282not be unduly interrupted. If you have a problem with system calls getting
2121interrupted by signals you can block all signals in an C<ev_check> watcher 2283interrupted by signals you can block all signals in an C<ev_check> watcher
2122and unblock them in an C<ev_prepare> watcher. 2284and unblock them in an C<ev_prepare> watcher.
2123 2285
2286=head3 The special problem of inheritance over fork/execve/pthread_create
2287
2288Both the signal mask (C<sigprocmask>) and the signal disposition
2289(C<sigaction>) are unspecified after starting a signal watcher (and after
2290stopping it again), that is, libev might or might not block the signal,
2291and might or might not set or restore the installed signal handler.
2292
2293While this does not matter for the signal disposition (libev never
2294sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2295C<execve>), this matters for the signal mask: many programs do not expect
2296certain signals to be blocked.
2297
2298This means that before calling C<exec> (from the child) you should reset
2299the signal mask to whatever "default" you expect (all clear is a good
2300choice usually).
2301
2302The simplest way to ensure that the signal mask is reset in the child is
2303to install a fork handler with C<pthread_atfork> that resets it. That will
2304catch fork calls done by libraries (such as the libc) as well.
2305
2306In current versions of libev, the signal will not be blocked indefinitely
2307unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2308the window of opportunity for problems, it will not go away, as libev
2309I<has> to modify the signal mask, at least temporarily.
2310
2311So I can't stress this enough: I<If you do not reset your signal mask when
2312you expect it to be empty, you have a race condition in your code>. This
2313is not a libev-specific thing, this is true for most event libraries.
2314
2124=head3 Watcher-Specific Functions and Data Members 2315=head3 Watcher-Specific Functions and Data Members
2125 2316
2126=over 4 2317=over 4
2127 2318
2128=item ev_signal_init (ev_signal *, callback, int signum) 2319=item ev_signal_init (ev_signal *, callback, int signum)
2143Example: Try to exit cleanly on SIGINT. 2334Example: Try to exit cleanly on SIGINT.
2144 2335
2145 static void 2336 static void
2146 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents) 2337 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
2147 { 2338 {
2148 ev_unloop (loop, EVUNLOOP_ALL); 2339 ev_break (loop, EVBREAK_ALL);
2149 } 2340 }
2150 2341
2151 ev_signal signal_watcher; 2342 ev_signal signal_watcher;
2152 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 2343 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
2153 ev_signal_start (loop, &signal_watcher); 2344 ev_signal_start (loop, &signal_watcher);
2539 2730
2540Prepare and check watchers are usually (but not always) used in pairs: 2731Prepare and check watchers are usually (but not always) used in pairs:
2541prepare watchers get invoked before the process blocks and check watchers 2732prepare watchers get invoked before the process blocks and check watchers
2542afterwards. 2733afterwards.
2543 2734
2544You I<must not> call C<ev_loop> or similar functions that enter 2735You I<must not> call C<ev_run> or similar functions that enter
2545the current event loop from either C<ev_prepare> or C<ev_check> 2736the current event loop from either C<ev_prepare> or C<ev_check>
2546watchers. Other loops than the current one are fine, however. The 2737watchers. Other loops than the current one are fine, however. The
2547rationale behind this is that you do not need to check for recursion in 2738rationale behind this is that you do not need to check for recursion in
2548those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 2739those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
2549C<ev_check> so if you have one watcher of each kind they will always be 2740C<ev_check> so if you have one watcher of each kind they will always be
2717 2908
2718 if (timeout >= 0) 2909 if (timeout >= 0)
2719 // create/start timer 2910 // create/start timer
2720 2911
2721 // poll 2912 // poll
2722 ev_loop (EV_A_ 0); 2913 ev_run (EV_A_ 0);
2723 2914
2724 // stop timer again 2915 // stop timer again
2725 if (timeout >= 0) 2916 if (timeout >= 0)
2726 ev_timer_stop (EV_A_ &to); 2917 ev_timer_stop (EV_A_ &to);
2727 2918
2805if you do not want that, you need to temporarily stop the embed watcher). 2996if you do not want that, you need to temporarily stop the embed watcher).
2806 2997
2807=item ev_embed_sweep (loop, ev_embed *) 2998=item ev_embed_sweep (loop, ev_embed *)
2808 2999
2809Make a single, non-blocking sweep over the embedded loop. This works 3000Make a single, non-blocking sweep over the embedded loop. This works
2810similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 3001similarly to C<ev_run (embedded_loop, EVRUN_NOWAIT)>, but in the most
2811appropriate way for embedded loops. 3002appropriate way for embedded loops.
2812 3003
2813=item struct ev_loop *other [read-only] 3004=item struct ev_loop *other [read-only]
2814 3005
2815The embedded event loop. 3006The embedded event loop.
2875C<ev_default_fork> cheats and calls it in the wrong process, the fork 3066C<ev_default_fork> cheats and calls it in the wrong process, the fork
2876handlers will be invoked, too, of course. 3067handlers will be invoked, too, of course.
2877 3068
2878=head3 The special problem of life after fork - how is it possible? 3069=head3 The special problem of life after fork - how is it possible?
2879 3070
2880Most uses of C<fork()> consist of forking, then some simple calls to ste 3071Most uses of C<fork()> consist of forking, then some simple calls to set
2881up/change the process environment, followed by a call to C<exec()>. This 3072up/change the process environment, followed by a call to C<exec()>. This
2882sequence should be handled by libev without any problems. 3073sequence should be handled by libev without any problems.
2883 3074
2884This changes when the application actually wants to do event handling 3075This changes when the application actually wants to do event handling
2885in the child, or both parent in child, in effect "continuing" after the 3076in the child, or both parent in child, in effect "continuing" after the
2901disadvantage of having to use multiple event loops (which do not support 3092disadvantage of having to use multiple event loops (which do not support
2902signal watchers). 3093signal watchers).
2903 3094
2904When this is not possible, or you want to use the default loop for 3095When this is not possible, or you want to use the default loop for
2905other reasons, then in the process that wants to start "fresh", call 3096other reasons, then in the process that wants to start "fresh", call
2906C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying 3097C<ev_loop_destroy (EV_DEFAULT)> followed by C<ev_default_loop (...)>.
2907the default loop will "orphan" (not stop) all registered watchers, so you 3098Destroying the default loop will "orphan" (not stop) all registered
2908have to be careful not to execute code that modifies those watchers. Note 3099watchers, so you have to be careful not to execute code that modifies
2909also that in that case, you have to re-register any signal watchers. 3100those watchers. Note also that in that case, you have to re-register any
3101signal watchers.
2910 3102
2911=head3 Watcher-Specific Functions and Data Members 3103=head3 Watcher-Specific Functions and Data Members
2912 3104
2913=over 4 3105=over 4
2914 3106
2915=item ev_fork_init (ev_signal *, callback) 3107=item ev_fork_init (ev_fork *, callback)
2916 3108
2917Initialises and configures the fork watcher - it has no parameters of any 3109Initialises and configures the fork watcher - it has no parameters of any
2918kind. There is a C<ev_fork_set> macro, but using it is utterly pointless, 3110kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
2919believe me. 3111really.
2920 3112
2921=back 3113=back
2922 3114
2923 3115
3116=head2 C<ev_cleanup> - even the best things end
3117
3118Cleanup watchers are called just before the event loop is being destroyed
3119by a call to C<ev_loop_destroy>.
3120
3121While there is no guarantee that the event loop gets destroyed, cleanup
3122watchers provide a convenient method to install cleanup hooks for your
3123program, worker threads and so on - you just to make sure to destroy the
3124loop when you want them to be invoked.
3125
3126Cleanup watchers are invoked in the same way as any other watcher. Unlike
3127all other watchers, they do not keep a reference to the event loop (which
3128makes a lot of sense if you think about it). Like all other watchers, you
3129can call libev functions in the callback, except C<ev_cleanup_start>.
3130
3131=head3 Watcher-Specific Functions and Data Members
3132
3133=over 4
3134
3135=item ev_cleanup_init (ev_cleanup *, callback)
3136
3137Initialises and configures the cleanup watcher - it has no parameters of
3138any kind. There is a C<ev_cleanup_set> macro, but using it is utterly
3139pointless, I assure you.
3140
3141=back
3142
3143Example: Register an atexit handler to destroy the default loop, so any
3144cleanup functions are called.
3145
3146 static void
3147 program_exits (void)
3148 {
3149 ev_loop_destroy (EV_DEFAULT_UC);
3150 }
3151
3152 ...
3153 atexit (program_exits);
3154
3155
2924=head2 C<ev_async> - how to wake up another event loop 3156=head2 C<ev_async> - how to wake up an event loop
2925 3157
2926In general, you cannot use an C<ev_loop> from multiple threads or other 3158In general, you cannot use an C<ev_run> from multiple threads or other
2927asynchronous sources such as signal handlers (as opposed to multiple event 3159asynchronous sources such as signal handlers (as opposed to multiple event
2928loops - those are of course safe to use in different threads). 3160loops - those are of course safe to use in different threads).
2929 3161
2930Sometimes, however, you need to wake up another event loop you do not 3162Sometimes, however, you need to wake up an event loop you do not control,
2931control, for example because it belongs to another thread. This is what 3163for example because it belongs to another thread. This is what C<ev_async>
2932C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you 3164watchers do: as long as the C<ev_async> watcher is active, you can signal
2933can signal it by calling C<ev_async_send>, which is thread- and signal 3165it by calling C<ev_async_send>, which is thread- and signal safe.
2934safe.
2935 3166
2936This functionality is very similar to C<ev_signal> watchers, as signals, 3167This functionality is very similar to C<ev_signal> watchers, as signals,
2937too, are asynchronous in nature, and signals, too, will be compressed 3168too, are asynchronous in nature, and signals, too, will be compressed
2938(i.e. the number of callback invocations may be less than the number of 3169(i.e. the number of callback invocations may be less than the number of
2939C<ev_async_sent> calls). 3170C<ev_async_sent> calls).
2944=head3 Queueing 3175=head3 Queueing
2945 3176
2946C<ev_async> does not support queueing of data in any way. The reason 3177C<ev_async> does not support queueing of data in any way. The reason
2947is that the author does not know of a simple (or any) algorithm for a 3178is that the author does not know of a simple (or any) algorithm for a
2948multiple-writer-single-reader queue that works in all cases and doesn't 3179multiple-writer-single-reader queue that works in all cases and doesn't
2949need elaborate support such as pthreads. 3180need elaborate support such as pthreads or unportable memory access
3181semantics.
2950 3182
2951That means that if you want to queue data, you have to provide your own 3183That means that if you want to queue data, you have to provide your own
2952queue. But at least I can tell you how to implement locking around your 3184queue. But at least I can tell you how to implement locking around your
2953queue: 3185queue:
2954 3186
3093 3325
3094If C<timeout> is less than 0, then no timeout watcher will be 3326If C<timeout> is less than 0, then no timeout watcher will be
3095started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3327started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3096repeat = 0) will be started. C<0> is a valid timeout. 3328repeat = 0) will be started. C<0> is a valid timeout.
3097 3329
3098The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3330The callback has the type C<void (*cb)(int revents, void *arg)> and is
3099passed an C<revents> set like normal event callbacks (a combination of 3331passed an C<revents> set like normal event callbacks (a combination of
3100C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3332C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
3101value passed to C<ev_once>. Note that it is possible to receive I<both> 3333value passed to C<ev_once>. Note that it is possible to receive I<both>
3102a timeout and an io event at the same time - you probably should give io 3334a timeout and an io event at the same time - you probably should give io
3103events precedence. 3335events precedence.
3104 3336
3105Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3337Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3106 3338
3107 static void stdin_ready (int revents, void *arg) 3339 static void stdin_ready (int revents, void *arg)
3108 { 3340 {
3109 if (revents & EV_READ) 3341 if (revents & EV_READ)
3110 /* stdin might have data for us, joy! */; 3342 /* stdin might have data for us, joy! */;
3111 else if (revents & EV_TIMEOUT) 3343 else if (revents & EV_TIMER)
3112 /* doh, nothing entered */; 3344 /* doh, nothing entered */;
3113 } 3345 }
3114 3346
3115 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3347 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3116 3348
3117=item ev_feed_event (struct ev_loop *, watcher *, int revents)
3118
3119Feeds the given event set into the event loop, as if the specified event
3120had happened for the specified watcher (which must be a pointer to an
3121initialised but not necessarily started event watcher).
3122
3123=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3349=item ev_feed_fd_event (loop, int fd, int revents)
3124 3350
3125Feed an event on the given fd, as if a file descriptor backend detected 3351Feed an event on the given fd, as if a file descriptor backend detected
3126the given events it. 3352the given events it.
3127 3353
3128=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3354=item ev_feed_signal_event (loop, int signum)
3129 3355
3130Feed an event as if the given signal occurred (C<loop> must be the default 3356Feed an event as if the given signal occurred (C<loop> must be the default
3131loop!). 3357loop!).
3132 3358
3133=back 3359=back
3213 3439
3214=over 4 3440=over 4
3215 3441
3216=item ev::TYPE::TYPE () 3442=item ev::TYPE::TYPE ()
3217 3443
3218=item ev::TYPE::TYPE (struct ev_loop *) 3444=item ev::TYPE::TYPE (loop)
3219 3445
3220=item ev::TYPE::~TYPE 3446=item ev::TYPE::~TYPE
3221 3447
3222The constructor (optionally) takes an event loop to associate the watcher 3448The constructor (optionally) takes an event loop to associate the watcher
3223with. If it is omitted, it will use C<EV_DEFAULT>. 3449with. If it is omitted, it will use C<EV_DEFAULT>.
3256 myclass obj; 3482 myclass obj;
3257 ev::io iow; 3483 ev::io iow;
3258 iow.set <myclass, &myclass::io_cb> (&obj); 3484 iow.set <myclass, &myclass::io_cb> (&obj);
3259 3485
3260=item w->set (object *) 3486=item w->set (object *)
3261
3262This is an B<experimental> feature that might go away in a future version.
3263 3487
3264This is a variation of a method callback - leaving out the method to call 3488This is a variation of a method callback - leaving out the method to call
3265will default the method to C<operator ()>, which makes it possible to use 3489will default the method to C<operator ()>, which makes it possible to use
3266functor objects without having to manually specify the C<operator ()> all 3490functor objects without having to manually specify the C<operator ()> all
3267the time. Incidentally, you can then also leave out the template argument 3491the time. Incidentally, you can then also leave out the template argument
3300Example: Use a plain function as callback. 3524Example: Use a plain function as callback.
3301 3525
3302 static void io_cb (ev::io &w, int revents) { } 3526 static void io_cb (ev::io &w, int revents) { }
3303 iow.set <io_cb> (); 3527 iow.set <io_cb> ();
3304 3528
3305=item w->set (struct ev_loop *) 3529=item w->set (loop)
3306 3530
3307Associates a different C<struct ev_loop> with this watcher. You can only 3531Associates a different C<struct ev_loop> with this watcher. You can only
3308do this when the watcher is inactive (and not pending either). 3532do this when the watcher is inactive (and not pending either).
3309 3533
3310=item w->set ([arguments]) 3534=item w->set ([arguments])
3311 3535
3312Basically the same as C<ev_TYPE_set>, with the same arguments. Must be 3536Basically the same as C<ev_TYPE_set>, with the same arguments. Either this
3313called at least once. Unlike the C counterpart, an active watcher gets 3537method or a suitable start method must be called at least once. Unlike the
3314automatically stopped and restarted when reconfiguring it with this 3538C counterpart, an active watcher gets automatically stopped and restarted
3315method. 3539when reconfiguring it with this method.
3316 3540
3317=item w->start () 3541=item w->start ()
3318 3542
3319Starts the watcher. Note that there is no C<loop> argument, as the 3543Starts the watcher. Note that there is no C<loop> argument, as the
3320constructor already stores the event loop. 3544constructor already stores the event loop.
3321 3545
3546=item w->start ([arguments])
3547
3548Instead of calling C<set> and C<start> methods separately, it is often
3549convenient to wrap them in one call. Uses the same type of arguments as
3550the configure C<set> method of the watcher.
3551
3322=item w->stop () 3552=item w->stop ()
3323 3553
3324Stops the watcher if it is active. Again, no C<loop> argument. 3554Stops the watcher if it is active. Again, no C<loop> argument.
3325 3555
3326=item w->again () (C<ev::timer>, C<ev::periodic> only) 3556=item w->again () (C<ev::timer>, C<ev::periodic> only)
3338 3568
3339=back 3569=back
3340 3570
3341=back 3571=back
3342 3572
3343Example: Define a class with an IO and idle watcher, start one of them in 3573Example: Define a class with two I/O and idle watchers, start the I/O
3344the constructor. 3574watchers in the constructor.
3345 3575
3346 class myclass 3576 class myclass
3347 { 3577 {
3348 ev::io io ; void io_cb (ev::io &w, int revents); 3578 ev::io io ; void io_cb (ev::io &w, int revents);
3579 ev::io2 io2 ; void io2_cb (ev::io &w, int revents);
3349 ev::idle idle; void idle_cb (ev::idle &w, int revents); 3580 ev::idle idle; void idle_cb (ev::idle &w, int revents);
3350 3581
3351 myclass (int fd) 3582 myclass (int fd)
3352 { 3583 {
3353 io .set <myclass, &myclass::io_cb > (this); 3584 io .set <myclass, &myclass::io_cb > (this);
3585 io2 .set <myclass, &myclass::io2_cb > (this);
3354 idle.set <myclass, &myclass::idle_cb> (this); 3586 idle.set <myclass, &myclass::idle_cb> (this);
3355 3587
3356 io.start (fd, ev::READ); 3588 io.set (fd, ev::WRITE); // configure the watcher
3589 io.start (); // start it whenever convenient
3590
3591 io2.start (fd, ev::READ); // set + start in one call
3357 } 3592 }
3358 }; 3593 };
3359 3594
3360 3595
3361=head1 OTHER LANGUAGE BINDINGS 3596=head1 OTHER LANGUAGE BINDINGS
3407=item Ocaml 3642=item Ocaml
3408 3643
3409Erkki Seppala has written Ocaml bindings for libev, to be found at 3644Erkki Seppala has written Ocaml bindings for libev, to be found at
3410L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3645L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3411 3646
3647=item Lua
3648
3649Brian Maher has written a partial interface to libev for lua (at the
3650time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3651L<http://github.com/brimworks/lua-ev>.
3652
3412=back 3653=back
3413 3654
3414 3655
3415=head1 MACRO MAGIC 3656=head1 MACRO MAGIC
3416 3657
3429loop argument"). The C<EV_A> form is used when this is the sole argument, 3670loop argument"). The C<EV_A> form is used when this is the sole argument,
3430C<EV_A_> is used when other arguments are following. Example: 3671C<EV_A_> is used when other arguments are following. Example:
3431 3672
3432 ev_unref (EV_A); 3673 ev_unref (EV_A);
3433 ev_timer_add (EV_A_ watcher); 3674 ev_timer_add (EV_A_ watcher);
3434 ev_loop (EV_A_ 0); 3675 ev_run (EV_A_ 0);
3435 3676
3436It assumes the variable C<loop> of type C<struct ev_loop *> is in scope, 3677It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
3437which is often provided by the following macro. 3678which is often provided by the following macro.
3438 3679
3439=item C<EV_P>, C<EV_P_> 3680=item C<EV_P>, C<EV_P_>
3479 } 3720 }
3480 3721
3481 ev_check check; 3722 ev_check check;
3482 ev_check_init (&check, check_cb); 3723 ev_check_init (&check, check_cb);
3483 ev_check_start (EV_DEFAULT_ &check); 3724 ev_check_start (EV_DEFAULT_ &check);
3484 ev_loop (EV_DEFAULT_ 0); 3725 ev_run (EV_DEFAULT_ 0);
3485 3726
3486=head1 EMBEDDING 3727=head1 EMBEDDING
3487 3728
3488Libev can (and often is) directly embedded into host 3729Libev can (and often is) directly embedded into host
3489applications. Examples of applications that embed it include the Deliantra 3730applications. Examples of applications that embed it include the Deliantra
3569 libev.m4 3810 libev.m4
3570 3811
3571=head2 PREPROCESSOR SYMBOLS/MACROS 3812=head2 PREPROCESSOR SYMBOLS/MACROS
3572 3813
3573Libev can be configured via a variety of preprocessor symbols you have to 3814Libev can be configured via a variety of preprocessor symbols you have to
3574define before including any of its files. The default in the absence of 3815define before including (or compiling) any of its files. The default in
3575autoconf is documented for every option. 3816the absence of autoconf is documented for every option.
3817
3818Symbols marked with "(h)" do not change the ABI, and can have different
3819values when compiling libev vs. including F<ev.h>, so it is permissible
3820to redefine them before including F<ev.h> without breaking compatibility
3821to a compiled library. All other symbols change the ABI, which means all
3822users of libev and the libev code itself must be compiled with compatible
3823settings.
3576 3824
3577=over 4 3825=over 4
3578 3826
3827=item EV_COMPAT3 (h)
3828
3829Backwards compatibility is a major concern for libev. This is why this
3830release of libev comes with wrappers for the functions and symbols that
3831have been renamed between libev version 3 and 4.
3832
3833You can disable these wrappers (to test compatibility with future
3834versions) by defining C<EV_COMPAT3> to C<0> when compiling your
3835sources. This has the additional advantage that you can drop the C<struct>
3836from C<struct ev_loop> declarations, as libev will provide an C<ev_loop>
3837typedef in that case.
3838
3839In some future version, the default for C<EV_COMPAT3> will become C<0>,
3840and in some even more future version the compatibility code will be
3841removed completely.
3842
3579=item EV_STANDALONE 3843=item EV_STANDALONE (h)
3580 3844
3581Must always be C<1> if you do not use autoconf configuration, which 3845Must always be C<1> if you do not use autoconf configuration, which
3582keeps libev from including F<config.h>, and it also defines dummy 3846keeps libev from including F<config.h>, and it also defines dummy
3583implementations for some libevent functions (such as logging, which is not 3847implementations for some libevent functions (such as logging, which is not
3584supported). It will also not define any of the structs usually found in 3848supported). It will also not define any of the structs usually found in
3657be used is the winsock select). This means that it will call 3921be used is the winsock select). This means that it will call
3658C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3922C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3659it is assumed that all these functions actually work on fds, even 3923it is assumed that all these functions actually work on fds, even
3660on win32. Should not be defined on non-win32 platforms. 3924on win32. Should not be defined on non-win32 platforms.
3661 3925
3662=item EV_FD_TO_WIN32_HANDLE 3926=item EV_FD_TO_WIN32_HANDLE(fd)
3663 3927
3664If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3928If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3665file descriptors to socket handles. When not defining this symbol (the 3929file descriptors to socket handles. When not defining this symbol (the
3666default), then libev will call C<_get_osfhandle>, which is usually 3930default), then libev will call C<_get_osfhandle>, which is usually
3667correct. In some cases, programs use their own file descriptor management, 3931correct. In some cases, programs use their own file descriptor management,
3668in which case they can provide this function to map fds to socket handles. 3932in which case they can provide this function to map fds to socket handles.
3933
3934=item EV_WIN32_HANDLE_TO_FD(handle)
3935
3936If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3937using the standard C<_open_osfhandle> function. For programs implementing
3938their own fd to handle mapping, overwriting this function makes it easier
3939to do so. This can be done by defining this macro to an appropriate value.
3940
3941=item EV_WIN32_CLOSE_FD(fd)
3942
3943If programs implement their own fd to handle mapping on win32, then this
3944macro can be used to override the C<close> function, useful to unregister
3945file descriptors again. Note that the replacement function has to close
3946the underlying OS handle.
3669 3947
3670=item EV_USE_POLL 3948=item EV_USE_POLL
3671 3949
3672If defined to be C<1>, libev will compile in support for the C<poll>(2) 3950If defined to be C<1>, libev will compile in support for the C<poll>(2)
3673backend. Otherwise it will be enabled on non-win32 platforms. It 3951backend. Otherwise it will be enabled on non-win32 platforms. It
3720as well as for signal and thread safety in C<ev_async> watchers. 3998as well as for signal and thread safety in C<ev_async> watchers.
3721 3999
3722In the absence of this define, libev will use C<sig_atomic_t volatile> 4000In the absence of this define, libev will use C<sig_atomic_t volatile>
3723(from F<signal.h>), which is usually good enough on most platforms. 4001(from F<signal.h>), which is usually good enough on most platforms.
3724 4002
3725=item EV_H 4003=item EV_H (h)
3726 4004
3727The name of the F<ev.h> header file used to include it. The default if 4005The name of the F<ev.h> header file used to include it. The default if
3728undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 4006undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3729used to virtually rename the F<ev.h> header file in case of conflicts. 4007used to virtually rename the F<ev.h> header file in case of conflicts.
3730 4008
3731=item EV_CONFIG_H 4009=item EV_CONFIG_H (h)
3732 4010
3733If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 4011If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3734F<ev.c>'s idea of where to find the F<config.h> file, similarly to 4012F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3735C<EV_H>, above. 4013C<EV_H>, above.
3736 4014
3737=item EV_EVENT_H 4015=item EV_EVENT_H (h)
3738 4016
3739Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 4017Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3740of how the F<event.h> header can be found, the default is C<"event.h">. 4018of how the F<event.h> header can be found, the default is C<"event.h">.
3741 4019
3742=item EV_PROTOTYPES 4020=item EV_PROTOTYPES (h)
3743 4021
3744If defined to be C<0>, then F<ev.h> will not define any function 4022If defined to be C<0>, then F<ev.h> will not define any function
3745prototypes, but still define all the structs and other symbols. This is 4023prototypes, but still define all the structs and other symbols. This is
3746occasionally useful if you want to provide your own wrapper functions 4024occasionally useful if you want to provide your own wrapper functions
3747around libev functions. 4025around libev functions.
3769fine. 4047fine.
3770 4048
3771If your embedding application does not need any priorities, defining these 4049If your embedding application does not need any priorities, defining these
3772both to C<0> will save some memory and CPU. 4050both to C<0> will save some memory and CPU.
3773 4051
3774=item EV_PERIODIC_ENABLE 4052=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
4053EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
4054EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3775 4055
3776If undefined or defined to be C<1>, then periodic timers are supported. If 4056If undefined or defined to be C<1> (and the platform supports it), then
3777defined to be C<0>, then they are not. Disabling them saves a few kB of 4057the respective watcher type is supported. If defined to be C<0>, then it
3778code. 4058is not. Disabling watcher types mainly saves code size.
3779 4059
3780=item EV_IDLE_ENABLE 4060=item EV_FEATURES
3781
3782If undefined or defined to be C<1>, then idle watchers are supported. If
3783defined to be C<0>, then they are not. Disabling them saves a few kB of
3784code.
3785
3786=item EV_EMBED_ENABLE
3787
3788If undefined or defined to be C<1>, then embed watchers are supported. If
3789defined to be C<0>, then they are not. Embed watchers rely on most other
3790watcher types, which therefore must not be disabled.
3791
3792=item EV_STAT_ENABLE
3793
3794If undefined or defined to be C<1>, then stat watchers are supported. If
3795defined to be C<0>, then they are not.
3796
3797=item EV_FORK_ENABLE
3798
3799If undefined or defined to be C<1>, then fork watchers are supported. If
3800defined to be C<0>, then they are not.
3801
3802=item EV_ASYNC_ENABLE
3803
3804If undefined or defined to be C<1>, then async watchers are supported. If
3805defined to be C<0>, then they are not.
3806
3807=item EV_MINIMAL
3808 4061
3809If you need to shave off some kilobytes of code at the expense of some 4062If you need to shave off some kilobytes of code at the expense of some
3810speed (but with the full API), define this symbol to C<1>. Currently this 4063speed (but with the full API), you can define this symbol to request
3811is used to override some inlining decisions, saves roughly 30% code size 4064certain subsets of functionality. The default is to enable all features
3812on amd64. It also selects a much smaller 2-heap for timer management over 4065that can be enabled on the platform.
3813the default 4-heap.
3814 4066
3815You can save even more by disabling watcher types you do not need 4067A typical way to use this symbol is to define it to C<0> (or to a bitset
3816and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 4068with some broad features you want) and then selectively re-enable
3817(C<-DNDEBUG>) will usually reduce code size a lot. 4069additional parts you want, for example if you want everything minimal,
4070but multiple event loop support, async and child watchers and the poll
4071backend, use this:
3818 4072
3819Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 4073 #define EV_FEATURES 0
3820provide a bare-bones event library. See C<ev.h> for details on what parts 4074 #define EV_MULTIPLICITY 1
3821of the API are still available, and do not complain if this subset changes 4075 #define EV_USE_POLL 1
3822over time. 4076 #define EV_CHILD_ENABLE 1
4077 #define EV_ASYNC_ENABLE 1
4078
4079The actual value is a bitset, it can be a combination of the following
4080values:
4081
4082=over 4
4083
4084=item C<1> - faster/larger code
4085
4086Use larger code to speed up some operations.
4087
4088Currently this is used to override some inlining decisions (enlarging the
4089code size by roughly 30% on amd64).
4090
4091When optimising for size, use of compiler flags such as C<-Os> with
4092gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
4093assertions.
4094
4095=item C<2> - faster/larger data structures
4096
4097Replaces the small 2-heap for timer management by a faster 4-heap, larger
4098hash table sizes and so on. This will usually further increase code size
4099and can additionally have an effect on the size of data structures at
4100runtime.
4101
4102=item C<4> - full API configuration
4103
4104This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
4105enables multiplicity (C<EV_MULTIPLICITY>=1).
4106
4107=item C<8> - full API
4108
4109This enables a lot of the "lesser used" API functions. See C<ev.h> for
4110details on which parts of the API are still available without this
4111feature, and do not complain if this subset changes over time.
4112
4113=item C<16> - enable all optional watcher types
4114
4115Enables all optional watcher types. If you want to selectively enable
4116only some watcher types other than I/O and timers (e.g. prepare,
4117embed, async, child...) you can enable them manually by defining
4118C<EV_watchertype_ENABLE> to C<1> instead.
4119
4120=item C<32> - enable all backends
4121
4122This enables all backends - without this feature, you need to enable at
4123least one backend manually (C<EV_USE_SELECT> is a good choice).
4124
4125=item C<64> - enable OS-specific "helper" APIs
4126
4127Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
4128default.
4129
4130=back
4131
4132Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
4133reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
4134code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
4135watchers, timers and monotonic clock support.
4136
4137With an intelligent-enough linker (gcc+binutils are intelligent enough
4138when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
4139your program might be left out as well - a binary starting a timer and an
4140I/O watcher then might come out at only 5Kb.
4141
4142=item EV_AVOID_STDIO
4143
4144If this is set to C<1> at compiletime, then libev will avoid using stdio
4145functions (printf, scanf, perror etc.). This will increase the code size
4146somewhat, but if your program doesn't otherwise depend on stdio and your
4147libc allows it, this avoids linking in the stdio library which is quite
4148big.
4149
4150Note that error messages might become less precise when this option is
4151enabled.
3823 4152
3824=item EV_NSIG 4153=item EV_NSIG
3825 4154
3826The highest supported signal number, +1 (or, the number of 4155The highest supported signal number, +1 (or, the number of
3827signals): Normally, libev tries to deduce the maximum number of signals 4156signals): Normally, libev tries to deduce the maximum number of signals
3828automatically, but sometimes this fails, in which case it can be 4157automatically, but sometimes this fails, in which case it can be
3829specified. Also, using a lower number than detected (C<32> should be 4158specified. Also, using a lower number than detected (C<32> should be
3830good for about any system in existance) can save some memory, as libev 4159good for about any system in existence) can save some memory, as libev
3831statically allocates some 12-24 bytes per signal number. 4160statically allocates some 12-24 bytes per signal number.
3832 4161
3833=item EV_PID_HASHSIZE 4162=item EV_PID_HASHSIZE
3834 4163
3835C<ev_child> watchers use a small hash table to distribute workload by 4164C<ev_child> watchers use a small hash table to distribute workload by
3836pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 4165pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3837than enough. If you need to manage thousands of children you might want to 4166usually more than enough. If you need to manage thousands of children you
3838increase this value (I<must> be a power of two). 4167might want to increase this value (I<must> be a power of two).
3839 4168
3840=item EV_INOTIFY_HASHSIZE 4169=item EV_INOTIFY_HASHSIZE
3841 4170
3842C<ev_stat> watchers use a small hash table to distribute workload by 4171C<ev_stat> watchers use a small hash table to distribute workload by
3843inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4172inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3844usually more than enough. If you need to manage thousands of C<ev_stat> 4173disabled), usually more than enough. If you need to manage thousands of
3845watchers you might want to increase this value (I<must> be a power of 4174C<ev_stat> watchers you might want to increase this value (I<must> be a
3846two). 4175power of two).
3847 4176
3848=item EV_USE_4HEAP 4177=item EV_USE_4HEAP
3849 4178
3850Heaps are not very cache-efficient. To improve the cache-efficiency of the 4179Heaps are not very cache-efficient. To improve the cache-efficiency of the
3851timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4180timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3852to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4181to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3853faster performance with many (thousands) of watchers. 4182faster performance with many (thousands) of watchers.
3854 4183
3855The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4184The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3856(disabled). 4185will be C<0>.
3857 4186
3858=item EV_HEAP_CACHE_AT 4187=item EV_HEAP_CACHE_AT
3859 4188
3860Heaps are not very cache-efficient. To improve the cache-efficiency of the 4189Heaps are not very cache-efficient. To improve the cache-efficiency of the
3861timer and periodics heaps, libev can cache the timestamp (I<at>) within 4190timer and periodics heaps, libev can cache the timestamp (I<at>) within
3862the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4191the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3863which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4192which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3864but avoids random read accesses on heap changes. This improves performance 4193but avoids random read accesses on heap changes. This improves performance
3865noticeably with many (hundreds) of watchers. 4194noticeably with many (hundreds) of watchers.
3866 4195
3867The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4196The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3868(disabled). 4197will be C<0>.
3869 4198
3870=item EV_VERIFY 4199=item EV_VERIFY
3871 4200
3872Controls how much internal verification (see C<ev_loop_verify ()>) will 4201Controls how much internal verification (see C<ev_verify ()>) will
3873be done: If set to C<0>, no internal verification code will be compiled 4202be done: If set to C<0>, no internal verification code will be compiled
3874in. If set to C<1>, then verification code will be compiled in, but not 4203in. If set to C<1>, then verification code will be compiled in, but not
3875called. If set to C<2>, then the internal verification code will be 4204called. If set to C<2>, then the internal verification code will be
3876called once per loop, which can slow down libev. If set to C<3>, then the 4205called once per loop, which can slow down libev. If set to C<3>, then the
3877verification code will be called very frequently, which will slow down 4206verification code will be called very frequently, which will slow down
3878libev considerably. 4207libev considerably.
3879 4208
3880The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4209The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3881C<0>. 4210will be C<0>.
3882 4211
3883=item EV_COMMON 4212=item EV_COMMON
3884 4213
3885By default, all watchers have a C<void *data> member. By redefining 4214By default, all watchers have a C<void *data> member. By redefining
3886this macro to a something else you can include more and other types of 4215this macro to something else you can include more and other types of
3887members. You have to define it each time you include one of the files, 4216members. You have to define it each time you include one of the files,
3888though, and it must be identical each time. 4217though, and it must be identical each time.
3889 4218
3890For example, the perl EV module uses something like this: 4219For example, the perl EV module uses something like this:
3891 4220
3944file. 4273file.
3945 4274
3946The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4275The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3947that everybody includes and which overrides some configure choices: 4276that everybody includes and which overrides some configure choices:
3948 4277
3949 #define EV_MINIMAL 1 4278 #define EV_FEATURES 8
3950 #define EV_USE_POLL 0 4279 #define EV_USE_SELECT 1
3951 #define EV_MULTIPLICITY 0
3952 #define EV_PERIODIC_ENABLE 0 4280 #define EV_PREPARE_ENABLE 1
4281 #define EV_IDLE_ENABLE 1
3953 #define EV_STAT_ENABLE 0 4282 #define EV_SIGNAL_ENABLE 1
3954 #define EV_FORK_ENABLE 0 4283 #define EV_CHILD_ENABLE 1
4284 #define EV_USE_STDEXCEPT 0
3955 #define EV_CONFIG_H <config.h> 4285 #define EV_CONFIG_H <config.h>
3956 #define EV_MINPRI 0
3957 #define EV_MAXPRI 0
3958 4286
3959 #include "ev++.h" 4287 #include "ev++.h"
3960 4288
3961And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4289And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3962 4290
4093 userdata *u = ev_userdata (EV_A); 4421 userdata *u = ev_userdata (EV_A);
4094 pthread_mutex_lock (&u->lock); 4422 pthread_mutex_lock (&u->lock);
4095 } 4423 }
4096 4424
4097The event loop thread first acquires the mutex, and then jumps straight 4425The event loop thread first acquires the mutex, and then jumps straight
4098into C<ev_loop>: 4426into C<ev_run>:
4099 4427
4100 void * 4428 void *
4101 l_run (void *thr_arg) 4429 l_run (void *thr_arg)
4102 { 4430 {
4103 struct ev_loop *loop = (struct ev_loop *)thr_arg; 4431 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4104 4432
4105 l_acquire (EV_A); 4433 l_acquire (EV_A);
4106 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0); 4434 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4107 ev_loop (EV_A_ 0); 4435 ev_run (EV_A_ 0);
4108 l_release (EV_A); 4436 l_release (EV_A);
4109 4437
4110 return 0; 4438 return 0;
4111 } 4439 }
4112 4440
4164 4492
4165=head3 COROUTINES 4493=head3 COROUTINES
4166 4494
4167Libev is very accommodating to coroutines ("cooperative threads"): 4495Libev is very accommodating to coroutines ("cooperative threads"):
4168libev fully supports nesting calls to its functions from different 4496libev fully supports nesting calls to its functions from different
4169coroutines (e.g. you can call C<ev_loop> on the same loop from two 4497coroutines (e.g. you can call C<ev_run> on the same loop from two
4170different coroutines, and switch freely between both coroutines running 4498different coroutines, and switch freely between both coroutines running
4171the loop, as long as you don't confuse yourself). The only exception is 4499the loop, as long as you don't confuse yourself). The only exception is
4172that you must not do this from C<ev_periodic> reschedule callbacks. 4500that you must not do this from C<ev_periodic> reschedule callbacks.
4173 4501
4174Care has been taken to ensure that libev does not keep local state inside 4502Care has been taken to ensure that libev does not keep local state inside
4175C<ev_loop>, and other calls do not usually allow for coroutine switches as 4503C<ev_run>, and other calls do not usually allow for coroutine switches as
4176they do not call any callbacks. 4504they do not call any callbacks.
4177 4505
4178=head2 COMPILER WARNINGS 4506=head2 COMPILER WARNINGS
4179 4507
4180Depending on your compiler and compiler settings, you might get no or a 4508Depending on your compiler and compiler settings, you might get no or a
4191maintainable. 4519maintainable.
4192 4520
4193And of course, some compiler warnings are just plain stupid, or simply 4521And of course, some compiler warnings are just plain stupid, or simply
4194wrong (because they don't actually warn about the condition their message 4522wrong (because they don't actually warn about the condition their message
4195seems to warn about). For example, certain older gcc versions had some 4523seems to warn about). For example, certain older gcc versions had some
4196warnings that resulted an extreme number of false positives. These have 4524warnings that resulted in an extreme number of false positives. These have
4197been fixed, but some people still insist on making code warn-free with 4525been fixed, but some people still insist on making code warn-free with
4198such buggy versions. 4526such buggy versions.
4199 4527
4200While libev is written to generate as few warnings as possible, 4528While libev is written to generate as few warnings as possible,
4201"warn-free" code is not a goal, and it is recommended not to build libev 4529"warn-free" code is not a goal, and it is recommended not to build libev
4237I suggest using suppression lists. 4565I suggest using suppression lists.
4238 4566
4239 4567
4240=head1 PORTABILITY NOTES 4568=head1 PORTABILITY NOTES
4241 4569
4570=head2 GNU/LINUX 32 BIT LIMITATIONS
4571
4572GNU/Linux is the only common platform that supports 64 bit file/large file
4573interfaces but I<disables> them by default.
4574
4575That means that libev compiled in the default environment doesn't support
4576files larger than 2GiB or so, which mainly affects C<ev_stat> watchers.
4577
4578Unfortunately, many programs try to work around this GNU/Linux issue
4579by enabling the large file API, which makes them incompatible with the
4580standard libev compiled for their system.
4581
4582Likewise, libev cannot enable the large file API itself as this would
4583suddenly make it incompatible to the default compile time environment,
4584i.e. all programs not using special compile switches.
4585
4586=head2 OS/X AND DARWIN BUGS
4587
4588The whole thing is a bug if you ask me - basically any system interface
4589you touch is broken, whether it is locales, poll, kqueue or even the
4590OpenGL drivers.
4591
4592=head3 C<kqueue> is buggy
4593
4594The kqueue syscall is broken in all known versions - most versions support
4595only sockets, many support pipes.
4596
4597Libev tries to work around this by not using C<kqueue> by default on this
4598rotten platform, but of course you can still ask for it when creating a
4599loop - embedding a socket-only kqueue loop into a select-based one is
4600probably going to work well.
4601
4602=head3 C<poll> is buggy
4603
4604Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
4605implementation by something calling C<kqueue> internally around the 10.5.6
4606release, so now C<kqueue> I<and> C<poll> are broken.
4607
4608Libev tries to work around this by not using C<poll> by default on
4609this rotten platform, but of course you can still ask for it when creating
4610a loop.
4611
4612=head3 C<select> is buggy
4613
4614All that's left is C<select>, and of course Apple found a way to fuck this
4615one up as well: On OS/X, C<select> actively limits the number of file
4616descriptors you can pass in to 1024 - your program suddenly crashes when
4617you use more.
4618
4619There is an undocumented "workaround" for this - defining
4620C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
4621work on OS/X.
4622
4623=head2 SOLARIS PROBLEMS AND WORKAROUNDS
4624
4625=head3 C<errno> reentrancy
4626
4627The default compile environment on Solaris is unfortunately so
4628thread-unsafe that you can't even use components/libraries compiled
4629without C<-D_REENTRANT> in a threaded program, which, of course, isn't
4630defined by default. A valid, if stupid, implementation choice.
4631
4632If you want to use libev in threaded environments you have to make sure
4633it's compiled with C<_REENTRANT> defined.
4634
4635=head3 Event port backend
4636
4637The scalable event interface for Solaris is called "event
4638ports". Unfortunately, this mechanism is very buggy in all major
4639releases. If you run into high CPU usage, your program freezes or you get
4640a large number of spurious wakeups, make sure you have all the relevant
4641and latest kernel patches applied. No, I don't know which ones, but there
4642are multiple ones to apply, and afterwards, event ports actually work
4643great.
4644
4645If you can't get it to work, you can try running the program by setting
4646the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and
4647C<select> backends.
4648
4649=head2 AIX POLL BUG
4650
4651AIX unfortunately has a broken C<poll.h> header. Libev works around
4652this by trying to avoid the poll backend altogether (i.e. it's not even
4653compiled in), which normally isn't a big problem as C<select> works fine
4654with large bitsets on AIX, and AIX is dead anyway.
4655
4242=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 4656=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
4657
4658=head3 General issues
4243 4659
4244Win32 doesn't support any of the standards (e.g. POSIX) that libev 4660Win32 doesn't support any of the standards (e.g. POSIX) that libev
4245requires, and its I/O model is fundamentally incompatible with the POSIX 4661requires, and its I/O model is fundamentally incompatible with the POSIX
4246model. Libev still offers limited functionality on this platform in 4662model. Libev still offers limited functionality on this platform in
4247the form of the C<EVBACKEND_SELECT> backend, and only supports socket 4663the form of the C<EVBACKEND_SELECT> backend, and only supports socket
4248descriptors. This only applies when using Win32 natively, not when using 4664descriptors. This only applies when using Win32 natively, not when using
4249e.g. cygwin. 4665e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4666as every compielr comes with a slightly differently broken/incompatible
4667environment.
4250 4668
4251Lifting these limitations would basically require the full 4669Lifting these limitations would basically require the full
4252re-implementation of the I/O system. If you are into these kinds of 4670re-implementation of the I/O system. If you are into this kind of thing,
4253things, then note that glib does exactly that for you in a very portable 4671then note that glib does exactly that for you in a very portable way (note
4254way (note also that glib is the slowest event library known to man). 4672also that glib is the slowest event library known to man).
4255 4673
4256There is no supported compilation method available on windows except 4674There is no supported compilation method available on windows except
4257embedding it into other applications. 4675embedding it into other applications.
4258 4676
4259Sensible signal handling is officially unsupported by Microsoft - libev 4677Sensible signal handling is officially unsupported by Microsoft - libev
4287you do I<not> compile the F<ev.c> or any other embedded source files!): 4705you do I<not> compile the F<ev.c> or any other embedded source files!):
4288 4706
4289 #include "evwrap.h" 4707 #include "evwrap.h"
4290 #include "ev.c" 4708 #include "ev.c"
4291 4709
4292=over 4
4293
4294=item The winsocket select function 4710=head3 The winsocket C<select> function
4295 4711
4296The winsocket C<select> function doesn't follow POSIX in that it 4712The winsocket C<select> function doesn't follow POSIX in that it
4297requires socket I<handles> and not socket I<file descriptors> (it is 4713requires socket I<handles> and not socket I<file descriptors> (it is
4298also extremely buggy). This makes select very inefficient, and also 4714also extremely buggy). This makes select very inefficient, and also
4299requires a mapping from file descriptors to socket handles (the Microsoft 4715requires a mapping from file descriptors to socket handles (the Microsoft
4308 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 4724 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
4309 4725
4310Note that winsockets handling of fd sets is O(n), so you can easily get a 4726Note that winsockets handling of fd sets is O(n), so you can easily get a
4311complexity in the O(n²) range when using win32. 4727complexity in the O(n²) range when using win32.
4312 4728
4313=item Limited number of file descriptors 4729=head3 Limited number of file descriptors
4314 4730
4315Windows has numerous arbitrary (and low) limits on things. 4731Windows has numerous arbitrary (and low) limits on things.
4316 4732
4317Early versions of winsocket's select only supported waiting for a maximum 4733Early versions of winsocket's select only supported waiting for a maximum
4318of C<64> handles (probably owning to the fact that all windows kernels 4734of C<64> handles (probably owning to the fact that all windows kernels
4333runtime libraries. This might get you to about C<512> or C<2048> sockets 4749runtime libraries. This might get you to about C<512> or C<2048> sockets
4334(depending on windows version and/or the phase of the moon). To get more, 4750(depending on windows version and/or the phase of the moon). To get more,
4335you need to wrap all I/O functions and provide your own fd management, but 4751you need to wrap all I/O functions and provide your own fd management, but
4336the cost of calling select (O(n²)) will likely make this unworkable. 4752the cost of calling select (O(n²)) will likely make this unworkable.
4337 4753
4338=back
4339
4340=head2 PORTABILITY REQUIREMENTS 4754=head2 PORTABILITY REQUIREMENTS
4341 4755
4342In addition to a working ISO-C implementation and of course the 4756In addition to a working ISO-C implementation and of course the
4343backend-specific APIs, libev relies on a few additional extensions: 4757backend-specific APIs, libev relies on a few additional extensions:
4344 4758
4350Libev assumes not only that all watcher pointers have the same internal 4764Libev assumes not only that all watcher pointers have the same internal
4351structure (guaranteed by POSIX but not by ISO C for example), but it also 4765structure (guaranteed by POSIX but not by ISO C for example), but it also
4352assumes that the same (machine) code can be used to call any watcher 4766assumes that the same (machine) code can be used to call any watcher
4353callback: The watcher callbacks have different type signatures, but libev 4767callback: The watcher callbacks have different type signatures, but libev
4354calls them using an C<ev_watcher *> internally. 4768calls them using an C<ev_watcher *> internally.
4769
4770=item pointer accesses must be thread-atomic
4771
4772Accessing a pointer value must be atomic, it must both be readable and
4773writable in one piece - this is the case on all current architectures.
4355 4774
4356=item C<sig_atomic_t volatile> must be thread-atomic as well 4775=item C<sig_atomic_t volatile> must be thread-atomic as well
4357 4776
4358The type C<sig_atomic_t volatile> (or whatever is defined as 4777The type C<sig_atomic_t volatile> (or whatever is defined as
4359C<EV_ATOMIC_T>) must be atomic with respect to accesses from different 4778C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
4382watchers. 4801watchers.
4383 4802
4384=item C<double> must hold a time value in seconds with enough accuracy 4803=item C<double> must hold a time value in seconds with enough accuracy
4385 4804
4386The type C<double> is used to represent timestamps. It is required to 4805The type C<double> is used to represent timestamps. It is required to
4387have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4806have at least 51 bits of mantissa (and 9 bits of exponent), which is
4388enough for at least into the year 4000. This requirement is fulfilled by 4807good enough for at least into the year 4000 with millisecond accuracy
4808(the design goal for libev). This requirement is overfulfilled by
4389implementations implementing IEEE 754, which is basically all existing 4809implementations using IEEE 754, which is basically all existing ones. With
4390ones. With IEEE 754 doubles, you get microsecond accuracy until at least 4810IEEE 754 doubles, you get microsecond accuracy until at least 2200.
43912200.
4392 4811
4393=back 4812=back
4394 4813
4395If you know of other additional requirements drop me a note. 4814If you know of other additional requirements drop me a note.
4396 4815
4464involves iterating over all running async watchers or all signal numbers. 4883involves iterating over all running async watchers or all signal numbers.
4465 4884
4466=back 4885=back
4467 4886
4468 4887
4888=head1 PORTING FROM LIBEV 3.X TO 4.X
4889
4890The major version 4 introduced some incompatible changes to the API.
4891
4892At the moment, the C<ev.h> header file provides compatibility definitions
4893for all changes, so most programs should still compile. The compatibility
4894layer might be removed in later versions of libev, so better update to the
4895new API early than late.
4896
4897=over 4
4898
4899=item C<EV_COMPAT3> backwards compatibility mechanism
4900
4901The backward compatibility mechanism can be controlled by
4902C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
4903section.
4904
4905=item C<ev_default_destroy> and C<ev_default_fork> have been removed
4906
4907These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
4908
4909 ev_loop_destroy (EV_DEFAULT_UC);
4910 ev_loop_fork (EV_DEFAULT);
4911
4912=item function/symbol renames
4913
4914A number of functions and symbols have been renamed:
4915
4916 ev_loop => ev_run
4917 EVLOOP_NONBLOCK => EVRUN_NOWAIT
4918 EVLOOP_ONESHOT => EVRUN_ONCE
4919
4920 ev_unloop => ev_break
4921 EVUNLOOP_CANCEL => EVBREAK_CANCEL
4922 EVUNLOOP_ONE => EVBREAK_ONE
4923 EVUNLOOP_ALL => EVBREAK_ALL
4924
4925 EV_TIMEOUT => EV_TIMER
4926
4927 ev_loop_count => ev_iteration
4928 ev_loop_depth => ev_depth
4929 ev_loop_verify => ev_verify
4930
4931Most functions working on C<struct ev_loop> objects don't have an
4932C<ev_loop_> prefix, so it was removed; C<ev_loop>, C<ev_unloop> and
4933associated constants have been renamed to not collide with the C<struct
4934ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme
4935as all other watcher types. Note that C<ev_loop_fork> is still called
4936C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
4937typedef.
4938
4939=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4940
4941The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4942mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4943and work, but the library code will of course be larger.
4944
4945=back
4946
4947
4469=head1 GLOSSARY 4948=head1 GLOSSARY
4470 4949
4471=over 4 4950=over 4
4472 4951
4473=item active 4952=item active
4474 4953
4475A watcher is active as long as it has been started (has been attached to 4954A watcher is active as long as it has been started and not yet stopped.
4476an event loop) but not yet stopped (disassociated from the event loop). 4955See L<WATCHER STATES> for details.
4477 4956
4478=item application 4957=item application
4479 4958
4480In this document, an application is whatever is using libev. 4959In this document, an application is whatever is using libev.
4960
4961=item backend
4962
4963The part of the code dealing with the operating system interfaces.
4481 4964
4482=item callback 4965=item callback
4483 4966
4484The address of a function that is called when some event has been 4967The address of a function that is called when some event has been
4485detected. Callbacks are being passed the event loop, the watcher that 4968detected. Callbacks are being passed the event loop, the watcher that
4486received the event, and the actual event bitset. 4969received the event, and the actual event bitset.
4487 4970
4488=item callback invocation 4971=item callback/watcher invocation
4489 4972
4490The act of calling the callback associated with a watcher. 4973The act of calling the callback associated with a watcher.
4491 4974
4492=item event 4975=item event
4493 4976
4494A change of state of some external event, such as data now being available 4977A change of state of some external event, such as data now being available
4495for reading on a file descriptor, time having passed or simply not having 4978for reading on a file descriptor, time having passed or simply not having
4496any other events happening anymore. 4979any other events happening anymore.
4497 4980
4498In libev, events are represented as single bits (such as C<EV_READ> or 4981In libev, events are represented as single bits (such as C<EV_READ> or
4499C<EV_TIMEOUT>). 4982C<EV_TIMER>).
4500 4983
4501=item event library 4984=item event library
4502 4985
4503A software package implementing an event model and loop. 4986A software package implementing an event model and loop.
4504 4987
4512The model used to describe how an event loop handles and processes 4995The model used to describe how an event loop handles and processes
4513watchers and events. 4996watchers and events.
4514 4997
4515=item pending 4998=item pending
4516 4999
4517A watcher is pending as soon as the corresponding event has been detected, 5000A watcher is pending as soon as the corresponding event has been
4518and stops being pending as soon as the watcher will be invoked or its 5001detected. See L<WATCHER STATES> for details.
4519pending status is explicitly cleared by the application.
4520
4521A watcher can be pending, but not active. Stopping a watcher also clears
4522its pending status.
4523 5002
4524=item real time 5003=item real time
4525 5004
4526The physical time that is observed. It is apparently strictly monotonic :) 5005The physical time that is observed. It is apparently strictly monotonic :)
4527 5006
4534=item watcher 5013=item watcher
4535 5014
4536A data structure that describes interest in certain events. Watchers need 5015A data structure that describes interest in certain events. Watchers need
4537to be started (attached to an event loop) before they can receive events. 5016to be started (attached to an event loop) before they can receive events.
4538 5017
4539=item watcher invocation
4540
4541The act of calling the callback associated with a watcher.
4542
4543=back 5018=back
4544 5019
4545=head1 AUTHOR 5020=head1 AUTHOR
4546 5021
4547Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 5022Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
5023Magnusson and Emanuele Giaquinta.
4548 5024

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines