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

Comparing libev/ev.pod (file contents):
Revision 1.178 by root, Sat Sep 13 18:25:50 2008 UTC vs.
Revision 1.189 by root, Tue Sep 30 19:33:33 2008 UTC

… …
214C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 214C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
215recommended ones. 215recommended ones.
216 216
217See the description of C<ev_embed> watchers for more info. 217See the description of C<ev_embed> watchers for more info.
218 218
219=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 219=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
220 220
221Sets the allocation function to use (the prototype is similar - the 221Sets the allocation function to use (the prototype is similar - the
222semantics are identical to the C<realloc> C89/SuS/POSIX function). It is 222semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
223used to allocate and free memory (no surprises here). If it returns zero 223used to allocate and free memory (no surprises here). If it returns zero
224when memory needs to be allocated (C<size != 0>), the library might abort 224when memory needs to be allocated (C<size != 0>), the library might abort
… …
250 } 250 }
251 251
252 ... 252 ...
253 ev_set_allocator (persistent_realloc); 253 ev_set_allocator (persistent_realloc);
254 254
255=item ev_set_syserr_cb (void (*cb)(const char *msg)); 255=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
256 256
257Set the callback function to call on a retryable system call error (such 257Set the callback function to call on a retryable system call error (such
258as failed select, poll, epoll_wait). The message is a printable string 258as failed select, poll, epoll_wait). The message is a printable string
259indicating the system call or subsystem causing the problem. If this 259indicating the system call or subsystem causing the problem. If this
260callback is set, then libev will expect it to remedy the situation, no 260callback is set, then libev will expect it to remedy the situation, no
… …
359writing a server, you should C<accept ()> in a loop to accept as many 359writing a server, you should C<accept ()> in a loop to accept as many
360connections as possible during one iteration. You might also want to have 360connections as possible during one iteration. You might also want to have
361a look at C<ev_set_io_collect_interval ()> to increase the amount of 361a look at C<ev_set_io_collect_interval ()> to increase the amount of
362readiness notifications you get per iteration. 362readiness notifications you get per iteration.
363 363
364This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the
365C<writefds> set (and to work around Microsoft Windows bugs, also onto the
366C<exceptfds> set on that platform).
367
364=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) 368=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
365 369
366And this is your standard poll(2) backend. It's more complicated 370And this is your standard poll(2) backend. It's more complicated
367than select, but handles sparse fds better and has no artificial 371than select, but handles sparse fds better and has no artificial
368limit on the number of fds you can use (except it will slow down 372limit on the number of fds you can use (except it will slow down
369considerably with a lot of inactive fds). It scales similarly to select, 373considerably with a lot of inactive fds). It scales similarly to select,
370i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for 374i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
371performance tips. 375performance tips.
376
377This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
378C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
372 379
373=item C<EVBACKEND_EPOLL> (value 4, Linux) 380=item C<EVBACKEND_EPOLL> (value 4, Linux)
374 381
375For few fds, this backend is a bit little slower than poll and select, 382For few fds, this backend is a bit little slower than poll and select,
376but it scales phenomenally better. While poll and select usually scale 383but it scales phenomenally better. While poll and select usually scale
… …
389Please note that epoll sometimes generates spurious notifications, so you 396Please note that epoll sometimes generates spurious notifications, so you
390need to use non-blocking I/O or other means to avoid blocking when no data 397need to use non-blocking I/O or other means to avoid blocking when no data
391(or space) is available. 398(or space) is available.
392 399
393Best performance from this backend is achieved by not unregistering all 400Best performance from this backend is achieved by not unregistering all
394watchers for a file descriptor until it has been closed, if possible, i.e. 401watchers for a file descriptor until it has been closed, if possible,
395keep at least one watcher active per fd at all times. 402i.e. keep at least one watcher active per fd at all times. Stopping and
403starting a watcher (without re-setting it) also usually doesn't cause
404extra overhead.
396 405
397While nominally embeddable in other event loops, this feature is broken in 406While nominally embeddable in other event loops, this feature is broken in
398all kernel versions tested so far. 407all kernel versions tested so far.
399 408
409This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
410C<EVBACKEND_POLL>.
411
400=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 412=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
401 413
402Kqueue deserves special mention, as at the time of this writing, it 414Kqueue deserves special mention, as at the time of this writing, it was
403was broken on all BSDs except NetBSD (usually it doesn't work reliably 415broken on all BSDs except NetBSD (usually it doesn't work reliably with
404with anything but sockets and pipes, except on Darwin, where of course 416anything but sockets and pipes, except on Darwin, where of course it's
405it's completely useless). For this reason it's not being "auto-detected" 417completely useless). For this reason it's not being "auto-detected" unless
406unless you explicitly specify it explicitly in the flags (i.e. using 418you explicitly specify it in the flags (i.e. using C<EVBACKEND_KQUEUE>) or
407C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 419libev was compiled on a known-to-be-good (-enough) system like NetBSD.
408system like NetBSD.
409 420
410You still can embed kqueue into a normal poll or select backend and use it 421You still can embed kqueue into a normal poll or select backend and use it
411only for sockets (after having made sure that sockets work with kqueue on 422only for sockets (after having made sure that sockets work with kqueue on
412the target platform). See C<ev_embed> watchers for more info. 423the target platform). See C<ev_embed> watchers for more info.
413 424
414It scales in the same way as the epoll backend, but the interface to the 425It scales in the same way as the epoll backend, but the interface to the
415kernel is more efficient (which says nothing about its actual speed, of 426kernel is more efficient (which says nothing about its actual speed, of
416course). While stopping, setting and starting an I/O watcher does never 427course). While stopping, setting and starting an I/O watcher does never
417cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 428cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
418two event changes per incident, support for C<fork ()> is very bad and it 429two event changes per incident. Support for C<fork ()> is very bad and it
419drops fds silently in similarly hard-to-detect cases. 430drops fds silently in similarly hard-to-detect cases.
420 431
421This backend usually performs well under most conditions. 432This backend usually performs well under most conditions.
422 433
423While nominally embeddable in other event loops, this doesn't work 434While nominally embeddable in other event loops, this doesn't work
424everywhere, so you might need to test for this. And since it is broken 435everywhere, so you might need to test for this. And since it is broken
425almost everywhere, you should only use it when you have a lot of sockets 436almost everywhere, you should only use it when you have a lot of sockets
426(for which it usually works), by embedding it into another event loop 437(for which it usually works), by embedding it into another event loop
427(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for 438(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it,
428sockets. 439using it only for sockets.
440
441This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
442C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
443C<NOTE_EOF>.
429 444
430=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 445=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
431 446
432This is not implemented yet (and might never be, unless you send me an 447This is not implemented yet (and might never be, unless you send me an
433implementation). According to reports, C</dev/poll> only supports sockets 448implementation). According to reports, C</dev/poll> only supports sockets
… …
446While this backend scales well, it requires one system call per active 461While this backend scales well, it requires one system call per active
447file descriptor per loop iteration. For small and medium numbers of file 462file descriptor per loop iteration. For small and medium numbers of file
448descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 463descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
449might perform better. 464might perform better.
450 465
451On the positive side, ignoring the spurious readiness notifications, this 466On the positive side, with the exception of the spurious readiness
452backend actually performed to specification in all tests and is fully 467notifications, this backend actually performed fully to specification
453embeddable, which is a rare feat among the OS-specific backends. 468in all tests and is fully embeddable, which is a rare feat among the
469OS-specific backends.
470
471This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
472C<EVBACKEND_POLL>.
454 473
455=item C<EVBACKEND_ALL> 474=item C<EVBACKEND_ALL>
456 475
457Try all backends (even potentially broken ones that wouldn't be tried 476Try all backends (even potentially broken ones that wouldn't be tried
458with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 477with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
… …
464 483
465If one or more of these are or'ed into the flags value, then only these 484If one or more of these are or'ed into the flags value, then only these
466backends will be tried (in the reverse order as listed here). If none are 485backends will be tried (in the reverse order as listed here). If none are
467specified, all backends in C<ev_recommended_backends ()> will be tried. 486specified, all backends in C<ev_recommended_backends ()> will be tried.
468 487
469The most typical usage is like this: 488Example: This is the most typical usage.
470 489
471 if (!ev_default_loop (0)) 490 if (!ev_default_loop (0))
472 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 491 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
473 492
474Restrict libev to the select and poll backends, and do not allow 493Example: Restrict libev to the select and poll backends, and do not allow
475environment settings to be taken into account: 494environment settings to be taken into account:
476 495
477 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); 496 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
478 497
479Use whatever libev has to offer, but make sure that kqueue is used if 498Example: Use whatever libev has to offer, but make sure that kqueue is
480available (warning, breaks stuff, best use only with your own private 499used if available (warning, breaks stuff, best use only with your own
481event loop and only if you know the OS supports your types of fds): 500private event loop and only if you know the OS supports your types of
501fds):
482 502
483 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 503 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
484 504
485=item struct ev_loop *ev_loop_new (unsigned int flags) 505=item struct ev_loop *ev_loop_new (unsigned int flags)
486 506
… …
544 564
545=item ev_loop_fork (loop) 565=item ev_loop_fork (loop)
546 566
547Like C<ev_default_fork>, but acts on an event loop created by 567Like C<ev_default_fork>, but acts on an event loop created by
548C<ev_loop_new>. Yes, you have to call this on every allocated event loop 568C<ev_loop_new>. Yes, you have to call this on every allocated event loop
549after fork, and how you do this is entirely your own problem. 569after fork that you want to re-use in the child, and how you do this is
570entirely your own problem.
550 571
551=item int ev_is_default_loop (loop) 572=item int ev_is_default_loop (loop)
552 573
553Returns true when the given loop actually is the default loop, false otherwise. 574Returns true when the given loop is, in fact, the default loop, and false
575otherwise.
554 576
555=item unsigned int ev_loop_count (loop) 577=item unsigned int ev_loop_count (loop)
556 578
557Returns the count of loop iterations for the loop, which is identical to 579Returns the count of loop iterations for the loop, which is identical to
558the number of times libev did poll for new events. It starts at C<0> and 580the number of times libev did poll for new events. It starts at C<0> and
… …
596If the flags argument is specified as C<0>, it will not return until 618If the flags argument is specified as C<0>, it will not return until
597either no event watchers are active anymore or C<ev_unloop> was called. 619either no event watchers are active anymore or C<ev_unloop> was called.
598 620
599Please note that an explicit C<ev_unloop> is usually better than 621Please note that an explicit C<ev_unloop> is usually better than
600relying on all watchers to be stopped when deciding when a program has 622relying on all watchers to be stopped when deciding when a program has
601finished (especially in interactive programs), but having a program that 623finished (especially in interactive programs), but having a program
602automatically loops as long as it has to and no longer by virtue of 624that automatically loops as long as it has to and no longer by virtue
603relying on its watchers stopping correctly is a thing of beauty. 625of relying on its watchers stopping correctly, that is truly a thing of
626beauty.
604 627
605A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 628A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
606those events and any outstanding ones, but will not block your process in 629those events and any already outstanding ones, but will not block your
607case there are no events and will return after one iteration of the loop. 630process in case there are no events and will return after one iteration of
631the loop.
608 632
609A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 633A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
610necessary) and will handle those and any outstanding ones. It will block 634necessary) and will handle those and any already outstanding ones. It
611your process until at least one new event arrives, and will return after 635will block your process until at least one new event arrives (which could
612one iteration of the loop. This is useful if you are waiting for some 636be an event internal to libev itself, so there is no guarentee that a
613external event in conjunction with something not expressible using other 637user-registered callback will be called), and will return after one
638iteration of the loop.
639
640This is useful if you are waiting for some external event in conjunction
641with something not expressible using other libev watchers (i.e. "roll your
614libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is 642own C<ev_loop>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
615usually a better approach for this kind of thing. 643usually a better approach for this kind of thing.
616 644
617Here are the gory details of what C<ev_loop> does: 645Here are the gory details of what C<ev_loop> does:
618 646
619 - Before the first iteration, call any pending watchers. 647 - Before the first iteration, call any pending watchers.
… …
629 any active watchers at all will result in not sleeping). 657 any active watchers at all will result in not sleeping).
630 - Sleep if the I/O and timer collect interval say so. 658 - Sleep if the I/O and timer collect interval say so.
631 - Block the process, waiting for any events. 659 - Block the process, waiting for any events.
632 - Queue all outstanding I/O (fd) events. 660 - Queue all outstanding I/O (fd) events.
633 - Update the "event loop time" (ev_now ()), and do time jump adjustments. 661 - Update the "event loop time" (ev_now ()), and do time jump adjustments.
634 - Queue all outstanding timers. 662 - Queue all expired timers.
635 - Queue all outstanding periodics. 663 - Queue all expired periodics.
636 - Unless any events are pending now, queue all idle watchers. 664 - Unless any events are pending now, queue all idle watchers.
637 - Queue all check watchers. 665 - Queue all check watchers.
638 - Call all queued watchers in reverse order (i.e. check watchers first). 666 - Call all queued watchers in reverse order (i.e. check watchers first).
639 Signals and child watchers are implemented as I/O watchers, and will 667 Signals and child watchers are implemented as I/O watchers, and will
640 be handled here by queueing them when their watcher gets executed. 668 be handled here by queueing them when their watcher gets executed.
… …
663 691
664=item ev_unref (loop) 692=item ev_unref (loop)
665 693
666Ref/unref can be used to add or remove a reference count on the event 694Ref/unref can be used to add or remove a reference count on the event
667loop: Every watcher keeps one reference, and as long as the reference 695loop: Every watcher keeps one reference, and as long as the reference
668count is nonzero, C<ev_loop> will not return on its own. If you have 696count is nonzero, C<ev_loop> will not return on its own.
697
669a watcher you never unregister that should not keep C<ev_loop> from 698If you have a watcher you never unregister that should not keep C<ev_loop>
670returning, ev_unref() after starting, and ev_ref() before stopping it. For 699from returning, call ev_unref() after starting, and ev_ref() before
700stopping it.
701
671example, libev itself uses this for its internal signal pipe: It is not 702As an example, libev itself uses this for its internal signal pipe: It is
672visible to the libev user and should not keep C<ev_loop> from exiting if 703not visible to the libev user and should not keep C<ev_loop> from exiting
673no event watchers registered by it are active. It is also an excellent 704if no event watchers registered by it are active. It is also an excellent
674way to do this for generic recurring timers or from within third-party 705way to do this for generic recurring timers or from within third-party
675libraries. Just remember to I<unref after start> and I<ref before stop> 706libraries. Just remember to I<unref after start> and I<ref before stop>
676(but only if the watcher wasn't active before, or was active before, 707(but only if the watcher wasn't active before, or was active before,
677respectively). 708respectively).
678 709
… …
701Setting these to a higher value (the C<interval> I<must> be >= C<0>) 732Setting these to a higher value (the C<interval> I<must> be >= C<0>)
702allows libev to delay invocation of I/O and timer/periodic callbacks 733allows libev to delay invocation of I/O and timer/periodic callbacks
703to increase efficiency of loop iterations (or to increase power-saving 734to increase efficiency of loop iterations (or to increase power-saving
704opportunities). 735opportunities).
705 736
706The background is that sometimes your program runs just fast enough to 737The idea is that sometimes your program runs just fast enough to handle
707handle one (or very few) event(s) per loop iteration. While this makes 738one (or very few) event(s) per loop iteration. While this makes the
708the program responsive, it also wastes a lot of CPU time to poll for new 739program responsive, it also wastes a lot of CPU time to poll for new
709events, especially with backends like C<select ()> which have a high 740events, especially with backends like C<select ()> which have a high
710overhead for the actual polling but can deliver many events at once. 741overhead for the actual polling but can deliver many events at once.
711 742
712By setting a higher I<io collect interval> you allow libev to spend more 743By setting a higher I<io collect interval> you allow libev to spend more
713time collecting I/O events, so you can handle more events per iteration, 744time collecting I/O events, so you can handle more events per iteration,
… …
715C<ev_timer>) will be not affected. Setting this to a non-null value will 746C<ev_timer>) will be not affected. Setting this to a non-null value will
716introduce an additional C<ev_sleep ()> call into most loop iterations. 747introduce an additional C<ev_sleep ()> call into most loop iterations.
717 748
718Likewise, by setting a higher I<timeout collect interval> you allow libev 749Likewise, by setting a higher I<timeout collect interval> you allow libev
719to spend more time collecting timeouts, at the expense of increased 750to spend more time collecting timeouts, at the expense of increased
720latency (the watcher callback will be called later). C<ev_io> watchers 751latency/jitter/inexactness (the watcher callback will be called
721will not be affected. Setting this to a non-null value will not introduce 752later). C<ev_io> watchers will not be affected. Setting this to a non-null
722any overhead in libev. 753value will not introduce any overhead in libev.
723 754
724Many (busy) programs can usually benefit by setting the I/O collect 755Many (busy) programs can usually benefit by setting the I/O collect
725interval to a value near C<0.1> or so, which is often enough for 756interval to a value near C<0.1> or so, which is often enough for
726interactive servers (of course not for games), likewise for timeouts. It 757interactive servers (of course not for games), likewise for timeouts. It
727usually doesn't make much sense to set it to a lower value than C<0.01>, 758usually doesn't make much sense to set it to a lower value than C<0.01>,
… …
735they fire on, say, one-second boundaries only. 766they fire on, say, one-second boundaries only.
736 767
737=item ev_loop_verify (loop) 768=item ev_loop_verify (loop)
738 769
739This function only does something when C<EV_VERIFY> support has been 770This function only does something when C<EV_VERIFY> support has been
740compiled in. It tries to go through all internal structures and checks 771compiled in. which is the default for non-minimal builds. It tries to go
741them for validity. If anything is found to be inconsistent, it will print 772through all internal structures and checks them for validity. If anything
742an error message to standard error and call C<abort ()>. 773is found to be inconsistent, it will print an error message to standard
774error and call C<abort ()>.
743 775
744This can be used to catch bugs inside libev itself: under normal 776This can be used to catch bugs inside libev itself: under normal
745circumstances, this function will never abort as of course libev keeps its 777circumstances, this function will never abort as of course libev keeps its
746data structures consistent. 778data structures consistent.
747 779
… …
863happen because the watcher could not be properly started because libev 895happen because the watcher could not be properly started because libev
864ran out of memory, a file descriptor was found to be closed or any other 896ran out of memory, a file descriptor was found to be closed or any other
865problem. You best act on it by reporting the problem and somehow coping 897problem. You best act on it by reporting the problem and somehow coping
866with the watcher being stopped. 898with the watcher being stopped.
867 899
868Libev will usually signal a few "dummy" events together with an error, 900Libev will usually signal a few "dummy" events together with an error, for
869for example it might indicate that a fd is readable or writable, and if 901example it might indicate that a fd is readable or writable, and if your
870your callbacks is well-written it can just attempt the operation and cope 902callbacks is well-written it can just attempt the operation and cope with
871with the error from read() or write(). This will not work in multi-threaded 903the error from read() or write(). This will not work in multi-threaded
872programs, though, so beware. 904programs, though, as the fd could already be closed and reused for another
905thing, so beware.
873 906
874=back 907=back
875 908
876=head2 GENERIC WATCHER FUNCTIONS 909=head2 GENERIC WATCHER FUNCTIONS
877 910
… …
893(or never started) and there are no pending events outstanding. 926(or never started) and there are no pending events outstanding.
894 927
895The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher, 928The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher,
896int revents)>. 929int revents)>.
897 930
931Example: Initialise an C<ev_io> watcher in two steps.
932
933 ev_io w;
934 ev_init (&w, my_cb);
935 ev_io_set (&w, STDIN_FILENO, EV_READ);
936
898=item C<ev_TYPE_set> (ev_TYPE *, [args]) 937=item C<ev_TYPE_set> (ev_TYPE *, [args])
899 938
900This macro initialises the type-specific parts of a watcher. You need to 939This macro initialises the type-specific parts of a watcher. You need to
901call C<ev_init> at least once before you call this macro, but you can 940call C<ev_init> at least once before you call this macro, but you can
902call C<ev_TYPE_set> any number of times. You must not, however, call this 941call C<ev_TYPE_set> any number of times. You must not, however, call this
… …
904difference to the C<ev_init> macro). 943difference to the C<ev_init> macro).
905 944
906Although some watcher types do not have type-specific arguments 945Although some watcher types do not have type-specific arguments
907(e.g. C<ev_prepare>) you still need to call its C<set> macro. 946(e.g. C<ev_prepare>) you still need to call its C<set> macro.
908 947
948See C<ev_init>, above, for an example.
949
909=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args]) 950=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
910 951
911This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro 952This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
912calls into a single call. This is the most convenient method to initialise 953calls into a single call. This is the most convenient method to initialise
913a watcher. The same limitations apply, of course. 954a watcher. The same limitations apply, of course.
914 955
956Example: Initialise and set an C<ev_io> watcher in one step.
957
958 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
959
915=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 960=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
916 961
917Starts (activates) the given watcher. Only active watchers will receive 962Starts (activates) the given watcher. Only active watchers will receive
918events. If the watcher is already active nothing will happen. 963events. If the watcher is already active nothing will happen.
964
965Example: Start the C<ev_io> watcher that is being abused as example in this
966whole section.
967
968 ev_io_start (EV_DEFAULT_UC, &w);
919 969
920=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 970=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
921 971
922Stops the given watcher again (if active) and clears the pending 972Stops the given watcher again (if active) and clears the pending
923status. It is possible that stopped watchers are pending (for example, 973status. It is possible that stopped watchers are pending (for example,
… …
980 1030
981=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1031=item ev_invoke (loop, ev_TYPE *watcher, int revents)
982 1032
983Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1033Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
984C<loop> nor C<revents> need to be valid as long as the watcher callback 1034C<loop> nor C<revents> need to be valid as long as the watcher callback
985can deal with that fact. 1035can deal with that fact, as both are simply passed through to the
1036callback.
986 1037
987=item int ev_clear_pending (loop, ev_TYPE *watcher) 1038=item int ev_clear_pending (loop, ev_TYPE *watcher)
988 1039
989If the watcher is pending, this function returns clears its pending status 1040If the watcher is pending, this function clears its pending status and
990and returns its C<revents> bitset (as if its callback was invoked). If the 1041returns its C<revents> bitset (as if its callback was invoked). If the
991watcher isn't pending it does nothing and returns C<0>. 1042watcher isn't pending it does nothing and returns C<0>.
992 1043
1044Sometimes it can be useful to "poll" a watcher instead of waiting for its
1045callback to be invoked, which can be accomplished with this function.
1046
993=back 1047=back
994 1048
995 1049
996=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1050=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
997 1051
998Each watcher has, by default, a member C<void *data> that you can change 1052Each watcher has, by default, a member C<void *data> that you can change
999and read at any time, libev will completely ignore it. This can be used 1053and read at any time: libev will completely ignore it. This can be used
1000to associate arbitrary data with your watcher. If you need more data and 1054to associate arbitrary data with your watcher. If you need more data and
1001don't want to allocate memory and store a pointer to it in that data 1055don't want to allocate memory and store a pointer to it in that data
1002member, you can also "subclass" the watcher type and provide your own 1056member, you can also "subclass" the watcher type and provide your own
1003data: 1057data:
1004 1058
… …
1036 ev_timer t2; 1090 ev_timer t2;
1037 } 1091 }
1038 1092
1039In this case getting the pointer to C<my_biggy> is a bit more 1093In this case getting the pointer to C<my_biggy> is a bit more
1040complicated: Either you store the address of your C<my_biggy> struct 1094complicated: Either you store the address of your C<my_biggy> struct
1041in the C<data> member of the watcher, or you need to use some pointer 1095in the C<data> member of the watcher (for woozies), or you need to use
1042arithmetic using C<offsetof> inside your watchers: 1096some pointer arithmetic using C<offsetof> inside your watchers (for real
1097programmers):
1043 1098
1044 #include <stddef.h> 1099 #include <stddef.h>
1045 1100
1046 static void 1101 static void
1047 t1_cb (EV_P_ struct ev_timer *w, int revents) 1102 t1_cb (EV_P_ struct ev_timer *w, int revents)
… …
1087In general you can register as many read and/or write event watchers per 1142In general you can register as many read and/or write event watchers per
1088fd as you want (as long as you don't confuse yourself). Setting all file 1143fd as you want (as long as you don't confuse yourself). Setting all file
1089descriptors to non-blocking mode is also usually a good idea (but not 1144descriptors to non-blocking mode is also usually a good idea (but not
1090required if you know what you are doing). 1145required if you know what you are doing).
1091 1146
1092If you must do this, then force the use of a known-to-be-good backend 1147If you cannot use non-blocking mode, then force the use of a
1093(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 1148known-to-be-good backend (at the time of this writing, this includes only
1094C<EVBACKEND_POLL>). 1149C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>).
1095 1150
1096Another thing you have to watch out for is that it is quite easy to 1151Another thing you have to watch out for is that it is quite easy to
1097receive "spurious" readiness notifications, that is your callback might 1152receive "spurious" readiness notifications, that is your callback might
1098be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1153be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1099because there is no data. Not only are some backends known to create a 1154because there is no data. Not only are some backends known to create a
1100lot of those (for example Solaris ports), it is very easy to get into 1155lot of those (for example Solaris ports), it is very easy to get into
1101this situation even with a relatively standard program structure. Thus 1156this situation even with a relatively standard program structure. Thus
1102it is best to always use non-blocking I/O: An extra C<read>(2) returning 1157it is best to always use non-blocking I/O: An extra C<read>(2) returning
1103C<EAGAIN> is far preferable to a program hanging until some data arrives. 1158C<EAGAIN> is far preferable to a program hanging until some data arrives.
1104 1159
1105If you cannot run the fd in non-blocking mode (for example you should not 1160If you cannot run the fd in non-blocking mode (for example you should
1106play around with an Xlib connection), then you have to separately re-test 1161not play around with an Xlib connection), then you have to separately
1107whether a file descriptor is really ready with a known-to-be good interface 1162re-test whether a file descriptor is really ready with a known-to-be good
1108such as poll (fortunately in our Xlib example, Xlib already does this on 1163interface such as poll (fortunately in our Xlib example, Xlib already
1109its own, so its quite safe to use). 1164does this on its own, so its quite safe to use). Some people additionally
1165use C<SIGALRM> and an interval timer, just to be sure you won't block
1166indefinitely.
1167
1168But really, best use non-blocking mode.
1110 1169
1111=head3 The special problem of disappearing file descriptors 1170=head3 The special problem of disappearing file descriptors
1112 1171
1113Some backends (e.g. kqueue, epoll) need to be told about closing a file 1172Some backends (e.g. kqueue, epoll) need to be told about closing a file
1114descriptor (either by calling C<close> explicitly or by any other means, 1173descriptor (either due to calling C<close> explicitly or any other means,
1115such as C<dup>). The reason is that you register interest in some file 1174such as C<dup2>). The reason is that you register interest in some file
1116descriptor, but when it goes away, the operating system will silently drop 1175descriptor, but when it goes away, the operating system will silently drop
1117this interest. If another file descriptor with the same number then is 1176this interest. If another file descriptor with the same number then is
1118registered with libev, there is no efficient way to see that this is, in 1177registered with libev, there is no efficient way to see that this is, in
1119fact, a different file descriptor. 1178fact, a different file descriptor.
1120 1179
… …
1151enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or 1210enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1152C<EVBACKEND_POLL>. 1211C<EVBACKEND_POLL>.
1153 1212
1154=head3 The special problem of SIGPIPE 1213=head3 The special problem of SIGPIPE
1155 1214
1156While not really specific to libev, it is easy to forget about SIGPIPE: 1215While not really specific to libev, it is easy to forget about C<SIGPIPE>:
1157when writing to a pipe whose other end has been closed, your program gets 1216when writing to a pipe whose other end has been closed, your program gets
1158send a SIGPIPE, which, by default, aborts your program. For most programs 1217sent a SIGPIPE, which, by default, aborts your program. For most programs
1159this is sensible behaviour, for daemons, this is usually undesirable. 1218this is sensible behaviour, for daemons, this is usually undesirable.
1160 1219
1161So when you encounter spurious, unexplained daemon exits, make sure you 1220So when you encounter spurious, unexplained daemon exits, make sure you
1162ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1221ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1163somewhere, as that would have given you a big clue). 1222somewhere, as that would have given you a big clue).
… …
1170=item ev_io_init (ev_io *, callback, int fd, int events) 1229=item ev_io_init (ev_io *, callback, int fd, int events)
1171 1230
1172=item ev_io_set (ev_io *, int fd, int events) 1231=item ev_io_set (ev_io *, int fd, int events)
1173 1232
1174Configures an C<ev_io> watcher. The C<fd> is the file descriptor to 1233Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1175receive events for and events is either C<EV_READ>, C<EV_WRITE> or 1234receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or
1176C<EV_READ | EV_WRITE> to receive the given events. 1235C<EV_READ | EV_WRITE>, to express the desire to receive the given events.
1177 1236
1178=item int fd [read-only] 1237=item int fd [read-only]
1179 1238
1180The file descriptor being watched. 1239The file descriptor being watched.
1181 1240
… …
1193 1252
1194 static void 1253 static void
1195 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1254 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1196 { 1255 {
1197 ev_io_stop (loop, w); 1256 ev_io_stop (loop, w);
1198 .. read from stdin here (or from w->fd) and haqndle any I/O errors 1257 .. read from stdin here (or from w->fd) and handle any I/O errors
1199 } 1258 }
1200 1259
1201 ... 1260 ...
1202 struct ev_loop *loop = ev_default_init (0); 1261 struct ev_loop *loop = ev_default_init (0);
1203 struct ev_io stdin_readable; 1262 struct ev_io stdin_readable;
… …
1211Timer watchers are simple relative timers that generate an event after a 1270Timer watchers are simple relative timers that generate an event after a
1212given time, and optionally repeating in regular intervals after that. 1271given time, and optionally repeating in regular intervals after that.
1213 1272
1214The timers are based on real time, that is, if you register an event that 1273The timers are based on real time, that is, if you register an event that
1215times out after an hour and you reset your system clock to January last 1274times out after an hour and you reset your system clock to January last
1216year, it will still time out after (roughly) and hour. "Roughly" because 1275year, it will still time out after (roughly) one hour. "Roughly" because
1217detecting time jumps is hard, and some inaccuracies are unavoidable (the 1276detecting time jumps is hard, and some inaccuracies are unavoidable (the
1218monotonic clock option helps a lot here). 1277monotonic clock option helps a lot here).
1219 1278
1220The callback is guaranteed to be invoked only after its timeout has passed, 1279The callback is guaranteed to be invoked only I<after> its timeout has
1221but if multiple timers become ready during the same loop iteration then 1280passed, but if multiple timers become ready during the same loop iteration
1222order of execution is undefined. 1281then order of execution is undefined.
1223 1282
1224=head3 The special problem of time updates 1283=head3 The special problem of time updates
1225 1284
1226Establishing the current time is a costly operation (it usually takes at 1285Establishing the current time is a costly operation (it usually takes at
1227least two system calls): EV therefore updates its idea of the current 1286least two system calls): EV therefore updates its idea of the current
1228time only before and after C<ev_loop> polls for new events, which causes 1287time only before and after C<ev_loop> collects new events, which causes a
1229a growing difference between C<ev_now ()> and C<ev_time ()> when handling 1288growing difference between C<ev_now ()> and C<ev_time ()> when handling
1230lots of events. 1289lots of events in one iteration.
1231 1290
1232The relative timeouts are calculated relative to the C<ev_now ()> 1291The relative timeouts are calculated relative to the C<ev_now ()>
1233time. This is usually the right thing as this timestamp refers to the time 1292time. This is usually the right thing as this timestamp refers to the time
1234of the event triggering whatever timeout you are modifying/starting. If 1293of the event triggering whatever timeout you are modifying/starting. If
1235you suspect event processing to be delayed and you I<need> to base the 1294you suspect event processing to be delayed and you I<need> to base the
… …
1296 ev_timer_again (loop, timer); 1355 ev_timer_again (loop, timer);
1297 1356
1298This is more slightly efficient then stopping/starting the timer each time 1357This is more slightly efficient then stopping/starting the timer each time
1299you want to modify its timeout value. 1358you want to modify its timeout value.
1300 1359
1360Note, however, that it is often even more efficient to remember the
1361time of the last activity and let the timer time-out naturally. In the
1362callback, you then check whether the time-out is real, or, if there was
1363some activity, you reschedule the watcher to time-out in "last_activity +
1364timeout - ev_now ()" seconds.
1365
1301=item ev_tstamp repeat [read-write] 1366=item ev_tstamp repeat [read-write]
1302 1367
1303The current C<repeat> value. Will be used each time the watcher times out 1368The current C<repeat> value. Will be used each time the watcher times out
1304or C<ev_timer_again> is called and determines the next timeout (if any), 1369or C<ev_timer_again> is called, and determines the next timeout (if any),
1305which is also when any modifications are taken into account. 1370which is also when any modifications are taken into account.
1306 1371
1307=back 1372=back
1308 1373
1309=head3 Examples 1374=head3 Examples
… …
1353to trigger the event (unlike an C<ev_timer>, which would still trigger 1418to trigger the event (unlike an C<ev_timer>, which would still trigger
1354roughly 10 seconds later as it uses a relative timeout). 1419roughly 10 seconds later as it uses a relative timeout).
1355 1420
1356C<ev_periodic>s can also be used to implement vastly more complex timers, 1421C<ev_periodic>s can also be used to implement vastly more complex timers,
1357such as triggering an event on each "midnight, local time", or other 1422such as triggering an event on each "midnight, local time", or other
1358complicated, rules. 1423complicated rules.
1359 1424
1360As with timers, the callback is guaranteed to be invoked only when the 1425As with timers, the callback is guaranteed to be invoked only when the
1361time (C<at>) has passed, but if multiple periodic timers become ready 1426time (C<at>) has passed, but if multiple periodic timers become ready
1362during the same loop iteration then order of execution is undefined. 1427during the same loop iteration, then order of execution is undefined.
1363 1428
1364=head3 Watcher-Specific Functions and Data Members 1429=head3 Watcher-Specific Functions and Data Members
1365 1430
1366=over 4 1431=over 4
1367 1432
1368=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1433=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1369 1434
1370=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1435=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
1371 1436
1372Lots of arguments, lets sort it out... There are basically three modes of 1437Lots of arguments, lets sort it out... There are basically three modes of
1373operation, and we will explain them from simplest to complex: 1438operation, and we will explain them from simplest to most complex:
1374 1439
1375=over 4 1440=over 4
1376 1441
1377=item * absolute timer (at = time, interval = reschedule_cb = 0) 1442=item * absolute timer (at = time, interval = reschedule_cb = 0)
1378 1443
1379In this configuration the watcher triggers an event after the wall clock 1444In this configuration the watcher triggers an event after the wall clock
1380time C<at> has passed and doesn't repeat. It will not adjust when a time 1445time C<at> has passed. It will not repeat and will not adjust when a time
1381jump occurs, that is, if it is to be run at January 1st 2011 then it will 1446jump occurs, that is, if it is to be run at January 1st 2011 then it will
1382run when the system time reaches or surpasses this time. 1447only run when the system clock reaches or surpasses this time.
1383 1448
1384=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1449=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1385 1450
1386In this mode the watcher will always be scheduled to time out at the next 1451In this mode the watcher will always be scheduled to time out at the next
1387C<at + N * interval> time (for some integer N, which can also be negative) 1452C<at + N * interval> time (for some integer N, which can also be negative)
1388and then repeat, regardless of any time jumps. 1453and then repeat, regardless of any time jumps.
1389 1454
1390This can be used to create timers that do not drift with respect to system 1455This can be used to create timers that do not drift with respect to the
1391time, for example, here is a C<ev_periodic> that triggers each hour, on 1456system clock, for example, here is a C<ev_periodic> that triggers each
1392the hour: 1457hour, on the hour:
1393 1458
1394 ev_periodic_set (&periodic, 0., 3600., 0); 1459 ev_periodic_set (&periodic, 0., 3600., 0);
1395 1460
1396This doesn't mean there will always be 3600 seconds in between triggers, 1461This doesn't mean there will always be 3600 seconds in between triggers,
1397but only that the callback will be called when the system time shows a 1462but only that the callback will be called when the system time shows a
… …
1484=back 1549=back
1485 1550
1486=head3 Examples 1551=head3 Examples
1487 1552
1488Example: Call a callback every hour, or, more precisely, whenever the 1553Example: Call a callback every hour, or, more precisely, whenever the
1489system clock is divisible by 3600. The callback invocation times have 1554system time is divisible by 3600. The callback invocation times have
1490potentially a lot of jitter, but good long-term stability. 1555potentially a lot of jitter, but good long-term stability.
1491 1556
1492 static void 1557 static void
1493 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1558 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1494 { 1559 {
… …
1504 #include <math.h> 1569 #include <math.h>
1505 1570
1506 static ev_tstamp 1571 static ev_tstamp
1507 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 1572 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
1508 { 1573 {
1509 return fmod (now, 3600.) + 3600.; 1574 return now + (3600. - fmod (now, 3600.));
1510 } 1575 }
1511 1576
1512 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); 1577 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1513 1578
1514Example: Call a callback every hour, starting now: 1579Example: Call a callback every hour, starting now:
… …
1524Signal watchers will trigger an event when the process receives a specific 1589Signal watchers will trigger an event when the process receives a specific
1525signal one or more times. Even though signals are very asynchronous, libev 1590signal one or more times. Even though signals are very asynchronous, libev
1526will try it's best to deliver signals synchronously, i.e. as part of the 1591will try it's best to deliver signals synchronously, i.e. as part of the
1527normal event processing, like any other event. 1592normal event processing, like any other event.
1528 1593
1594If you want signals asynchronously, just use C<sigaction> as you would
1595do without libev and forget about sharing the signal. You can even use
1596C<ev_async> from a signal handler to synchronously wake up an event loop.
1597
1529You can configure as many watchers as you like per signal. Only when the 1598You can configure as many watchers as you like per signal. Only when the
1530first watcher gets started will libev actually register a signal watcher 1599first watcher gets started will libev actually register a signal handler
1531with the kernel (thus it coexists with your own signal handlers as long 1600with the kernel (thus it coexists with your own signal handlers as long as
1532as you don't register any with libev). Similarly, when the last signal 1601you don't register any with libev for the same signal). Similarly, when
1533watcher for a signal is stopped libev will reset the signal handler to 1602the last signal watcher for a signal is stopped, libev will reset the
1534SIG_DFL (regardless of what it was set to before). 1603signal handler to SIG_DFL (regardless of what it was set to before).
1535 1604
1536If possible and supported, libev will install its handlers with 1605If possible and supported, libev will install its handlers with
1537C<SA_RESTART> behaviour enabled, so system calls should not be unduly 1606C<SA_RESTART> behaviour enabled, so system calls should not be unduly
1538interrupted. If you have a problem with system calls getting interrupted by 1607interrupted. If you have a problem with system calls getting interrupted by
1539signals you can block all signals in an C<ev_check> watcher and unblock 1608signals you can block all signals in an C<ev_check> watcher and unblock
… …
1556 1625
1557=back 1626=back
1558 1627
1559=head3 Examples 1628=head3 Examples
1560 1629
1561Example: Try to exit cleanly on SIGINT and SIGTERM. 1630Example: Try to exit cleanly on SIGINT.
1562 1631
1563 static void 1632 static void
1564 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1633 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1565 { 1634 {
1566 ev_unloop (loop, EVUNLOOP_ALL); 1635 ev_unloop (loop, EVUNLOOP_ALL);
1567 } 1636 }
1568 1637
1569 struct ev_signal signal_watcher; 1638 struct ev_signal signal_watcher;
1570 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1639 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1571 ev_signal_start (loop, &sigint_cb); 1640 ev_signal_start (loop, &signal_watcher);
1572 1641
1573 1642
1574=head2 C<ev_child> - watch out for process status changes 1643=head2 C<ev_child> - watch out for process status changes
1575 1644
1576Child watchers trigger when your process receives a SIGCHLD in response to 1645Child watchers trigger when your process receives a SIGCHLD in response to
1577some child status changes (most typically when a child of yours dies). It 1646some child status changes (most typically when a child of yours dies or
1578is permissible to install a child watcher I<after> the child has been 1647exits). It is permissible to install a child watcher I<after> the child
1579forked (which implies it might have already exited), as long as the event 1648has been forked (which implies it might have already exited), as long
1580loop isn't entered (or is continued from a watcher). 1649as the event loop isn't entered (or is continued from a watcher), i.e.,
1650forking and then immediately registering a watcher for the child is fine,
1651but forking and registering a watcher a few event loop iterations later is
1652not.
1581 1653
1582Only the default event loop is capable of handling signals, and therefore 1654Only the default event loop is capable of handling signals, and therefore
1583you can only register child watchers in the default event loop. 1655you can only register child watchers in the default event loop.
1584 1656
1585=head3 Process Interaction 1657=head3 Process Interaction
… …
1683the stat buffer having unspecified contents. 1755the stat buffer having unspecified contents.
1684 1756
1685The path I<should> be absolute and I<must not> end in a slash. If it is 1757The path I<should> be absolute and I<must not> end in a slash. If it is
1686relative and your working directory changes, the behaviour is undefined. 1758relative and your working directory changes, the behaviour is undefined.
1687 1759
1688Since there is no standard to do this, the portable implementation simply 1760Since there is no standard kernel interface to do this, the portable
1689calls C<stat (2)> regularly on the path to see if it changed somehow. You 1761implementation simply calls C<stat (2)> regularly on the path to see if
1690can specify a recommended polling interval for this case. If you specify 1762it changed somehow. You can specify a recommended polling interval for
1691a polling interval of C<0> (highly recommended!) then a I<suitable, 1763this case. If you specify a polling interval of C<0> (highly recommended!)
1692unspecified default> value will be used (which you can expect to be around 1764then a I<suitable, unspecified default> value will be used (which
1693five seconds, although this might change dynamically). Libev will also 1765you can expect to be around five seconds, although this might change
1694impose a minimum interval which is currently around C<0.1>, but thats 1766dynamically). Libev will also impose a minimum interval which is currently
1695usually overkill. 1767around C<0.1>, but thats usually overkill.
1696 1768
1697This watcher type is not meant for massive numbers of stat watchers, 1769This watcher type is not meant for massive numbers of stat watchers,
1698as even with OS-supported change notifications, this can be 1770as even with OS-supported change notifications, this can be
1699resource-intensive. 1771resource-intensive.
1700 1772
1701At the time of this writing, only the Linux inotify interface is 1773At the time of this writing, the only OS-specific interface implemented
1702implemented (implementing kqueue support is left as an exercise for the 1774is the Linux inotify interface (implementing kqueue support is left as
1703reader, note, however, that the author sees no way of implementing ev_stat 1775an exercise for the reader. Note, however, that the author sees no way
1704semantics with kqueue). Inotify will be used to give hints only and should 1776of implementing C<ev_stat> semantics with kqueue).
1705not change the semantics of C<ev_stat> watchers, which means that libev
1706sometimes needs to fall back to regular polling again even with inotify,
1707but changes are usually detected immediately, and if the file exists there
1708will be no polling.
1709 1777
1710=head3 ABI Issues (Largefile Support) 1778=head3 ABI Issues (Largefile Support)
1711 1779
1712Libev by default (unless the user overrides this) uses the default 1780Libev by default (unless the user overrides this) uses the default
1713compilation environment, which means that on systems with large file 1781compilation environment, which means that on systems with large file
… …
1722file interfaces available by default (as e.g. FreeBSD does) and not 1790file interfaces available by default (as e.g. FreeBSD does) and not
1723optional. Libev cannot simply switch on large file support because it has 1791optional. Libev cannot simply switch on large file support because it has
1724to exchange stat structures with application programs compiled using the 1792to exchange stat structures with application programs compiled using the
1725default compilation environment. 1793default compilation environment.
1726 1794
1727=head3 Inotify 1795=head3 Inotify and Kqueue
1728 1796
1729When C<inotify (7)> support has been compiled into libev (generally only 1797When C<inotify (7)> support has been compiled into libev (generally only
1730available on Linux) and present at runtime, it will be used to speed up 1798available with Linux) and present at runtime, it will be used to speed up
1731change detection where possible. The inotify descriptor will be created lazily 1799change detection where possible. The inotify descriptor will be created lazily
1732when the first C<ev_stat> watcher is being started. 1800when the first C<ev_stat> watcher is being started.
1733 1801
1734Inotify presence does not change the semantics of C<ev_stat> watchers 1802Inotify presence does not change the semantics of C<ev_stat> watchers
1735except that changes might be detected earlier, and in some cases, to avoid 1803except that changes might be detected earlier, and in some cases, to avoid
1736making regular C<stat> calls. Even in the presence of inotify support 1804making regular C<stat> calls. Even in the presence of inotify support
1737there are many cases where libev has to resort to regular C<stat> polling. 1805there are many cases where libev has to resort to regular C<stat> polling,
1806but as long as the path exists, libev usually gets away without polling.
1738 1807
1739(There is no support for kqueue, as apparently it cannot be used to 1808There is no support for kqueue, as apparently it cannot be used to
1740implement this functionality, due to the requirement of having a file 1809implement this functionality, due to the requirement of having a file
1741descriptor open on the object at all times). 1810descriptor open on the object at all times, and detecting renames, unlinks
1811etc. is difficult.
1742 1812
1743=head3 The special problem of stat time resolution 1813=head3 The special problem of stat time resolution
1744 1814
1745The C<stat ()> system call only supports full-second resolution portably, and 1815The C<stat ()> system call only supports full-second resolution portably, and
1746even on systems where the resolution is higher, many file systems still 1816even on systems where the resolution is higher, most file systems still
1747only support whole seconds. 1817only support whole seconds.
1748 1818
1749That means that, if the time is the only thing that changes, you can 1819That means that, if the time is the only thing that changes, you can
1750easily miss updates: on the first update, C<ev_stat> detects a change and 1820easily miss updates: on the first update, C<ev_stat> detects a change and
1751calls your callback, which does something. When there is another update 1821calls your callback, which does something. When there is another update
1752within the same second, C<ev_stat> will be unable to detect it as the stat 1822within the same second, C<ev_stat> will be unable to detect unless the
1753data does not change. 1823stat data does change in other ways (e.g. file size).
1754 1824
1755The solution to this is to delay acting on a change for slightly more 1825The solution to this is to delay acting on a change for slightly more
1756than a second (or till slightly after the next full second boundary), using 1826than a second (or till slightly after the next full second boundary), using
1757a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02); 1827a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
1758ev_timer_again (loop, w)>). 1828ev_timer_again (loop, w)>).
… …
1778C<path>. The C<interval> is a hint on how quickly a change is expected to 1848C<path>. The C<interval> is a hint on how quickly a change is expected to
1779be detected and should normally be specified as C<0> to let libev choose 1849be detected and should normally be specified as C<0> to let libev choose
1780a suitable value. The memory pointed to by C<path> must point to the same 1850a suitable value. The memory pointed to by C<path> must point to the same
1781path for as long as the watcher is active. 1851path for as long as the watcher is active.
1782 1852
1783The callback will receive C<EV_STAT> when a change was detected, relative 1853The callback will receive an C<EV_STAT> event when a change was detected,
1784to the attributes at the time the watcher was started (or the last change 1854relative to the attributes at the time the watcher was started (or the
1785was detected). 1855last change was detected).
1786 1856
1787=item ev_stat_stat (loop, ev_stat *) 1857=item ev_stat_stat (loop, ev_stat *)
1788 1858
1789Updates the stat buffer immediately with new values. If you change the 1859Updates the stat buffer immediately with new values. If you change the
1790watched path in your callback, you could call this function to avoid 1860watched path in your callback, you could call this function to avoid
… …
1873 1943
1874 1944
1875=head2 C<ev_idle> - when you've got nothing better to do... 1945=head2 C<ev_idle> - when you've got nothing better to do...
1876 1946
1877Idle watchers trigger events when no other events of the same or higher 1947Idle watchers trigger events when no other events of the same or higher
1878priority are pending (prepare, check and other idle watchers do not 1948priority are pending (prepare, check and other idle watchers do not count
1879count). 1949as receiving "events").
1880 1950
1881That is, as long as your process is busy handling sockets or timeouts 1951That is, as long as your process is busy handling sockets or timeouts
1882(or even signals, imagine) of the same or higher priority it will not be 1952(or even signals, imagine) of the same or higher priority it will not be
1883triggered. But when your process is idle (or only lower-priority watchers 1953triggered. But when your process is idle (or only lower-priority watchers
1884are pending), the idle watchers are being called once per event loop 1954are pending), the idle watchers are being called once per event loop
… …
1923 ev_idle_start (loop, idle_cb); 1993 ev_idle_start (loop, idle_cb);
1924 1994
1925 1995
1926=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 1996=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
1927 1997
1928Prepare and check watchers are usually (but not always) used in tandem: 1998Prepare and check watchers are usually (but not always) used in pairs:
1929prepare watchers get invoked before the process blocks and check watchers 1999prepare watchers get invoked before the process blocks and check watchers
1930afterwards. 2000afterwards.
1931 2001
1932You I<must not> call C<ev_loop> or similar functions that enter 2002You I<must not> call C<ev_loop> or similar functions that enter
1933the current event loop from either C<ev_prepare> or C<ev_check> 2003the current event loop from either C<ev_prepare> or C<ev_check>
… …
1936those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 2006those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
1937C<ev_check> so if you have one watcher of each kind they will always be 2007C<ev_check> so if you have one watcher of each kind they will always be
1938called in pairs bracketing the blocking call. 2008called in pairs bracketing the blocking call.
1939 2009
1940Their main purpose is to integrate other event mechanisms into libev and 2010Their main purpose is to integrate other event mechanisms into libev and
1941their use is somewhat advanced. This could be used, for example, to track 2011their use is somewhat advanced. They could be used, for example, to track
1942variable changes, implement your own watchers, integrate net-snmp or a 2012variable changes, implement your own watchers, integrate net-snmp or a
1943coroutine library and lots more. They are also occasionally useful if 2013coroutine library and lots more. They are also occasionally useful if
1944you cache some data and want to flush it before blocking (for example, 2014you cache some data and want to flush it before blocking (for example,
1945in X programs you might want to do an C<XFlush ()> in an C<ev_prepare> 2015in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
1946watcher). 2016watcher).
1947 2017
1948This is done by examining in each prepare call which file descriptors need 2018This is done by examining in each prepare call which file descriptors
1949to be watched by the other library, registering C<ev_io> watchers for 2019need to be watched by the other library, registering C<ev_io> watchers
1950them and starting an C<ev_timer> watcher for any timeouts (many libraries 2020for them and starting an C<ev_timer> watcher for any timeouts (many
1951provide just this functionality). Then, in the check watcher you check for 2021libraries provide exactly this functionality). Then, in the check watcher,
1952any events that occurred (by checking the pending status of all watchers 2022you check for any events that occurred (by checking the pending status
1953and stopping them) and call back into the library. The I/O and timer 2023of all watchers and stopping them) and call back into the library. The
1954callbacks will never actually be called (but must be valid nevertheless, 2024I/O and timer callbacks will never actually be called (but must be valid
1955because you never know, you know?). 2025nevertheless, because you never know, you know?).
1956 2026
1957As another example, the Perl Coro module uses these hooks to integrate 2027As another example, the Perl Coro module uses these hooks to integrate
1958coroutines into libev programs, by yielding to other active coroutines 2028coroutines into libev programs, by yielding to other active coroutines
1959during each prepare and only letting the process block if no coroutines 2029during each prepare and only letting the process block if no coroutines
1960are ready to run (it's actually more complicated: it only runs coroutines 2030are ready to run (it's actually more complicated: it only runs coroutines
… …
1963loop from blocking if lower-priority coroutines are active, thus mapping 2033loop from blocking if lower-priority coroutines are active, thus mapping
1964low-priority coroutines to idle/background tasks). 2034low-priority coroutines to idle/background tasks).
1965 2035
1966It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 2036It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1967priority, to ensure that they are being run before any other watchers 2037priority, to ensure that they are being run before any other watchers
2038after the poll (this doesn't matter for C<ev_prepare> watchers).
2039
1968after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers, 2040Also, C<ev_check> watchers (and C<ev_prepare> watchers, too) should not
1969too) should not activate ("feed") events into libev. While libev fully 2041activate ("feed") events into libev. While libev fully supports this, they
1970supports this, they might get executed before other C<ev_check> watchers 2042might get executed before other C<ev_check> watchers did their job. As
1971did their job. As C<ev_check> watchers are often used to embed other 2043C<ev_check> watchers are often used to embed other (non-libev) event
1972(non-libev) event loops those other event loops might be in an unusable 2044loops those other event loops might be in an unusable state until their
1973state until their C<ev_check> watcher ran (always remind yourself to 2045C<ev_check> watcher ran (always remind yourself to coexist peacefully with
1974coexist peacefully with others). 2046others).
1975 2047
1976=head3 Watcher-Specific Functions and Data Members 2048=head3 Watcher-Specific Functions and Data Members
1977 2049
1978=over 4 2050=over 4
1979 2051
… …
1981 2053
1982=item ev_check_init (ev_check *, callback) 2054=item ev_check_init (ev_check *, callback)
1983 2055
1984Initialises and configures the prepare or check watcher - they have no 2056Initialises and configures the prepare or check watcher - they have no
1985parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 2057parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1986macros, but using them is utterly, utterly and completely pointless. 2058macros, but using them is utterly, utterly, utterly and completely
2059pointless.
1987 2060
1988=back 2061=back
1989 2062
1990=head3 Examples 2063=head3 Examples
1991 2064
… …
2084 } 2157 }
2085 2158
2086 // do not ever call adns_afterpoll 2159 // do not ever call adns_afterpoll
2087 2160
2088Method 4: Do not use a prepare or check watcher because the module you 2161Method 4: Do not use a prepare or check watcher because the module you
2089want to embed is too inflexible to support it. Instead, you can override 2162want to embed is not flexible enough to support it. Instead, you can
2090their poll function. The drawback with this solution is that the main 2163override their poll function. The drawback with this solution is that the
2091loop is now no longer controllable by EV. The C<Glib::EV> module does 2164main loop is now no longer controllable by EV. The C<Glib::EV> module uses
2092this. 2165this approach, effectively embedding EV as a client into the horrible
2166libglib event loop.
2093 2167
2094 static gint 2168 static gint
2095 event_poll_func (GPollFD *fds, guint nfds, gint timeout) 2169 event_poll_func (GPollFD *fds, guint nfds, gint timeout)
2096 { 2170 {
2097 int got_events = 0; 2171 int got_events = 0;
… …
2128prioritise I/O. 2202prioritise I/O.
2129 2203
2130As an example for a bug workaround, the kqueue backend might only support 2204As an example for a bug workaround, the kqueue backend might only support
2131sockets on some platform, so it is unusable as generic backend, but you 2205sockets on some platform, so it is unusable as generic backend, but you
2132still want to make use of it because you have many sockets and it scales 2206still want to make use of it because you have many sockets and it scales
2133so nicely. In this case, you would create a kqueue-based loop and embed it 2207so nicely. In this case, you would create a kqueue-based loop and embed
2134into your default loop (which might use e.g. poll). Overall operation will 2208it into your default loop (which might use e.g. poll). Overall operation
2135be a bit slower because first libev has to poll and then call kevent, but 2209will be a bit slower because first libev has to call C<poll> and then
2136at least you can use both at what they are best. 2210C<kevent>, but at least you can use both mechanisms for what they are
2211best: C<kqueue> for scalable sockets and C<poll> if you want it to work :)
2137 2212
2138As for prioritising I/O: rarely you have the case where some fds have 2213As for prioritising I/O: under rare circumstances you have the case where
2139to be watched and handled very quickly (with low latency), and even 2214some fds have to be watched and handled very quickly (with low latency),
2140priorities and idle watchers might have too much overhead. In this case 2215and even priorities and idle watchers might have too much overhead. In
2141you would put all the high priority stuff in one loop and all the rest in 2216this case you would put all the high priority stuff in one loop and all
2142a second one, and embed the second one in the first. 2217the rest in a second one, and embed the second one in the first.
2143 2218
2144As long as the watcher is active, the callback will be invoked every time 2219As long as the watcher is active, the callback will be invoked every time
2145there might be events pending in the embedded loop. The callback must then 2220there might be events pending in the embedded loop. The callback must then
2146call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2221call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke
2147their callbacks (you could also start an idle watcher to give the embedded 2222their callbacks (you could also start an idle watcher to give the embedded
… …
2155interested in that. 2230interested in that.
2156 2231
2157Also, there have not currently been made special provisions for forking: 2232Also, there have not currently been made special provisions for forking:
2158when you fork, you not only have to call C<ev_loop_fork> on both loops, 2233when you fork, you not only have to call C<ev_loop_fork> on both loops,
2159but you will also have to stop and restart any C<ev_embed> watchers 2234but you will also have to stop and restart any C<ev_embed> watchers
2160yourself. 2235yourself - but you can use a fork watcher to handle this automatically,
2236and future versions of libev might do just that.
2161 2237
2162Unfortunately, not all backends are embeddable, only the ones returned by 2238Unfortunately, not all backends are embeddable: only the ones returned by
2163C<ev_embeddable_backends> are, which, unfortunately, does not include any 2239C<ev_embeddable_backends> are, which, unfortunately, does not include any
2164portable one. 2240portable one.
2165 2241
2166So when you want to use this feature you will always have to be prepared 2242So when you want to use this feature you will always have to be prepared
2167that you cannot get an embeddable loop. The recommended way to get around 2243that you cannot get an embeddable loop. The recommended way to get around
2168this is to have a separate variables for your embeddable loop, try to 2244this is to have a separate variables for your embeddable loop, try to
2169create it, and if that fails, use the normal loop for everything. 2245create it, and if that fails, use the normal loop for everything.
2246
2247=head3 C<ev_embed> and fork
2248
2249While the C<ev_embed> watcher is running, forks in the embedding loop will
2250automatically be applied to the embedded loop as well, so no special
2251fork handling is required in that case. When the watcher is not running,
2252however, it is still the task of the libev user to call C<ev_loop_fork ()>
2253as applicable.
2170 2254
2171=head3 Watcher-Specific Functions and Data Members 2255=head3 Watcher-Specific Functions and Data Members
2172 2256
2173=over 4 2257=over 4
2174 2258
… …
2292is that the author does not know of a simple (or any) algorithm for a 2376is that the author does not know of a simple (or any) algorithm for a
2293multiple-writer-single-reader queue that works in all cases and doesn't 2377multiple-writer-single-reader queue that works in all cases and doesn't
2294need elaborate support such as pthreads. 2378need elaborate support such as pthreads.
2295 2379
2296That means that if you want to queue data, you have to provide your own 2380That means that if you want to queue data, you have to provide your own
2297queue. But at least I can tell you would implement locking around your 2381queue. But at least I can tell you how to implement locking around your
2298queue: 2382queue:
2299 2383
2300=over 4 2384=over 4
2301 2385
2302=item queueing from a signal handler context 2386=item queueing from a signal handler context
… …
2378 2462
2379=item ev_async_init (ev_async *, callback) 2463=item ev_async_init (ev_async *, callback)
2380 2464
2381Initialises and configures the async watcher - it has no parameters of any 2465Initialises and configures the async watcher - it has no parameters of any
2382kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, 2466kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
2383believe me. 2467trust me.
2384 2468
2385=item ev_async_send (loop, ev_async *) 2469=item ev_async_send (loop, ev_async *)
2386 2470
2387Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2471Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2388an C<EV_ASYNC> event on the watcher into the event loop. Unlike 2472an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2389C<ev_feed_event>, this call is safe to do in other threads, signal or 2473C<ev_feed_event>, this call is safe to do from other threads, signal or
2390similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 2474similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2391section below on what exactly this means). 2475section below on what exactly this means).
2392 2476
2393This call incurs the overhead of a system call only once per loop iteration, 2477This call incurs the overhead of a system call only once per loop iteration,
2394so while the overhead might be noticeable, it doesn't apply to repeated 2478so while the overhead might be noticeable, it doesn't apply to repeated
… …
2600 2684
2601The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>. 2685The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
2602 2686
2603See the method-C<set> above for more details. 2687See the method-C<set> above for more details.
2604 2688
2605Example: 2689Example: Use a plain function as callback.
2606 2690
2607 static void io_cb (ev::io &w, int revents) { } 2691 static void io_cb (ev::io &w, int revents) { }
2608 iow.set <io_cb> (); 2692 iow.set <io_cb> ();
2609 2693
2610=item w->set (struct ev_loop *) 2694=item w->set (struct ev_loop *)
… …
2648Example: Define a class with an IO and idle watcher, start one of them in 2732Example: Define a class with an IO and idle watcher, start one of them in
2649the constructor. 2733the constructor.
2650 2734
2651 class myclass 2735 class myclass
2652 { 2736 {
2653 ev::io io; void io_cb (ev::io &w, int revents); 2737 ev::io io ; void io_cb (ev::io &w, int revents);
2654 ev:idle idle void idle_cb (ev::idle &w, int revents); 2738 ev::idle idle; void idle_cb (ev::idle &w, int revents);
2655 2739
2656 myclass (int fd) 2740 myclass (int fd)
2657 { 2741 {
2658 io .set <myclass, &myclass::io_cb > (this); 2742 io .set <myclass, &myclass::io_cb > (this);
2659 idle.set <myclass, &myclass::idle_cb> (this); 2743 idle.set <myclass, &myclass::idle_cb> (this);
… …
2675=item Perl 2759=item Perl
2676 2760
2677The EV module implements the full libev API and is actually used to test 2761The EV module implements the full libev API and is actually used to test
2678libev. EV is developed together with libev. Apart from the EV core module, 2762libev. EV is developed together with libev. Apart from the EV core module,
2679there are additional modules that implement libev-compatible interfaces 2763there are additional modules that implement libev-compatible interfaces
2680to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the 2764to C<libadns> (C<EV::ADNS>, but C<AnyEvent::DNS> is preferred nowadays),
2681C<libglib> event core (C<Glib::EV> and C<EV::Glib>). 2765C<Net::SNMP> (C<Net::SNMP::EV>) and the C<libglib> event core (C<Glib::EV>
2766and C<EV::Glib>).
2682 2767
2683It can be found and installed via CPAN, its homepage is at 2768It can be found and installed via CPAN, its homepage is at
2684L<http://software.schmorp.de/pkg/EV>. 2769L<http://software.schmorp.de/pkg/EV>.
2685 2770
2686=item Python 2771=item Python
… …
2865 2950
2866=head2 PREPROCESSOR SYMBOLS/MACROS 2951=head2 PREPROCESSOR SYMBOLS/MACROS
2867 2952
2868Libev can be configured via a variety of preprocessor symbols you have to 2953Libev can be configured via a variety of preprocessor symbols you have to
2869define before including any of its files. The default in the absence of 2954define before including any of its files. The default in the absence of
2870autoconf is noted for every option. 2955autoconf is documented for every option.
2871 2956
2872=over 4 2957=over 4
2873 2958
2874=item EV_STANDALONE 2959=item EV_STANDALONE
2875 2960
… …
3045When doing priority-based operations, libev usually has to linearly search 3130When doing priority-based operations, libev usually has to linearly search
3046all the priorities, so having many of them (hundreds) uses a lot of space 3131all the priorities, so having many of them (hundreds) uses a lot of space
3047and time, so using the defaults of five priorities (-2 .. +2) is usually 3132and time, so using the defaults of five priorities (-2 .. +2) is usually
3048fine. 3133fine.
3049 3134
3050If your embedding application does not need any priorities, defining these both to 3135If your embedding application does not need any priorities, defining these
3051C<0> will save some memory and CPU. 3136both to C<0> will save some memory and CPU.
3052 3137
3053=item EV_PERIODIC_ENABLE 3138=item EV_PERIODIC_ENABLE
3054 3139
3055If undefined or defined to be C<1>, then periodic timers are supported. If 3140If undefined or defined to be C<1>, then periodic timers are supported. If
3056defined to be C<0>, then they are not. Disabling them saves a few kB of 3141defined to be C<0>, then they are not. Disabling them saves a few kB of
… …
3063code. 3148code.
3064 3149
3065=item EV_EMBED_ENABLE 3150=item EV_EMBED_ENABLE
3066 3151
3067If undefined or defined to be C<1>, then embed watchers are supported. If 3152If undefined or defined to be C<1>, then embed watchers are supported. If
3068defined to be C<0>, then they are not. 3153defined to be C<0>, then they are not. Embed watchers rely on most other
3154watcher types, which therefore must not be disabled.
3069 3155
3070=item EV_STAT_ENABLE 3156=item EV_STAT_ENABLE
3071 3157
3072If undefined or defined to be C<1>, then stat watchers are supported. If 3158If undefined or defined to be C<1>, then stat watchers are supported. If
3073defined to be C<0>, then they are not. 3159defined to be C<0>, then they are not.
… …
3105two). 3191two).
3106 3192
3107=item EV_USE_4HEAP 3193=item EV_USE_4HEAP
3108 3194
3109Heaps are not very cache-efficient. To improve the cache-efficiency of the 3195Heaps are not very cache-efficient. To improve the cache-efficiency of the
3110timer and periodics heap, libev uses a 4-heap when this symbol is defined 3196timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3111to C<1>. The 4-heap uses more complicated (longer) code but has 3197to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3112noticeably faster performance with many (thousands) of watchers. 3198faster performance with many (thousands) of watchers.
3113 3199
3114The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 3200The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3115(disabled). 3201(disabled).
3116 3202
3117=item EV_HEAP_CACHE_AT 3203=item EV_HEAP_CACHE_AT
3118 3204
3119Heaps are not very cache-efficient. To improve the cache-efficiency of the 3205Heaps are not very cache-efficient. To improve the cache-efficiency of the
3120timer and periodics heap, libev can cache the timestamp (I<at>) within 3206timer and periodics heaps, libev can cache the timestamp (I<at>) within
3121the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 3207the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3122which uses 8-12 bytes more per watcher and a few hundred bytes more code, 3208which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3123but avoids random read accesses on heap changes. This improves performance 3209but avoids random read accesses on heap changes. This improves performance
3124noticeably with with many (hundreds) of watchers. 3210noticeably with many (hundreds) of watchers.
3125 3211
3126The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 3212The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3127(disabled). 3213(disabled).
3128 3214
3129=item EV_VERIFY 3215=item EV_VERIFY
… …
3135called once per loop, which can slow down libev. If set to C<3>, then the 3221called once per loop, which can slow down libev. If set to C<3>, then the
3136verification code will be called very frequently, which will slow down 3222verification code will be called very frequently, which will slow down
3137libev considerably. 3223libev considerably.
3138 3224
3139The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 3225The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be
3140C<0.> 3226C<0>.
3141 3227
3142=item EV_COMMON 3228=item EV_COMMON
3143 3229
3144By default, all watchers have a C<void *data> member. By redefining 3230By default, all watchers have a C<void *data> member. By redefining
3145this macro to a something else you can include more and other types of 3231this macro to a something else you can include more and other types of
… …
3162and the way callbacks are invoked and set. Must expand to a struct member 3248and the way callbacks are invoked and set. Must expand to a struct member
3163definition and a statement, respectively. See the F<ev.h> header file for 3249definition and a statement, respectively. See the F<ev.h> header file for
3164their default definitions. One possible use for overriding these is to 3250their default definitions. One possible use for overriding these is to
3165avoid the C<struct ev_loop *> as first argument in all cases, or to use 3251avoid the C<struct ev_loop *> as first argument in all cases, or to use
3166method calls instead of plain function calls in C++. 3252method calls instead of plain function calls in C++.
3253
3254=back
3167 3255
3168=head2 EXPORTED API SYMBOLS 3256=head2 EXPORTED API SYMBOLS
3169 3257
3170If you need to re-export the API (e.g. via a DLL) and you need a list of 3258If you need to re-export the API (e.g. via a DLL) and you need a list of
3171exported symbols, you can use the provided F<Symbol.*> files which list 3259exported symbols, you can use the provided F<Symbol.*> files which list
… …
3218And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 3306And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3219 3307
3220 #include "ev_cpp.h" 3308 #include "ev_cpp.h"
3221 #include "ev.c" 3309 #include "ev.c"
3222 3310
3311=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
3223 3312
3224=head1 THREADS AND COROUTINES 3313=head2 THREADS AND COROUTINES
3225 3314
3226=head2 THREADS 3315=head3 THREADS
3227 3316
3228Libev itself is completely thread-safe, but it uses no locking. This 3317All libev functions are reentrant and thread-safe unless explicitly
3318documented otherwise, but it uses no locking itself. This means that you
3229means that you can use as many loops as you want in parallel, as long as 3319can use as many loops as you want in parallel, as long as there are no
3230only one thread ever calls into one libev function with the same loop 3320concurrent calls into any libev function with the same loop parameter
3231parameter. 3321(C<ev_default_*> calls have an implicit default loop parameter, of
3322course): libev guarantees that different event loops share no data
3323structures that need any locking.
3232 3324
3233Or put differently: calls with different loop parameters can be done in 3325Or to put it differently: calls with different loop parameters can be done
3234parallel from multiple threads, calls with the same loop parameter must be 3326concurrently from multiple threads, calls with the same loop parameter
3235done serially (but can be done from different threads, as long as only one 3327must be done serially (but can be done from different threads, as long as
3236thread ever is inside a call at any point in time, e.g. by using a mutex 3328only one thread ever is inside a call at any point in time, e.g. by using
3237per loop). 3329a mutex per loop).
3330
3331Specifically to support threads (and signal handlers), libev implements
3332so-called C<ev_async> watchers, which allow some limited form of
3333concurrency on the same event loop, namely waking it up "from the
3334outside".
3238 3335
3239If you want to know which design (one loop, locking, or multiple loops 3336If you want to know which design (one loop, locking, or multiple loops
3240without or something else still) is best for your problem, then I cannot 3337without or something else still) is best for your problem, then I cannot
3241help you. I can give some generic advice however: 3338help you, but here is some generic advice:
3242 3339
3243=over 4 3340=over 4
3244 3341
3245=item * most applications have a main thread: use the default libev loop 3342=item * most applications have a main thread: use the default libev loop
3246in that thread, or create a separate thread running only the default loop. 3343in that thread, or create a separate thread running only the default loop.
… …
3258 3355
3259Choosing a model is hard - look around, learn, know that usually you can do 3356Choosing a model is hard - look around, learn, know that usually you can do
3260better than you currently do :-) 3357better than you currently do :-)
3261 3358
3262=item * often you need to talk to some other thread which blocks in the 3359=item * often you need to talk to some other thread which blocks in the
3360event loop.
3361
3263event loop - C<ev_async> watchers can be used to wake them up from other 3362C<ev_async> watchers can be used to wake them up from other threads safely
3264threads safely (or from signal contexts...). 3363(or from signal contexts...).
3364
3365An example use would be to communicate signals or other events that only
3366work in the default loop by registering the signal watcher with the
3367default loop and triggering an C<ev_async> watcher from the default loop
3368watcher callback into the event loop interested in the signal.
3265 3369
3266=back 3370=back
3267 3371
3268=head2 COROUTINES 3372=head3 COROUTINES
3269 3373
3270Libev is much more accommodating to coroutines ("cooperative threads"): 3374Libev is much more accommodating to coroutines ("cooperative threads"):
3271libev fully supports nesting calls to it's functions from different 3375libev fully supports nesting calls to it's functions from different
3272coroutines (e.g. you can call C<ev_loop> on the same loop from two 3376coroutines (e.g. you can call C<ev_loop> on the same loop from two
3273different coroutines and switch freely between both coroutines running the 3377different coroutines and switch freely between both coroutines running the
3274loop, as long as you don't confuse yourself). The only exception is that 3378loop, as long as you don't confuse yourself). The only exception is that
3275you must not do this from C<ev_periodic> reschedule callbacks. 3379you must not do this from C<ev_periodic> reschedule callbacks.
3276 3380
3277Care has been invested into making sure that libev does not keep local 3381Care has been taken to ensure that libev does not keep local state inside
3278state inside C<ev_loop>, and other calls do not usually allow coroutine 3382C<ev_loop>, and other calls do not usually allow coroutine switches.
3279switches. 3383
3384=head2 COMPILER WARNINGS
3385
3386Depending on your compiler and compiler settings, you might get no or a
3387lot of warnings when compiling libev code. Some people are apparently
3388scared by this.
3389
3390However, these are unavoidable for many reasons. For one, each compiler
3391has different warnings, and each user has different tastes regarding
3392warning options. "Warn-free" code therefore cannot be a goal except when
3393targeting a specific compiler and compiler-version.
3394
3395Another reason is that some compiler warnings require elaborate
3396workarounds, or other changes to the code that make it less clear and less
3397maintainable.
3398
3399And of course, some compiler warnings are just plain stupid, or simply
3400wrong (because they don't actually warn about the condition their message
3401seems to warn about). For example, certain older gcc versions had some
3402warnings that resulted an extreme number of false positives. These have
3403been fixed, but some people still insist on making code warn-free with
3404such buggy versions.
3405
3406While libev is written to generate as few warnings as possible,
3407"warn-free" code is not a goal, and it is recommended not to build libev
3408with any compiler warnings enabled unless you are prepared to cope with
3409them (e.g. by ignoring them). Remember that warnings are just that:
3410warnings, not errors, or proof of bugs.
3411
3412
3413=head1 VALGRIND
3414
3415Valgrind has a special section here because it is a popular tool that is
3416highly useful. Unfortunately, valgrind reports are very hard to interpret.
3417
3418If you think you found a bug (memory leak, uninitialised data access etc.)
3419in libev, then check twice: If valgrind reports something like:
3420
3421 ==2274== definitely lost: 0 bytes in 0 blocks.
3422 ==2274== possibly lost: 0 bytes in 0 blocks.
3423 ==2274== still reachable: 256 bytes in 1 blocks.
3424
3425Then there is no memory leak, just as memory accounted to global variables
3426is not a memleak - the memory is still being refernced, and didn't leak.
3427
3428Similarly, under some circumstances, valgrind might report kernel bugs
3429as if it were a bug in libev (e.g. in realloc or in the poll backend,
3430although an acceptable workaround has been found here), or it might be
3431confused.
3432
3433Keep in mind that valgrind is a very good tool, but only a tool. Don't
3434make it into some kind of religion.
3435
3436If you are unsure about something, feel free to contact the mailing list
3437with the full valgrind report and an explanation on why you think this
3438is a bug in libev (best check the archives, too :). However, don't be
3439annoyed when you get a brisk "this is no bug" answer and take the chance
3440of learning how to interpret valgrind properly.
3441
3442If you need, for some reason, empty reports from valgrind for your project
3443I suggest using suppression lists.
3444
3280 3445
3281 3446
3282=head1 COMPLEXITIES 3447=head1 COMPLEXITIES
3283 3448
3284In this section the complexities of (many of) the algorithms used inside 3449In this section the complexities of (many of) the algorithms used inside
… …
3332=item Priority handling: O(number_of_priorities) 3497=item Priority handling: O(number_of_priorities)
3333 3498
3334Priorities are implemented by allocating some space for each 3499Priorities are implemented by allocating some space for each
3335priority. When doing priority-based operations, libev usually has to 3500priority. When doing priority-based operations, libev usually has to
3336linearly search all the priorities, but starting/stopping and activating 3501linearly search all the priorities, but starting/stopping and activating
3337watchers becomes O(1) w.r.t. priority handling. 3502watchers becomes O(1) with respect to priority handling.
3338 3503
3339=item Sending an ev_async: O(1) 3504=item Sending an ev_async: O(1)
3340 3505
3341=item Processing ev_async_send: O(number_of_async_watchers) 3506=item Processing ev_async_send: O(number_of_async_watchers)
3342 3507
… …
3347involves iterating over all running async watchers or all signal numbers. 3512involves iterating over all running async watchers or all signal numbers.
3348 3513
3349=back 3514=back
3350 3515
3351 3516
3517=head1 PORTABILITY
3518
3352=head1 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 3519=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
3353 3520
3354Win32 doesn't support any of the standards (e.g. POSIX) that libev 3521Win32 doesn't support any of the standards (e.g. POSIX) that libev
3355requires, and its I/O model is fundamentally incompatible with the POSIX 3522requires, and its I/O model is fundamentally incompatible with the POSIX
3356model. Libev still offers limited functionality on this platform in 3523model. Libev still offers limited functionality on this platform in
3357the form of the C<EVBACKEND_SELECT> backend, and only supports socket 3524the form of the C<EVBACKEND_SELECT> backend, and only supports socket
… …
3368 3535
3369Not a libev limitation but worth mentioning: windows apparently doesn't 3536Not a libev limitation but worth mentioning: windows apparently doesn't
3370accept large writes: instead of resulting in a partial write, windows will 3537accept large writes: instead of resulting in a partial write, windows will
3371either accept everything or return C<ENOBUFS> if the buffer is too large, 3538either accept everything or return C<ENOBUFS> if the buffer is too large,
3372so make sure you only write small amounts into your sockets (less than a 3539so make sure you only write small amounts into your sockets (less than a
3373megabyte seems safe, but thsi apparently depends on the amount of memory 3540megabyte seems safe, but this apparently depends on the amount of memory
3374available). 3541available).
3375 3542
3376Due to the many, low, and arbitrary limits on the win32 platform and 3543Due to the many, low, and arbitrary limits on the win32 platform and
3377the abysmal performance of winsockets, using a large number of sockets 3544the abysmal performance of winsockets, using a large number of sockets
3378is not recommended (and not reasonable). If your program needs to use 3545is not recommended (and not reasonable). If your program needs to use
… …
3389 #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ 3556 #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */
3390 3557
3391 #include "ev.h" 3558 #include "ev.h"
3392 3559
3393And compile the following F<evwrap.c> file into your project (make sure 3560And compile the following F<evwrap.c> file into your project (make sure
3394you do I<not> compile the F<ev.c> or any other embedded soruce files!): 3561you do I<not> compile the F<ev.c> or any other embedded source files!):
3395 3562
3396 #include "evwrap.h" 3563 #include "evwrap.h"
3397 #include "ev.c" 3564 #include "ev.c"
3398 3565
3399=over 4 3566=over 4
… …
3444wrap all I/O functions and provide your own fd management, but the cost of 3611wrap all I/O functions and provide your own fd management, but the cost of
3445calling select (O(n²)) will likely make this unworkable. 3612calling select (O(n²)) will likely make this unworkable.
3446 3613
3447=back 3614=back
3448 3615
3449
3450=head1 PORTABILITY REQUIREMENTS 3616=head2 PORTABILITY REQUIREMENTS
3451 3617
3452In addition to a working ISO-C implementation, libev relies on a few 3618In addition to a working ISO-C implementation and of course the
3453additional extensions: 3619backend-specific APIs, libev relies on a few additional extensions:
3454 3620
3455=over 4 3621=over 4
3456 3622
3457=item C<void (*)(ev_watcher_type *, int revents)> must have compatible 3623=item C<void (*)(ev_watcher_type *, int revents)> must have compatible
3458calling conventions regardless of C<ev_watcher_type *>. 3624calling conventions regardless of C<ev_watcher_type *>.
… …
3464calls them using an C<ev_watcher *> internally. 3630calls them using an C<ev_watcher *> internally.
3465 3631
3466=item C<sig_atomic_t volatile> must be thread-atomic as well 3632=item C<sig_atomic_t volatile> must be thread-atomic as well
3467 3633
3468The type C<sig_atomic_t volatile> (or whatever is defined as 3634The type C<sig_atomic_t volatile> (or whatever is defined as
3469C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different 3635C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
3470threads. This is not part of the specification for C<sig_atomic_t>, but is 3636threads. This is not part of the specification for C<sig_atomic_t>, but is
3471believed to be sufficiently portable. 3637believed to be sufficiently portable.
3472 3638
3473=item C<sigprocmask> must work in a threaded environment 3639=item C<sigprocmask> must work in a threaded environment
3474 3640
… …
3483except the initial one, and run the default loop in the initial thread as 3649except the initial one, and run the default loop in the initial thread as
3484well. 3650well.
3485 3651
3486=item C<long> must be large enough for common memory allocation sizes 3652=item C<long> must be large enough for common memory allocation sizes
3487 3653
3488To improve portability and simplify using libev, libev uses C<long> 3654To improve portability and simplify its API, libev uses C<long> internally
3489internally instead of C<size_t> when allocating its data structures. On 3655instead of C<size_t> when allocating its data structures. On non-POSIX
3490non-POSIX systems (Microsoft...) this might be unexpectedly low, but 3656systems (Microsoft...) this might be unexpectedly low, but is still at
3491is still at least 31 bits everywhere, which is enough for hundreds of 3657least 31 bits everywhere, which is enough for hundreds of millions of
3492millions of watchers. 3658watchers.
3493 3659
3494=item C<double> must hold a time value in seconds with enough accuracy 3660=item C<double> must hold a time value in seconds with enough accuracy
3495 3661
3496The type C<double> is used to represent timestamps. It is required to 3662The type C<double> is used to represent timestamps. It is required to
3497have at least 51 bits of mantissa (and 9 bits of exponent), which is good 3663have at least 51 bits of mantissa (and 9 bits of exponent), which is good
… …
3501=back 3667=back
3502 3668
3503If you know of other additional requirements drop me a note. 3669If you know of other additional requirements drop me a note.
3504 3670
3505 3671
3506=head1 COMPILER WARNINGS
3507
3508Depending on your compiler and compiler settings, you might get no or a
3509lot of warnings when compiling libev code. Some people are apparently
3510scared by this.
3511
3512However, these are unavoidable for many reasons. For one, each compiler
3513has different warnings, and each user has different tastes regarding
3514warning options. "Warn-free" code therefore cannot be a goal except when
3515targeting a specific compiler and compiler-version.
3516
3517Another reason is that some compiler warnings require elaborate
3518workarounds, or other changes to the code that make it less clear and less
3519maintainable.
3520
3521And of course, some compiler warnings are just plain stupid, or simply
3522wrong (because they don't actually warn about the condition their message
3523seems to warn about).
3524
3525While libev is written to generate as few warnings as possible,
3526"warn-free" code is not a goal, and it is recommended not to build libev
3527with any compiler warnings enabled unless you are prepared to cope with
3528them (e.g. by ignoring them). Remember that warnings are just that:
3529warnings, not errors, or proof of bugs.
3530
3531
3532=head1 VALGRIND
3533
3534Valgrind has a special section here because it is a popular tool that is
3535highly useful, but valgrind reports are very hard to interpret.
3536
3537If you think you found a bug (memory leak, uninitialised data access etc.)
3538in libev, then check twice: If valgrind reports something like:
3539
3540 ==2274== definitely lost: 0 bytes in 0 blocks.
3541 ==2274== possibly lost: 0 bytes in 0 blocks.
3542 ==2274== still reachable: 256 bytes in 1 blocks.
3543
3544Then there is no memory leak. Similarly, under some circumstances,
3545valgrind might report kernel bugs as if it were a bug in libev, or it
3546might be confused (it is a very good tool, but only a tool).
3547
3548If you are unsure about something, feel free to contact the mailing list
3549with the full valgrind report and an explanation on why you think this is
3550a bug in libev. However, don't be annoyed when you get a brisk "this is
3551no bug" answer and take the chance of learning how to interpret valgrind
3552properly.
3553
3554If you need, for some reason, empty reports from valgrind for your project
3555I suggest using suppression lists.
3556
3557
3558=head1 AUTHOR 3672=head1 AUTHOR
3559 3673
3560Marc Lehmann <libev@schmorp.de>. 3674Marc Lehmann <libev@schmorp.de>.
3561 3675

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines