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

Comparing libev/ev.pod (file contents):
Revision 1.260 by root, Sun Jul 19 21:18:03 2009 UTC vs.
Revision 1.309 by root, Thu Oct 21 09:23:21 2010 UTC

75While this document tries to be as complete as possible in documenting 75While this document tries to be as complete as possible in documenting
76libev, its usage and the rationale behind its design, it is not a tutorial 76libev, its usage and the rationale behind its design, it is not a tutorial
77on event-based programming, nor will it introduce event-based programming 77on event-based programming, nor will it introduce event-based programming
78with libev. 78with libev.
79 79
80Familarity with event based programming techniques in general is assumed 80Familiarity with event based programming techniques in general is assumed
81throughout this document. 81throughout this document.
82 82
83=head1 ABOUT LIBEV 83=head1 ABOUT LIBEV
84 84
85Libev is an event loop: you register interest in certain events (such as a 85Libev is an event loop: you register interest in certain events (such as a
98=head2 FEATURES 98=head2 FEATURES
99 99
100Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 100Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
101BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 101BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
102for file descriptor events (C<ev_io>), the Linux C<inotify> interface 102for file descriptor events (C<ev_io>), the Linux C<inotify> interface
103(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 103(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
104with customised rescheduling (C<ev_periodic>), synchronous signals 104inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
105(C<ev_signal>), process status change events (C<ev_child>), and event 105timers (C<ev_timer>), absolute timers with customised rescheduling
106watchers dealing with the event loop mechanism itself (C<ev_idle>, 106(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
107C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 107change events (C<ev_child>), and event watchers dealing with the event
108file watchers (C<ev_stat>) and even limited support for fork events 108loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
109(C<ev_fork>). 109C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
110limited support for fork events (C<ev_fork>).
110 111
111It also is quite fast (see this 112It also is quite fast (see this
112L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 113L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
113for example). 114for example).
114 115
117Libev is very configurable. In this manual the default (and most common) 118Libev is very configurable. In this manual the default (and most common)
118configuration will be described, which supports multiple event loops. For 119configuration will be described, which supports multiple event loops. For
119more info about various configuration options please have a look at 120more info about various configuration options please have a look at
120B<EMBED> section in this manual. If libev was configured without support 121B<EMBED> section in this manual. If libev was configured without support
121for multiple event loops, then all functions taking an initial argument of 122for multiple event loops, then all functions taking an initial argument of
122name C<loop> (which is always of type C<ev_loop *>) will not have 123name C<loop> (which is always of type C<struct ev_loop *>) will not have
123this argument. 124this argument.
124 125
125=head2 TIME REPRESENTATION 126=head2 TIME REPRESENTATION
126 127
127Libev represents time as a single floating point number, representing 128Libev represents time as a single floating point number, representing
128the (fractional) number of seconds since the (POSIX) epoch (somewhere 129the (fractional) number of seconds since the (POSIX) epoch (in practise
129near the beginning of 1970, details are complicated, don't ask). This 130somewhere near the beginning of 1970, details are complicated, don't
130type is called C<ev_tstamp>, which is what you should use too. It usually 131ask). This type is called C<ev_tstamp>, which is what you should use
131aliases to the C<double> type in C. When you need to do any calculations 132too. It usually aliases to the C<double> type in C. When you need to do
132on it, you should treat it as some floating point value. Unlike the name 133any calculations on it, you should treat it as some floating point value.
134
133component C<stamp> might indicate, it is also used for time differences 135Unlike the name component C<stamp> might indicate, it is also used for
134throughout libev. 136time differences (e.g. delays) throughout libev.
135 137
136=head1 ERROR HANDLING 138=head1 ERROR HANDLING
137 139
138Libev knows three classes of errors: operating system errors, usage errors 140Libev knows three classes of errors: operating system errors, usage errors
139and internal errors (bugs). 141and internal errors (bugs).
190as this indicates an incompatible change. Minor versions are usually 192as this indicates an incompatible change. Minor versions are usually
191compatible to older versions, so a larger minor version alone is usually 193compatible to older versions, so a larger minor version alone is usually
192not a problem. 194not a problem.
193 195
194Example: Make sure we haven't accidentally been linked against the wrong 196Example: Make sure we haven't accidentally been linked against the wrong
195version. 197version (note, however, that this will not detect ABI mismatches :).
196 198
197 assert (("libev version mismatch", 199 assert (("libev version mismatch",
198 ev_version_major () == EV_VERSION_MAJOR 200 ev_version_major () == EV_VERSION_MAJOR
199 && ev_version_minor () >= EV_VERSION_MINOR)); 201 && ev_version_minor () >= EV_VERSION_MINOR));
200 202
344useful to try out specific backends to test their performance, or to work 346useful to try out specific backends to test their performance, or to work
345around bugs. 347around bugs.
346 348
347=item C<EVFLAG_FORKCHECK> 349=item C<EVFLAG_FORKCHECK>
348 350
349Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after 351Instead of calling C<ev_loop_fork> manually after a fork, you can also
350a fork, you can also make libev check for a fork in each iteration by 352make libev check for a fork in each iteration by enabling this flag.
351enabling this flag.
352 353
353This works by calling C<getpid ()> on every iteration of the loop, 354This works by calling C<getpid ()> on every iteration of the loop,
354and thus this might slow down your event loop if you do a lot of loop 355and thus this might slow down your event loop if you do a lot of loop
355iterations and little real work, but is usually not noticeable (on my 356iterations and little real work, but is usually not noticeable (on my
356GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 357GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
369When this flag is specified, then libev will not attempt to use the 370When this flag is specified, then libev will not attempt to use the
370I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and 371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
371testing, this flag can be useful to conserve inotify file descriptors, as 372testing, this flag can be useful to conserve inotify file descriptors, as
372otherwise each loop using C<ev_stat> watchers consumes one inotify handle. 373otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
373 374
374=item C<EVFLAG_NOSIGNALFD> 375=item C<EVFLAG_SIGNALFD>
375 376
376When this flag is specified, then libev will not attempt to use the 377When this flag is specified, then libev will attempt to use the
377I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is 378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
378probably only useful to work around any bugs in libev. Consequently, this 379delivers signals synchronously, which makes it both faster and might make
379flag might go away once the signalfd functionality is considered stable, 380it possible to get the queued signal data. It can also simplify signal
380so it's useful mostly in environment variables and not in program code. 381handling with threads, as long as you properly block signals in your
382threads that are not interested in handling them.
383
384Signalfd will not be used by default as this changes your signal mask, and
385there are a lot of shoddy libraries and programs (glib's threadpool for
386example) that can't properly initialise their signal masks.
381 387
382=item C<EVBACKEND_SELECT> (value 1, portable select backend) 388=item C<EVBACKEND_SELECT> (value 1, portable select backend)
383 389
384This is your standard select(2) backend. Not I<completely> standard, as 390This is your standard select(2) backend. Not I<completely> standard, as
385libev tries to roll its own fd_set with no limits on the number of fds, 391libev tries to roll its own fd_set with no limits on the number of fds,
409 415
410This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 416This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
411C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 417C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
412 418
413=item C<EVBACKEND_EPOLL> (value 4, Linux) 419=item C<EVBACKEND_EPOLL> (value 4, Linux)
420
421Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
422kernels).
414 423
415For few fds, this backend is a bit little slower than poll and select, 424For few fds, this backend is a bit little slower than poll and select,
416but it scales phenomenally better. While poll and select usually scale 425but it scales phenomenally better. While poll and select usually scale
417like O(total_fds) where n is the total number of fds (or the highest fd), 426like O(total_fds) where n is the total number of fds (or the highest fd),
418epoll scales either O(1) or O(active_fds). 427epoll scales either O(1) or O(active_fds).
430of course I<doesn't>, and epoll just loves to report events for totally 439of course I<doesn't>, and epoll just loves to report events for totally
431I<different> file descriptors (even already closed ones, so one cannot 440I<different> file descriptors (even already closed ones, so one cannot
432even remove them from the set) than registered in the set (especially 441even remove them from the set) than registered in the set (especially
433on SMP systems). Libev tries to counter these spurious notifications by 442on SMP systems). Libev tries to counter these spurious notifications by
434employing an additional generation counter and comparing that against the 443employing an additional generation counter and comparing that against the
435events to filter out spurious ones, recreating the set when required. 444events to filter out spurious ones, recreating the set when required. Last
445not least, it also refuses to work with some file descriptors which work
446perfectly fine with C<select> (files, many character devices...).
436 447
437While stopping, setting and starting an I/O watcher in the same iteration 448While stopping, setting and starting an I/O watcher in the same iteration
438will result in some caching, there is still a system call per such 449will result in some caching, there is still a system call per such
439incident (because the same I<file descriptor> could point to a different 450incident (because the same I<file descriptor> could point to a different
440I<file description> now), so its best to avoid that. Also, C<dup ()>'ed 451I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
558 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 569 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
559 570
560=item struct ev_loop *ev_loop_new (unsigned int flags) 571=item struct ev_loop *ev_loop_new (unsigned int flags)
561 572
562Similar to C<ev_default_loop>, but always creates a new event loop that is 573Similar to C<ev_default_loop>, but always creates a new event loop that is
563always distinct from the default loop. Unlike the default loop, it cannot 574always distinct from the default loop.
564handle signal and child watchers, and attempts to do so will be greeted by
565undefined behaviour (or a failed assertion if assertions are enabled).
566 575
567Note that this function I<is> thread-safe, and the recommended way to use 576Note that this function I<is> thread-safe, and one common way to use
568libev with threads is indeed to create one loop per thread, and using the 577libev with threads is indeed to create one loop per thread, and using the
569default loop in the "main" or "initial" thread. 578default loop in the "main" or "initial" thread.
570 579
571Example: Try to create a event loop that uses epoll and nothing else. 580Example: Try to create a event loop that uses epoll and nothing else.
572 581
574 if (!epoller) 583 if (!epoller)
575 fatal ("no epoll found here, maybe it hides under your chair"); 584 fatal ("no epoll found here, maybe it hides under your chair");
576 585
577=item ev_default_destroy () 586=item ev_default_destroy ()
578 587
579Destroys the default loop again (frees all memory and kernel state 588Destroys the default loop (frees all memory and kernel state etc.). None
580etc.). None of the active event watchers will be stopped in the normal 589of the active event watchers will be stopped in the normal sense, so
581sense, so e.g. C<ev_is_active> might still return true. It is your 590e.g. C<ev_is_active> might still return true. It is your responsibility to
582responsibility to either stop all watchers cleanly yourself I<before> 591either stop all watchers cleanly yourself I<before> calling this function,
583calling this function, or cope with the fact afterwards (which is usually 592or cope with the fact afterwards (which is usually the easiest thing, you
584the easiest thing, you can just ignore the watchers and/or C<free ()> them 593can just ignore the watchers and/or C<free ()> them for example).
585for example).
586 594
587Note that certain global state, such as signal state (and installed signal 595Note that certain global state, such as signal state (and installed signal
588handlers), will not be freed by this function, and related watchers (such 596handlers), will not be freed by this function, and related watchers (such
589as signal and child watchers) would need to be stopped manually. 597as signal and child watchers) would need to be stopped manually.
590 598
591In general it is not advisable to call this function except in the 599In general it is not advisable to call this function except in the
592rare occasion where you really need to free e.g. the signal handling 600rare occasion where you really need to free e.g. the signal handling
593pipe fds. If you need dynamically allocated loops it is better to use 601pipe fds. If you need dynamically allocated loops it is better to use
594C<ev_loop_new> and C<ev_loop_destroy>). 602C<ev_loop_new> and C<ev_loop_destroy>.
595 603
596=item ev_loop_destroy (loop) 604=item ev_loop_destroy (loop)
597 605
598Like C<ev_default_destroy>, but destroys an event loop created by an 606Like C<ev_default_destroy>, but destroys an event loop created by an
599earlier call to C<ev_loop_new>. 607earlier call to C<ev_loop_new>.
605name, you can call it anytime, but it makes most sense after forking, in 613name, you can call it anytime, but it makes most sense after forking, in
606the child process (or both child and parent, but that again makes little 614the child process (or both child and parent, but that again makes little
607sense). You I<must> call it in the child before using any of the libev 615sense). You I<must> call it in the child before using any of the libev
608functions, and it will only take effect at the next C<ev_loop> iteration. 616functions, and it will only take effect at the next C<ev_loop> iteration.
609 617
618Again, you I<have> to call it on I<any> loop that you want to re-use after
619a fork, I<even if you do not plan to use the loop in the parent>. This is
620because some kernel interfaces *cough* I<kqueue> *cough* do funny things
621during fork.
622
610On the other hand, you only need to call this function in the child 623On the other hand, you only need to call this function in the child
611process if and only if you want to use the event library in the child. If 624process if and only if you want to use the event loop in the child. If you
612you just fork+exec, you don't have to call it at all. 625just fork+exec or create a new loop in the child, you don't have to call
626it at all.
613 627
614The function itself is quite fast and it's usually not a problem to call 628The function itself is quite fast and it's usually not a problem to call
615it just in case after a fork. To make this easy, the function will fit in 629it just in case after a fork. To make this easy, the function will fit in
616quite nicely into a call to C<pthread_atfork>: 630quite nicely into a call to C<pthread_atfork>:
617 631
619 633
620=item ev_loop_fork (loop) 634=item ev_loop_fork (loop)
621 635
622Like C<ev_default_fork>, but acts on an event loop created by 636Like C<ev_default_fork>, but acts on an event loop created by
623C<ev_loop_new>. Yes, you have to call this on every allocated event loop 637C<ev_loop_new>. Yes, you have to call this on every allocated event loop
624after fork that you want to re-use in the child, and how you do this is 638after fork that you want to re-use in the child, and how you keep track of
625entirely your own problem. 639them is entirely your own problem.
626 640
627=item int ev_is_default_loop (loop) 641=item int ev_is_default_loop (loop)
628 642
629Returns true when the given loop is, in fact, the default loop, and false 643Returns true when the given loop is, in fact, the default loop, and false
630otherwise. 644otherwise.
631 645
632=item unsigned int ev_loop_count (loop) 646=item unsigned int ev_iteration (loop)
633 647
634Returns the count of loop iterations for the loop, which is identical to 648Returns the current iteration count for the loop, which is identical to
635the number of times libev did poll for new events. It starts at C<0> and 649the number of times libev did poll for new events. It starts at C<0> and
636happily wraps around with enough iterations. 650happily wraps around with enough iterations.
637 651
638This value can sometimes be useful as a generation counter of sorts (it 652This value can sometimes be useful as a generation counter of sorts (it
639"ticks" the number of loop iterations), as it roughly corresponds with 653"ticks" the number of loop iterations), as it roughly corresponds with
640C<ev_prepare> and C<ev_check> calls. 654C<ev_prepare> and C<ev_check> calls - and is incremented between the
655prepare and check phases.
641 656
642=item unsigned int ev_loop_depth (loop) 657=item unsigned int ev_depth (loop)
643 658
644Returns the number of times C<ev_loop> was entered minus the number of 659Returns the number of times C<ev_loop> was entered minus the number of
645times C<ev_loop> was exited, in other words, the recursion depth. 660times C<ev_loop> was exited, in other words, the recursion depth.
646 661
647Outside C<ev_loop>, this number is zero. In a callback, this number is 662Outside C<ev_loop>, this number is zero. In a callback, this number is
648C<1>, unless C<ev_loop> was invoked recursively (or from another thread), 663C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
649in which case it is higher. 664in which case it is higher.
650 665
651Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread 666Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
652etc.), doesn't count as exit. 667etc.), doesn't count as "exit" - consider this as a hint to avoid such
668ungentleman behaviour unless it's really convenient.
653 669
654=item unsigned int ev_backend (loop) 670=item unsigned int ev_backend (loop)
655 671
656Returns one of the C<EVBACKEND_*> flags indicating the event backend in 672Returns one of the C<EVBACKEND_*> flags indicating the event backend in
657use. 673use.
691C<ev_resume> directly afterwards to resume timer processing. 707C<ev_resume> directly afterwards to resume timer processing.
692 708
693Effectively, all C<ev_timer> watchers will be delayed by the time spend 709Effectively, all C<ev_timer> watchers will be delayed by the time spend
694between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers 710between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
695will be rescheduled (that is, they will lose any events that would have 711will be rescheduled (that is, they will lose any events that would have
696occured while suspended). 712occurred while suspended).
697 713
698After calling C<ev_suspend> you B<must not> call I<any> function on the 714After calling C<ev_suspend> you B<must not> call I<any> function on the
699given loop other than C<ev_resume>, and you B<must not> call C<ev_resume> 715given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
700without a previous call to C<ev_suspend>. 716without a previous call to C<ev_suspend>.
701 717
703event loop time (see C<ev_now_update>). 719event loop time (see C<ev_now_update>).
704 720
705=item ev_loop (loop, int flags) 721=item ev_loop (loop, int flags)
706 722
707Finally, this is it, the event handler. This function usually is called 723Finally, this is it, the event handler. This function usually is called
708after you initialised all your watchers and you want to start handling 724after you have initialised all your watchers and you want to start
709events. 725handling events.
710 726
711If the flags argument is specified as C<0>, it will not return until 727If the flags argument is specified as C<0>, it will not return until
712either no event watchers are active anymore or C<ev_unloop> was called. 728either no event watchers are active anymore or C<ev_unloop> was called.
713 729
714Please note that an explicit C<ev_unloop> is usually better than 730Please note that an explicit C<ev_unloop> is usually better than
778C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or 794C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
779C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return. 795C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
780 796
781This "unloop state" will be cleared when entering C<ev_loop> again. 797This "unloop state" will be cleared when entering C<ev_loop> again.
782 798
783It is safe to call C<ev_unloop> from otuside any C<ev_loop> calls. 799It is safe to call C<ev_unloop> from outside any C<ev_loop> calls.
784 800
785=item ev_ref (loop) 801=item ev_ref (loop)
786 802
787=item ev_unref (loop) 803=item ev_unref (loop)
788 804
789Ref/unref can be used to add or remove a reference count on the event 805Ref/unref can be used to add or remove a reference count on the event
790loop: Every watcher keeps one reference, and as long as the reference 806loop: Every watcher keeps one reference, and as long as the reference
791count is nonzero, C<ev_loop> will not return on its own. 807count is nonzero, C<ev_loop> will not return on its own.
792 808
793If you have a watcher you never unregister that should not keep C<ev_loop> 809This is useful when you have a watcher that you never intend to
794from returning, call ev_unref() after starting, and ev_ref() before 810unregister, but that nevertheless should not keep C<ev_loop> from
811returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
795stopping it. 812before stopping it.
796 813
797As an example, libev itself uses this for its internal signal pipe: It 814As an example, libev itself uses this for its internal signal pipe: It
798is not visible to the libev user and should not keep C<ev_loop> from 815is not visible to the libev user and should not keep C<ev_loop> from
799exiting if no event watchers registered by it are active. It is also an 816exiting if no event watchers registered by it are active. It is also an
800excellent way to do this for generic recurring timers or from within 817excellent way to do this for generic recurring timers or from within
857usually doesn't make much sense to set it to a lower value than C<0.01>, 874usually doesn't make much sense to set it to a lower value than C<0.01>,
858as this approaches the timing granularity of most systems. Note that if 875as this approaches the timing granularity of most systems. Note that if
859you do transactions with the outside world and you can't increase the 876you do transactions with the outside world and you can't increase the
860parallelity, then this setting will limit your transaction rate (if you 877parallelity, then this setting will limit your transaction rate (if you
861need to poll once per transaction and the I/O collect interval is 0.01, 878need to poll once per transaction and the I/O collect interval is 0.01,
862then you can't do more than 100 transations per second). 879then you can't do more than 100 transactions per second).
863 880
864Setting the I<timeout collect interval> can improve the opportunity for 881Setting the I<timeout collect interval> can improve the opportunity for
865saving power, as the program will "bundle" timer callback invocations that 882saving power, as the program will "bundle" timer callback invocations that
866are "near" in time together, by delaying some, thus reducing the number of 883are "near" in time together, by delaying some, thus reducing the number of
867times the process sleeps and wakes up again. Another useful technique to 884times the process sleeps and wakes up again. Another useful technique to
915 932
916While event loop modifications are allowed between invocations of 933While event loop modifications are allowed between invocations of
917C<release> and C<acquire> (that's their only purpose after all), no 934C<release> and C<acquire> (that's their only purpose after all), no
918modifications done will affect the event loop, i.e. adding watchers will 935modifications done will affect the event loop, i.e. adding watchers will
919have no effect on the set of file descriptors being watched, or the time 936have no effect on the set of file descriptors being watched, or the time
920waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it 937waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it
921to take note of any changes you made. 938to take note of any changes you made.
922 939
923In theory, threads executing C<ev_loop> will be async-cancel safe between 940In theory, threads executing C<ev_loop> will be async-cancel safe between
924invocations of C<release> and C<acquire>. 941invocations of C<release> and C<acquire>.
925 942
937These two functions can be used to associate arbitrary data with a loop, 954These two functions can be used to associate arbitrary data with a loop,
938and are intended solely for the C<invoke_pending_cb>, C<release> and 955and are intended solely for the C<invoke_pending_cb>, C<release> and
939C<acquire> callbacks described above, but of course can be (ab-)used for 956C<acquire> callbacks described above, but of course can be (ab-)used for
940any other purpose as well. 957any other purpose as well.
941 958
942=item ev_loop_verify (loop) 959=item ev_verify (loop)
943 960
944This function only does something when C<EV_VERIFY> support has been 961This function only does something when C<EV_VERIFY> support has been
945compiled in, which is the default for non-minimal builds. It tries to go 962compiled in, which is the default for non-minimal builds. It tries to go
946through all internal structures and checks them for validity. If anything 963through all internal structures and checks them for validity. If anything
947is found to be inconsistent, it will print an error message to standard 964is found to be inconsistent, it will print an error message to standard
1022=item C<EV_WRITE> 1039=item C<EV_WRITE>
1023 1040
1024The file descriptor in the C<ev_io> watcher has become readable and/or 1041The file descriptor in the C<ev_io> watcher has become readable and/or
1025writable. 1042writable.
1026 1043
1027=item C<EV_TIMEOUT> 1044=item C<EV_TIMER>
1028 1045
1029The C<ev_timer> watcher has timed out. 1046The C<ev_timer> watcher has timed out.
1030 1047
1031=item C<EV_PERIODIC> 1048=item C<EV_PERIODIC>
1032 1049
1122 1139
1123 ev_io w; 1140 ev_io w;
1124 ev_init (&w, my_cb); 1141 ev_init (&w, my_cb);
1125 ev_io_set (&w, STDIN_FILENO, EV_READ); 1142 ev_io_set (&w, STDIN_FILENO, EV_READ);
1126 1143
1127=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1144=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1128 1145
1129This macro initialises the type-specific parts of a watcher. You need to 1146This macro initialises the type-specific parts of a watcher. You need to
1130call C<ev_init> at least once before you call this macro, but you can 1147call C<ev_init> at least once before you call this macro, but you can
1131call C<ev_TYPE_set> any number of times. You must not, however, call this 1148call C<ev_TYPE_set> any number of times. You must not, however, call this
1132macro on a watcher that is active (it can be pending, however, which is a 1149macro on a watcher that is active (it can be pending, however, which is a
1145 1162
1146Example: Initialise and set an C<ev_io> watcher in one step. 1163Example: Initialise and set an C<ev_io> watcher in one step.
1147 1164
1148 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1165 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1149 1166
1150=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1167=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1151 1168
1152Starts (activates) the given watcher. Only active watchers will receive 1169Starts (activates) the given watcher. Only active watchers will receive
1153events. If the watcher is already active nothing will happen. 1170events. If the watcher is already active nothing will happen.
1154 1171
1155Example: Start the C<ev_io> watcher that is being abused as example in this 1172Example: Start the C<ev_io> watcher that is being abused as example in this
1156whole section. 1173whole section.
1157 1174
1158 ev_io_start (EV_DEFAULT_UC, &w); 1175 ev_io_start (EV_DEFAULT_UC, &w);
1159 1176
1160=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1177=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1161 1178
1162Stops the given watcher if active, and clears the pending status (whether 1179Stops the given watcher if active, and clears the pending status (whether
1163the watcher was active or not). 1180the watcher was active or not).
1164 1181
1165It is possible that stopped watchers are pending - for example, 1182It is possible that stopped watchers are pending - for example,
1190=item ev_cb_set (ev_TYPE *watcher, callback) 1207=item ev_cb_set (ev_TYPE *watcher, callback)
1191 1208
1192Change the callback. You can change the callback at virtually any time 1209Change the callback. You can change the callback at virtually any time
1193(modulo threads). 1210(modulo threads).
1194 1211
1195=item ev_set_priority (ev_TYPE *watcher, priority) 1212=item ev_set_priority (ev_TYPE *watcher, int priority)
1196 1213
1197=item int ev_priority (ev_TYPE *watcher) 1214=item int ev_priority (ev_TYPE *watcher)
1198 1215
1199Set and query the priority of the watcher. The priority is a small 1216Set and query the priority of the watcher. The priority is a small
1200integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1217integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1231returns its C<revents> bitset (as if its callback was invoked). If the 1248returns its C<revents> bitset (as if its callback was invoked). If the
1232watcher isn't pending it does nothing and returns C<0>. 1249watcher isn't pending it does nothing and returns C<0>.
1233 1250
1234Sometimes it can be useful to "poll" a watcher instead of waiting for its 1251Sometimes it can be useful to "poll" a watcher instead of waiting for its
1235callback to be invoked, which can be accomplished with this function. 1252callback to be invoked, which can be accomplished with this function.
1253
1254=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1255
1256Feeds the given event set into the event loop, as if the specified event
1257had happened for the specified watcher (which must be a pointer to an
1258initialised but not necessarily started event watcher). Obviously you must
1259not free the watcher as long as it has pending events.
1260
1261Stopping the watcher, letting libev invoke it, or calling
1262C<ev_clear_pending> will clear the pending event, even if the watcher was
1263not started in the first place.
1264
1265See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1266functions that do not need a watcher.
1236 1267
1237=back 1268=back
1238 1269
1239 1270
1240=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1271=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1351 1382
1352For example, to emulate how many other event libraries handle priorities, 1383For example, to emulate how many other event libraries handle priorities,
1353you can associate an C<ev_idle> watcher to each such watcher, and in 1384you can associate an C<ev_idle> watcher to each such watcher, and in
1354the normal watcher callback, you just start the idle watcher. The real 1385the normal watcher callback, you just start the idle watcher. The real
1355processing is done in the idle watcher callback. This causes libev to 1386processing is done in the idle watcher callback. This causes libev to
1356continously poll and process kernel event data for the watcher, but when 1387continuously poll and process kernel event data for the watcher, but when
1357the lock-out case is known to be rare (which in turn is rare :), this is 1388the lock-out case is known to be rare (which in turn is rare :), this is
1358workable. 1389workable.
1359 1390
1360Usually, however, the lock-out model implemented that way will perform 1391Usually, however, the lock-out model implemented that way will perform
1361miserably under the type of load it was designed to handle. In that case, 1392miserably under the type of load it was designed to handle. In that case,
1375 { 1406 {
1376 // stop the I/O watcher, we received the event, but 1407 // stop the I/O watcher, we received the event, but
1377 // are not yet ready to handle it. 1408 // are not yet ready to handle it.
1378 ev_io_stop (EV_A_ w); 1409 ev_io_stop (EV_A_ w);
1379 1410
1380 // start the idle watcher to ahndle the actual event. 1411 // start the idle watcher to handle the actual event.
1381 // it will not be executed as long as other watchers 1412 // it will not be executed as long as other watchers
1382 // with the default priority are receiving events. 1413 // with the default priority are receiving events.
1383 ev_idle_start (EV_A_ &idle); 1414 ev_idle_start (EV_A_ &idle);
1384 } 1415 }
1385 1416
1439 1470
1440If you cannot use non-blocking mode, then force the use of a 1471If you cannot use non-blocking mode, then force the use of a
1441known-to-be-good backend (at the time of this writing, this includes only 1472known-to-be-good backend (at the time of this writing, this includes only
1442C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file 1473C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1443descriptors for which non-blocking operation makes no sense (such as 1474descriptors for which non-blocking operation makes no sense (such as
1444files) - libev doesn't guarentee any specific behaviour in that case. 1475files) - libev doesn't guarantee any specific behaviour in that case.
1445 1476
1446Another thing you have to watch out for is that it is quite easy to 1477Another thing you have to watch out for is that it is quite easy to
1447receive "spurious" readiness notifications, that is your callback might 1478receive "spurious" readiness notifications, that is your callback might
1448be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1479be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1449because there is no data. Not only are some backends known to create a 1480because there is no data. Not only are some backends known to create a
1514 1545
1515So when you encounter spurious, unexplained daemon exits, make sure you 1546So when you encounter spurious, unexplained daemon exits, make sure you
1516ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1547ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1517somewhere, as that would have given you a big clue). 1548somewhere, as that would have given you a big clue).
1518 1549
1550=head3 The special problem of accept()ing when you can't
1551
1552Many implementations of the POSIX C<accept> function (for example,
1553found in post-2004 Linux) have the peculiar behaviour of not removing a
1554connection from the pending queue in all error cases.
1555
1556For example, larger servers often run out of file descriptors (because
1557of resource limits), causing C<accept> to fail with C<ENFILE> but not
1558rejecting the connection, leading to libev signalling readiness on
1559the next iteration again (the connection still exists after all), and
1560typically causing the program to loop at 100% CPU usage.
1561
1562Unfortunately, the set of errors that cause this issue differs between
1563operating systems, there is usually little the app can do to remedy the
1564situation, and no known thread-safe method of removing the connection to
1565cope with overload is known (to me).
1566
1567One of the easiest ways to handle this situation is to just ignore it
1568- when the program encounters an overload, it will just loop until the
1569situation is over. While this is a form of busy waiting, no OS offers an
1570event-based way to handle this situation, so it's the best one can do.
1571
1572A better way to handle the situation is to log any errors other than
1573C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1574messages, and continue as usual, which at least gives the user an idea of
1575what could be wrong ("raise the ulimit!"). For extra points one could stop
1576the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1577usage.
1578
1579If your program is single-threaded, then you could also keep a dummy file
1580descriptor for overload situations (e.g. by opening F</dev/null>), and
1581when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1582close that fd, and create a new dummy fd. This will gracefully refuse
1583clients under typical overload conditions.
1584
1585The last way to handle it is to simply log the error and C<exit>, as
1586is often done with C<malloc> failures, but this results in an easy
1587opportunity for a DoS attack.
1519 1588
1520=head3 Watcher-Specific Functions 1589=head3 Watcher-Specific Functions
1521 1590
1522=over 4 1591=over 4
1523 1592
1670 ev_tstamp timeout = last_activity + 60.; 1739 ev_tstamp timeout = last_activity + 60.;
1671 1740
1672 // if last_activity + 60. is older than now, we did time out 1741 // if last_activity + 60. is older than now, we did time out
1673 if (timeout < now) 1742 if (timeout < now)
1674 { 1743 {
1675 // timeout occured, take action 1744 // timeout occurred, take action
1676 } 1745 }
1677 else 1746 else
1678 { 1747 {
1679 // callback was invoked, but there was some activity, re-arm 1748 // callback was invoked, but there was some activity, re-arm
1680 // the watcher to fire in last_activity + 60, which is 1749 // the watcher to fire in last_activity + 60, which is
1702to the current time (meaning we just have some activity :), then call the 1771to the current time (meaning we just have some activity :), then call the
1703callback, which will "do the right thing" and start the timer: 1772callback, which will "do the right thing" and start the timer:
1704 1773
1705 ev_init (timer, callback); 1774 ev_init (timer, callback);
1706 last_activity = ev_now (loop); 1775 last_activity = ev_now (loop);
1707 callback (loop, timer, EV_TIMEOUT); 1776 callback (loop, timer, EV_TIMER);
1708 1777
1709And when there is some activity, simply store the current time in 1778And when there is some activity, simply store the current time in
1710C<last_activity>, no libev calls at all: 1779C<last_activity>, no libev calls at all:
1711 1780
1712 last_actiivty = ev_now (loop); 1781 last_activity = ev_now (loop);
1713 1782
1714This technique is slightly more complex, but in most cases where the 1783This technique is slightly more complex, but in most cases where the
1715time-out is unlikely to be triggered, much more efficient. 1784time-out is unlikely to be triggered, much more efficient.
1716 1785
1717Changing the timeout is trivial as well (if it isn't hard-coded in the 1786Changing the timeout is trivial as well (if it isn't hard-coded in the
1836C<repeat> value), or reset the running timer to the C<repeat> value. 1905C<repeat> value), or reset the running timer to the C<repeat> value.
1837 1906
1838This sounds a bit complicated, see L<Be smart about timeouts>, above, for a 1907This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1839usage example. 1908usage example.
1840 1909
1841=item ev_timer_remaining (loop, ev_timer *) 1910=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1842 1911
1843Returns the remaining time until a timer fires. If the timer is active, 1912Returns the remaining time until a timer fires. If the timer is active,
1844then this time is relative to the current event loop time, otherwise it's 1913then this time is relative to the current event loop time, otherwise it's
1845the timeout value currently configured. 1914the timeout value currently configured.
1846 1915
1847That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns 1916That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1848C<5>. When the timer is started and one second passes, C<ev_timer_remain> 1917C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
1849will return C<4>. When the timer expires and is restarted, it will return 1918will return C<4>. When the timer expires and is restarted, it will return
1850roughly C<7> (likely slightly less as callback invocation takes some time, 1919roughly C<7> (likely slightly less as callback invocation takes some time,
1851too), and so on. 1920too), and so on.
1852 1921
1853=item ev_tstamp repeat [read-write] 1922=item ev_tstamp repeat [read-write]
2056Example: Call a callback every hour, or, more precisely, whenever the 2125Example: Call a callback every hour, or, more precisely, whenever the
2057system time is divisible by 3600. The callback invocation times have 2126system time is divisible by 3600. The callback invocation times have
2058potentially a lot of jitter, but good long-term stability. 2127potentially a lot of jitter, but good long-term stability.
2059 2128
2060 static void 2129 static void
2061 clock_cb (struct ev_loop *loop, ev_io *w, int revents) 2130 clock_cb (struct ev_loop *loop, ev_periodic *w, int revents)
2062 { 2131 {
2063 ... its now a full hour (UTC, or TAI or whatever your clock follows) 2132 ... its now a full hour (UTC, or TAI or whatever your clock follows)
2064 } 2133 }
2065 2134
2066 ev_periodic hourly_tick; 2135 ev_periodic hourly_tick;
2107 2176
2108When the first watcher gets started will libev actually register something 2177When the first watcher gets started will libev actually register something
2109with the kernel (thus it coexists with your own signal handlers as long as 2178with the kernel (thus it coexists with your own signal handlers as long as
2110you don't register any with libev for the same signal). 2179you don't register any with libev for the same signal).
2111 2180
2112Both the signal mask state (C<sigprocmask>) and the signal handler state
2113(C<sigaction>) are unspecified after starting a signal watcher (and after
2114sotpping it again), that is, libev might or might not block the signal,
2115and might or might not set or restore the installed signal handler.
2116
2117If possible and supported, libev will install its handlers with 2181If possible and supported, libev will install its handlers with
2118C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2182C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2119not be unduly interrupted. If you have a problem with system calls getting 2183not be unduly interrupted. If you have a problem with system calls getting
2120interrupted by signals you can block all signals in an C<ev_check> watcher 2184interrupted by signals you can block all signals in an C<ev_check> watcher
2121and unblock them in an C<ev_prepare> watcher. 2185and unblock them in an C<ev_prepare> watcher.
2186
2187=head3 The special problem of inheritance over fork/execve/pthread_create
2188
2189Both the signal mask (C<sigprocmask>) and the signal disposition
2190(C<sigaction>) are unspecified after starting a signal watcher (and after
2191stopping it again), that is, libev might or might not block the signal,
2192and might or might not set or restore the installed signal handler.
2193
2194While this does not matter for the signal disposition (libev never
2195sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2196C<execve>), this matters for the signal mask: many programs do not expect
2197certain signals to be blocked.
2198
2199This means that before calling C<exec> (from the child) you should reset
2200the signal mask to whatever "default" you expect (all clear is a good
2201choice usually).
2202
2203The simplest way to ensure that the signal mask is reset in the child is
2204to install a fork handler with C<pthread_atfork> that resets it. That will
2205catch fork calls done by libraries (such as the libc) as well.
2206
2207In current versions of libev, the signal will not be blocked indefinitely
2208unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2209the window of opportunity for problems, it will not go away, as libev
2210I<has> to modify the signal mask, at least temporarily.
2211
2212So I can't stress this enough: I<If you do not reset your signal mask when
2213you expect it to be empty, you have a race condition in your code>. This
2214is not a libev-specific thing, this is true for most event libraries.
2122 2215
2123=head3 Watcher-Specific Functions and Data Members 2216=head3 Watcher-Specific Functions and Data Members
2124 2217
2125=over 4 2218=over 4
2126 2219
2874C<ev_default_fork> cheats and calls it in the wrong process, the fork 2967C<ev_default_fork> cheats and calls it in the wrong process, the fork
2875handlers will be invoked, too, of course. 2968handlers will be invoked, too, of course.
2876 2969
2877=head3 The special problem of life after fork - how is it possible? 2970=head3 The special problem of life after fork - how is it possible?
2878 2971
2879Most uses of C<fork()> consist of forking, then some simple calls to ste 2972Most uses of C<fork()> consist of forking, then some simple calls to set
2880up/change the process environment, followed by a call to C<exec()>. This 2973up/change the process environment, followed by a call to C<exec()>. This
2881sequence should be handled by libev without any problems. 2974sequence should be handled by libev without any problems.
2882 2975
2883This changes when the application actually wants to do event handling 2976This changes when the application actually wants to do event handling
2884in the child, or both parent in child, in effect "continuing" after the 2977in the child, or both parent in child, in effect "continuing" after the
2918believe me. 3011believe me.
2919 3012
2920=back 3013=back
2921 3014
2922 3015
2923=head2 C<ev_async> - how to wake up another event loop 3016=head2 C<ev_async> - how to wake up an event loop
2924 3017
2925In general, you cannot use an C<ev_loop> from multiple threads or other 3018In general, you cannot use an C<ev_loop> from multiple threads or other
2926asynchronous sources such as signal handlers (as opposed to multiple event 3019asynchronous sources such as signal handlers (as opposed to multiple event
2927loops - those are of course safe to use in different threads). 3020loops - those are of course safe to use in different threads).
2928 3021
2929Sometimes, however, you need to wake up another event loop you do not 3022Sometimes, however, you need to wake up an event loop you do not control,
2930control, for example because it belongs to another thread. This is what 3023for example because it belongs to another thread. This is what C<ev_async>
2931C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you 3024watchers do: as long as the C<ev_async> watcher is active, you can signal
2932can signal it by calling C<ev_async_send>, which is thread- and signal 3025it by calling C<ev_async_send>, which is thread- and signal safe.
2933safe.
2934 3026
2935This functionality is very similar to C<ev_signal> watchers, as signals, 3027This functionality is very similar to C<ev_signal> watchers, as signals,
2936too, are asynchronous in nature, and signals, too, will be compressed 3028too, are asynchronous in nature, and signals, too, will be compressed
2937(i.e. the number of callback invocations may be less than the number of 3029(i.e. the number of callback invocations may be less than the number of
2938C<ev_async_sent> calls). 3030C<ev_async_sent> calls).
2943=head3 Queueing 3035=head3 Queueing
2944 3036
2945C<ev_async> does not support queueing of data in any way. The reason 3037C<ev_async> does not support queueing of data in any way. The reason
2946is that the author does not know of a simple (or any) algorithm for a 3038is that the author does not know of a simple (or any) algorithm for a
2947multiple-writer-single-reader queue that works in all cases and doesn't 3039multiple-writer-single-reader queue that works in all cases and doesn't
2948need elaborate support such as pthreads. 3040need elaborate support such as pthreads or unportable memory access
3041semantics.
2949 3042
2950That means that if you want to queue data, you have to provide your own 3043That means that if you want to queue data, you have to provide your own
2951queue. But at least I can tell you how to implement locking around your 3044queue. But at least I can tell you how to implement locking around your
2952queue: 3045queue:
2953 3046
3092 3185
3093If C<timeout> is less than 0, then no timeout watcher will be 3186If C<timeout> is less than 0, then no timeout watcher will be
3094started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3187started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3095repeat = 0) will be started. C<0> is a valid timeout. 3188repeat = 0) will be started. C<0> is a valid timeout.
3096 3189
3097The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3190The callback has the type C<void (*cb)(int revents, void *arg)> and is
3098passed an C<revents> set like normal event callbacks (a combination of 3191passed an C<revents> set like normal event callbacks (a combination of
3099C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3192C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
3100value passed to C<ev_once>. Note that it is possible to receive I<both> 3193value passed to C<ev_once>. Note that it is possible to receive I<both>
3101a timeout and an io event at the same time - you probably should give io 3194a timeout and an io event at the same time - you probably should give io
3102events precedence. 3195events precedence.
3103 3196
3104Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3197Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3105 3198
3106 static void stdin_ready (int revents, void *arg) 3199 static void stdin_ready (int revents, void *arg)
3107 { 3200 {
3108 if (revents & EV_READ) 3201 if (revents & EV_READ)
3109 /* stdin might have data for us, joy! */; 3202 /* stdin might have data for us, joy! */;
3110 else if (revents & EV_TIMEOUT) 3203 else if (revents & EV_TIMER)
3111 /* doh, nothing entered */; 3204 /* doh, nothing entered */;
3112 } 3205 }
3113 3206
3114 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3207 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3115 3208
3116=item ev_feed_event (struct ev_loop *, watcher *, int revents)
3117
3118Feeds the given event set into the event loop, as if the specified event
3119had happened for the specified watcher (which must be a pointer to an
3120initialised but not necessarily started event watcher).
3121
3122=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3209=item ev_feed_fd_event (loop, int fd, int revents)
3123 3210
3124Feed an event on the given fd, as if a file descriptor backend detected 3211Feed an event on the given fd, as if a file descriptor backend detected
3125the given events it. 3212the given events it.
3126 3213
3127=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3214=item ev_feed_signal_event (loop, int signum)
3128 3215
3129Feed an event as if the given signal occurred (C<loop> must be the default 3216Feed an event as if the given signal occurred (C<loop> must be the default
3130loop!). 3217loop!).
3131 3218
3132=back 3219=back
3212 3299
3213=over 4 3300=over 4
3214 3301
3215=item ev::TYPE::TYPE () 3302=item ev::TYPE::TYPE ()
3216 3303
3217=item ev::TYPE::TYPE (struct ev_loop *) 3304=item ev::TYPE::TYPE (loop)
3218 3305
3219=item ev::TYPE::~TYPE 3306=item ev::TYPE::~TYPE
3220 3307
3221The constructor (optionally) takes an event loop to associate the watcher 3308The constructor (optionally) takes an event loop to associate the watcher
3222with. If it is omitted, it will use C<EV_DEFAULT>. 3309with. If it is omitted, it will use C<EV_DEFAULT>.
3255 myclass obj; 3342 myclass obj;
3256 ev::io iow; 3343 ev::io iow;
3257 iow.set <myclass, &myclass::io_cb> (&obj); 3344 iow.set <myclass, &myclass::io_cb> (&obj);
3258 3345
3259=item w->set (object *) 3346=item w->set (object *)
3260
3261This is an B<experimental> feature that might go away in a future version.
3262 3347
3263This is a variation of a method callback - leaving out the method to call 3348This is a variation of a method callback - leaving out the method to call
3264will default the method to C<operator ()>, which makes it possible to use 3349will default the method to C<operator ()>, which makes it possible to use
3265functor objects without having to manually specify the C<operator ()> all 3350functor objects without having to manually specify the C<operator ()> all
3266the time. Incidentally, you can then also leave out the template argument 3351the time. Incidentally, you can then also leave out the template argument
3299Example: Use a plain function as callback. 3384Example: Use a plain function as callback.
3300 3385
3301 static void io_cb (ev::io &w, int revents) { } 3386 static void io_cb (ev::io &w, int revents) { }
3302 iow.set <io_cb> (); 3387 iow.set <io_cb> ();
3303 3388
3304=item w->set (struct ev_loop *) 3389=item w->set (loop)
3305 3390
3306Associates a different C<struct ev_loop> with this watcher. You can only 3391Associates a different C<struct ev_loop> with this watcher. You can only
3307do this when the watcher is inactive (and not pending either). 3392do this when the watcher is inactive (and not pending either).
3308 3393
3309=item w->set ([arguments]) 3394=item w->set ([arguments])
3310 3395
3311Basically the same as C<ev_TYPE_set>, with the same arguments. Must be 3396Basically the same as C<ev_TYPE_set>, with the same arguments. Either this
3312called at least once. Unlike the C counterpart, an active watcher gets 3397method or a suitable start method must be called at least once. Unlike the
3313automatically stopped and restarted when reconfiguring it with this 3398C counterpart, an active watcher gets automatically stopped and restarted
3314method. 3399when reconfiguring it with this method.
3315 3400
3316=item w->start () 3401=item w->start ()
3317 3402
3318Starts the watcher. Note that there is no C<loop> argument, as the 3403Starts the watcher. Note that there is no C<loop> argument, as the
3319constructor already stores the event loop. 3404constructor already stores the event loop.
3320 3405
3406=item w->start ([arguments])
3407
3408Instead of calling C<set> and C<start> methods separately, it is often
3409convenient to wrap them in one call. Uses the same type of arguments as
3410the configure C<set> method of the watcher.
3411
3321=item w->stop () 3412=item w->stop ()
3322 3413
3323Stops the watcher if it is active. Again, no C<loop> argument. 3414Stops the watcher if it is active. Again, no C<loop> argument.
3324 3415
3325=item w->again () (C<ev::timer>, C<ev::periodic> only) 3416=item w->again () (C<ev::timer>, C<ev::periodic> only)
3337 3428
3338=back 3429=back
3339 3430
3340=back 3431=back
3341 3432
3342Example: Define a class with an IO and idle watcher, start one of them in 3433Example: Define a class with two I/O and idle watchers, start the I/O
3343the constructor. 3434watchers in the constructor.
3344 3435
3345 class myclass 3436 class myclass
3346 { 3437 {
3347 ev::io io ; void io_cb (ev::io &w, int revents); 3438 ev::io io ; void io_cb (ev::io &w, int revents);
3439 ev::io2 io2 ; void io2_cb (ev::io &w, int revents);
3348 ev::idle idle; void idle_cb (ev::idle &w, int revents); 3440 ev::idle idle; void idle_cb (ev::idle &w, int revents);
3349 3441
3350 myclass (int fd) 3442 myclass (int fd)
3351 { 3443 {
3352 io .set <myclass, &myclass::io_cb > (this); 3444 io .set <myclass, &myclass::io_cb > (this);
3445 io2 .set <myclass, &myclass::io2_cb > (this);
3353 idle.set <myclass, &myclass::idle_cb> (this); 3446 idle.set <myclass, &myclass::idle_cb> (this);
3354 3447
3355 io.start (fd, ev::READ); 3448 io.set (fd, ev::WRITE); // configure the watcher
3449 io.start (); // start it whenever convenient
3450
3451 io2.start (fd, ev::READ); // set + start in one call
3356 } 3452 }
3357 }; 3453 };
3358 3454
3359 3455
3360=head1 OTHER LANGUAGE BINDINGS 3456=head1 OTHER LANGUAGE BINDINGS
3406=item Ocaml 3502=item Ocaml
3407 3503
3408Erkki Seppala has written Ocaml bindings for libev, to be found at 3504Erkki Seppala has written Ocaml bindings for libev, to be found at
3409L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3505L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3410 3506
3507=item Lua
3508
3509Brian Maher has written a partial interface to libev for lua (at the
3510time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3511L<http://github.com/brimworks/lua-ev>.
3512
3411=back 3513=back
3412 3514
3413 3515
3414=head1 MACRO MAGIC 3516=head1 MACRO MAGIC
3415 3517
3568 libev.m4 3670 libev.m4
3569 3671
3570=head2 PREPROCESSOR SYMBOLS/MACROS 3672=head2 PREPROCESSOR SYMBOLS/MACROS
3571 3673
3572Libev can be configured via a variety of preprocessor symbols you have to 3674Libev can be configured via a variety of preprocessor symbols you have to
3573define before including any of its files. The default in the absence of 3675define before including (or compiling) any of its files. The default in
3574autoconf is documented for every option. 3676the absence of autoconf is documented for every option.
3677
3678Symbols marked with "(h)" do not change the ABI, and can have different
3679values when compiling libev vs. including F<ev.h>, so it is permissible
3680to redefine them before including F<ev.h> without breaking compatibility
3681to a compiled library. All other symbols change the ABI, which means all
3682users of libev and the libev code itself must be compiled with compatible
3683settings.
3575 3684
3576=over 4 3685=over 4
3577 3686
3578=item EV_STANDALONE 3687=item EV_STANDALONE (h)
3579 3688
3580Must always be C<1> if you do not use autoconf configuration, which 3689Must always be C<1> if you do not use autoconf configuration, which
3581keeps libev from including F<config.h>, and it also defines dummy 3690keeps libev from including F<config.h>, and it also defines dummy
3582implementations for some libevent functions (such as logging, which is not 3691implementations for some libevent functions (such as logging, which is not
3583supported). It will also not define any of the structs usually found in 3692supported). It will also not define any of the structs usually found in
3584F<event.h> that are not directly supported by the libev core alone. 3693F<event.h> that are not directly supported by the libev core alone.
3585 3694
3586In stanbdalone mode, libev will still try to automatically deduce the 3695In standalone mode, libev will still try to automatically deduce the
3587configuration, but has to be more conservative. 3696configuration, but has to be more conservative.
3588 3697
3589=item EV_USE_MONOTONIC 3698=item EV_USE_MONOTONIC
3590 3699
3591If defined to be C<1>, libev will try to detect the availability of the 3700If defined to be C<1>, libev will try to detect the availability of the
3656be used is the winsock select). This means that it will call 3765be used is the winsock select). This means that it will call
3657C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3766C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3658it is assumed that all these functions actually work on fds, even 3767it is assumed that all these functions actually work on fds, even
3659on win32. Should not be defined on non-win32 platforms. 3768on win32. Should not be defined on non-win32 platforms.
3660 3769
3661=item EV_FD_TO_WIN32_HANDLE 3770=item EV_FD_TO_WIN32_HANDLE(fd)
3662 3771
3663If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3772If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3664file descriptors to socket handles. When not defining this symbol (the 3773file descriptors to socket handles. When not defining this symbol (the
3665default), then libev will call C<_get_osfhandle>, which is usually 3774default), then libev will call C<_get_osfhandle>, which is usually
3666correct. In some cases, programs use their own file descriptor management, 3775correct. In some cases, programs use their own file descriptor management,
3667in which case they can provide this function to map fds to socket handles. 3776in which case they can provide this function to map fds to socket handles.
3777
3778=item EV_WIN32_HANDLE_TO_FD(handle)
3779
3780If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3781using the standard C<_open_osfhandle> function. For programs implementing
3782their own fd to handle mapping, overwriting this function makes it easier
3783to do so. This can be done by defining this macro to an appropriate value.
3784
3785=item EV_WIN32_CLOSE_FD(fd)
3786
3787If programs implement their own fd to handle mapping on win32, then this
3788macro can be used to override the C<close> function, useful to unregister
3789file descriptors again. Note that the replacement function has to close
3790the underlying OS handle.
3668 3791
3669=item EV_USE_POLL 3792=item EV_USE_POLL
3670 3793
3671If defined to be C<1>, libev will compile in support for the C<poll>(2) 3794If defined to be C<1>, libev will compile in support for the C<poll>(2)
3672backend. Otherwise it will be enabled on non-win32 platforms. It 3795backend. Otherwise it will be enabled on non-win32 platforms. It
3719as well as for signal and thread safety in C<ev_async> watchers. 3842as well as for signal and thread safety in C<ev_async> watchers.
3720 3843
3721In the absence of this define, libev will use C<sig_atomic_t volatile> 3844In the absence of this define, libev will use C<sig_atomic_t volatile>
3722(from F<signal.h>), which is usually good enough on most platforms. 3845(from F<signal.h>), which is usually good enough on most platforms.
3723 3846
3724=item EV_H 3847=item EV_H (h)
3725 3848
3726The name of the F<ev.h> header file used to include it. The default if 3849The name of the F<ev.h> header file used to include it. The default if
3727undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 3850undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3728used to virtually rename the F<ev.h> header file in case of conflicts. 3851used to virtually rename the F<ev.h> header file in case of conflicts.
3729 3852
3730=item EV_CONFIG_H 3853=item EV_CONFIG_H (h)
3731 3854
3732If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3855If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3733F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3856F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3734C<EV_H>, above. 3857C<EV_H>, above.
3735 3858
3736=item EV_EVENT_H 3859=item EV_EVENT_H (h)
3737 3860
3738Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3861Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3739of how the F<event.h> header can be found, the default is C<"event.h">. 3862of how the F<event.h> header can be found, the default is C<"event.h">.
3740 3863
3741=item EV_PROTOTYPES 3864=item EV_PROTOTYPES (h)
3742 3865
3743If defined to be C<0>, then F<ev.h> will not define any function 3866If defined to be C<0>, then F<ev.h> will not define any function
3744prototypes, but still define all the structs and other symbols. This is 3867prototypes, but still define all the structs and other symbols. This is
3745occasionally useful if you want to provide your own wrapper functions 3868occasionally useful if you want to provide your own wrapper functions
3746around libev functions. 3869around libev functions.
3768fine. 3891fine.
3769 3892
3770If your embedding application does not need any priorities, defining these 3893If your embedding application does not need any priorities, defining these
3771both to C<0> will save some memory and CPU. 3894both to C<0> will save some memory and CPU.
3772 3895
3773=item EV_PERIODIC_ENABLE 3896=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3897EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3898EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3774 3899
3775If undefined or defined to be C<1>, then periodic timers are supported. If 3900If undefined or defined to be C<1> (and the platform supports it), then
3776defined to be C<0>, then they are not. Disabling them saves a few kB of 3901the respective watcher type is supported. If defined to be C<0>, then it
3777code. 3902is not. Disabling watcher types mainly saves code size.
3778 3903
3779=item EV_IDLE_ENABLE 3904=item EV_FEATURES
3780
3781If undefined or defined to be C<1>, then idle watchers are supported. If
3782defined to be C<0>, then they are not. Disabling them saves a few kB of
3783code.
3784
3785=item EV_EMBED_ENABLE
3786
3787If undefined or defined to be C<1>, then embed watchers are supported. If
3788defined to be C<0>, then they are not. Embed watchers rely on most other
3789watcher types, which therefore must not be disabled.
3790
3791=item EV_STAT_ENABLE
3792
3793If undefined or defined to be C<1>, then stat watchers are supported. If
3794defined to be C<0>, then they are not.
3795
3796=item EV_FORK_ENABLE
3797
3798If undefined or defined to be C<1>, then fork watchers are supported. If
3799defined to be C<0>, then they are not.
3800
3801=item EV_ASYNC_ENABLE
3802
3803If undefined or defined to be C<1>, then async watchers are supported. If
3804defined to be C<0>, then they are not.
3805
3806=item EV_MINIMAL
3807 3905
3808If you need to shave off some kilobytes of code at the expense of some 3906If you need to shave off some kilobytes of code at the expense of some
3809speed (but with the full API), define this symbol to C<1>. Currently this 3907speed (but with the full API), you can define this symbol to request
3810is used to override some inlining decisions, saves roughly 30% code size 3908certain subsets of functionality. The default is to enable all features
3811on amd64. It also selects a much smaller 2-heap for timer management over 3909that can be enabled on the platform.
3812the default 4-heap.
3813 3910
3814You can save even more by disabling watcher types you do not need 3911A typical way to use this symbol is to define it to C<0> (or to a bitset
3815and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 3912with some broad features you want) and then selectively re-enable
3816(C<-DNDEBUG>) will usually reduce code size a lot. 3913additional parts you want, for example if you want everything minimal,
3914but multiple event loop support, async and child watchers and the poll
3915backend, use this:
3817 3916
3818Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 3917 #define EV_FEATURES 0
3819provide a bare-bones event library. See C<ev.h> for details on what parts 3918 #define EV_MULTIPLICITY 1
3820of the API are still available, and do not complain if this subset changes 3919 #define EV_USE_POLL 1
3821over time. 3920 #define EV_CHILD_ENABLE 1
3921 #define EV_ASYNC_ENABLE 1
3922
3923The actual value is a bitset, it can be a combination of the following
3924values:
3925
3926=over 4
3927
3928=item C<1> - faster/larger code
3929
3930Use larger code to speed up some operations.
3931
3932Currently this is used to override some inlining decisions (enlarging the
3933code size by roughly 30% on amd64).
3934
3935When optimising for size, use of compiler flags such as C<-Os> with
3936gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
3937assertions.
3938
3939=item C<2> - faster/larger data structures
3940
3941Replaces the small 2-heap for timer management by a faster 4-heap, larger
3942hash table sizes and so on. This will usually further increase code size
3943and can additionally have an effect on the size of data structures at
3944runtime.
3945
3946=item C<4> - full API configuration
3947
3948This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3949enables multiplicity (C<EV_MULTIPLICITY>=1).
3950
3951=item C<8> - full API
3952
3953This enables a lot of the "lesser used" API functions. See C<ev.h> for
3954details on which parts of the API are still available without this
3955feature, and do not complain if this subset changes over time.
3956
3957=item C<16> - enable all optional watcher types
3958
3959Enables all optional watcher types. If you want to selectively enable
3960only some watcher types other than I/O and timers (e.g. prepare,
3961embed, async, child...) you can enable them manually by defining
3962C<EV_watchertype_ENABLE> to C<1> instead.
3963
3964=item C<32> - enable all backends
3965
3966This enables all backends - without this feature, you need to enable at
3967least one backend manually (C<EV_USE_SELECT> is a good choice).
3968
3969=item C<64> - enable OS-specific "helper" APIs
3970
3971Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3972default.
3973
3974=back
3975
3976Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
3977reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
3978code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
3979watchers, timers and monotonic clock support.
3980
3981With an intelligent-enough linker (gcc+binutils are intelligent enough
3982when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
3983your program might be left out as well - a binary starting a timer and an
3984I/O watcher then might come out at only 5Kb.
3985
3986=item EV_AVOID_STDIO
3987
3988If this is set to C<1> at compiletime, then libev will avoid using stdio
3989functions (printf, scanf, perror etc.). This will increase the code size
3990somewhat, but if your program doesn't otherwise depend on stdio and your
3991libc allows it, this avoids linking in the stdio library which is quite
3992big.
3993
3994Note that error messages might become less precise when this option is
3995enabled.
3822 3996
3823=item EV_NSIG 3997=item EV_NSIG
3824 3998
3825The highest supported signal number, +1 (or, the number of 3999The highest supported signal number, +1 (or, the number of
3826signals): Normally, libev tries to deduce the maximum number of signals 4000signals): Normally, libev tries to deduce the maximum number of signals
3827automatically, but sometimes this fails, in which case it can be 4001automatically, but sometimes this fails, in which case it can be
3828specified. Also, using a lower number than detected (C<32> should be 4002specified. Also, using a lower number than detected (C<32> should be
3829good for about any system in existance) can save some memory, as libev 4003good for about any system in existence) can save some memory, as libev
3830statically allocates some 12-24 bytes per signal number. 4004statically allocates some 12-24 bytes per signal number.
3831 4005
3832=item EV_PID_HASHSIZE 4006=item EV_PID_HASHSIZE
3833 4007
3834C<ev_child> watchers use a small hash table to distribute workload by 4008C<ev_child> watchers use a small hash table to distribute workload by
3835pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 4009pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3836than enough. If you need to manage thousands of children you might want to 4010usually more than enough. If you need to manage thousands of children you
3837increase this value (I<must> be a power of two). 4011might want to increase this value (I<must> be a power of two).
3838 4012
3839=item EV_INOTIFY_HASHSIZE 4013=item EV_INOTIFY_HASHSIZE
3840 4014
3841C<ev_stat> watchers use a small hash table to distribute workload by 4015C<ev_stat> watchers use a small hash table to distribute workload by
3842inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4016inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3843usually more than enough. If you need to manage thousands of C<ev_stat> 4017disabled), usually more than enough. If you need to manage thousands of
3844watchers you might want to increase this value (I<must> be a power of 4018C<ev_stat> watchers you might want to increase this value (I<must> be a
3845two). 4019power of two).
3846 4020
3847=item EV_USE_4HEAP 4021=item EV_USE_4HEAP
3848 4022
3849Heaps are not very cache-efficient. To improve the cache-efficiency of the 4023Heaps are not very cache-efficient. To improve the cache-efficiency of the
3850timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4024timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3851to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4025to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3852faster performance with many (thousands) of watchers. 4026faster performance with many (thousands) of watchers.
3853 4027
3854The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4028The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3855(disabled). 4029will be C<0>.
3856 4030
3857=item EV_HEAP_CACHE_AT 4031=item EV_HEAP_CACHE_AT
3858 4032
3859Heaps are not very cache-efficient. To improve the cache-efficiency of the 4033Heaps are not very cache-efficient. To improve the cache-efficiency of the
3860timer and periodics heaps, libev can cache the timestamp (I<at>) within 4034timer and periodics heaps, libev can cache the timestamp (I<at>) within
3861the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4035the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3862which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4036which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3863but avoids random read accesses on heap changes. This improves performance 4037but avoids random read accesses on heap changes. This improves performance
3864noticeably with many (hundreds) of watchers. 4038noticeably with many (hundreds) of watchers.
3865 4039
3866The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4040The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3867(disabled). 4041will be C<0>.
3868 4042
3869=item EV_VERIFY 4043=item EV_VERIFY
3870 4044
3871Controls how much internal verification (see C<ev_loop_verify ()>) will 4045Controls how much internal verification (see C<ev_verify ()>) will
3872be done: If set to C<0>, no internal verification code will be compiled 4046be done: If set to C<0>, no internal verification code will be compiled
3873in. If set to C<1>, then verification code will be compiled in, but not 4047in. If set to C<1>, then verification code will be compiled in, but not
3874called. If set to C<2>, then the internal verification code will be 4048called. If set to C<2>, then the internal verification code will be
3875called once per loop, which can slow down libev. If set to C<3>, then the 4049called once per loop, which can slow down libev. If set to C<3>, then the
3876verification code will be called very frequently, which will slow down 4050verification code will be called very frequently, which will slow down
3877libev considerably. 4051libev considerably.
3878 4052
3879The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4053The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3880C<0>. 4054will be C<0>.
3881 4055
3882=item EV_COMMON 4056=item EV_COMMON
3883 4057
3884By default, all watchers have a C<void *data> member. By redefining 4058By default, all watchers have a C<void *data> member. By redefining
3885this macro to a something else you can include more and other types of 4059this macro to something else you can include more and other types of
3886members. You have to define it each time you include one of the files, 4060members. You have to define it each time you include one of the files,
3887though, and it must be identical each time. 4061though, and it must be identical each time.
3888 4062
3889For example, the perl EV module uses something like this: 4063For example, the perl EV module uses something like this:
3890 4064
3943file. 4117file.
3944 4118
3945The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4119The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3946that everybody includes and which overrides some configure choices: 4120that everybody includes and which overrides some configure choices:
3947 4121
3948 #define EV_MINIMAL 1 4122 #define EV_FEATURES 8
3949 #define EV_USE_POLL 0 4123 #define EV_USE_SELECT 1
3950 #define EV_MULTIPLICITY 0
3951 #define EV_PERIODIC_ENABLE 0 4124 #define EV_PREPARE_ENABLE 1
4125 #define EV_IDLE_ENABLE 1
3952 #define EV_STAT_ENABLE 0 4126 #define EV_SIGNAL_ENABLE 1
3953 #define EV_FORK_ENABLE 0 4127 #define EV_CHILD_ENABLE 1
4128 #define EV_USE_STDEXCEPT 0
3954 #define EV_CONFIG_H <config.h> 4129 #define EV_CONFIG_H <config.h>
3955 #define EV_MINPRI 0
3956 #define EV_MAXPRI 0
3957 4130
3958 #include "ev++.h" 4131 #include "ev++.h"
3959 4132
3960And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4133And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3961 4134
4190maintainable. 4363maintainable.
4191 4364
4192And of course, some compiler warnings are just plain stupid, or simply 4365And of course, some compiler warnings are just plain stupid, or simply
4193wrong (because they don't actually warn about the condition their message 4366wrong (because they don't actually warn about the condition their message
4194seems to warn about). For example, certain older gcc versions had some 4367seems to warn about). For example, certain older gcc versions had some
4195warnings that resulted an extreme number of false positives. These have 4368warnings that resulted in an extreme number of false positives. These have
4196been fixed, but some people still insist on making code warn-free with 4369been fixed, but some people still insist on making code warn-free with
4197such buggy versions. 4370such buggy versions.
4198 4371
4199While libev is written to generate as few warnings as possible, 4372While libev is written to generate as few warnings as possible,
4200"warn-free" code is not a goal, and it is recommended not to build libev 4373"warn-free" code is not a goal, and it is recommended not to build libev
4236I suggest using suppression lists. 4409I suggest using suppression lists.
4237 4410
4238 4411
4239=head1 PORTABILITY NOTES 4412=head1 PORTABILITY NOTES
4240 4413
4414=head2 GNU/LINUX 32 BIT LIMITATIONS
4415
4416GNU/Linux is the only common platform that supports 64 bit file/large file
4417interfaces but I<disables> them by default.
4418
4419That means that libev compiled in the default environment doesn't support
4420files larger than 2GiB or so, which mainly affects C<ev_stat> watchers.
4421
4422Unfortunately, many programs try to work around this GNU/Linux issue
4423by enabling the large file API, which makes them incompatible with the
4424standard libev compiled for their system.
4425
4426Likewise, libev cannot enable the large file API itself as this would
4427suddenly make it incompatible to the default compile time environment,
4428i.e. all programs not using special compile switches.
4429
4430=head2 OS/X AND DARWIN BUGS
4431
4432The whole thing is a bug if you ask me - basically any system interface
4433you touch is broken, whether it is locales, poll, kqueue or even the
4434OpenGL drivers.
4435
4436=head3 C<kqueue> is buggy
4437
4438The kqueue syscall is broken in all known versions - most versions support
4439only sockets, many support pipes.
4440
4441Libev tries to work around this by not using C<kqueue> by default on
4442this rotten platform, but of course you can still ask for it when creating
4443a loop.
4444
4445=head3 C<poll> is buggy
4446
4447Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
4448implementation by something calling C<kqueue> internally around the 10.5.6
4449release, so now C<kqueue> I<and> C<poll> are broken.
4450
4451Libev tries to work around this by not using C<poll> by default on
4452this rotten platform, but of course you can still ask for it when creating
4453a loop.
4454
4455=head3 C<select> is buggy
4456
4457All that's left is C<select>, and of course Apple found a way to fuck this
4458one up as well: On OS/X, C<select> actively limits the number of file
4459descriptors you can pass in to 1024 - your program suddenly crashes when
4460you use more.
4461
4462There is an undocumented "workaround" for this - defining
4463C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
4464work on OS/X.
4465
4466=head2 SOLARIS PROBLEMS AND WORKAROUNDS
4467
4468=head3 C<errno> reentrancy
4469
4470The default compile environment on Solaris is unfortunately so
4471thread-unsafe that you can't even use components/libraries compiled
4472without C<-D_REENTRANT> (as long as they use C<errno>), which, of course,
4473isn't defined by default.
4474
4475If you want to use libev in threaded environments you have to make sure
4476it's compiled with C<_REENTRANT> defined.
4477
4478=head3 Event port backend
4479
4480The scalable event interface for Solaris is called "event ports". Unfortunately,
4481this mechanism is very buggy. If you run into high CPU usage, your program
4482freezes or you get a large number of spurious wakeups, make sure you have
4483all the relevant and latest kernel patches applied. No, I don't know which
4484ones, but there are multiple ones.
4485
4486If you can't get it to work, you can try running the program by setting
4487the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and
4488C<select> backends.
4489
4490=head2 AIX POLL BUG
4491
4492AIX unfortunately has a broken C<poll.h> header. Libev works around
4493this by trying to avoid the poll backend altogether (i.e. it's not even
4494compiled in), which normally isn't a big problem as C<select> works fine
4495with large bitsets, and AIX is dead anyway.
4496
4241=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 4497=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
4498
4499=head3 General issues
4242 4500
4243Win32 doesn't support any of the standards (e.g. POSIX) that libev 4501Win32 doesn't support any of the standards (e.g. POSIX) that libev
4244requires, and its I/O model is fundamentally incompatible with the POSIX 4502requires, and its I/O model is fundamentally incompatible with the POSIX
4245model. Libev still offers limited functionality on this platform in 4503model. Libev still offers limited functionality on this platform in
4246the form of the C<EVBACKEND_SELECT> backend, and only supports socket 4504the form of the C<EVBACKEND_SELECT> backend, and only supports socket
4247descriptors. This only applies when using Win32 natively, not when using 4505descriptors. This only applies when using Win32 natively, not when using
4248e.g. cygwin. 4506e.g. cygwin. Actually, it only applies to the microsofts own compilers,
4507as every compielr comes with a slightly differently broken/incompatible
4508environment.
4249 4509
4250Lifting these limitations would basically require the full 4510Lifting these limitations would basically require the full
4251re-implementation of the I/O system. If you are into these kinds of 4511re-implementation of the I/O system. If you are into this kind of thing,
4252things, then note that glib does exactly that for you in a very portable 4512then note that glib does exactly that for you in a very portable way (note
4253way (note also that glib is the slowest event library known to man). 4513also that glib is the slowest event library known to man).
4254 4514
4255There is no supported compilation method available on windows except 4515There is no supported compilation method available on windows except
4256embedding it into other applications. 4516embedding it into other applications.
4257 4517
4258Sensible signal handling is officially unsupported by Microsoft - libev 4518Sensible signal handling is officially unsupported by Microsoft - libev
4286you do I<not> compile the F<ev.c> or any other embedded source files!): 4546you do I<not> compile the F<ev.c> or any other embedded source files!):
4287 4547
4288 #include "evwrap.h" 4548 #include "evwrap.h"
4289 #include "ev.c" 4549 #include "ev.c"
4290 4550
4291=over 4
4292
4293=item The winsocket select function 4551=head3 The winsocket C<select> function
4294 4552
4295The winsocket C<select> function doesn't follow POSIX in that it 4553The winsocket C<select> function doesn't follow POSIX in that it
4296requires socket I<handles> and not socket I<file descriptors> (it is 4554requires socket I<handles> and not socket I<file descriptors> (it is
4297also extremely buggy). This makes select very inefficient, and also 4555also extremely buggy). This makes select very inefficient, and also
4298requires a mapping from file descriptors to socket handles (the Microsoft 4556requires a mapping from file descriptors to socket handles (the Microsoft
4307 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 4565 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
4308 4566
4309Note that winsockets handling of fd sets is O(n), so you can easily get a 4567Note that winsockets handling of fd sets is O(n), so you can easily get a
4310complexity in the O(n²) range when using win32. 4568complexity in the O(n²) range when using win32.
4311 4569
4312=item Limited number of file descriptors 4570=head3 Limited number of file descriptors
4313 4571
4314Windows has numerous arbitrary (and low) limits on things. 4572Windows has numerous arbitrary (and low) limits on things.
4315 4573
4316Early versions of winsocket's select only supported waiting for a maximum 4574Early versions of winsocket's select only supported waiting for a maximum
4317of C<64> handles (probably owning to the fact that all windows kernels 4575of C<64> handles (probably owning to the fact that all windows kernels
4332runtime libraries. This might get you to about C<512> or C<2048> sockets 4590runtime libraries. This might get you to about C<512> or C<2048> sockets
4333(depending on windows version and/or the phase of the moon). To get more, 4591(depending on windows version and/or the phase of the moon). To get more,
4334you need to wrap all I/O functions and provide your own fd management, but 4592you need to wrap all I/O functions and provide your own fd management, but
4335the cost of calling select (O(n²)) will likely make this unworkable. 4593the cost of calling select (O(n²)) will likely make this unworkable.
4336 4594
4337=back
4338
4339=head2 PORTABILITY REQUIREMENTS 4595=head2 PORTABILITY REQUIREMENTS
4340 4596
4341In addition to a working ISO-C implementation and of course the 4597In addition to a working ISO-C implementation and of course the
4342backend-specific APIs, libev relies on a few additional extensions: 4598backend-specific APIs, libev relies on a few additional extensions:
4343 4599
4381watchers. 4637watchers.
4382 4638
4383=item C<double> must hold a time value in seconds with enough accuracy 4639=item C<double> must hold a time value in seconds with enough accuracy
4384 4640
4385The type C<double> is used to represent timestamps. It is required to 4641The type C<double> is used to represent timestamps. It is required to
4386have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4642have at least 51 bits of mantissa (and 9 bits of exponent), which is
4387enough for at least into the year 4000. This requirement is fulfilled by 4643good enough for at least into the year 4000 with millisecond accuracy
4644(the design goal for libev). This requirement is overfulfilled by
4388implementations implementing IEEE 754, which is basically all existing 4645implementations using IEEE 754, which is basically all existing ones. With
4389ones. With IEEE 754 doubles, you get microsecond accuracy until at least 4646IEEE 754 doubles, you get microsecond accuracy until at least 2200.
43902200.
4391 4647
4392=back 4648=back
4393 4649
4394If you know of other additional requirements drop me a note. 4650If you know of other additional requirements drop me a note.
4395 4651
4463involves iterating over all running async watchers or all signal numbers. 4719involves iterating over all running async watchers or all signal numbers.
4464 4720
4465=back 4721=back
4466 4722
4467 4723
4724=head1 PORTING FROM LIBEV 3.X TO 4.X
4725
4726The major version 4 introduced some minor incompatible changes to the API.
4727
4728At the moment, the C<ev.h> header file tries to implement superficial
4729compatibility, so most programs should still compile. Those might be
4730removed in later versions of libev, so better update early than late.
4731
4732=over 4
4733
4734=item C<ev_loop_count> renamed to C<ev_iteration>
4735
4736=item C<ev_loop_depth> renamed to C<ev_depth>
4737
4738=item C<ev_loop_verify> renamed to C<ev_verify>
4739
4740Most functions working on C<struct ev_loop> objects don't have an
4741C<ev_loop_> prefix, so it was removed. Note that C<ev_loop_fork> is
4742still called C<ev_loop_fork> because it would otherwise clash with the
4743C<ev_fork> typedef.
4744
4745=item C<EV_TIMEOUT> renamed to C<EV_TIMER> in C<revents>
4746
4747This is a simple rename - all other watcher types use their name
4748as revents flag, and now C<ev_timer> does, too.
4749
4750Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
4751and continue to be present for the foreseeable future, so this is mostly a
4752documentation change.
4753
4754=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4755
4756The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4757mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4758and work, but the library code will of course be larger.
4759
4760=back
4761
4762
4468=head1 GLOSSARY 4763=head1 GLOSSARY
4469 4764
4470=over 4 4765=over 4
4471 4766
4472=item active 4767=item active
4493A change of state of some external event, such as data now being available 4788A change of state of some external event, such as data now being available
4494for reading on a file descriptor, time having passed or simply not having 4789for reading on a file descriptor, time having passed or simply not having
4495any other events happening anymore. 4790any other events happening anymore.
4496 4791
4497In libev, events are represented as single bits (such as C<EV_READ> or 4792In libev, events are represented as single bits (such as C<EV_READ> or
4498C<EV_TIMEOUT>). 4793C<EV_TIMER>).
4499 4794
4500=item event library 4795=item event library
4501 4796
4502A software package implementing an event model and loop. 4797A software package implementing an event model and loop.
4503 4798

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines