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

Comparing libev/ev.pod (file contents):
Revision 1.321 by sf-exg, Fri Oct 22 10:50:24 2010 UTC vs.
Revision 1.411 by root, Fri May 4 20:47:27 2012 UTC

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);
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_run (loop, 0); 61 ev_run (loop, 0);
62 62
63 // unloop was called, so exit 63 // break was called, so exit
64 return 0; 64 return 0;
65 } 65 }
66 66
67=head1 ABOUT THIS DOCUMENT 67=head1 ABOUT THIS DOCUMENT
68 68
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
80Familiarity 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
166=item ev_tstamp ev_time () 174=item ev_tstamp ev_time ()
167 175
168Returns 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
169C<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
170you actually want to know. Also interesting is the combination of 178you actually want to know. Also interesting is the combination of
171C<ev_update_now> and C<ev_now>. 179C<ev_now_update> and C<ev_now>.
172 180
173=item ev_sleep (ev_tstamp interval) 181=item ev_sleep (ev_tstamp interval)
174 182
175Sleep for the given interval: The current thread will be blocked until 183Sleep for the given interval: The current thread will be blocked
176either it is interrupted or the given time interval has passed. Basically 184until either it is interrupted or the given time interval has
185passed (approximately - it might return a bit earlier even if not
186interrupted). Returns immediately if C<< interval <= 0 >>.
187
177this is a sub-second-resolution C<sleep ()>. 188Basically this is a sub-second-resolution C<sleep ()>.
189
190The range of the C<interval> is limited - libev only guarantees to work
191with sleep times of up to one day (C<< interval <= 86400 >>).
178 192
179=item int ev_version_major () 193=item int ev_version_major ()
180 194
181=item int ev_version_minor () 195=item int ev_version_minor ()
182 196
233the current system, you would need to look at C<ev_embeddable_backends () 247the current system, you would need to look at C<ev_embeddable_backends ()
234& ev_supported_backends ()>, likewise for recommended ones. 248& ev_supported_backends ()>, likewise for recommended ones.
235 249
236See the description of C<ev_embed> watchers for more info. 250See the description of C<ev_embed> watchers for more info.
237 251
238=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT] 252=item ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())
239 253
240Sets the allocation function to use (the prototype is similar - the 254Sets the allocation function to use (the prototype is similar - the
241semantics are identical to the C<realloc> C89/SuS/POSIX function). It is 255semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
242used to allocate and free memory (no surprises here). If it returns zero 256used to allocate and free memory (no surprises here). If it returns zero
243when memory needs to be allocated (C<size != 0>), the library might abort 257when memory needs to be allocated (C<size != 0>), the library might abort
269 } 283 }
270 284
271 ... 285 ...
272 ev_set_allocator (persistent_realloc); 286 ev_set_allocator (persistent_realloc);
273 287
274=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT] 288=item ev_set_syserr_cb (void (*cb)(const char *msg) throw ())
275 289
276Set the callback function to call on a retryable system call error (such 290Set the callback function to call on a retryable system call error (such
277as failed select, poll, epoll_wait). The message is a printable string 291as failed select, poll, epoll_wait). The message is a printable string
278indicating the system call or subsystem causing the problem. If this 292indicating the system call or subsystem causing the problem. If this
279callback is set, then libev will expect it to remedy the situation, no 293callback is set, then libev will expect it to remedy the situation, no
291 } 305 }
292 306
293 ... 307 ...
294 ev_set_syserr_cb (fatal_error); 308 ev_set_syserr_cb (fatal_error);
295 309
310=item ev_feed_signal (int signum)
311
312This function can be used to "simulate" a signal receive. It is completely
313safe to call this function at any time, from any context, including signal
314handlers or random threads.
315
316Its main use is to customise signal handling in your process, especially
317in the presence of threads. For example, you could block signals
318by default in all threads (and specifying C<EVFLAG_NOSIGMASK> when
319creating any loops), and in one thread, use C<sigwait> or any other
320mechanism to wait for signals, then "deliver" them to libev by calling
321C<ev_feed_signal>.
322
296=back 323=back
297 324
298=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 325=head1 FUNCTIONS CONTROLLING EVENT LOOPS
299 326
300An event loop is described by a C<struct ev_loop *> (the C<struct> is 327An event loop is described by a C<struct ev_loop *> (the C<struct> is
301I<not> optional in this case unless libev 3 compatibility is disabled, as 328I<not> optional in this case unless libev 3 compatibility is disabled, as
302libev 3 had an C<ev_loop> function colliding with the struct name). 329libev 3 had an C<ev_loop> function colliding with the struct name).
303 330
304The library knows two types of such loops, the I<default> loop, which 331The library knows two types of such loops, the I<default> loop, which
305supports signals and child events, and dynamically created event loops 332supports child process events, and dynamically created event loops which
306which do not. 333do not.
307 334
308=over 4 335=over 4
309 336
310=item struct ev_loop *ev_default_loop (unsigned int flags) 337=item struct ev_loop *ev_default_loop (unsigned int flags)
311 338
312This will initialise the default event loop if it hasn't been initialised 339This returns the "default" event loop object, which is what you should
313yet and return it. If the default loop could not be initialised, returns 340normally use when you just need "the event loop". Event loop objects and
314false. If it already was initialised it simply returns it (and ignores the 341the C<flags> parameter are described in more detail in the entry for
315flags. If that is troubling you, check C<ev_backend ()> afterwards). 342C<ev_loop_new>.
343
344If the default loop is already initialised then this function simply
345returns it (and ignores the flags. If that is troubling you, check
346C<ev_backend ()> afterwards). Otherwise it will create it with the given
347flags, which should almost always be C<0>, unless the caller is also the
348one calling C<ev_run> or otherwise qualifies as "the main program".
316 349
317If you don't know what event loop to use, use the one returned from this 350If you don't know what event loop to use, use the one returned from this
318function. 351function (or via the C<EV_DEFAULT> macro).
319 352
320Note that this function is I<not> thread-safe, so if you want to use it 353Note that this function is I<not> thread-safe, so if you want to use it
321from multiple threads, you have to lock (note also that this is unlikely, 354from multiple threads, you have to employ some kind of mutex (note also
322as loops cannot be shared easily between threads anyway). 355that this case is unlikely, as loops cannot be shared easily between
356threads anyway).
323 357
324The default loop is the only loop that can handle C<ev_signal> and 358The default loop is the only loop that can handle C<ev_child> watchers,
325C<ev_child> watchers, and to do this, it always registers a handler 359and to do this, it always registers a handler for C<SIGCHLD>. If this is
326for C<SIGCHLD>. If this is a problem for your application you can either 360a problem for your application you can either create a dynamic loop with
327create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 361C<ev_loop_new> which doesn't do that, or you can simply overwrite the
328can simply overwrite the C<SIGCHLD> signal handler I<after> calling 362C<SIGCHLD> signal handler I<after> calling C<ev_default_init>.
329C<ev_default_init>. 363
364Example: This is the most typical usage.
365
366 if (!ev_default_loop (0))
367 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
368
369Example: Restrict libev to the select and poll backends, and do not allow
370environment settings to be taken into account:
371
372 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
373
374=item struct ev_loop *ev_loop_new (unsigned int flags)
375
376This will create and initialise a new event loop object. If the loop
377could not be initialised, returns false.
378
379This function is thread-safe, and one common way to use libev with
380threads is indeed to create one loop per thread, and using the default
381loop in the "main" or "initial" thread.
330 382
331The flags argument can be used to specify special behaviour or specific 383The flags argument can be used to specify special behaviour or specific
332backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>). 384backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
333 385
334The following flags are supported: 386The following flags are supported:
369environment variable. 421environment variable.
370 422
371=item C<EVFLAG_NOINOTIFY> 423=item C<EVFLAG_NOINOTIFY>
372 424
373When this flag is specified, then libev will not attempt to use the 425When this flag is specified, then libev will not attempt to use the
374I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and 426I<inotify> API for its C<ev_stat> watchers. Apart from debugging and
375testing, this flag can be useful to conserve inotify file descriptors, as 427testing, this flag can be useful to conserve inotify file descriptors, as
376otherwise each loop using C<ev_stat> watchers consumes one inotify handle. 428otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
377 429
378=item C<EVFLAG_SIGNALFD> 430=item C<EVFLAG_SIGNALFD>
379 431
380When this flag is specified, then libev will attempt to use the 432When this flag is specified, then libev will attempt to use the
381I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API 433I<signalfd> API for its C<ev_signal> (and C<ev_child>) watchers. This API
382delivers signals synchronously, which makes it both faster and might make 434delivers signals synchronously, which makes it both faster and might make
383it possible to get the queued signal data. It can also simplify signal 435it possible to get the queued signal data. It can also simplify signal
384handling with threads, as long as you properly block signals in your 436handling with threads, as long as you properly block signals in your
385threads that are not interested in handling them. 437threads that are not interested in handling them.
386 438
387Signalfd will not be used by default as this changes your signal mask, and 439Signalfd will not be used by default as this changes your signal mask, and
388there are a lot of shoddy libraries and programs (glib's threadpool for 440there are a lot of shoddy libraries and programs (glib's threadpool for
389example) that can't properly initialise their signal masks. 441example) that can't properly initialise their signal masks.
442
443=item C<EVFLAG_NOSIGMASK>
444
445When this flag is specified, then libev will avoid to modify the signal
446mask. Specifically, this means you have to make sure signals are unblocked
447when you want to receive them.
448
449This behaviour is useful when you want to do your own signal handling, or
450want to handle signals only in specific threads and want to avoid libev
451unblocking the signals.
452
453It's also required by POSIX in a threaded program, as libev calls
454C<sigprocmask>, whose behaviour is officially unspecified.
455
456This flag's behaviour will become the default in future versions of libev.
390 457
391=item C<EVBACKEND_SELECT> (value 1, portable select backend) 458=item C<EVBACKEND_SELECT> (value 1, portable select backend)
392 459
393This is your standard select(2) backend. Not I<completely> standard, as 460This is your standard select(2) backend. Not I<completely> standard, as
394libev tries to roll its own fd_set with no limits on the number of fds, 461libev tries to roll its own fd_set with no limits on the number of fds,
422=item C<EVBACKEND_EPOLL> (value 4, Linux) 489=item C<EVBACKEND_EPOLL> (value 4, Linux)
423 490
424Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9 491Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
425kernels). 492kernels).
426 493
427For few fds, this backend is a bit little slower than poll and select, 494For few fds, this backend is a bit little slower than poll and select, but
428but it scales phenomenally better. While poll and select usually scale 495it scales phenomenally better. While poll and select usually scale like
429like O(total_fds) where n is the total number of fds (or the highest fd), 496O(total_fds) where total_fds is the total number of fds (or the highest
430epoll scales either O(1) or O(active_fds). 497fd), epoll scales either O(1) or O(active_fds).
431 498
432The epoll mechanism deserves honorable mention as the most misdesigned 499The epoll mechanism deserves honorable mention as the most misdesigned
433of the more advanced event mechanisms: mere annoyances include silently 500of the more advanced event mechanisms: mere annoyances include silently
434dropping file descriptors, requiring a system call per change per file 501dropping file descriptors, requiring a system call per change per file
435descriptor (and unnecessary guessing of parameters), problems with dup and 502descriptor (and unnecessary guessing of parameters), problems with dup,
503returning before the timeout value, resulting in additional iterations
504(and only giving 5ms accuracy while select on the same platform gives
436so on. The biggest issue is fork races, however - if a program forks then 5050.1ms) and so on. The biggest issue is fork races, however - if a program
437I<both> parent and child process have to recreate the epoll set, which can 506forks then I<both> parent and child process have to recreate the epoll
438take considerable time (one syscall per file descriptor) and is of course 507set, which can take considerable time (one syscall per file descriptor)
439hard to detect. 508and is of course hard to detect.
440 509
441Epoll is also notoriously buggy - embedding epoll fds I<should> work, but 510Epoll is also notoriously buggy - embedding epoll fds I<should> work,
442of course I<doesn't>, and epoll just loves to report events for totally 511but of course I<doesn't>, and epoll just loves to report events for
443I<different> file descriptors (even already closed ones, so one cannot 512totally I<different> file descriptors (even already closed ones, so
444even remove them from the set) than registered in the set (especially 513one cannot even remove them from the set) than registered in the set
445on SMP systems). Libev tries to counter these spurious notifications by 514(especially on SMP systems). Libev tries to counter these spurious
446employing an additional generation counter and comparing that against the 515notifications by employing an additional generation counter and comparing
447events to filter out spurious ones, recreating the set when required. Last 516that against the events to filter out spurious ones, recreating the set
517when required. Epoll also erroneously rounds down timeouts, but gives you
518no way to know when and by how much, so sometimes you have to busy-wait
519because epoll returns immediately despite a nonzero timeout. And last
448not least, it also refuses to work with some file descriptors which work 520not least, it also refuses to work with some file descriptors which work
449perfectly fine with C<select> (files, many character devices...). 521perfectly fine with C<select> (files, many character devices...).
522
523Epoll is truly the train wreck among event poll mechanisms, a frankenpoll,
524cobbled together in a hurry, no thought to design or interaction with
525others. Oh, the pain, will it ever stop...
450 526
451While stopping, setting and starting an I/O watcher in the same iteration 527While stopping, setting and starting an I/O watcher in the same iteration
452will result in some caching, there is still a system call per such 528will result in some caching, there is still a system call per such
453incident (because the same I<file descriptor> could point to a different 529incident (because the same I<file descriptor> could point to a different
454I<file description> now), so its best to avoid that. Also, C<dup ()>'ed 530I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
491 567
492It scales in the same way as the epoll backend, but the interface to the 568It scales in the same way as the epoll backend, but the interface to the
493kernel is more efficient (which says nothing about its actual speed, of 569kernel is more efficient (which says nothing about its actual speed, of
494course). While stopping, setting and starting an I/O watcher does never 570course). While stopping, setting and starting an I/O watcher does never
495cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 571cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
496two event changes per incident. Support for C<fork ()> is very bad (but 572two event changes per incident. Support for C<fork ()> is very bad (you
497sane, unlike epoll) and it drops fds silently in similarly hard-to-detect 573might have to leak fd's on fork, but it's more sane than epoll) and it
498cases 574drops fds silently in similarly hard-to-detect cases
499 575
500This backend usually performs well under most conditions. 576This backend usually performs well under most conditions.
501 577
502While nominally embeddable in other event loops, this doesn't work 578While nominally embeddable in other event loops, this doesn't work
503everywhere, so you might need to test for this. And since it is broken 579everywhere, so you might need to test for this. And since it is broken
520=item C<EVBACKEND_PORT> (value 32, Solaris 10) 596=item C<EVBACKEND_PORT> (value 32, Solaris 10)
521 597
522This uses the Solaris 10 event port mechanism. As with everything on Solaris, 598This uses the Solaris 10 event port mechanism. As with everything on Solaris,
523it's really slow, but it still scales very well (O(active_fds)). 599it's really slow, but it still scales very well (O(active_fds)).
524 600
525Please note that Solaris event ports can deliver a lot of spurious
526notifications, so you need to use non-blocking I/O or other means to avoid
527blocking when no data (or space) is available.
528
529While this backend scales well, it requires one system call per active 601While this backend scales well, it requires one system call per active
530file descriptor per loop iteration. For small and medium numbers of file 602file descriptor per loop iteration. For small and medium numbers of file
531descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 603descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
532might perform better. 604might perform better.
533 605
534On the positive side, with the exception of the spurious readiness 606On the positive side, this backend actually performed fully to
535notifications, this backend actually performed fully to specification
536in all tests and is fully embeddable, which is a rare feat among the 607specification in all tests and is fully embeddable, which is a rare feat
537OS-specific backends (I vastly prefer correctness over speed hacks). 608among the OS-specific backends (I vastly prefer correctness over speed
609hacks).
610
611On the negative side, the interface is I<bizarre> - so bizarre that
612even sun itself gets it wrong in their code examples: The event polling
613function sometimes returns events to the caller even though an error
614occurred, but with no indication whether it has done so or not (yes, it's
615even documented that way) - deadly for edge-triggered interfaces where you
616absolutely have to know whether an event occurred or not because you have
617to re-arm the watcher.
618
619Fortunately libev seems to be able to work around these idiocies.
538 620
539This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 621This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
540C<EVBACKEND_POLL>. 622C<EVBACKEND_POLL>.
541 623
542=item C<EVBACKEND_ALL> 624=item C<EVBACKEND_ALL>
543 625
544Try all backends (even potentially broken ones that wouldn't be tried 626Try all backends (even potentially broken ones that wouldn't be tried
545with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 627with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
546C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 628C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
547 629
548It is definitely not recommended to use this flag. 630It is definitely not recommended to use this flag, use whatever
631C<ev_recommended_backends ()> returns, or simply do not specify a backend
632at all.
633
634=item C<EVBACKEND_MASK>
635
636Not a backend at all, but a mask to select all backend bits from a
637C<flags> value, in case you want to mask out any backends from a flags
638value (e.g. when modifying the C<LIBEV_FLAGS> environment variable).
549 639
550=back 640=back
551 641
552If one or more of the backend flags are or'ed into the flags value, 642If one or more of the backend flags are or'ed into the flags value,
553then only these backends will be tried (in the reverse order as listed 643then only these backends will be tried (in the reverse order as listed
554here). If none are specified, all backends in C<ev_recommended_backends 644here). If none are specified, all backends in C<ev_recommended_backends
555()> will be tried. 645()> will be tried.
556 646
557Example: This is the most typical usage.
558
559 if (!ev_default_loop (0))
560 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
561
562Example: Restrict libev to the select and poll backends, and do not allow
563environment settings to be taken into account:
564
565 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
566
567Example: Use whatever libev has to offer, but make sure that kqueue is
568used if available (warning, breaks stuff, best use only with your own
569private event loop and only if you know the OS supports your types of
570fds):
571
572 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
573
574=item struct ev_loop *ev_loop_new (unsigned int flags)
575
576Similar to C<ev_default_loop>, but always creates a new event loop that is
577always distinct from the default loop.
578
579Note that this function I<is> thread-safe, and one common way to use
580libev with threads is indeed to create one loop per thread, and using the
581default loop in the "main" or "initial" thread.
582
583Example: Try to create a event loop that uses epoll and nothing else. 647Example: Try to create a event loop that uses epoll and nothing else.
584 648
585 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 649 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
586 if (!epoller) 650 if (!epoller)
587 fatal ("no epoll found here, maybe it hides under your chair"); 651 fatal ("no epoll found here, maybe it hides under your chair");
588 652
653Example: Use whatever libev has to offer, but make sure that kqueue is
654used if available.
655
656 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
657
589=item ev_default_destroy () 658=item ev_loop_destroy (loop)
590 659
591Destroys the default loop (frees all memory and kernel state etc.). None 660Destroys an event loop object (frees all memory and kernel state
592of the active event watchers will be stopped in the normal sense, so 661etc.). None of the active event watchers will be stopped in the normal
593e.g. C<ev_is_active> might still return true. It is your responsibility to 662sense, so e.g. C<ev_is_active> might still return true. It is your
594either stop all watchers cleanly yourself I<before> calling this function, 663responsibility to either stop all watchers cleanly yourself I<before>
595or cope with the fact afterwards (which is usually the easiest thing, you 664calling this function, or cope with the fact afterwards (which is usually
596can just ignore the watchers and/or C<free ()> them for example). 665the easiest thing, you can just ignore the watchers and/or C<free ()> them
666for example).
597 667
598Note that certain global state, such as signal state (and installed signal 668Note that certain global state, such as signal state (and installed signal
599handlers), will not be freed by this function, and related watchers (such 669handlers), will not be freed by this function, and related watchers (such
600as signal and child watchers) would need to be stopped manually. 670as signal and child watchers) would need to be stopped manually.
601 671
602In general it is not advisable to call this function except in the 672This function is normally used on loop objects allocated by
603rare occasion where you really need to free e.g. the signal handling 673C<ev_loop_new>, but it can also be used on the default loop returned by
674C<ev_default_loop>, in which case it is not thread-safe.
675
676Note that it is not advisable to call this function on the default loop
677except in the rare occasion where you really need to free its resources.
604pipe fds. If you need dynamically allocated loops it is better to use 678If you need dynamically allocated loops it is better to use C<ev_loop_new>
605C<ev_loop_new> and C<ev_loop_destroy>. 679and C<ev_loop_destroy>.
606 680
607=item ev_loop_destroy (loop) 681=item ev_loop_fork (loop)
608 682
609Like C<ev_default_destroy>, but destroys an event loop created by an
610earlier call to C<ev_loop_new>.
611
612=item ev_default_fork ()
613
614This function sets a flag that causes subsequent C<ev_run> iterations 683This function sets a flag that causes subsequent C<ev_run> iterations to
615to reinitialise the kernel state for backends that have one. Despite the 684reinitialise the kernel state for backends that have one. Despite the
616name, you can call it anytime, but it makes most sense after forking, in 685name, you can call it anytime, but it makes most sense after forking, in
617the child process (or both child and parent, but that again makes little 686the child process. You I<must> call it (or use C<EVFLAG_FORKCHECK>) in the
618sense). You I<must> call it in the child before using any of the libev 687child before resuming or calling C<ev_run>.
619functions, and it will only take effect at the next C<ev_run> iteration.
620 688
621Again, you I<have> to call it on I<any> loop that you want to re-use after 689Again, you I<have> to call it on I<any> loop that you want to re-use after
622a fork, I<even if you do not plan to use the loop in the parent>. This is 690a fork, I<even if you do not plan to use the loop in the parent>. This is
623because some kernel interfaces *cough* I<kqueue> *cough* do funny things 691because some kernel interfaces *cough* I<kqueue> *cough* do funny things
624during fork. 692during fork.
629call it at all (in fact, C<epoll> is so badly broken that it makes a 697call it at all (in fact, C<epoll> is so badly broken that it makes a
630difference, but libev will usually detect this case on its own and do a 698difference, but libev will usually detect this case on its own and do a
631costly reset of the backend). 699costly reset of the backend).
632 700
633The function itself is quite fast and it's usually not a problem to call 701The function itself is quite fast and it's usually not a problem to call
634it just in case after a fork. To make this easy, the function will fit in 702it just in case after a fork.
635quite nicely into a call to C<pthread_atfork>:
636 703
704Example: Automate calling C<ev_loop_fork> on the default loop when
705using pthreads.
706
707 static void
708 post_fork_child (void)
709 {
710 ev_loop_fork (EV_DEFAULT);
711 }
712
713 ...
637 pthread_atfork (0, 0, ev_default_fork); 714 pthread_atfork (0, 0, post_fork_child);
638
639=item ev_loop_fork (loop)
640
641Like C<ev_default_fork>, but acts on an event loop created by
642C<ev_loop_new>. Yes, you have to call this on every allocated event loop
643after fork that you want to re-use in the child, and how you keep track of
644them is entirely your own problem.
645 715
646=item int ev_is_default_loop (loop) 716=item int ev_is_default_loop (loop)
647 717
648Returns true when the given loop is, in fact, the default loop, and false 718Returns true when the given loop is, in fact, the default loop, and false
649otherwise. 719otherwise.
660prepare and check phases. 730prepare and check phases.
661 731
662=item unsigned int ev_depth (loop) 732=item unsigned int ev_depth (loop)
663 733
664Returns the number of times C<ev_run> was entered minus the number of 734Returns the number of times C<ev_run> was entered minus the number of
665times C<ev_run> was exited, in other words, the recursion depth. 735times C<ev_run> was exited normally, in other words, the recursion depth.
666 736
667Outside C<ev_run>, this number is zero. In a callback, this number is 737Outside C<ev_run>, this number is zero. In a callback, this number is
668C<1>, unless C<ev_run> was invoked recursively (or from another thread), 738C<1>, unless C<ev_run> was invoked recursively (or from another thread),
669in which case it is higher. 739in which case it is higher.
670 740
671Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread 741Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread,
672etc.), doesn't count as "exit" - consider this as a hint to avoid such 742throwing an exception etc.), doesn't count as "exit" - consider this
673ungentleman-like behaviour unless it's really convenient. 743as a hint to avoid such ungentleman-like behaviour unless it's really
744convenient, in which case it is fully supported.
674 745
675=item unsigned int ev_backend (loop) 746=item unsigned int ev_backend (loop)
676 747
677Returns one of the C<EVBACKEND_*> flags indicating the event backend in 748Returns one of the C<EVBACKEND_*> flags indicating the event backend in
678use. 749use.
721without a previous call to C<ev_suspend>. 792without a previous call to C<ev_suspend>.
722 793
723Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the 794Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
724event loop time (see C<ev_now_update>). 795event loop time (see C<ev_now_update>).
725 796
726=item ev_run (loop, int flags) 797=item bool ev_run (loop, int flags)
727 798
728Finally, this is it, the event handler. This function usually is called 799Finally, this is it, the event handler. This function usually is called
729after you have initialised all your watchers and you want to start 800after you have initialised all your watchers and you want to start
730handling events. It will ask the operating system for any new events, call 801handling events. It will ask the operating system for any new events, call
731the watcher callbacks, an then repeat the whole process indefinitely: This 802the watcher callbacks, and then repeat the whole process indefinitely: This
732is why event loops are called I<loops>. 803is why event loops are called I<loops>.
733 804
734If the flags argument is specified as C<0>, it will keep handling events 805If the flags argument is specified as C<0>, it will keep handling events
735until either no event watchers are active anymore or C<ev_break> was 806until either no event watchers are active anymore or C<ev_break> was
736called. 807called.
808
809The return value is false if there are no more active watchers (which
810usually means "all jobs done" or "deadlock"), and true in all other cases
811(which usually means " you should call C<ev_run> again").
737 812
738Please note that an explicit C<ev_break> is usually better than 813Please note that an explicit C<ev_break> is usually better than
739relying on all watchers to be stopped when deciding when a program has 814relying on all watchers to be stopped when deciding when a program has
740finished (especially in interactive programs), but having a program 815finished (especially in interactive programs), but having a program
741that automatically loops as long as it has to and no longer by virtue 816that automatically loops as long as it has to and no longer by virtue
742of relying on its watchers stopping correctly, that is truly a thing of 817of relying on its watchers stopping correctly, that is truly a thing of
743beauty. 818beauty.
744 819
820This function is I<mostly> exception-safe - you can break out of a
821C<ev_run> call by calling C<longjmp> in a callback, throwing a C++
822exception and so on. This does not decrement the C<ev_depth> value, nor
823will it clear any outstanding C<EVBREAK_ONE> breaks.
824
745A flags value of C<EVRUN_NOWAIT> will look for new events, will handle 825A flags value of C<EVRUN_NOWAIT> will look for new events, will handle
746those events and any already outstanding ones, but will not wait and 826those events and any already outstanding ones, but will not wait and
747block your process in case there are no events and will return after one 827block your process in case there are no events and will return after one
748iteration of the loop. This is sometimes useful to poll and handle new 828iteration of the loop. This is sometimes useful to poll and handle new
749events while doing lengthy calculations, to keep the program responsive. 829events while doing lengthy calculations, to keep the program responsive.
758This is useful if you are waiting for some external event in conjunction 838This is useful if you are waiting for some external event in conjunction
759with something not expressible using other libev watchers (i.e. "roll your 839with something not expressible using other libev watchers (i.e. "roll your
760own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is 840own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
761usually a better approach for this kind of thing. 841usually a better approach for this kind of thing.
762 842
763Here are the gory details of what C<ev_run> does: 843Here are the gory details of what C<ev_run> does (this is for your
844understanding, not a guarantee that things will work exactly like this in
845future versions):
764 846
765 - Increment loop depth. 847 - Increment loop depth.
766 - Reset the ev_break status. 848 - Reset the ev_break status.
767 - Before the first iteration, call any pending watchers. 849 - Before the first iteration, call any pending watchers.
768 LOOP: 850 LOOP:
801anymore. 883anymore.
802 884
803 ... queue jobs here, make sure they register event watchers as long 885 ... queue jobs here, make sure they register event watchers as long
804 ... as they still have work to do (even an idle watcher will do..) 886 ... as they still have work to do (even an idle watcher will do..)
805 ev_run (my_loop, 0); 887 ev_run (my_loop, 0);
806 ... jobs done or somebody called unloop. yeah! 888 ... jobs done or somebody called break. yeah!
807 889
808=item ev_break (loop, how) 890=item ev_break (loop, how)
809 891
810Can be used to make a call to C<ev_run> return early (but only after it 892Can be used to make a call to C<ev_run> return early (but only after it
811has processed all outstanding events). The C<how> argument must be either 893has processed all outstanding events). The C<how> argument must be either
812C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or 894C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or
813C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return. 895C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return.
814 896
815This "unloop state" will be cleared when entering C<ev_run> again. 897This "break state" will be cleared on the next call to C<ev_run>.
816 898
817It is safe to call C<ev_break> from outside any C<ev_run> calls. ##TODO## 899It is safe to call C<ev_break> from outside any C<ev_run> calls, too, in
900which case it will have no effect.
818 901
819=item ev_ref (loop) 902=item ev_ref (loop)
820 903
821=item ev_unref (loop) 904=item ev_unref (loop)
822 905
843running when nothing else is active. 926running when nothing else is active.
844 927
845 ev_signal exitsig; 928 ev_signal exitsig;
846 ev_signal_init (&exitsig, sig_cb, SIGINT); 929 ev_signal_init (&exitsig, sig_cb, SIGINT);
847 ev_signal_start (loop, &exitsig); 930 ev_signal_start (loop, &exitsig);
848 evf_unref (loop); 931 ev_unref (loop);
849 932
850Example: For some weird reason, unregister the above signal handler again. 933Example: For some weird reason, unregister the above signal handler again.
851 934
852 ev_ref (loop); 935 ev_ref (loop);
853 ev_signal_stop (loop, &exitsig); 936 ev_signal_stop (loop, &exitsig);
873overhead for the actual polling but can deliver many events at once. 956overhead for the actual polling but can deliver many events at once.
874 957
875By setting a higher I<io collect interval> you allow libev to spend more 958By setting a higher I<io collect interval> you allow libev to spend more
876time collecting I/O events, so you can handle more events per iteration, 959time collecting I/O events, so you can handle more events per iteration,
877at the cost of increasing latency. Timeouts (both C<ev_periodic> and 960at the cost of increasing latency. Timeouts (both C<ev_periodic> and
878C<ev_timer>) will be not affected. Setting this to a non-null value will 961C<ev_timer>) will not be affected. Setting this to a non-null value will
879introduce an additional C<ev_sleep ()> call into most loop iterations. The 962introduce an additional C<ev_sleep ()> call into most loop iterations. The
880sleep time ensures that libev will not poll for I/O events more often then 963sleep time ensures that libev will not poll for I/O events more often then
881once per this interval, on average. 964once per this interval, on average (as long as the host time resolution is
965good enough).
882 966
883Likewise, by setting a higher I<timeout collect interval> you allow libev 967Likewise, by setting a higher I<timeout collect interval> you allow libev
884to spend more time collecting timeouts, at the expense of increased 968to spend more time collecting timeouts, at the expense of increased
885latency/jitter/inexactness (the watcher callback will be called 969latency/jitter/inexactness (the watcher callback will be called
886later). C<ev_io> watchers will not be affected. Setting this to a non-null 970later). C<ev_io> watchers will not be affected. Setting this to a non-null
932invoke the actual watchers inside another context (another thread etc.). 1016invoke the actual watchers inside another context (another thread etc.).
933 1017
934If you want to reset the callback, use C<ev_invoke_pending> as new 1018If you want to reset the callback, use C<ev_invoke_pending> as new
935callback. 1019callback.
936 1020
937=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P)) 1021=item ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())
938 1022
939Sometimes you want to share the same loop between multiple threads. This 1023Sometimes you want to share the same loop between multiple threads. This
940can be done relatively simply by putting mutex_lock/unlock calls around 1024can be done relatively simply by putting mutex_lock/unlock calls around
941each call to a libev function. 1025each call to a libev function.
942 1026
943However, C<ev_run> can run an indefinite time, so it is not feasible 1027However, C<ev_run> can run an indefinite time, so it is not feasible
944to wait for it to return. One way around this is to wake up the event 1028to wait for it to return. One way around this is to wake up the event
945loop via C<ev_break> and C<av_async_send>, another way is to set these 1029loop via C<ev_break> and C<ev_async_send>, another way is to set these
946I<release> and I<acquire> callbacks on the loop. 1030I<release> and I<acquire> callbacks on the loop.
947 1031
948When set, then C<release> will be called just before the thread is 1032When set, then C<release> will be called just before the thread is
949suspended waiting for new events, and C<acquire> is called just 1033suspended waiting for new events, and C<acquire> is called just
950afterwards. 1034afterwards.
965See also the locking example in the C<THREADS> section later in this 1049See also the locking example in the C<THREADS> section later in this
966document. 1050document.
967 1051
968=item ev_set_userdata (loop, void *data) 1052=item ev_set_userdata (loop, void *data)
969 1053
970=item ev_userdata (loop) 1054=item void *ev_userdata (loop)
971 1055
972Set and retrieve a single C<void *> associated with a loop. When 1056Set and retrieve a single C<void *> associated with a loop. When
973C<ev_set_userdata> has never been called, then C<ev_userdata> returns 1057C<ev_set_userdata> has never been called, then C<ev_userdata> returns
974C<0.> 1058C<0>.
975 1059
976These two functions can be used to associate arbitrary data with a loop, 1060These two functions can be used to associate arbitrary data with a loop,
977and are intended solely for the C<invoke_pending_cb>, C<release> and 1061and are intended solely for the C<invoke_pending_cb>, C<release> and
978C<acquire> callbacks described above, but of course can be (ab-)used for 1062C<acquire> callbacks described above, but of course can be (ab-)used for
979any other purpose as well. 1063any other purpose as well.
1090 1174
1091=item C<EV_PREPARE> 1175=item C<EV_PREPARE>
1092 1176
1093=item C<EV_CHECK> 1177=item C<EV_CHECK>
1094 1178
1095All C<ev_prepare> watchers are invoked just I<before> C<ev_run> starts 1179All C<ev_prepare> watchers are invoked just I<before> C<ev_run> starts to
1096to gather new events, and all C<ev_check> watchers are invoked just after 1180gather new events, and all C<ev_check> watchers are queued (not invoked)
1097C<ev_run> has gathered them, but before it invokes any callbacks for any 1181just after C<ev_run> has gathered them, but before it queues any callbacks
1182for any received events. That means C<ev_prepare> watchers are the last
1183watchers invoked before the event loop sleeps or polls for new events, and
1184C<ev_check> watchers will be invoked before any other watchers of the same
1185or lower priority within an event loop iteration.
1186
1098received events. Callbacks of both watcher types can start and stop as 1187Callbacks of both watcher types can start and stop as many watchers as
1099many watchers as they want, and all of them will be taken into account 1188they want, and all of them will be taken into account (for example, a
1100(for example, a C<ev_prepare> watcher might start an idle watcher to keep 1189C<ev_prepare> watcher might start an idle watcher to keep C<ev_run> from
1101C<ev_run> from blocking). 1190blocking).
1102 1191
1103=item C<EV_EMBED> 1192=item C<EV_EMBED>
1104 1193
1105The embedded event loop specified in the C<ev_embed> watcher needs attention. 1194The embedded event loop specified in the C<ev_embed> watcher needs attention.
1106 1195
1107=item C<EV_FORK> 1196=item C<EV_FORK>
1108 1197
1109The event loop has been resumed in the child process after fork (see 1198The event loop has been resumed in the child process after fork (see
1110C<ev_fork>). 1199C<ev_fork>).
1200
1201=item C<EV_CLEANUP>
1202
1203The event loop is about to be destroyed (see C<ev_cleanup>).
1111 1204
1112=item C<EV_ASYNC> 1205=item C<EV_ASYNC>
1113 1206
1114The given async watcher has been asynchronously notified (see C<ev_async>). 1207The given async watcher has been asynchronously notified (see C<ev_async>).
1115 1208
1137programs, though, as the fd could already be closed and reused for another 1230programs, though, as the fd could already be closed and reused for another
1138thing, so beware. 1231thing, so beware.
1139 1232
1140=back 1233=back
1141 1234
1235=head2 GENERIC WATCHER FUNCTIONS
1236
1237=over 4
1238
1239=item C<ev_init> (ev_TYPE *watcher, callback)
1240
1241This macro initialises the generic portion of a watcher. The contents
1242of the watcher object can be arbitrary (so C<malloc> will do). Only
1243the generic parts of the watcher are initialised, you I<need> to call
1244the type-specific C<ev_TYPE_set> macro afterwards to initialise the
1245type-specific parts. For each type there is also a C<ev_TYPE_init> macro
1246which rolls both calls into one.
1247
1248You can reinitialise a watcher at any time as long as it has been stopped
1249(or never started) and there are no pending events outstanding.
1250
1251The callback is always of type C<void (*)(struct ev_loop *loop, ev_TYPE *watcher,
1252int revents)>.
1253
1254Example: Initialise an C<ev_io> watcher in two steps.
1255
1256 ev_io w;
1257 ev_init (&w, my_cb);
1258 ev_io_set (&w, STDIN_FILENO, EV_READ);
1259
1260=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1261
1262This macro initialises the type-specific parts of a watcher. You need to
1263call C<ev_init> at least once before you call this macro, but you can
1264call C<ev_TYPE_set> any number of times. You must not, however, call this
1265macro on a watcher that is active (it can be pending, however, which is a
1266difference to the C<ev_init> macro).
1267
1268Although some watcher types do not have type-specific arguments
1269(e.g. C<ev_prepare>) you still need to call its C<set> macro.
1270
1271See C<ev_init>, above, for an example.
1272
1273=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
1274
1275This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
1276calls into a single call. This is the most convenient method to initialise
1277a watcher. The same limitations apply, of course.
1278
1279Example: Initialise and set an C<ev_io> watcher in one step.
1280
1281 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1282
1283=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1284
1285Starts (activates) the given watcher. Only active watchers will receive
1286events. If the watcher is already active nothing will happen.
1287
1288Example: Start the C<ev_io> watcher that is being abused as example in this
1289whole section.
1290
1291 ev_io_start (EV_DEFAULT_UC, &w);
1292
1293=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1294
1295Stops the given watcher if active, and clears the pending status (whether
1296the watcher was active or not).
1297
1298It is possible that stopped watchers are pending - for example,
1299non-repeating timers are being stopped when they become pending - but
1300calling C<ev_TYPE_stop> ensures that the watcher is neither active nor
1301pending. If you want to free or reuse the memory used by the watcher it is
1302therefore a good idea to always call its C<ev_TYPE_stop> function.
1303
1304=item bool ev_is_active (ev_TYPE *watcher)
1305
1306Returns a true value iff the watcher is active (i.e. it has been started
1307and not yet been stopped). As long as a watcher is active you must not modify
1308it.
1309
1310=item bool ev_is_pending (ev_TYPE *watcher)
1311
1312Returns a true value iff the watcher is pending, (i.e. it has outstanding
1313events but its callback has not yet been invoked). As long as a watcher
1314is pending (but not active) you must not call an init function on it (but
1315C<ev_TYPE_set> is safe), you must not change its priority, and you must
1316make sure the watcher is available to libev (e.g. you cannot C<free ()>
1317it).
1318
1319=item callback ev_cb (ev_TYPE *watcher)
1320
1321Returns the callback currently set on the watcher.
1322
1323=item ev_set_cb (ev_TYPE *watcher, callback)
1324
1325Change the callback. You can change the callback at virtually any time
1326(modulo threads).
1327
1328=item ev_set_priority (ev_TYPE *watcher, int priority)
1329
1330=item int ev_priority (ev_TYPE *watcher)
1331
1332Set and query the priority of the watcher. The priority is a small
1333integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1334(default: C<-2>). Pending watchers with higher priority will be invoked
1335before watchers with lower priority, but priority will not keep watchers
1336from being executed (except for C<ev_idle> watchers).
1337
1338If you need to suppress invocation when higher priority events are pending
1339you need to look at C<ev_idle> watchers, which provide this functionality.
1340
1341You I<must not> change the priority of a watcher as long as it is active or
1342pending.
1343
1344Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1345fine, as long as you do not mind that the priority value you query might
1346or might not have been clamped to the valid range.
1347
1348The default priority used by watchers when no priority has been set is
1349always C<0>, which is supposed to not be too high and not be too low :).
1350
1351See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1352priorities.
1353
1354=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1355
1356Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1357C<loop> nor C<revents> need to be valid as long as the watcher callback
1358can deal with that fact, as both are simply passed through to the
1359callback.
1360
1361=item int ev_clear_pending (loop, ev_TYPE *watcher)
1362
1363If the watcher is pending, this function clears its pending status and
1364returns its C<revents> bitset (as if its callback was invoked). If the
1365watcher isn't pending it does nothing and returns C<0>.
1366
1367Sometimes it can be useful to "poll" a watcher instead of waiting for its
1368callback to be invoked, which can be accomplished with this function.
1369
1370=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1371
1372Feeds the given event set into the event loop, as if the specified event
1373had happened for the specified watcher (which must be a pointer to an
1374initialised but not necessarily started event watcher). Obviously you must
1375not free the watcher as long as it has pending events.
1376
1377Stopping the watcher, letting libev invoke it, or calling
1378C<ev_clear_pending> will clear the pending event, even if the watcher was
1379not started in the first place.
1380
1381See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1382functions that do not need a watcher.
1383
1384=back
1385
1386See also the L<ASSOCIATING CUSTOM DATA WITH A WATCHER> and L<BUILDING YOUR
1387OWN COMPOSITE WATCHERS> idioms.
1388
1142=head2 WATCHER STATES 1389=head2 WATCHER STATES
1143 1390
1144There are various watcher states mentioned throughout this manual - 1391There are various watcher states mentioned throughout this manual -
1145active, pending and so on. In this section these states and the rules to 1392active, pending and so on. In this section these states and the rules to
1146transition between them will be described in more detail - and while these 1393transition between them will be described in more detail - and while these
1148 1395
1149=over 4 1396=over 4
1150 1397
1151=item initialiased 1398=item initialiased
1152 1399
1153Before a watcher can be registered with the event looop it has to be 1400Before a watcher can be registered with the event loop it has to be
1154initialised. This can be done with a call to C<ev_TYPE_init>, or calls to 1401initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
1155C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function. 1402C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1156 1403
1157In this state it is simply some block of memory that is suitable for use 1404In this state it is simply some block of memory that is suitable for
1158in an event loop. It can be moved around, freed, reused etc. at will. 1405use in an event loop. It can be moved around, freed, reused etc. at
1406will - as long as you either keep the memory contents intact, or call
1407C<ev_TYPE_init> again.
1159 1408
1160=item started/running/active 1409=item started/running/active
1161 1410
1162Once a watcher has been started with a call to C<ev_TYPE_start> it becomes 1411Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
1163property of the event loop, and is actively waiting for events. While in 1412property of the event loop, and is actively waiting for events. While in
1191latter will clear any pending state the watcher might be in, regardless 1440latter will clear any pending state the watcher might be in, regardless
1192of whether it was active or not, so stopping a watcher explicitly before 1441of whether it was active or not, so stopping a watcher explicitly before
1193freeing it is often a good idea. 1442freeing it is often a good idea.
1194 1443
1195While stopped (and not pending) the watcher is essentially in the 1444While stopped (and not pending) the watcher is essentially in the
1196initialised state, that is it can be reused, moved, modified in any way 1445initialised state, that is, it can be reused, moved, modified in any way
1197you wish. 1446you wish (but when you trash the memory block, you need to C<ev_TYPE_init>
1447it again).
1198 1448
1199=back 1449=back
1200
1201=head2 GENERIC WATCHER FUNCTIONS
1202
1203=over 4
1204
1205=item C<ev_init> (ev_TYPE *watcher, callback)
1206
1207This macro initialises the generic portion of a watcher. The contents
1208of the watcher object can be arbitrary (so C<malloc> will do). Only
1209the generic parts of the watcher are initialised, you I<need> to call
1210the type-specific C<ev_TYPE_set> macro afterwards to initialise the
1211type-specific parts. For each type there is also a C<ev_TYPE_init> macro
1212which rolls both calls into one.
1213
1214You can reinitialise a watcher at any time as long as it has been stopped
1215(or never started) and there are no pending events outstanding.
1216
1217The callback is always of type C<void (*)(struct ev_loop *loop, ev_TYPE *watcher,
1218int revents)>.
1219
1220Example: Initialise an C<ev_io> watcher in two steps.
1221
1222 ev_io w;
1223 ev_init (&w, my_cb);
1224 ev_io_set (&w, STDIN_FILENO, EV_READ);
1225
1226=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1227
1228This macro initialises the type-specific parts of a watcher. You need to
1229call C<ev_init> at least once before you call this macro, but you can
1230call C<ev_TYPE_set> any number of times. You must not, however, call this
1231macro on a watcher that is active (it can be pending, however, which is a
1232difference to the C<ev_init> macro).
1233
1234Although some watcher types do not have type-specific arguments
1235(e.g. C<ev_prepare>) you still need to call its C<set> macro.
1236
1237See C<ev_init>, above, for an example.
1238
1239=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
1240
1241This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
1242calls into a single call. This is the most convenient method to initialise
1243a watcher. The same limitations apply, of course.
1244
1245Example: Initialise and set an C<ev_io> watcher in one step.
1246
1247 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1248
1249=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1250
1251Starts (activates) the given watcher. Only active watchers will receive
1252events. If the watcher is already active nothing will happen.
1253
1254Example: Start the C<ev_io> watcher that is being abused as example in this
1255whole section.
1256
1257 ev_io_start (EV_DEFAULT_UC, &w);
1258
1259=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1260
1261Stops the given watcher if active, and clears the pending status (whether
1262the watcher was active or not).
1263
1264It is possible that stopped watchers are pending - for example,
1265non-repeating timers are being stopped when they become pending - but
1266calling C<ev_TYPE_stop> ensures that the watcher is neither active nor
1267pending. If you want to free or reuse the memory used by the watcher it is
1268therefore a good idea to always call its C<ev_TYPE_stop> function.
1269
1270=item bool ev_is_active (ev_TYPE *watcher)
1271
1272Returns a true value iff the watcher is active (i.e. it has been started
1273and not yet been stopped). As long as a watcher is active you must not modify
1274it.
1275
1276=item bool ev_is_pending (ev_TYPE *watcher)
1277
1278Returns a true value iff the watcher is pending, (i.e. it has outstanding
1279events but its callback has not yet been invoked). As long as a watcher
1280is pending (but not active) you must not call an init function on it (but
1281C<ev_TYPE_set> is safe), you must not change its priority, and you must
1282make sure the watcher is available to libev (e.g. you cannot C<free ()>
1283it).
1284
1285=item callback ev_cb (ev_TYPE *watcher)
1286
1287Returns the callback currently set on the watcher.
1288
1289=item ev_cb_set (ev_TYPE *watcher, callback)
1290
1291Change the callback. You can change the callback at virtually any time
1292(modulo threads).
1293
1294=item ev_set_priority (ev_TYPE *watcher, int priority)
1295
1296=item int ev_priority (ev_TYPE *watcher)
1297
1298Set and query the priority of the watcher. The priority is a small
1299integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1300(default: C<-2>). Pending watchers with higher priority will be invoked
1301before watchers with lower priority, but priority will not keep watchers
1302from being executed (except for C<ev_idle> watchers).
1303
1304If you need to suppress invocation when higher priority events are pending
1305you need to look at C<ev_idle> watchers, which provide this functionality.
1306
1307You I<must not> change the priority of a watcher as long as it is active or
1308pending.
1309
1310Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1311fine, as long as you do not mind that the priority value you query might
1312or might not have been clamped to the valid range.
1313
1314The default priority used by watchers when no priority has been set is
1315always C<0>, which is supposed to not be too high and not be too low :).
1316
1317See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1318priorities.
1319
1320=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1321
1322Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1323C<loop> nor C<revents> need to be valid as long as the watcher callback
1324can deal with that fact, as both are simply passed through to the
1325callback.
1326
1327=item int ev_clear_pending (loop, ev_TYPE *watcher)
1328
1329If the watcher is pending, this function clears its pending status and
1330returns its C<revents> bitset (as if its callback was invoked). If the
1331watcher isn't pending it does nothing and returns C<0>.
1332
1333Sometimes it can be useful to "poll" a watcher instead of waiting for its
1334callback to be invoked, which can be accomplished with this function.
1335
1336=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1337
1338Feeds the given event set into the event loop, as if the specified event
1339had happened for the specified watcher (which must be a pointer to an
1340initialised but not necessarily started event watcher). Obviously you must
1341not free the watcher as long as it has pending events.
1342
1343Stopping the watcher, letting libev invoke it, or calling
1344C<ev_clear_pending> will clear the pending event, even if the watcher was
1345not started in the first place.
1346
1347See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1348functions that do not need a watcher.
1349
1350=back
1351
1352
1353=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1354
1355Each watcher has, by default, a member C<void *data> that you can change
1356and read at any time: libev will completely ignore it. This can be used
1357to associate arbitrary data with your watcher. If you need more data and
1358don't want to allocate memory and store a pointer to it in that data
1359member, you can also "subclass" the watcher type and provide your own
1360data:
1361
1362 struct my_io
1363 {
1364 ev_io io;
1365 int otherfd;
1366 void *somedata;
1367 struct whatever *mostinteresting;
1368 };
1369
1370 ...
1371 struct my_io w;
1372 ev_io_init (&w.io, my_cb, fd, EV_READ);
1373
1374And since your callback will be called with a pointer to the watcher, you
1375can cast it back to your own type:
1376
1377 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
1378 {
1379 struct my_io *w = (struct my_io *)w_;
1380 ...
1381 }
1382
1383More interesting and less C-conformant ways of casting your callback type
1384instead have been omitted.
1385
1386Another common scenario is to use some data structure with multiple
1387embedded watchers:
1388
1389 struct my_biggy
1390 {
1391 int some_data;
1392 ev_timer t1;
1393 ev_timer t2;
1394 }
1395
1396In this case getting the pointer to C<my_biggy> is a bit more
1397complicated: Either you store the address of your C<my_biggy> struct
1398in the C<data> member of the watcher (for woozies), or you need to use
1399some pointer arithmetic using C<offsetof> inside your watchers (for real
1400programmers):
1401
1402 #include <stddef.h>
1403
1404 static void
1405 t1_cb (EV_P_ ev_timer *w, int revents)
1406 {
1407 struct my_biggy big = (struct my_biggy *)
1408 (((char *)w) - offsetof (struct my_biggy, t1));
1409 }
1410
1411 static void
1412 t2_cb (EV_P_ ev_timer *w, int revents)
1413 {
1414 struct my_biggy big = (struct my_biggy *)
1415 (((char *)w) - offsetof (struct my_biggy, t2));
1416 }
1417 1450
1418=head2 WATCHER PRIORITY MODELS 1451=head2 WATCHER PRIORITY MODELS
1419 1452
1420Many event loops support I<watcher priorities>, which are usually small 1453Many event loops support I<watcher priorities>, which are usually small
1421integers that influence the ordering of event callback invocation 1454integers that influence the ordering of event callback invocation
1548In general you can register as many read and/or write event watchers per 1581In general you can register as many read and/or write event watchers per
1549fd as you want (as long as you don't confuse yourself). Setting all file 1582fd as you want (as long as you don't confuse yourself). Setting all file
1550descriptors to non-blocking mode is also usually a good idea (but not 1583descriptors to non-blocking mode is also usually a good idea (but not
1551required if you know what you are doing). 1584required if you know what you are doing).
1552 1585
1553If you cannot use non-blocking mode, then force the use of a
1554known-to-be-good backend (at the time of this writing, this includes only
1555C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1556descriptors for which non-blocking operation makes no sense (such as
1557files) - libev doesn't guarantee any specific behaviour in that case.
1558
1559Another thing you have to watch out for is that it is quite easy to 1586Another thing you have to watch out for is that it is quite easy to
1560receive "spurious" readiness notifications, that is your callback might 1587receive "spurious" readiness notifications, that is, your callback might
1561be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1588be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1562because there is no data. Not only are some backends known to create a 1589because there is no data. It is very easy to get into this situation even
1563lot of those (for example Solaris ports), it is very easy to get into 1590with a relatively standard program structure. Thus it is best to always
1564this situation even with a relatively standard program structure. Thus 1591use non-blocking I/O: An extra C<read>(2) returning C<EAGAIN> is far
1565it is best to always use non-blocking I/O: An extra C<read>(2) returning
1566C<EAGAIN> is far preferable to a program hanging until some data arrives. 1592preferable to a program hanging until some data arrives.
1567 1593
1568If you cannot run the fd in non-blocking mode (for example you should 1594If you cannot run the fd in non-blocking mode (for example you should
1569not play around with an Xlib connection), then you have to separately 1595not play around with an Xlib connection), then you have to separately
1570re-test whether a file descriptor is really ready with a known-to-be good 1596re-test whether a file descriptor is really ready with a known-to-be good
1571interface such as poll (fortunately in our Xlib example, Xlib already 1597interface such as poll (fortunately in the case of Xlib, it already does
1572does this on its own, so its quite safe to use). Some people additionally 1598this on its own, so its quite safe to use). Some people additionally
1573use C<SIGALRM> and an interval timer, just to be sure you won't block 1599use C<SIGALRM> and an interval timer, just to be sure you won't block
1574indefinitely. 1600indefinitely.
1575 1601
1576But really, best use non-blocking mode. 1602But really, best use non-blocking mode.
1577 1603
1605 1631
1606There is no workaround possible except not registering events 1632There is no workaround possible except not registering events
1607for potentially C<dup ()>'ed file descriptors, or to resort to 1633for potentially C<dup ()>'ed file descriptors, or to resort to
1608C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. 1634C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1609 1635
1636=head3 The special problem of files
1637
1638Many people try to use C<select> (or libev) on file descriptors
1639representing files, and expect it to become ready when their program
1640doesn't block on disk accesses (which can take a long time on their own).
1641
1642However, this cannot ever work in the "expected" way - you get a readiness
1643notification as soon as the kernel knows whether and how much data is
1644there, and in the case of open files, that's always the case, so you
1645always get a readiness notification instantly, and your read (or possibly
1646write) will still block on the disk I/O.
1647
1648Another way to view it is that in the case of sockets, pipes, character
1649devices and so on, there is another party (the sender) that delivers data
1650on its own, but in the case of files, there is no such thing: the disk
1651will not send data on its own, simply because it doesn't know what you
1652wish to read - you would first have to request some data.
1653
1654Since files are typically not-so-well supported by advanced notification
1655mechanism, libev tries hard to emulate POSIX behaviour with respect
1656to files, even though you should not use it. The reason for this is
1657convenience: sometimes you want to watch STDIN or STDOUT, which is
1658usually a tty, often a pipe, but also sometimes files or special devices
1659(for example, C<epoll> on Linux works with F</dev/random> but not with
1660F</dev/urandom>), and even though the file might better be served with
1661asynchronous I/O instead of with non-blocking I/O, it is still useful when
1662it "just works" instead of freezing.
1663
1664So avoid file descriptors pointing to files when you know it (e.g. use
1665libeio), but use them when it is convenient, e.g. for STDIN/STDOUT, or
1666when you rarely read from a file instead of from a socket, and want to
1667reuse the same code path.
1668
1610=head3 The special problem of fork 1669=head3 The special problem of fork
1611 1670
1612Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit 1671Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
1613useless behaviour. Libev fully supports fork, but needs to be told about 1672useless behaviour. Libev fully supports fork, but needs to be told about
1614it in the child. 1673it in the child if you want to continue to use it in the child.
1615 1674
1616To support fork in your programs, you either have to call 1675To support fork in your child processes, you have to call C<ev_loop_fork
1617C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child, 1676()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to
1618enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or 1677C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1619C<EVBACKEND_POLL>.
1620 1678
1621=head3 The special problem of SIGPIPE 1679=head3 The special problem of SIGPIPE
1622 1680
1623While not really specific to libev, it is easy to forget about C<SIGPIPE>: 1681While not really specific to libev, it is easy to forget about C<SIGPIPE>:
1624when writing to a pipe whose other end has been closed, your program gets 1682when writing to a pipe whose other end has been closed, your program gets
1722detecting time jumps is hard, and some inaccuracies are unavoidable (the 1780detecting time jumps is hard, and some inaccuracies are unavoidable (the
1723monotonic clock option helps a lot here). 1781monotonic clock option helps a lot here).
1724 1782
1725The callback is guaranteed to be invoked only I<after> its timeout has 1783The callback is guaranteed to be invoked only I<after> its timeout has
1726passed (not I<at>, so on systems with very low-resolution clocks this 1784passed (not I<at>, so on systems with very low-resolution clocks this
1727might introduce a small delay). If multiple timers become ready during the 1785might introduce a small delay, see "the special problem of being too
1786early", below). If multiple timers become ready during the same loop
1728same loop iteration then the ones with earlier time-out values are invoked 1787iteration then the ones with earlier time-out values are invoked before
1729before ones of the same priority with later time-out values (but this is 1788ones of the same priority with later time-out values (but this is no
1730no longer true when a callback calls C<ev_run> recursively). 1789longer true when a callback calls C<ev_run> recursively).
1731 1790
1732=head3 Be smart about timeouts 1791=head3 Be smart about timeouts
1733 1792
1734Many real-world problems involve some kind of timeout, usually for error 1793Many real-world problems involve some kind of timeout, usually for error
1735recovery. A typical example is an HTTP request - if the other side hangs, 1794recovery. A typical example is an HTTP request - if the other side hangs,
1810 1869
1811In this case, it would be more efficient to leave the C<ev_timer> alone, 1870In this case, it would be more efficient to leave the C<ev_timer> alone,
1812but remember the time of last activity, and check for a real timeout only 1871but remember the time of last activity, and check for a real timeout only
1813within the callback: 1872within the callback:
1814 1873
1874 ev_tstamp timeout = 60.;
1815 ev_tstamp last_activity; // time of last activity 1875 ev_tstamp last_activity; // time of last activity
1876 ev_timer timer;
1816 1877
1817 static void 1878 static void
1818 callback (EV_P_ ev_timer *w, int revents) 1879 callback (EV_P_ ev_timer *w, int revents)
1819 { 1880 {
1820 ev_tstamp now = ev_now (EV_A); 1881 // calculate when the timeout would happen
1821 ev_tstamp timeout = last_activity + 60.; 1882 ev_tstamp after = last_activity - ev_now (EV_A) + timeout;
1822 1883
1823 // if last_activity + 60. is older than now, we did time out 1884 // if negative, it means we the timeout already occurred
1824 if (timeout < now) 1885 if (after < 0.)
1825 { 1886 {
1826 // timeout occurred, take action 1887 // timeout occurred, take action
1827 } 1888 }
1828 else 1889 else
1829 { 1890 {
1830 // callback was invoked, but there was some activity, re-arm 1891 // callback was invoked, but there was some recent
1831 // the watcher to fire in last_activity + 60, which is 1892 // activity. simply restart the timer to time out
1832 // guaranteed to be in the future, so "again" is positive: 1893 // after "after" seconds, which is the earliest time
1833 w->repeat = timeout - now; 1894 // the timeout can occur.
1895 ev_timer_set (w, after, 0.);
1834 ev_timer_again (EV_A_ w); 1896 ev_timer_start (EV_A_ w);
1835 } 1897 }
1836 } 1898 }
1837 1899
1838To summarise the callback: first calculate the real timeout (defined 1900To summarise the callback: first calculate in how many seconds the
1839as "60 seconds after the last activity"), then check if that time has 1901timeout will occur (by calculating the absolute time when it would occur,
1840been reached, which means something I<did>, in fact, time out. Otherwise 1902C<last_activity + timeout>, and subtracting the current time, C<ev_now
1841the callback was invoked too early (C<timeout> is in the future), so 1903(EV_A)> from that).
1842re-schedule the timer to fire at that future time, to see if maybe we have
1843a timeout then.
1844 1904
1845Note how C<ev_timer_again> is used, taking advantage of the 1905If this value is negative, then we are already past the timeout, i.e. we
1846C<ev_timer_again> optimisation when the timer is already running. 1906timed out, and need to do whatever is needed in this case.
1907
1908Otherwise, we now the earliest time at which the timeout would trigger,
1909and simply start the timer with this timeout value.
1910
1911In other words, each time the callback is invoked it will check whether
1912the timeout occurred. If not, it will simply reschedule itself to check
1913again at the earliest time it could time out. Rinse. Repeat.
1847 1914
1848This scheme causes more callback invocations (about one every 60 seconds 1915This scheme causes more callback invocations (about one every 60 seconds
1849minus half the average time between activity), but virtually no calls to 1916minus half the average time between activity), but virtually no calls to
1850libev to change the timeout. 1917libev to change the timeout.
1851 1918
1852To start the timer, simply initialise the watcher and set C<last_activity> 1919To start the machinery, simply initialise the watcher and set
1853to the current time (meaning we just have some activity :), then call the 1920C<last_activity> to the current time (meaning there was some activity just
1854callback, which will "do the right thing" and start the timer: 1921now), then call the callback, which will "do the right thing" and start
1922the timer:
1855 1923
1924 last_activity = ev_now (EV_A);
1856 ev_init (timer, callback); 1925 ev_init (&timer, callback);
1857 last_activity = ev_now (loop); 1926 callback (EV_A_ &timer, 0);
1858 callback (loop, timer, EV_TIMER);
1859 1927
1860And when there is some activity, simply store the current time in 1928When there is some activity, simply store the current time in
1861C<last_activity>, no libev calls at all: 1929C<last_activity>, no libev calls at all:
1862 1930
1931 if (activity detected)
1863 last_activity = ev_now (loop); 1932 last_activity = ev_now (EV_A);
1933
1934When your timeout value changes, then the timeout can be changed by simply
1935providing a new value, stopping the timer and calling the callback, which
1936will again do the right thing (for example, time out immediately :).
1937
1938 timeout = new_value;
1939 ev_timer_stop (EV_A_ &timer);
1940 callback (EV_A_ &timer, 0);
1864 1941
1865This technique is slightly more complex, but in most cases where the 1942This technique is slightly more complex, but in most cases where the
1866time-out is unlikely to be triggered, much more efficient. 1943time-out is unlikely to be triggered, much more efficient.
1867
1868Changing the timeout is trivial as well (if it isn't hard-coded in the
1869callback :) - just change the timeout and invoke the callback, which will
1870fix things for you.
1871 1944
1872=item 4. Wee, just use a double-linked list for your timeouts. 1945=item 4. Wee, just use a double-linked list for your timeouts.
1873 1946
1874If there is not one request, but many thousands (millions...), all 1947If there is not one request, but many thousands (millions...), all
1875employing some kind of timeout with the same timeout value, then one can 1948employing some kind of timeout with the same timeout value, then one can
1902Method #1 is almost always a bad idea, and buys you nothing. Method #4 is 1975Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1903rather complicated, but extremely efficient, something that really pays 1976rather complicated, but extremely efficient, something that really pays
1904off after the first million or so of active timers, i.e. it's usually 1977off after the first million or so of active timers, i.e. it's usually
1905overkill :) 1978overkill :)
1906 1979
1980=head3 The special problem of being too early
1981
1982If you ask a timer to call your callback after three seconds, then
1983you expect it to be invoked after three seconds - but of course, this
1984cannot be guaranteed to infinite precision. Less obviously, it cannot be
1985guaranteed to any precision by libev - imagine somebody suspending the
1986process with a STOP signal for a few hours for example.
1987
1988So, libev tries to invoke your callback as soon as possible I<after> the
1989delay has occurred, but cannot guarantee this.
1990
1991A less obvious failure mode is calling your callback too early: many event
1992loops compare timestamps with a "elapsed delay >= requested delay", but
1993this can cause your callback to be invoked much earlier than you would
1994expect.
1995
1996To see why, imagine a system with a clock that only offers full second
1997resolution (think windows if you can't come up with a broken enough OS
1998yourself). If you schedule a one-second timer at the time 500.9, then the
1999event loop will schedule your timeout to elapse at a system time of 500
2000(500.9 truncated to the resolution) + 1, or 501.
2001
2002If an event library looks at the timeout 0.1s later, it will see "501 >=
2003501" and invoke the callback 0.1s after it was started, even though a
2004one-second delay was requested - this is being "too early", despite best
2005intentions.
2006
2007This is the reason why libev will never invoke the callback if the elapsed
2008delay equals the requested delay, but only when the elapsed delay is
2009larger than the requested delay. In the example above, libev would only invoke
2010the callback at system time 502, or 1.1s after the timer was started.
2011
2012So, while libev cannot guarantee that your callback will be invoked
2013exactly when requested, it I<can> and I<does> guarantee that the requested
2014delay has actually elapsed, or in other words, it always errs on the "too
2015late" side of things.
2016
1907=head3 The special problem of time updates 2017=head3 The special problem of time updates
1908 2018
1909Establishing the current time is a costly operation (it usually takes at 2019Establishing the current time is a costly operation (it usually takes
1910least two system calls): EV therefore updates its idea of the current 2020at least one system call): EV therefore updates its idea of the current
1911time only before and after C<ev_run> collects new events, which causes a 2021time only before and after C<ev_run> collects new events, which causes a
1912growing difference between C<ev_now ()> and C<ev_time ()> when handling 2022growing difference between C<ev_now ()> and C<ev_time ()> when handling
1913lots of events in one iteration. 2023lots of events in one iteration.
1914 2024
1915The relative timeouts are calculated relative to the C<ev_now ()> 2025The relative timeouts are calculated relative to the C<ev_now ()>
1921 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 2031 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1922 2032
1923If the event loop is suspended for a long time, you can also force an 2033If the event loop is suspended for a long time, you can also force an
1924update of the time returned by C<ev_now ()> by calling C<ev_now_update 2034update of the time returned by C<ev_now ()> by calling C<ev_now_update
1925()>. 2035()>.
2036
2037=head3 The special problem of unsynchronised clocks
2038
2039Modern systems have a variety of clocks - libev itself uses the normal
2040"wall clock" clock and, if available, the monotonic clock (to avoid time
2041jumps).
2042
2043Neither of these clocks is synchronised with each other or any other clock
2044on the system, so C<ev_time ()> might return a considerably different time
2045than C<gettimeofday ()> or C<time ()>. On a GNU/Linux system, for example,
2046a call to C<gettimeofday> might return a second count that is one higher
2047than a directly following call to C<time>.
2048
2049The moral of this is to only compare libev-related timestamps with
2050C<ev_time ()> and C<ev_now ()>, at least if you want better precision than
2051a second or so.
2052
2053One more problem arises due to this lack of synchronisation: if libev uses
2054the system monotonic clock and you compare timestamps from C<ev_time>
2055or C<ev_now> from when you started your timer and when your callback is
2056invoked, you will find that sometimes the callback is a bit "early".
2057
2058This is because C<ev_timer>s work in real time, not wall clock time, so
2059libev makes sure your callback is not invoked before the delay happened,
2060I<measured according to the real time>, not the system clock.
2061
2062If your timeouts are based on a physical timescale (e.g. "time out this
2063connection after 100 seconds") then this shouldn't bother you as it is
2064exactly the right behaviour.
2065
2066If you want to compare wall clock/system timestamps to your timers, then
2067you need to use C<ev_periodic>s, as these are based on the wall clock
2068time, where your comparisons will always generate correct results.
1926 2069
1927=head3 The special problems of suspended animation 2070=head3 The special problems of suspended animation
1928 2071
1929When you leave the server world it is quite customary to hit machines that 2072When you leave the server world it is quite customary to hit machines that
1930can suspend/hibernate - what happens to the clocks during such a suspend? 2073can suspend/hibernate - what happens to the clocks during such a suspend?
1974keep up with the timer (because it takes longer than those 10 seconds to 2117keep up with the timer (because it takes longer than those 10 seconds to
1975do stuff) the timer will not fire more than once per event loop iteration. 2118do stuff) the timer will not fire more than once per event loop iteration.
1976 2119
1977=item ev_timer_again (loop, ev_timer *) 2120=item ev_timer_again (loop, ev_timer *)
1978 2121
1979This will act as if the timer timed out and restart it again if it is 2122This will act as if the timer timed out, and restarts it again if it is
1980repeating. The exact semantics are: 2123repeating. It basically works like calling C<ev_timer_stop>, updating the
2124timeout to the C<repeat> value and calling C<ev_timer_start>.
1981 2125
2126The exact semantics are as in the following rules, all of which will be
2127applied to the watcher:
2128
2129=over 4
2130
1982If the timer is pending, its pending status is cleared. 2131=item If the timer is pending, the pending status is always cleared.
1983 2132
1984If the timer is started but non-repeating, stop it (as if it timed out). 2133=item If the timer is started but non-repeating, stop it (as if it timed
2134out, without invoking it).
1985 2135
1986If the timer is repeating, either start it if necessary (with the 2136=item If the timer is repeating, make the C<repeat> value the new timeout
1987C<repeat> value), or reset the running timer to the C<repeat> value. 2137and start the timer, if necessary.
2138
2139=back
1988 2140
1989This sounds a bit complicated, see L<Be smart about timeouts>, above, for a 2141This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1990usage example. 2142usage example.
1991 2143
1992=item ev_tstamp ev_timer_remaining (loop, ev_timer *) 2144=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
2114 2266
2115Another way to think about it (for the mathematically inclined) is that 2267Another way to think about it (for the mathematically inclined) is that
2116C<ev_periodic> will try to run the callback in this mode at the next possible 2268C<ev_periodic> will try to run the callback in this mode at the next possible
2117time where C<time = offset (mod interval)>, regardless of any time jumps. 2269time where C<time = offset (mod interval)>, regardless of any time jumps.
2118 2270
2119For numerical stability it is preferable that the C<offset> value is near 2271The C<interval> I<MUST> be positive, and for numerical stability, the
2120C<ev_now ()> (the current time), but there is no range requirement for 2272interval value should be higher than C<1/8192> (which is around 100
2121this value, and in fact is often specified as zero. 2273microseconds) and C<offset> should be higher than C<0> and should have
2274at most a similar magnitude as the current time (say, within a factor of
2275ten). Typical values for offset are, in fact, C<0> or something between
2276C<0> and C<interval>, which is also the recommended range.
2122 2277
2123Note also that there is an upper limit to how often a timer can fire (CPU 2278Note also that there is an upper limit to how often a timer can fire (CPU
2124speed for example), so if C<interval> is very small then timing stability 2279speed for example), so if C<interval> is very small then timing stability
2125will of course deteriorate. Libev itself tries to be exact to be about one 2280will of course deteriorate. Libev itself tries to be exact to be about one
2126millisecond (if the OS supports it and the machine is fast enough). 2281millisecond (if the OS supports it and the machine is fast enough).
2240 2395
2241=head2 C<ev_signal> - signal me when a signal gets signalled! 2396=head2 C<ev_signal> - signal me when a signal gets signalled!
2242 2397
2243Signal watchers will trigger an event when the process receives a specific 2398Signal watchers will trigger an event when the process receives a specific
2244signal one or more times. Even though signals are very asynchronous, libev 2399signal one or more times. Even though signals are very asynchronous, libev
2245will try it's best to deliver signals synchronously, i.e. as part of the 2400will try its best to deliver signals synchronously, i.e. as part of the
2246normal event processing, like any other event. 2401normal event processing, like any other event.
2247 2402
2248If you want signals to be delivered truly asynchronously, just use 2403If you want signals to be delivered truly asynchronously, just use
2249C<sigaction> as you would do without libev and forget about sharing 2404C<sigaction> as you would do without libev and forget about sharing
2250the signal. You can even use C<ev_async> from a signal handler to 2405the signal. You can even use C<ev_async> from a signal handler to
2269=head3 The special problem of inheritance over fork/execve/pthread_create 2424=head3 The special problem of inheritance over fork/execve/pthread_create
2270 2425
2271Both the signal mask (C<sigprocmask>) and the signal disposition 2426Both the signal mask (C<sigprocmask>) and the signal disposition
2272(C<sigaction>) are unspecified after starting a signal watcher (and after 2427(C<sigaction>) are unspecified after starting a signal watcher (and after
2273stopping it again), that is, libev might or might not block the signal, 2428stopping it again), that is, libev might or might not block the signal,
2274and might or might not set or restore the installed signal handler. 2429and might or might not set or restore the installed signal handler (but
2430see C<EVFLAG_NOSIGMASK>).
2275 2431
2276While this does not matter for the signal disposition (libev never 2432While this does not matter for the signal disposition (libev never
2277sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on 2433sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2278C<execve>), this matters for the signal mask: many programs do not expect 2434C<execve>), this matters for the signal mask: many programs do not expect
2279certain signals to be blocked. 2435certain signals to be blocked.
2292I<has> to modify the signal mask, at least temporarily. 2448I<has> to modify the signal mask, at least temporarily.
2293 2449
2294So I can't stress this enough: I<If you do not reset your signal mask when 2450So I can't stress this enough: I<If you do not reset your signal mask when
2295you expect it to be empty, you have a race condition in your code>. This 2451you expect it to be empty, you have a race condition in your code>. This
2296is not a libev-specific thing, this is true for most event libraries. 2452is not a libev-specific thing, this is true for most event libraries.
2453
2454=head3 The special problem of threads signal handling
2455
2456POSIX threads has problematic signal handling semantics, specifically,
2457a lot of functionality (sigfd, sigwait etc.) only really works if all
2458threads in a process block signals, which is hard to achieve.
2459
2460When you want to use sigwait (or mix libev signal handling with your own
2461for the same signals), you can tackle this problem by globally blocking
2462all signals before creating any threads (or creating them with a fully set
2463sigprocmask) and also specifying the C<EVFLAG_NOSIGMASK> when creating
2464loops. Then designate one thread as "signal receiver thread" which handles
2465these signals. You can pass on any signals that libev might be interested
2466in by calling C<ev_feed_signal>.
2297 2467
2298=head3 Watcher-Specific Functions and Data Members 2468=head3 Watcher-Specific Functions and Data Members
2299 2469
2300=over 4 2470=over 4
2301 2471
2677Apart from keeping your process non-blocking (which is a useful 2847Apart from keeping your process non-blocking (which is a useful
2678effect on its own sometimes), idle watchers are a good place to do 2848effect on its own sometimes), idle watchers are a good place to do
2679"pseudo-background processing", or delay processing stuff to after the 2849"pseudo-background processing", or delay processing stuff to after the
2680event loop has handled all outstanding events. 2850event loop has handled all outstanding events.
2681 2851
2852=head3 Abusing an C<ev_idle> watcher for its side-effect
2853
2854As long as there is at least one active idle watcher, libev will never
2855sleep unnecessarily. Or in other words, it will loop as fast as possible.
2856For this to work, the idle watcher doesn't need to be invoked at all - the
2857lowest priority will do.
2858
2859This mode of operation can be useful together with an C<ev_check> watcher,
2860to do something on each event loop iteration - for example to balance load
2861between different connections.
2862
2863See L<Abusing an ev_check watcher for its side-effect> for a longer
2864example.
2865
2682=head3 Watcher-Specific Functions and Data Members 2866=head3 Watcher-Specific Functions and Data Members
2683 2867
2684=over 4 2868=over 4
2685 2869
2686=item ev_idle_init (ev_idle *, callback) 2870=item ev_idle_init (ev_idle *, callback)
2697callback, free it. Also, use no error checking, as usual. 2881callback, free it. Also, use no error checking, as usual.
2698 2882
2699 static void 2883 static void
2700 idle_cb (struct ev_loop *loop, ev_idle *w, int revents) 2884 idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
2701 { 2885 {
2886 // stop the watcher
2887 ev_idle_stop (loop, w);
2888
2889 // now we can free it
2702 free (w); 2890 free (w);
2891
2703 // now do something you wanted to do when the program has 2892 // now do something you wanted to do when the program has
2704 // no longer anything immediate to do. 2893 // no longer anything immediate to do.
2705 } 2894 }
2706 2895
2707 ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 2896 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2709 ev_idle_start (loop, idle_watcher); 2898 ev_idle_start (loop, idle_watcher);
2710 2899
2711 2900
2712=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2901=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2713 2902
2714Prepare and check watchers are usually (but not always) used in pairs: 2903Prepare and check watchers are often (but not always) used in pairs:
2715prepare watchers get invoked before the process blocks and check watchers 2904prepare watchers get invoked before the process blocks and check watchers
2716afterwards. 2905afterwards.
2717 2906
2718You I<must not> call C<ev_run> or similar functions that enter 2907You I<must not> call C<ev_run> or similar functions that enter
2719the current event loop from either C<ev_prepare> or C<ev_check> 2908the current event loop from either C<ev_prepare> or C<ev_check>
2747with priority higher than or equal to the event loop and one coroutine 2936with priority higher than or equal to the event loop and one coroutine
2748of lower priority, but only once, using idle watchers to keep the event 2937of lower priority, but only once, using idle watchers to keep the event
2749loop from blocking if lower-priority coroutines are active, thus mapping 2938loop from blocking if lower-priority coroutines are active, thus mapping
2750low-priority coroutines to idle/background tasks). 2939low-priority coroutines to idle/background tasks).
2751 2940
2752It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 2941When used for this purpose, it is recommended to give C<ev_check> watchers
2753priority, to ensure that they are being run before any other watchers 2942highest (C<EV_MAXPRI>) priority, to ensure that they are being run before
2754after the poll (this doesn't matter for C<ev_prepare> watchers). 2943any other watchers after the poll (this doesn't matter for C<ev_prepare>
2944watchers).
2755 2945
2756Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not 2946Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not
2757activate ("feed") events into libev. While libev fully supports this, they 2947activate ("feed") events into libev. While libev fully supports this, they
2758might get executed before other C<ev_check> watchers did their job. As 2948might get executed before other C<ev_check> watchers did their job. As
2759C<ev_check> watchers are often used to embed other (non-libev) event 2949C<ev_check> watchers are often used to embed other (non-libev) event
2760loops those other event loops might be in an unusable state until their 2950loops those other event loops might be in an unusable state until their
2761C<ev_check> watcher ran (always remind yourself to coexist peacefully with 2951C<ev_check> watcher ran (always remind yourself to coexist peacefully with
2762others). 2952others).
2953
2954=head3 Abusing an C<ev_check> watcher for its side-effect
2955
2956C<ev_check> (and less often also C<ev_prepare>) watchers can also be
2957useful because they are called once per event loop iteration. For
2958example, if you want to handle a large number of connections fairly, you
2959normally only do a bit of work for each active connection, and if there
2960is more work to do, you wait for the next event loop iteration, so other
2961connections have a chance of making progress.
2962
2963Using an C<ev_check> watcher is almost enough: it will be called on the
2964next event loop iteration. However, that isn't as soon as possible -
2965without external events, your C<ev_check> watcher will not be invoked.
2966
2967
2968This is where C<ev_idle> watchers come in handy - all you need is a
2969single global idle watcher that is active as long as you have one active
2970C<ev_check> watcher. The C<ev_idle> watcher makes sure the event loop
2971will not sleep, and the C<ev_check> watcher makes sure a callback gets
2972invoked. Neither watcher alone can do that.
2763 2973
2764=head3 Watcher-Specific Functions and Data Members 2974=head3 Watcher-Specific Functions and Data Members
2765 2975
2766=over 4 2976=over 4
2767 2977
3075disadvantage of having to use multiple event loops (which do not support 3285disadvantage of having to use multiple event loops (which do not support
3076signal watchers). 3286signal watchers).
3077 3287
3078When this is not possible, or you want to use the default loop for 3288When this is not possible, or you want to use the default loop for
3079other reasons, then in the process that wants to start "fresh", call 3289other reasons, then in the process that wants to start "fresh", call
3080C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying 3290C<ev_loop_destroy (EV_DEFAULT)> followed by C<ev_default_loop (...)>.
3081the default loop will "orphan" (not stop) all registered watchers, so you 3291Destroying the default loop will "orphan" (not stop) all registered
3082have to be careful not to execute code that modifies those watchers. Note 3292watchers, so you have to be careful not to execute code that modifies
3083also that in that case, you have to re-register any signal watchers. 3293those watchers. Note also that in that case, you have to re-register any
3294signal watchers.
3084 3295
3085=head3 Watcher-Specific Functions and Data Members 3296=head3 Watcher-Specific Functions and Data Members
3086 3297
3087=over 4 3298=over 4
3088 3299
3089=item ev_fork_init (ev_signal *, callback) 3300=item ev_fork_init (ev_fork *, callback)
3090 3301
3091Initialises and configures the fork watcher - it has no parameters of any 3302Initialises and configures the fork watcher - it has no parameters of any
3092kind. There is a C<ev_fork_set> macro, but using it is utterly pointless, 3303kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
3093believe me. 3304really.
3094 3305
3095=back 3306=back
3096 3307
3097 3308
3309=head2 C<ev_cleanup> - even the best things end
3310
3311Cleanup watchers are called just before the event loop is being destroyed
3312by a call to C<ev_loop_destroy>.
3313
3314While there is no guarantee that the event loop gets destroyed, cleanup
3315watchers provide a convenient method to install cleanup hooks for your
3316program, worker threads and so on - you just to make sure to destroy the
3317loop when you want them to be invoked.
3318
3319Cleanup watchers are invoked in the same way as any other watcher. Unlike
3320all other watchers, they do not keep a reference to the event loop (which
3321makes a lot of sense if you think about it). Like all other watchers, you
3322can call libev functions in the callback, except C<ev_cleanup_start>.
3323
3324=head3 Watcher-Specific Functions and Data Members
3325
3326=over 4
3327
3328=item ev_cleanup_init (ev_cleanup *, callback)
3329
3330Initialises and configures the cleanup watcher - it has no parameters of
3331any kind. There is a C<ev_cleanup_set> macro, but using it is utterly
3332pointless, I assure you.
3333
3334=back
3335
3336Example: Register an atexit handler to destroy the default loop, so any
3337cleanup functions are called.
3338
3339 static void
3340 program_exits (void)
3341 {
3342 ev_loop_destroy (EV_DEFAULT_UC);
3343 }
3344
3345 ...
3346 atexit (program_exits);
3347
3348
3098=head2 C<ev_async> - how to wake up an event loop 3349=head2 C<ev_async> - how to wake up an event loop
3099 3350
3100In general, you cannot use an C<ev_run> from multiple threads or other 3351In general, you cannot use an C<ev_loop> from multiple threads or other
3101asynchronous sources such as signal handlers (as opposed to multiple event 3352asynchronous sources such as signal handlers (as opposed to multiple event
3102loops - those are of course safe to use in different threads). 3353loops - those are of course safe to use in different threads).
3103 3354
3104Sometimes, however, you need to wake up an event loop you do not control, 3355Sometimes, however, you need to wake up an event loop you do not control,
3105for example because it belongs to another thread. This is what C<ev_async> 3356for example because it belongs to another thread. This is what C<ev_async>
3107it by calling C<ev_async_send>, which is thread- and signal safe. 3358it by calling C<ev_async_send>, which is thread- and signal safe.
3108 3359
3109This functionality is very similar to C<ev_signal> watchers, as signals, 3360This functionality is very similar to C<ev_signal> watchers, as signals,
3110too, are asynchronous in nature, and signals, too, will be compressed 3361too, are asynchronous in nature, and signals, too, will be compressed
3111(i.e. the number of callback invocations may be less than the number of 3362(i.e. the number of callback invocations may be less than the number of
3112C<ev_async_sent> calls). 3363C<ev_async_send> calls). In fact, you could use signal watchers as a kind
3113 3364of "global async watchers" by using a watcher on an otherwise unused
3114Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not 3365signal, and C<ev_feed_signal> to signal this watcher from another thread,
3115just the default loop. 3366even without knowing which loop owns the signal.
3116 3367
3117=head3 Queueing 3368=head3 Queueing
3118 3369
3119C<ev_async> does not support queueing of data in any way. The reason 3370C<ev_async> does not support queueing of data in any way. The reason
3120is that the author does not know of a simple (or any) algorithm for a 3371is that the author does not know of a simple (or any) algorithm for a
3212trust me. 3463trust me.
3213 3464
3214=item ev_async_send (loop, ev_async *) 3465=item ev_async_send (loop, ev_async *)
3215 3466
3216Sends/signals/activates the given C<ev_async> watcher, that is, feeds 3467Sends/signals/activates the given C<ev_async> watcher, that is, feeds
3217an C<EV_ASYNC> event on the watcher into the event loop. Unlike 3468an C<EV_ASYNC> event on the watcher into the event loop, and instantly
3469returns.
3470
3218C<ev_feed_event>, this call is safe to do from other threads, signal or 3471Unlike C<ev_feed_event>, this call is safe to do from other threads,
3219similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 3472signal or similar contexts (see the discussion of C<EV_ATOMIC_T> in the
3220section below on what exactly this means). 3473embedding section below on what exactly this means).
3221 3474
3222Note that, as with other watchers in libev, multiple events might get 3475Note that, as with other watchers in libev, multiple events might get
3223compressed into a single callback invocation (another way to look at this 3476compressed into a single callback invocation (another way to look at
3224is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>, 3477this is that C<ev_async> watchers are level-triggered: they are set on
3225reset when the event loop detects that). 3478C<ev_async_send>, reset when the event loop detects that).
3226 3479
3227This call incurs the overhead of a system call only once per event loop 3480This call incurs the overhead of at most one extra system call per event
3228iteration, so while the overhead might be noticeable, it doesn't apply to 3481loop iteration, if the event loop is blocked, and no syscall at all if
3229repeated calls to C<ev_async_send> for the same event loop. 3482the event loop (or your program) is processing events. That means that
3483repeated calls are basically free (there is no need to avoid calls for
3484performance reasons) and that the overhead becomes smaller (typically
3485zero) under load.
3230 3486
3231=item bool = ev_async_pending (ev_async *) 3487=item bool = ev_async_pending (ev_async *)
3232 3488
3233Returns a non-zero value when C<ev_async_send> has been called on the 3489Returns a non-zero value when C<ev_async_send> has been called on the
3234watcher but the event has not yet been processed (or even noted) by the 3490watcher but the event has not yet been processed (or even noted) by the
3289 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3545 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3290 3546
3291=item ev_feed_fd_event (loop, int fd, int revents) 3547=item ev_feed_fd_event (loop, int fd, int revents)
3292 3548
3293Feed an event on the given fd, as if a file descriptor backend detected 3549Feed an event on the given fd, as if a file descriptor backend detected
3294the given events it. 3550the given events.
3295 3551
3296=item ev_feed_signal_event (loop, int signum) 3552=item ev_feed_signal_event (loop, int signum)
3297 3553
3298Feed an event as if the given signal occurred (C<loop> must be the default 3554Feed an event as if the given signal occurred. See also C<ev_feed_signal>,
3299loop!). 3555which is async-safe.
3300 3556
3301=back 3557=back
3558
3559
3560=head1 COMMON OR USEFUL IDIOMS (OR BOTH)
3561
3562This section explains some common idioms that are not immediately
3563obvious. Note that examples are sprinkled over the whole manual, and this
3564section only contains stuff that wouldn't fit anywhere else.
3565
3566=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
3567
3568Each watcher has, by default, a C<void *data> member that you can read
3569or modify at any time: libev will completely ignore it. This can be used
3570to associate arbitrary data with your watcher. If you need more data and
3571don't want to allocate memory separately and store a pointer to it in that
3572data member, you can also "subclass" the watcher type and provide your own
3573data:
3574
3575 struct my_io
3576 {
3577 ev_io io;
3578 int otherfd;
3579 void *somedata;
3580 struct whatever *mostinteresting;
3581 };
3582
3583 ...
3584 struct my_io w;
3585 ev_io_init (&w.io, my_cb, fd, EV_READ);
3586
3587And since your callback will be called with a pointer to the watcher, you
3588can cast it back to your own type:
3589
3590 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
3591 {
3592 struct my_io *w = (struct my_io *)w_;
3593 ...
3594 }
3595
3596More interesting and less C-conformant ways of casting your callback
3597function type instead have been omitted.
3598
3599=head2 BUILDING YOUR OWN COMPOSITE WATCHERS
3600
3601Another common scenario is to use some data structure with multiple
3602embedded watchers, in effect creating your own watcher that combines
3603multiple libev event sources into one "super-watcher":
3604
3605 struct my_biggy
3606 {
3607 int some_data;
3608 ev_timer t1;
3609 ev_timer t2;
3610 }
3611
3612In this case getting the pointer to C<my_biggy> is a bit more
3613complicated: Either you store the address of your C<my_biggy> struct in
3614the C<data> member of the watcher (for woozies or C++ coders), or you need
3615to use some pointer arithmetic using C<offsetof> inside your watchers (for
3616real programmers):
3617
3618 #include <stddef.h>
3619
3620 static void
3621 t1_cb (EV_P_ ev_timer *w, int revents)
3622 {
3623 struct my_biggy big = (struct my_biggy *)
3624 (((char *)w) - offsetof (struct my_biggy, t1));
3625 }
3626
3627 static void
3628 t2_cb (EV_P_ ev_timer *w, int revents)
3629 {
3630 struct my_biggy big = (struct my_biggy *)
3631 (((char *)w) - offsetof (struct my_biggy, t2));
3632 }
3633
3634=head2 AVOIDING FINISHING BEFORE RETURNING
3635
3636Often you have structures like this in event-based programs:
3637
3638 callback ()
3639 {
3640 free (request);
3641 }
3642
3643 request = start_new_request (..., callback);
3644
3645The intent is to start some "lengthy" operation. The C<request> could be
3646used to cancel the operation, or do other things with it.
3647
3648It's not uncommon to have code paths in C<start_new_request> that
3649immediately invoke the callback, for example, to report errors. Or you add
3650some caching layer that finds that it can skip the lengthy aspects of the
3651operation and simply invoke the callback with the result.
3652
3653The problem here is that this will happen I<before> C<start_new_request>
3654has returned, so C<request> is not set.
3655
3656Even if you pass the request by some safer means to the callback, you
3657might want to do something to the request after starting it, such as
3658canceling it, which probably isn't working so well when the callback has
3659already been invoked.
3660
3661A common way around all these issues is to make sure that
3662C<start_new_request> I<always> returns before the callback is invoked. If
3663C<start_new_request> immediately knows the result, it can artificially
3664delay invoking the callback by e.g. using a C<prepare> or C<idle> watcher
3665for example, or more sneakily, by reusing an existing (stopped) watcher
3666and pushing it into the pending queue:
3667
3668 ev_set_cb (watcher, callback);
3669 ev_feed_event (EV_A_ watcher, 0);
3670
3671This way, C<start_new_request> can safely return before the callback is
3672invoked, while not delaying callback invocation too much.
3673
3674=head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS
3675
3676Often (especially in GUI toolkits) there are places where you have
3677I<modal> interaction, which is most easily implemented by recursively
3678invoking C<ev_run>.
3679
3680This brings the problem of exiting - a callback might want to finish the
3681main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but
3682a modal "Are you sure?" dialog is still waiting), or just the nested one
3683and not the main one (e.g. user clocked "Ok" in a modal dialog), or some
3684other combination: In these cases, C<ev_break> will not work alone.
3685
3686The solution is to maintain "break this loop" variable for each C<ev_run>
3687invocation, and use a loop around C<ev_run> until the condition is
3688triggered, using C<EVRUN_ONCE>:
3689
3690 // main loop
3691 int exit_main_loop = 0;
3692
3693 while (!exit_main_loop)
3694 ev_run (EV_DEFAULT_ EVRUN_ONCE);
3695
3696 // in a modal watcher
3697 int exit_nested_loop = 0;
3698
3699 while (!exit_nested_loop)
3700 ev_run (EV_A_ EVRUN_ONCE);
3701
3702To exit from any of these loops, just set the corresponding exit variable:
3703
3704 // exit modal loop
3705 exit_nested_loop = 1;
3706
3707 // exit main program, after modal loop is finished
3708 exit_main_loop = 1;
3709
3710 // exit both
3711 exit_main_loop = exit_nested_loop = 1;
3712
3713=head2 THREAD LOCKING EXAMPLE
3714
3715Here is a fictitious example of how to run an event loop in a different
3716thread from where callbacks are being invoked and watchers are
3717created/added/removed.
3718
3719For a real-world example, see the C<EV::Loop::Async> perl module,
3720which uses exactly this technique (which is suited for many high-level
3721languages).
3722
3723The example uses a pthread mutex to protect the loop data, a condition
3724variable to wait for callback invocations, an async watcher to notify the
3725event loop thread and an unspecified mechanism to wake up the main thread.
3726
3727First, you need to associate some data with the event loop:
3728
3729 typedef struct {
3730 mutex_t lock; /* global loop lock */
3731 ev_async async_w;
3732 thread_t tid;
3733 cond_t invoke_cv;
3734 } userdata;
3735
3736 void prepare_loop (EV_P)
3737 {
3738 // for simplicity, we use a static userdata struct.
3739 static userdata u;
3740
3741 ev_async_init (&u->async_w, async_cb);
3742 ev_async_start (EV_A_ &u->async_w);
3743
3744 pthread_mutex_init (&u->lock, 0);
3745 pthread_cond_init (&u->invoke_cv, 0);
3746
3747 // now associate this with the loop
3748 ev_set_userdata (EV_A_ u);
3749 ev_set_invoke_pending_cb (EV_A_ l_invoke);
3750 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3751
3752 // then create the thread running ev_run
3753 pthread_create (&u->tid, 0, l_run, EV_A);
3754 }
3755
3756The callback for the C<ev_async> watcher does nothing: the watcher is used
3757solely to wake up the event loop so it takes notice of any new watchers
3758that might have been added:
3759
3760 static void
3761 async_cb (EV_P_ ev_async *w, int revents)
3762 {
3763 // just used for the side effects
3764 }
3765
3766The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
3767protecting the loop data, respectively.
3768
3769 static void
3770 l_release (EV_P)
3771 {
3772 userdata *u = ev_userdata (EV_A);
3773 pthread_mutex_unlock (&u->lock);
3774 }
3775
3776 static void
3777 l_acquire (EV_P)
3778 {
3779 userdata *u = ev_userdata (EV_A);
3780 pthread_mutex_lock (&u->lock);
3781 }
3782
3783The event loop thread first acquires the mutex, and then jumps straight
3784into C<ev_run>:
3785
3786 void *
3787 l_run (void *thr_arg)
3788 {
3789 struct ev_loop *loop = (struct ev_loop *)thr_arg;
3790
3791 l_acquire (EV_A);
3792 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
3793 ev_run (EV_A_ 0);
3794 l_release (EV_A);
3795
3796 return 0;
3797 }
3798
3799Instead of invoking all pending watchers, the C<l_invoke> callback will
3800signal the main thread via some unspecified mechanism (signals? pipe
3801writes? C<Async::Interrupt>?) and then waits until all pending watchers
3802have been called (in a while loop because a) spurious wakeups are possible
3803and b) skipping inter-thread-communication when there are no pending
3804watchers is very beneficial):
3805
3806 static void
3807 l_invoke (EV_P)
3808 {
3809 userdata *u = ev_userdata (EV_A);
3810
3811 while (ev_pending_count (EV_A))
3812 {
3813 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
3814 pthread_cond_wait (&u->invoke_cv, &u->lock);
3815 }
3816 }
3817
3818Now, whenever the main thread gets told to invoke pending watchers, it
3819will grab the lock, call C<ev_invoke_pending> and then signal the loop
3820thread to continue:
3821
3822 static void
3823 real_invoke_pending (EV_P)
3824 {
3825 userdata *u = ev_userdata (EV_A);
3826
3827 pthread_mutex_lock (&u->lock);
3828 ev_invoke_pending (EV_A);
3829 pthread_cond_signal (&u->invoke_cv);
3830 pthread_mutex_unlock (&u->lock);
3831 }
3832
3833Whenever you want to start/stop a watcher or do other modifications to an
3834event loop, you will now have to lock:
3835
3836 ev_timer timeout_watcher;
3837 userdata *u = ev_userdata (EV_A);
3838
3839 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
3840
3841 pthread_mutex_lock (&u->lock);
3842 ev_timer_start (EV_A_ &timeout_watcher);
3843 ev_async_send (EV_A_ &u->async_w);
3844 pthread_mutex_unlock (&u->lock);
3845
3846Note that sending the C<ev_async> watcher is required because otherwise
3847an event loop currently blocking in the kernel will have no knowledge
3848about the newly added timer. By waking up the loop it will pick up any new
3849watchers in the next event loop iteration.
3850
3851=head2 THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS
3852
3853While the overhead of a callback that e.g. schedules a thread is small, it
3854is still an overhead. If you embed libev, and your main usage is with some
3855kind of threads or coroutines, you might want to customise libev so that
3856doesn't need callbacks anymore.
3857
3858Imagine you have coroutines that you can switch to using a function
3859C<switch_to (coro)>, that libev runs in a coroutine called C<libev_coro>
3860and that due to some magic, the currently active coroutine is stored in a
3861global called C<current_coro>. Then you can build your own "wait for libev
3862event" primitive by changing C<EV_CB_DECLARE> and C<EV_CB_INVOKE> (note
3863the differing C<;> conventions):
3864
3865 #define EV_CB_DECLARE(type) struct my_coro *cb;
3866 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
3867
3868That means instead of having a C callback function, you store the
3869coroutine to switch to in each watcher, and instead of having libev call
3870your callback, you instead have it switch to that coroutine.
3871
3872A coroutine might now wait for an event with a function called
3873C<wait_for_event>. (the watcher needs to be started, as always, but it doesn't
3874matter when, or whether the watcher is active or not when this function is
3875called):
3876
3877 void
3878 wait_for_event (ev_watcher *w)
3879 {
3880 ev_set_cb (w, current_coro);
3881 switch_to (libev_coro);
3882 }
3883
3884That basically suspends the coroutine inside C<wait_for_event> and
3885continues the libev coroutine, which, when appropriate, switches back to
3886this or any other coroutine.
3887
3888You can do similar tricks if you have, say, threads with an event queue -
3889instead of storing a coroutine, you store the queue object and instead of
3890switching to a coroutine, you push the watcher onto the queue and notify
3891any waiters.
3892
3893To embed libev, see L<EMBEDDING>, but in short, it's easiest to create two
3894files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
3895
3896 // my_ev.h
3897 #define EV_CB_DECLARE(type) struct my_coro *cb;
3898 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb);
3899 #include "../libev/ev.h"
3900
3901 // my_ev.c
3902 #define EV_H "my_ev.h"
3903 #include "../libev/ev.c"
3904
3905And then use F<my_ev.h> when you would normally use F<ev.h>, and compile
3906F<my_ev.c> into your project. When properly specifying include paths, you
3907can even use F<ev.h> as header file name directly.
3302 3908
3303 3909
3304=head1 LIBEVENT EMULATION 3910=head1 LIBEVENT EMULATION
3305 3911
3306Libev offers a compatibility emulation layer for libevent. It cannot 3912Libev offers a compatibility emulation layer for libevent. It cannot
3307emulate the internals of libevent, so here are some usage hints: 3913emulate the internals of libevent, so here are some usage hints:
3308 3914
3309=over 4 3915=over 4
3916
3917=item * Only the libevent-1.4.1-beta API is being emulated.
3918
3919This was the newest libevent version available when libev was implemented,
3920and is still mostly unchanged in 2010.
3310 3921
3311=item * Use it by including <event.h>, as usual. 3922=item * Use it by including <event.h>, as usual.
3312 3923
3313=item * The following members are fully supported: ev_base, ev_callback, 3924=item * The following members are fully supported: ev_base, ev_callback,
3314ev_arg, ev_fd, ev_res, ev_events. 3925ev_arg, ev_fd, ev_res, ev_events.
3320=item * Priorities are not currently supported. Initialising priorities 3931=item * Priorities are not currently supported. Initialising priorities
3321will fail and all watchers will have the same priority, even though there 3932will fail and all watchers will have the same priority, even though there
3322is an ev_pri field. 3933is an ev_pri field.
3323 3934
3324=item * In libevent, the last base created gets the signals, in libev, the 3935=item * In libevent, the last base created gets the signals, in libev, the
3325first base created (== the default loop) gets the signals. 3936base that registered the signal gets the signals.
3326 3937
3327=item * Other members are not supported. 3938=item * Other members are not supported.
3328 3939
3329=item * The libev emulation is I<not> ABI compatible to libevent, you need 3940=item * The libev emulation is I<not> ABI compatible to libevent, you need
3330to use the libev header file and library. 3941to use the libev header file and library.
3331 3942
3332=back 3943=back
3333 3944
3334=head1 C++ SUPPORT 3945=head1 C++ SUPPORT
3946
3947=head2 C API
3948
3949The normal C API should work fine when used from C++: both ev.h and the
3950libev sources can be compiled as C++. Therefore, code that uses the C API
3951will work fine.
3952
3953Proper exception specifications might have to be added to callbacks passed
3954to libev: exceptions may be thrown only from watcher callbacks, all
3955other callbacks (allocator, syserr, loop acquire/release and periodioc
3956reschedule callbacks) must not throw exceptions, and might need a C<throw
3957()> specification. If you have code that needs to be compiled as both C
3958and C++ you can use the C<EV_THROW> macro for this:
3959
3960 static void
3961 fatal_error (const char *msg) EV_THROW
3962 {
3963 perror (msg);
3964 abort ();
3965 }
3966
3967 ...
3968 ev_set_syserr_cb (fatal_error);
3969
3970The only API functions that can currently throw exceptions are C<ev_run>,
3971C<ev_invoke>, C<ev_invoke_pending> and C<ev_loop_destroy> (the latter
3972because it runs cleanup watchers).
3973
3974Throwing exceptions in watcher callbacks is only supported if libev itself
3975is compiled with a C++ compiler or your C and C++ environments allow
3976throwing exceptions through C libraries (most do).
3977
3978=head2 C++ API
3335 3979
3336Libev comes with some simplistic wrapper classes for C++ that mainly allow 3980Libev comes with some simplistic wrapper classes for C++ that mainly allow
3337you to use some convenience methods to start/stop watchers and also change 3981you to use some convenience methods to start/stop watchers and also change
3338the callback model to a model using method callbacks on objects. 3982the callback model to a model using method callbacks on objects.
3339 3983
3349Care has been taken to keep the overhead low. The only data member the C++ 3993Care has been taken to keep the overhead low. The only data member the C++
3350classes add (compared to plain C-style watchers) is the event loop pointer 3994classes add (compared to plain C-style watchers) is the event loop pointer
3351that the watcher is associated with (or no additional members at all if 3995that the watcher is associated with (or no additional members at all if
3352you disable C<EV_MULTIPLICITY> when embedding libev). 3996you disable C<EV_MULTIPLICITY> when embedding libev).
3353 3997
3354Currently, functions, and static and non-static member functions can be 3998Currently, functions, static and non-static member functions and classes
3355used as callbacks. Other types should be easy to add as long as they only 3999with C<operator ()> can be used as callbacks. Other types should be easy
3356need one additional pointer for context. If you need support for other 4000to add as long as they only need one additional pointer for context. If
3357types of functors please contact the author (preferably after implementing 4001you need support for other types of functors please contact the author
3358it). 4002(preferably after implementing it).
4003
4004For all this to work, your C++ compiler either has to use the same calling
4005conventions as your C compiler (for static member functions), or you have
4006to embed libev and compile libev itself as C++.
3359 4007
3360Here is a list of things available in the C<ev> namespace: 4008Here is a list of things available in the C<ev> namespace:
3361 4009
3362=over 4 4010=over 4
3363 4011
3373=item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc. 4021=item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc.
3374 4022
3375For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of 4023For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of
3376the same name in the C<ev> namespace, with the exception of C<ev_signal> 4024the same name in the C<ev> namespace, with the exception of C<ev_signal>
3377which is called C<ev::sig> to avoid clashes with the C<signal> macro 4025which is called C<ev::sig> to avoid clashes with the C<signal> macro
3378defines by many implementations. 4026defined by many implementations.
3379 4027
3380All of those classes have these methods: 4028All of those classes have these methods:
3381 4029
3382=over 4 4030=over 4
3383 4031
3516watchers in the constructor. 4164watchers in the constructor.
3517 4165
3518 class myclass 4166 class myclass
3519 { 4167 {
3520 ev::io io ; void io_cb (ev::io &w, int revents); 4168 ev::io io ; void io_cb (ev::io &w, int revents);
3521 ev::io2 io2 ; void io2_cb (ev::io &w, int revents); 4169 ev::io io2 ; void io2_cb (ev::io &w, int revents);
3522 ev::idle idle; void idle_cb (ev::idle &w, int revents); 4170 ev::idle idle; void idle_cb (ev::idle &w, int revents);
3523 4171
3524 myclass (int fd) 4172 myclass (int fd)
3525 { 4173 {
3526 io .set <myclass, &myclass::io_cb > (this); 4174 io .set <myclass, &myclass::io_cb > (this);
3577L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>. 4225L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3578 4226
3579=item D 4227=item D
3580 4228
3581Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 4229Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
3582be found at L<http://proj.llucax.com.ar/wiki/evd>. 4230be found at L<http://www.llucax.com.ar/proj/ev.d/index.html>.
3583 4231
3584=item Ocaml 4232=item Ocaml
3585 4233
3586Erkki Seppala has written Ocaml bindings for libev, to be found at 4234Erkki Seppala has written Ocaml bindings for libev, to be found at
3587L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 4235L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3635suitable for use with C<EV_A>. 4283suitable for use with C<EV_A>.
3636 4284
3637=item C<EV_DEFAULT>, C<EV_DEFAULT_> 4285=item C<EV_DEFAULT>, C<EV_DEFAULT_>
3638 4286
3639Similar to the other two macros, this gives you the value of the default 4287Similar to the other two macros, this gives you the value of the default
3640loop, if multiple loops are supported ("ev loop default"). 4288loop, if multiple loops are supported ("ev loop default"). The default loop
4289will be initialised if it isn't already initialised.
4290
4291For non-multiplicity builds, these macros do nothing, so you always have
4292to initialise the loop somewhere.
3641 4293
3642=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_> 4294=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
3643 4295
3644Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the 4296Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
3645default loop has been initialised (C<UC> == unchecked). Their behaviour 4297default loop has been initialised (C<UC> == unchecked). Their behaviour
3790supported). It will also not define any of the structs usually found in 4442supported). It will also not define any of the structs usually found in
3791F<event.h> that are not directly supported by the libev core alone. 4443F<event.h> that are not directly supported by the libev core alone.
3792 4444
3793In standalone mode, libev will still try to automatically deduce the 4445In standalone mode, libev will still try to automatically deduce the
3794configuration, but has to be more conservative. 4446configuration, but has to be more conservative.
4447
4448=item EV_USE_FLOOR
4449
4450If defined to be C<1>, libev will use the C<floor ()> function for its
4451periodic reschedule calculations, otherwise libev will fall back on a
4452portable (slower) implementation. If you enable this, you usually have to
4453link against libm or something equivalent. Enabling this when the C<floor>
4454function is not available will fail, so the safe default is to not enable
4455this.
3795 4456
3796=item EV_USE_MONOTONIC 4457=item EV_USE_MONOTONIC
3797 4458
3798If defined to be C<1>, libev will try to detect the availability of the 4459If defined to be C<1>, libev will try to detect the availability of the
3799monotonic clock option at both compile time and runtime. Otherwise no 4460monotonic clock option at both compile time and runtime. Otherwise no
3929If defined to be C<1>, libev will compile in support for the Linux inotify 4590If defined to be C<1>, libev will compile in support for the Linux inotify
3930interface to speed up C<ev_stat> watchers. Its actual availability will 4591interface to speed up C<ev_stat> watchers. Its actual availability will
3931be detected at runtime. If undefined, it will be enabled if the headers 4592be detected at runtime. If undefined, it will be enabled if the headers
3932indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4593indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
3933 4594
4595=item EV_NO_SMP
4596
4597If defined to be C<1>, libev will assume that memory is always coherent
4598between threads, that is, threads can be used, but threads never run on
4599different cpus (or different cpu cores). This reduces dependencies
4600and makes libev faster.
4601
4602=item EV_NO_THREADS
4603
4604If defined to be C<1>, libev will assume that it will never be called
4605from different threads, which is a stronger assumption than C<EV_NO_SMP>,
4606above. This reduces dependencies and makes libev faster.
4607
3934=item EV_ATOMIC_T 4608=item EV_ATOMIC_T
3935 4609
3936Libev requires an integer type (suitable for storing C<0> or C<1>) whose 4610Libev requires an integer type (suitable for storing C<0> or C<1>) whose
3937access is atomic with respect to other threads or signal contexts. No such 4611access is atomic and serialised with respect to other threads or signal
3938type is easily found in the C language, so you can provide your own type 4612contexts. No such type is easily found in the C language, so you can
3939that you know is safe for your purposes. It is used both for signal handler "locking" 4613provide your own type that you know is safe for your purposes. It is used
3940as well as for signal and thread safety in C<ev_async> watchers. 4614both for signal handler "locking" as well as for signal and thread safety
4615in C<ev_async> watchers.
3941 4616
3942In the absence of this define, libev will use C<sig_atomic_t volatile> 4617In the absence of this define, libev will use C<sig_atomic_t volatile>
3943(from F<signal.h>), which is usually good enough on most platforms. 4618(from F<signal.h>), which is usually good enough on most platforms,
4619although strictly speaking using a type that also implies a memory fence
4620is required.
3944 4621
3945=item EV_H (h) 4622=item EV_H (h)
3946 4623
3947The name of the F<ev.h> header file used to include it. The default if 4624The name of the F<ev.h> header file used to include it. The default if
3948undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 4625undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3972will have the C<struct ev_loop *> as first argument, and you can create 4649will have the C<struct ev_loop *> as first argument, and you can create
3973additional independent event loops. Otherwise there will be no support 4650additional independent event loops. Otherwise there will be no support
3974for multiple event loops and there is no first event loop pointer 4651for multiple event loops and there is no first event loop pointer
3975argument. Instead, all functions act on the single default loop. 4652argument. Instead, all functions act on the single default loop.
3976 4653
4654Note that C<EV_DEFAULT> and C<EV_DEFAULT_> will no longer provide a
4655default loop when multiplicity is switched off - you always have to
4656initialise the loop manually in this case.
4657
3977=item EV_MINPRI 4658=item EV_MINPRI
3978 4659
3979=item EV_MAXPRI 4660=item EV_MAXPRI
3980 4661
3981The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to 4662The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
4017 #define EV_USE_POLL 1 4698 #define EV_USE_POLL 1
4018 #define EV_CHILD_ENABLE 1 4699 #define EV_CHILD_ENABLE 1
4019 #define EV_ASYNC_ENABLE 1 4700 #define EV_ASYNC_ENABLE 1
4020 4701
4021The actual value is a bitset, it can be a combination of the following 4702The actual value is a bitset, it can be a combination of the following
4022values: 4703values (by default, all of these are enabled):
4023 4704
4024=over 4 4705=over 4
4025 4706
4026=item C<1> - faster/larger code 4707=item C<1> - faster/larger code
4027 4708
4031code size by roughly 30% on amd64). 4712code size by roughly 30% on amd64).
4032 4713
4033When optimising for size, use of compiler flags such as C<-Os> with 4714When optimising for size, use of compiler flags such as C<-Os> with
4034gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of 4715gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
4035assertions. 4716assertions.
4717
4718The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
4719(e.g. gcc with C<-Os>).
4036 4720
4037=item C<2> - faster/larger data structures 4721=item C<2> - faster/larger data structures
4038 4722
4039Replaces the small 2-heap for timer management by a faster 4-heap, larger 4723Replaces the small 2-heap for timer management by a faster 4-heap, larger
4040hash table sizes and so on. This will usually further increase code size 4724hash table sizes and so on. This will usually further increase code size
4041and can additionally have an effect on the size of data structures at 4725and can additionally have an effect on the size of data structures at
4042runtime. 4726runtime.
4043 4727
4728The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
4729(e.g. gcc with C<-Os>).
4730
4044=item C<4> - full API configuration 4731=item C<4> - full API configuration
4045 4732
4046This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and 4733This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
4047enables multiplicity (C<EV_MULTIPLICITY>=1). 4734enables multiplicity (C<EV_MULTIPLICITY>=1).
4048 4735
4078 4765
4079With an intelligent-enough linker (gcc+binutils are intelligent enough 4766With an intelligent-enough linker (gcc+binutils are intelligent enough
4080when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by 4767when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
4081your program might be left out as well - a binary starting a timer and an 4768your program might be left out as well - a binary starting a timer and an
4082I/O watcher then might come out at only 5Kb. 4769I/O watcher then might come out at only 5Kb.
4770
4771=item EV_API_STATIC
4772
4773If this symbol is defined (by default it is not), then all identifiers
4774will have static linkage. This means that libev will not export any
4775identifiers, and you cannot link against libev anymore. This can be useful
4776when you embed libev, only want to use libev functions in a single file,
4777and do not want its identifiers to be visible.
4778
4779To use this, define C<EV_API_STATIC> and include F<ev.c> in the file that
4780wants to use libev.
4781
4782This option only works when libev is compiled with a C compiler, as C++
4783doesn't support the required declaration syntax.
4083 4784
4084=item EV_AVOID_STDIO 4785=item EV_AVOID_STDIO
4085 4786
4086If this is set to C<1> at compiletime, then libev will avoid using stdio 4787If this is set to C<1> at compiletime, then libev will avoid using stdio
4087functions (printf, scanf, perror etc.). This will increase the code size 4788functions (printf, scanf, perror etc.). This will increase the code size
4231And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4932And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
4232 4933
4233 #include "ev_cpp.h" 4934 #include "ev_cpp.h"
4234 #include "ev.c" 4935 #include "ev.c"
4235 4936
4236=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES 4937=head1 INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT
4237 4938
4238=head2 THREADS AND COROUTINES 4939=head2 THREADS AND COROUTINES
4239 4940
4240=head3 THREADS 4941=head3 THREADS
4241 4942
4292default loop and triggering an C<ev_async> watcher from the default loop 4993default loop and triggering an C<ev_async> watcher from the default loop
4293watcher callback into the event loop interested in the signal. 4994watcher callback into the event loop interested in the signal.
4294 4995
4295=back 4996=back
4296 4997
4297=head4 THREAD LOCKING EXAMPLE 4998See also L<THREAD LOCKING EXAMPLE>.
4298
4299Here is a fictitious example of how to run an event loop in a different
4300thread than where callbacks are being invoked and watchers are
4301created/added/removed.
4302
4303For a real-world example, see the C<EV::Loop::Async> perl module,
4304which uses exactly this technique (which is suited for many high-level
4305languages).
4306
4307The example uses a pthread mutex to protect the loop data, a condition
4308variable to wait for callback invocations, an async watcher to notify the
4309event loop thread and an unspecified mechanism to wake up the main thread.
4310
4311First, you need to associate some data with the event loop:
4312
4313 typedef struct {
4314 mutex_t lock; /* global loop lock */
4315 ev_async async_w;
4316 thread_t tid;
4317 cond_t invoke_cv;
4318 } userdata;
4319
4320 void prepare_loop (EV_P)
4321 {
4322 // for simplicity, we use a static userdata struct.
4323 static userdata u;
4324
4325 ev_async_init (&u->async_w, async_cb);
4326 ev_async_start (EV_A_ &u->async_w);
4327
4328 pthread_mutex_init (&u->lock, 0);
4329 pthread_cond_init (&u->invoke_cv, 0);
4330
4331 // now associate this with the loop
4332 ev_set_userdata (EV_A_ u);
4333 ev_set_invoke_pending_cb (EV_A_ l_invoke);
4334 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4335
4336 // then create the thread running ev_loop
4337 pthread_create (&u->tid, 0, l_run, EV_A);
4338 }
4339
4340The callback for the C<ev_async> watcher does nothing: the watcher is used
4341solely to wake up the event loop so it takes notice of any new watchers
4342that might have been added:
4343
4344 static void
4345 async_cb (EV_P_ ev_async *w, int revents)
4346 {
4347 // just used for the side effects
4348 }
4349
4350The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4351protecting the loop data, respectively.
4352
4353 static void
4354 l_release (EV_P)
4355 {
4356 userdata *u = ev_userdata (EV_A);
4357 pthread_mutex_unlock (&u->lock);
4358 }
4359
4360 static void
4361 l_acquire (EV_P)
4362 {
4363 userdata *u = ev_userdata (EV_A);
4364 pthread_mutex_lock (&u->lock);
4365 }
4366
4367The event loop thread first acquires the mutex, and then jumps straight
4368into C<ev_run>:
4369
4370 void *
4371 l_run (void *thr_arg)
4372 {
4373 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4374
4375 l_acquire (EV_A);
4376 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4377 ev_run (EV_A_ 0);
4378 l_release (EV_A);
4379
4380 return 0;
4381 }
4382
4383Instead of invoking all pending watchers, the C<l_invoke> callback will
4384signal the main thread via some unspecified mechanism (signals? pipe
4385writes? C<Async::Interrupt>?) and then waits until all pending watchers
4386have been called (in a while loop because a) spurious wakeups are possible
4387and b) skipping inter-thread-communication when there are no pending
4388watchers is very beneficial):
4389
4390 static void
4391 l_invoke (EV_P)
4392 {
4393 userdata *u = ev_userdata (EV_A);
4394
4395 while (ev_pending_count (EV_A))
4396 {
4397 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4398 pthread_cond_wait (&u->invoke_cv, &u->lock);
4399 }
4400 }
4401
4402Now, whenever the main thread gets told to invoke pending watchers, it
4403will grab the lock, call C<ev_invoke_pending> and then signal the loop
4404thread to continue:
4405
4406 static void
4407 real_invoke_pending (EV_P)
4408 {
4409 userdata *u = ev_userdata (EV_A);
4410
4411 pthread_mutex_lock (&u->lock);
4412 ev_invoke_pending (EV_A);
4413 pthread_cond_signal (&u->invoke_cv);
4414 pthread_mutex_unlock (&u->lock);
4415 }
4416
4417Whenever you want to start/stop a watcher or do other modifications to an
4418event loop, you will now have to lock:
4419
4420 ev_timer timeout_watcher;
4421 userdata *u = ev_userdata (EV_A);
4422
4423 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4424
4425 pthread_mutex_lock (&u->lock);
4426 ev_timer_start (EV_A_ &timeout_watcher);
4427 ev_async_send (EV_A_ &u->async_w);
4428 pthread_mutex_unlock (&u->lock);
4429
4430Note that sending the C<ev_async> watcher is required because otherwise
4431an event loop currently blocking in the kernel will have no knowledge
4432about the newly added timer. By waking up the loop it will pick up any new
4433watchers in the next event loop iteration.
4434 4999
4435=head3 COROUTINES 5000=head3 COROUTINES
4436 5001
4437Libev is very accommodating to coroutines ("cooperative threads"): 5002Libev is very accommodating to coroutines ("cooperative threads"):
4438libev fully supports nesting calls to its functions from different 5003libev fully supports nesting calls to its functions from different
4603requires, and its I/O model is fundamentally incompatible with the POSIX 5168requires, and its I/O model is fundamentally incompatible with the POSIX
4604model. Libev still offers limited functionality on this platform in 5169model. Libev still offers limited functionality on this platform in
4605the form of the C<EVBACKEND_SELECT> backend, and only supports socket 5170the form of the C<EVBACKEND_SELECT> backend, and only supports socket
4606descriptors. This only applies when using Win32 natively, not when using 5171descriptors. This only applies when using Win32 natively, not when using
4607e.g. cygwin. Actually, it only applies to the microsofts own compilers, 5172e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4608as every compielr comes with a slightly differently broken/incompatible 5173as every compiler comes with a slightly differently broken/incompatible
4609environment. 5174environment.
4610 5175
4611Lifting these limitations would basically require the full 5176Lifting these limitations would basically require the full
4612re-implementation of the I/O system. If you are into this kind of thing, 5177re-implementation of the I/O system. If you are into this kind of thing,
4613then note that glib does exactly that for you in a very portable way (note 5178then note that glib does exactly that for you in a very portable way (note
4707structure (guaranteed by POSIX but not by ISO C for example), but it also 5272structure (guaranteed by POSIX but not by ISO C for example), but it also
4708assumes that the same (machine) code can be used to call any watcher 5273assumes that the same (machine) code can be used to call any watcher
4709callback: The watcher callbacks have different type signatures, but libev 5274callback: The watcher callbacks have different type signatures, but libev
4710calls them using an C<ev_watcher *> internally. 5275calls them using an C<ev_watcher *> internally.
4711 5276
5277=item pointer accesses must be thread-atomic
5278
5279Accessing a pointer value must be atomic, it must both be readable and
5280writable in one piece - this is the case on all current architectures.
5281
4712=item C<sig_atomic_t volatile> must be thread-atomic as well 5282=item C<sig_atomic_t volatile> must be thread-atomic as well
4713 5283
4714The type C<sig_atomic_t volatile> (or whatever is defined as 5284The type C<sig_atomic_t volatile> (or whatever is defined as
4715C<EV_ATOMIC_T>) must be atomic with respect to accesses from different 5285C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
4716threads. This is not part of the specification for C<sig_atomic_t>, but is 5286threads. This is not part of the specification for C<sig_atomic_t>, but is
4741 5311
4742The type C<double> is used to represent timestamps. It is required to 5312The type C<double> is used to represent timestamps. It is required to
4743have at least 51 bits of mantissa (and 9 bits of exponent), which is 5313have at least 51 bits of mantissa (and 9 bits of exponent), which is
4744good enough for at least into the year 4000 with millisecond accuracy 5314good enough for at least into the year 4000 with millisecond accuracy
4745(the design goal for libev). This requirement is overfulfilled by 5315(the design goal for libev). This requirement is overfulfilled by
4746implementations using IEEE 754, which is basically all existing ones. With 5316implementations using IEEE 754, which is basically all existing ones.
5317
4747IEEE 754 doubles, you get microsecond accuracy until at least 2200. 5318With IEEE 754 doubles, you get microsecond accuracy until at least the
5319year 2255 (and millisecond accuracy till the year 287396 - by then, libev
5320is either obsolete or somebody patched it to use C<long double> or
5321something like that, just kidding).
4748 5322
4749=back 5323=back
4750 5324
4751If you know of other additional requirements drop me a note. 5325If you know of other additional requirements drop me a note.
4752 5326
4814=item Processing ev_async_send: O(number_of_async_watchers) 5388=item Processing ev_async_send: O(number_of_async_watchers)
4815 5389
4816=item Processing signals: O(max_signal_number) 5390=item Processing signals: O(max_signal_number)
4817 5391
4818Sending involves a system call I<iff> there were no other C<ev_async_send> 5392Sending involves a system call I<iff> there were no other C<ev_async_send>
4819calls in the current loop iteration. Checking for async and signal events 5393calls in the current loop iteration and the loop is currently
5394blocked. Checking for async and signal events involves iterating over all
4820involves iterating over all running async watchers or all signal numbers. 5395running async watchers or all signal numbers.
4821 5396
4822=back 5397=back
4823 5398
4824 5399
4825=head1 PORTING FROM LIBEV 3.X TO 4.X 5400=head1 PORTING FROM LIBEV 3.X TO 4.X
4826 5401
4827The major version 4 introduced some minor incompatible changes to the API. 5402The major version 4 introduced some incompatible changes to the API.
4828 5403
4829At the moment, the C<ev.h> header file tries to implement superficial 5404At the moment, the C<ev.h> header file provides compatibility definitions
4830compatibility, so most programs should still compile. Those might be 5405for all changes, so most programs should still compile. The compatibility
4831removed in later versions of libev, so better update early than late. 5406layer might be removed in later versions of libev, so better update to the
5407new API early than late.
4832 5408
4833=over 4 5409=over 4
5410
5411=item C<EV_COMPAT3> backwards compatibility mechanism
5412
5413The backward compatibility mechanism can be controlled by
5414C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
5415section.
5416
5417=item C<ev_default_destroy> and C<ev_default_fork> have been removed
5418
5419These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
5420
5421 ev_loop_destroy (EV_DEFAULT_UC);
5422 ev_loop_fork (EV_DEFAULT);
4834 5423
4835=item function/symbol renames 5424=item function/symbol renames
4836 5425
4837A number of functions and symbols have been renamed: 5426A number of functions and symbols have been renamed:
4838 5427
4857ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme 5446ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme
4858as all other watcher types. Note that C<ev_loop_fork> is still called 5447as all other watcher types. Note that C<ev_loop_fork> is still called
4859C<ev_loop_fork> because it would otherwise clash with the C<ev_fork> 5448C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
4860typedef. 5449typedef.
4861 5450
4862=item C<EV_COMPAT3> backwards compatibility mechanism
4863
4864The backward compatibility mechanism can be controlled by
4865C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
4866section.
4867
4868=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES> 5451=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4869 5452
4870The preprocessor symbol C<EV_MINIMAL> has been replaced by a different 5453The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4871mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile 5454mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4872and work, but the library code will of course be larger. 5455and work, but the library code will of course be larger.
4934The physical time that is observed. It is apparently strictly monotonic :) 5517The physical time that is observed. It is apparently strictly monotonic :)
4935 5518
4936=item wall-clock time 5519=item wall-clock time
4937 5520
4938The time and date as shown on clocks. Unlike real time, it can actually 5521The time and date as shown on clocks. Unlike real time, it can actually
4939be wrong and jump forwards and backwards, e.g. when the you adjust your 5522be wrong and jump forwards and backwards, e.g. when you adjust your
4940clock. 5523clock.
4941 5524
4942=item watcher 5525=item watcher
4943 5526
4944A data structure that describes interest in certain events. Watchers need 5527A data structure that describes interest in certain events. Watchers need
4946 5529
4947=back 5530=back
4948 5531
4949=head1 AUTHOR 5532=head1 AUTHOR
4950 5533
4951Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 5534Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
5535Magnusson and Emanuele Giaquinta, and minor corrections by many others.
4952 5536

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines