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

Comparing libev/ev.pod (file contents):
Revision 1.254 by root, Tue Jul 14 19:02:43 2009 UTC vs.
Revision 1.292 by sf-exg, Mon Mar 22 09:57:01 2010 UTC

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
344useful to try out specific backends to test their performance, or to work 345useful to try out specific backends to test their performance, or to work
345around bugs. 346around bugs.
346 347
347=item C<EVFLAG_FORKCHECK> 348=item C<EVFLAG_FORKCHECK>
348 349
349Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after 350Instead 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 351make libev check for a fork in each iteration by enabling this flag.
351enabling this flag.
352 352
353This works by calling C<getpid ()> on every iteration of the loop, 353This 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 354and 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 355iterations 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 356GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
362flag. 362flag.
363 363
364This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 364This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
365environment variable. 365environment variable.
366 366
367=item C<EVFLAG_NOINOTIFY>
368
369When 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
371testing, this flag can be useful to conserve inotify file descriptors, as
372otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
373
374=item C<EVFLAG_SIGNALFD>
375
376When 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 API
378delivers signals synchronously, which makes it both faster and might make
379it possible to get the queued signal data. It can also simplify signal
380handling with threads, as long as you properly block signals in your
381threads that are not interested in handling them.
382
383Signalfd will not be used by default as this changes your signal mask, and
384there are a lot of shoddy libraries and programs (glib's threadpool for
385example) that can't properly initialise their signal masks.
386
367=item C<EVBACKEND_SELECT> (value 1, portable select backend) 387=item C<EVBACKEND_SELECT> (value 1, portable select backend)
368 388
369This is your standard select(2) backend. Not I<completely> standard, as 389This is your standard select(2) backend. Not I<completely> standard, as
370libev tries to roll its own fd_set with no limits on the number of fds, 390libev tries to roll its own fd_set with no limits on the number of fds,
371but if that fails, expect a fairly low limit on the number of fds when 391but if that fails, expect a fairly low limit on the number of fds when
394 414
395This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 415This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
396C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 416C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
397 417
398=item C<EVBACKEND_EPOLL> (value 4, Linux) 418=item C<EVBACKEND_EPOLL> (value 4, Linux)
419
420Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
421kernels).
399 422
400For few fds, this backend is a bit little slower than poll and select, 423For few fds, this backend is a bit little slower than poll and select,
401but it scales phenomenally better. While poll and select usually scale 424but it scales phenomenally better. While poll and select usually scale
402like O(total_fds) where n is the total number of fds (or the highest fd), 425like O(total_fds) where n is the total number of fds (or the highest fd),
403epoll scales either O(1) or O(active_fds). 426epoll scales either O(1) or O(active_fds).
518 541
519It is definitely not recommended to use this flag. 542It is definitely not recommended to use this flag.
520 543
521=back 544=back
522 545
523If one or more of these are or'ed into the flags value, then only these 546If one or more of the backend flags are or'ed into the flags value,
524backends will be tried (in the reverse order as listed here). If none are 547then only these backends will be tried (in the reverse order as listed
525specified, all backends in C<ev_recommended_backends ()> will be tried. 548here). If none are specified, all backends in C<ev_recommended_backends
549()> will be tried.
526 550
527Example: This is the most typical usage. 551Example: This is the most typical usage.
528 552
529 if (!ev_default_loop (0)) 553 if (!ev_default_loop (0))
530 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 554 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
542 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 566 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
543 567
544=item struct ev_loop *ev_loop_new (unsigned int flags) 568=item struct ev_loop *ev_loop_new (unsigned int flags)
545 569
546Similar to C<ev_default_loop>, but always creates a new event loop that is 570Similar to C<ev_default_loop>, but always creates a new event loop that is
547always distinct from the default loop. Unlike the default loop, it cannot 571always distinct from the default loop.
548handle signal and child watchers, and attempts to do so will be greeted by
549undefined behaviour (or a failed assertion if assertions are enabled).
550 572
551Note that this function I<is> thread-safe, and the recommended way to use 573Note that this function I<is> thread-safe, and one common way to use
552libev with threads is indeed to create one loop per thread, and using the 574libev with threads is indeed to create one loop per thread, and using the
553default loop in the "main" or "initial" thread. 575default loop in the "main" or "initial" thread.
554 576
555Example: Try to create a event loop that uses epoll and nothing else. 577Example: Try to create a event loop that uses epoll and nothing else.
556 578
558 if (!epoller) 580 if (!epoller)
559 fatal ("no epoll found here, maybe it hides under your chair"); 581 fatal ("no epoll found here, maybe it hides under your chair");
560 582
561=item ev_default_destroy () 583=item ev_default_destroy ()
562 584
563Destroys the default loop again (frees all memory and kernel state 585Destroys the default loop (frees all memory and kernel state etc.). None
564etc.). None of the active event watchers will be stopped in the normal 586of the active event watchers will be stopped in the normal sense, so
565sense, so e.g. C<ev_is_active> might still return true. It is your 587e.g. C<ev_is_active> might still return true. It is your responsibility to
566responsibility to either stop all watchers cleanly yourself I<before> 588either stop all watchers cleanly yourself I<before> calling this function,
567calling this function, or cope with the fact afterwards (which is usually 589or cope with the fact afterwards (which is usually the easiest thing, you
568the easiest thing, you can just ignore the watchers and/or C<free ()> them 590can just ignore the watchers and/or C<free ()> them for example).
569for example).
570 591
571Note that certain global state, such as signal state (and installed signal 592Note that certain global state, such as signal state (and installed signal
572handlers), will not be freed by this function, and related watchers (such 593handlers), will not be freed by this function, and related watchers (such
573as signal and child watchers) would need to be stopped manually. 594as signal and child watchers) would need to be stopped manually.
574 595
575In general it is not advisable to call this function except in the 596In general it is not advisable to call this function except in the
576rare occasion where you really need to free e.g. the signal handling 597rare occasion where you really need to free e.g. the signal handling
577pipe fds. If you need dynamically allocated loops it is better to use 598pipe fds. If you need dynamically allocated loops it is better to use
578C<ev_loop_new> and C<ev_loop_destroy>). 599C<ev_loop_new> and C<ev_loop_destroy>.
579 600
580=item ev_loop_destroy (loop) 601=item ev_loop_destroy (loop)
581 602
582Like C<ev_default_destroy>, but destroys an event loop created by an 603Like C<ev_default_destroy>, but destroys an event loop created by an
583earlier call to C<ev_loop_new>. 604earlier call to C<ev_loop_new>.
589name, you can call it anytime, but it makes most sense after forking, in 610name, you can call it anytime, but it makes most sense after forking, in
590the child process (or both child and parent, but that again makes little 611the child process (or both child and parent, but that again makes little
591sense). You I<must> call it in the child before using any of the libev 612sense). You I<must> call it in the child before using any of the libev
592functions, and it will only take effect at the next C<ev_loop> iteration. 613functions, and it will only take effect at the next C<ev_loop> iteration.
593 614
615Again, you I<have> to call it on I<any> loop that you want to re-use after
616a fork, I<even if you do not plan to use the loop in the parent>. This is
617because some kernel interfaces *cough* I<kqueue> *cough* do funny things
618during fork.
619
594On the other hand, you only need to call this function in the child 620On the other hand, you only need to call this function in the child
595process if and only if you want to use the event library in the child. If 621process if and only if you want to use the event loop in the child. If you
596you just fork+exec, you don't have to call it at all. 622just fork+exec or create a new loop in the child, you don't have to call
623it at all.
597 624
598The function itself is quite fast and it's usually not a problem to call 625The function itself is quite fast and it's usually not a problem to call
599it just in case after a fork. To make this easy, the function will fit in 626it just in case after a fork. To make this easy, the function will fit in
600quite nicely into a call to C<pthread_atfork>: 627quite nicely into a call to C<pthread_atfork>:
601 628
603 630
604=item ev_loop_fork (loop) 631=item ev_loop_fork (loop)
605 632
606Like C<ev_default_fork>, but acts on an event loop created by 633Like C<ev_default_fork>, but acts on an event loop created by
607C<ev_loop_new>. Yes, you have to call this on every allocated event loop 634C<ev_loop_new>. Yes, you have to call this on every allocated event loop
608after fork that you want to re-use in the child, and how you do this is 635after fork that you want to re-use in the child, and how you keep track of
609entirely your own problem. 636them is entirely your own problem.
610 637
611=item int ev_is_default_loop (loop) 638=item int ev_is_default_loop (loop)
612 639
613Returns true when the given loop is, in fact, the default loop, and false 640Returns true when the given loop is, in fact, the default loop, and false
614otherwise. 641otherwise.
615 642
616=item unsigned int ev_loop_count (loop) 643=item unsigned int ev_iteration (loop)
617 644
618Returns the count of loop iterations for the loop, which is identical to 645Returns the current iteration count for the loop, which is identical to
619the number of times libev did poll for new events. It starts at C<0> and 646the number of times libev did poll for new events. It starts at C<0> and
620happily wraps around with enough iterations. 647happily wraps around with enough iterations.
621 648
622This value can sometimes be useful as a generation counter of sorts (it 649This value can sometimes be useful as a generation counter of sorts (it
623"ticks" the number of loop iterations), as it roughly corresponds with 650"ticks" the number of loop iterations), as it roughly corresponds with
624C<ev_prepare> and C<ev_check> calls. 651C<ev_prepare> and C<ev_check> calls - and is incremented between the
652prepare and check phases.
625 653
626=item unsigned int ev_loop_depth (loop) 654=item unsigned int ev_depth (loop)
627 655
628Returns the number of times C<ev_loop> was entered minus the number of 656Returns the number of times C<ev_loop> was entered minus the number of
629times C<ev_loop> was exited, in other words, the recursion depth. 657times C<ev_loop> was exited, in other words, the recursion depth.
630 658
631Outside C<ev_loop>, this number is zero. In a callback, this number is 659Outside C<ev_loop>, this number is zero. In a callback, this number is
632C<1>, unless C<ev_loop> was invoked recursively (or from another thread), 660C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
633in which case it is higher. 661in which case it is higher.
634 662
635Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread 663Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
636etc.), doesn't count as exit. 664etc.), doesn't count as "exit" - consider this as a hint to avoid such
665ungentleman behaviour unless it's really convenient.
637 666
638=item unsigned int ev_backend (loop) 667=item unsigned int ev_backend (loop)
639 668
640Returns one of the C<EVBACKEND_*> flags indicating the event backend in 669Returns one of the C<EVBACKEND_*> flags indicating the event backend in
641use. 670use.
687event loop time (see C<ev_now_update>). 716event loop time (see C<ev_now_update>).
688 717
689=item ev_loop (loop, int flags) 718=item ev_loop (loop, int flags)
690 719
691Finally, this is it, the event handler. This function usually is called 720Finally, this is it, the event handler. This function usually is called
692after you initialised all your watchers and you want to start handling 721after you have initialised all your watchers and you want to start
693events. 722handling events.
694 723
695If the flags argument is specified as C<0>, it will not return until 724If the flags argument is specified as C<0>, it will not return until
696either no event watchers are active anymore or C<ev_unloop> was called. 725either no event watchers are active anymore or C<ev_unloop> was called.
697 726
698Please note that an explicit C<ev_unloop> is usually better than 727Please note that an explicit C<ev_unloop> is usually better than
772 801
773Ref/unref can be used to add or remove a reference count on the event 802Ref/unref can be used to add or remove a reference count on the event
774loop: Every watcher keeps one reference, and as long as the reference 803loop: Every watcher keeps one reference, and as long as the reference
775count is nonzero, C<ev_loop> will not return on its own. 804count is nonzero, C<ev_loop> will not return on its own.
776 805
777If you have a watcher you never unregister that should not keep C<ev_loop> 806This is useful when you have a watcher that you never intend to
778from returning, call ev_unref() after starting, and ev_ref() before 807unregister, but that nevertheless should not keep C<ev_loop> from
808returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
779stopping it. 809before stopping it.
780 810
781As an example, libev itself uses this for its internal signal pipe: It 811As an example, libev itself uses this for its internal signal pipe: It
782is not visible to the libev user and should not keep C<ev_loop> from 812is not visible to the libev user and should not keep C<ev_loop> from
783exiting if no event watchers registered by it are active. It is also an 813exiting if no event watchers registered by it are active. It is also an
784excellent way to do this for generic recurring timers or from within 814excellent way to do this for generic recurring timers or from within
862 892
863This call will simply invoke all pending watchers while resetting their 893This call will simply invoke all pending watchers while resetting their
864pending state. Normally, C<ev_loop> does this automatically when required, 894pending state. Normally, C<ev_loop> does this automatically when required,
865but when overriding the invoke callback this call comes handy. 895but when overriding the invoke callback this call comes handy.
866 896
897=item int ev_pending_count (loop)
898
899Returns the number of pending watchers - zero indicates that no watchers
900are pending.
901
867=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P)) 902=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
868 903
869This overrides the invoke pending functionality of the loop: Instead of 904This overrides the invoke pending functionality of the loop: Instead of
870invoking all pending watchers when there are any, C<ev_loop> will call 905invoking all pending watchers when there are any, C<ev_loop> will call
871this callback instead. This is useful, for example, when you want to 906this callback instead. This is useful, for example, when you want to
894 929
895While event loop modifications are allowed between invocations of 930While event loop modifications are allowed between invocations of
896C<release> and C<acquire> (that's their only purpose after all), no 931C<release> and C<acquire> (that's their only purpose after all), no
897modifications done will affect the event loop, i.e. adding watchers will 932modifications done will affect the event loop, i.e. adding watchers will
898have no effect on the set of file descriptors being watched, or the time 933have no effect on the set of file descriptors being watched, or the time
899waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it 934waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it
900to take note of any changes you made. 935to take note of any changes you made.
901 936
902In theory, threads executing C<ev_loop> will be async-cancel safe between 937In theory, threads executing C<ev_loop> will be async-cancel safe between
903invocations of C<release> and C<acquire>. 938invocations of C<release> and C<acquire>.
904 939
1001=item C<EV_WRITE> 1036=item C<EV_WRITE>
1002 1037
1003The file descriptor in the C<ev_io> watcher has become readable and/or 1038The file descriptor in the C<ev_io> watcher has become readable and/or
1004writable. 1039writable.
1005 1040
1006=item C<EV_TIMEOUT> 1041=item C<EV_TIMER>
1007 1042
1008The C<ev_timer> watcher has timed out. 1043The C<ev_timer> watcher has timed out.
1009 1044
1010=item C<EV_PERIODIC> 1045=item C<EV_PERIODIC>
1011 1046
1101 1136
1102 ev_io w; 1137 ev_io w;
1103 ev_init (&w, my_cb); 1138 ev_init (&w, my_cb);
1104 ev_io_set (&w, STDIN_FILENO, EV_READ); 1139 ev_io_set (&w, STDIN_FILENO, EV_READ);
1105 1140
1106=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1141=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1107 1142
1108This macro initialises the type-specific parts of a watcher. You need to 1143This macro initialises the type-specific parts of a watcher. You need to
1109call C<ev_init> at least once before you call this macro, but you can 1144call C<ev_init> at least once before you call this macro, but you can
1110call C<ev_TYPE_set> any number of times. You must not, however, call this 1145call C<ev_TYPE_set> any number of times. You must not, however, call this
1111macro on a watcher that is active (it can be pending, however, which is a 1146macro on a watcher that is active (it can be pending, however, which is a
1124 1159
1125Example: Initialise and set an C<ev_io> watcher in one step. 1160Example: Initialise and set an C<ev_io> watcher in one step.
1126 1161
1127 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1162 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1128 1163
1129=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1164=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1130 1165
1131Starts (activates) the given watcher. Only active watchers will receive 1166Starts (activates) the given watcher. Only active watchers will receive
1132events. If the watcher is already active nothing will happen. 1167events. If the watcher is already active nothing will happen.
1133 1168
1134Example: Start the C<ev_io> watcher that is being abused as example in this 1169Example: Start the C<ev_io> watcher that is being abused as example in this
1135whole section. 1170whole section.
1136 1171
1137 ev_io_start (EV_DEFAULT_UC, &w); 1172 ev_io_start (EV_DEFAULT_UC, &w);
1138 1173
1139=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1174=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1140 1175
1141Stops the given watcher if active, and clears the pending status (whether 1176Stops the given watcher if active, and clears the pending status (whether
1142the watcher was active or not). 1177the watcher was active or not).
1143 1178
1144It is possible that stopped watchers are pending - for example, 1179It is possible that stopped watchers are pending - for example,
1169=item ev_cb_set (ev_TYPE *watcher, callback) 1204=item ev_cb_set (ev_TYPE *watcher, callback)
1170 1205
1171Change the callback. You can change the callback at virtually any time 1206Change the callback. You can change the callback at virtually any time
1172(modulo threads). 1207(modulo threads).
1173 1208
1174=item ev_set_priority (ev_TYPE *watcher, priority) 1209=item ev_set_priority (ev_TYPE *watcher, int priority)
1175 1210
1176=item int ev_priority (ev_TYPE *watcher) 1211=item int ev_priority (ev_TYPE *watcher)
1177 1212
1178Set and query the priority of the watcher. The priority is a small 1213Set and query the priority of the watcher. The priority is a small
1179integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1214integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1210returns its C<revents> bitset (as if its callback was invoked). If the 1245returns its C<revents> bitset (as if its callback was invoked). If the
1211watcher isn't pending it does nothing and returns C<0>. 1246watcher isn't pending it does nothing and returns C<0>.
1212 1247
1213Sometimes it can be useful to "poll" a watcher instead of waiting for its 1248Sometimes it can be useful to "poll" a watcher instead of waiting for its
1214callback to be invoked, which can be accomplished with this function. 1249callback to be invoked, which can be accomplished with this function.
1250
1251=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1252
1253Feeds the given event set into the event loop, as if the specified event
1254had happened for the specified watcher (which must be a pointer to an
1255initialised but not necessarily started event watcher). Obviously you must
1256not free the watcher as long as it has pending events.
1257
1258Stopping the watcher, letting libev invoke it, or calling
1259C<ev_clear_pending> will clear the pending event, even if the watcher was
1260not started in the first place.
1261
1262See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1263functions that do not need a watcher.
1215 1264
1216=back 1265=back
1217 1266
1218 1267
1219=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1268=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1493 1542
1494So when you encounter spurious, unexplained daemon exits, make sure you 1543So when you encounter spurious, unexplained daemon exits, make sure you
1495ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1544ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1496somewhere, as that would have given you a big clue). 1545somewhere, as that would have given you a big clue).
1497 1546
1547=head3 The special problem of accept()ing when you can't
1548
1549Many implementations of the POSIX C<accept> function (for example,
1550found in post-2004 Linux) have the peculiar behaviour of not removing a
1551connection from the pending queue in all error cases.
1552
1553For example, larger servers often run out of file descriptors (because
1554of resource limits), causing C<accept> to fail with C<ENFILE> but not
1555rejecting the connection, leading to libev signalling readiness on
1556the next iteration again (the connection still exists after all), and
1557typically causing the program to loop at 100% CPU usage.
1558
1559Unfortunately, the set of errors that cause this issue differs between
1560operating systems, there is usually little the app can do to remedy the
1561situation, and no known thread-safe method of removing the connection to
1562cope with overload is known (to me).
1563
1564One of the easiest ways to handle this situation is to just ignore it
1565- when the program encounters an overload, it will just loop until the
1566situation is over. While this is a form of busy waiting, no OS offers an
1567event-based way to handle this situation, so it's the best one can do.
1568
1569A better way to handle the situation is to log any errors other than
1570C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1571messages, and continue as usual, which at least gives the user an idea of
1572what could be wrong ("raise the ulimit!"). For extra points one could stop
1573the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1574usage.
1575
1576If your program is single-threaded, then you could also keep a dummy file
1577descriptor for overload situations (e.g. by opening F</dev/null>), and
1578when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1579close that fd, and create a new dummy fd. This will gracefully refuse
1580clients under typical overload conditions.
1581
1582The last way to handle it is to simply log the error and C<exit>, as
1583is often done with C<malloc> failures, but this results in an easy
1584opportunity for a DoS attack.
1498 1585
1499=head3 Watcher-Specific Functions 1586=head3 Watcher-Specific Functions
1500 1587
1501=over 4 1588=over 4
1502 1589
1681to the current time (meaning we just have some activity :), then call the 1768to the current time (meaning we just have some activity :), then call the
1682callback, which will "do the right thing" and start the timer: 1769callback, which will "do the right thing" and start the timer:
1683 1770
1684 ev_init (timer, callback); 1771 ev_init (timer, callback);
1685 last_activity = ev_now (loop); 1772 last_activity = ev_now (loop);
1686 callback (loop, timer, EV_TIMEOUT); 1773 callback (loop, timer, EV_TIMER);
1687 1774
1688And when there is some activity, simply store the current time in 1775And when there is some activity, simply store the current time in
1689C<last_activity>, no libev calls at all: 1776C<last_activity>, no libev calls at all:
1690 1777
1691 last_actiivty = ev_now (loop); 1778 last_actiivty = ev_now (loop);
1750 1837
1751If the event loop is suspended for a long time, you can also force an 1838If the event loop is suspended for a long time, you can also force an
1752update of the time returned by C<ev_now ()> by calling C<ev_now_update 1839update of the time returned by C<ev_now ()> by calling C<ev_now_update
1753()>. 1840()>.
1754 1841
1842=head3 The special problems of suspended animation
1843
1844When you leave the server world it is quite customary to hit machines that
1845can suspend/hibernate - what happens to the clocks during such a suspend?
1846
1847Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
1848all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
1849to run until the system is suspended, but they will not advance while the
1850system is suspended. That means, on resume, it will be as if the program
1851was frozen for a few seconds, but the suspend time will not be counted
1852towards C<ev_timer> when a monotonic clock source is used. The real time
1853clock advanced as expected, but if it is used as sole clocksource, then a
1854long suspend would be detected as a time jump by libev, and timers would
1855be adjusted accordingly.
1856
1857I would not be surprised to see different behaviour in different between
1858operating systems, OS versions or even different hardware.
1859
1860The other form of suspend (job control, or sending a SIGSTOP) will see a
1861time jump in the monotonic clocks and the realtime clock. If the program
1862is suspended for a very long time, and monotonic clock sources are in use,
1863then you can expect C<ev_timer>s to expire as the full suspension time
1864will be counted towards the timers. When no monotonic clock source is in
1865use, then libev will again assume a timejump and adjust accordingly.
1866
1867It might be beneficial for this latter case to call C<ev_suspend>
1868and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
1869deterministic behaviour in this case (you can do nothing against
1870C<SIGSTOP>).
1871
1755=head3 Watcher-Specific Functions and Data Members 1872=head3 Watcher-Specific Functions and Data Members
1756 1873
1757=over 4 1874=over 4
1758 1875
1759=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1876=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1784If the timer is repeating, either start it if necessary (with the 1901If the timer is repeating, either start it if necessary (with the
1785C<repeat> value), or reset the running timer to the C<repeat> value. 1902C<repeat> value), or reset the running timer to the C<repeat> value.
1786 1903
1787This sounds a bit complicated, see L<Be smart about timeouts>, above, for a 1904This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1788usage example. 1905usage example.
1906
1907=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1908
1909Returns the remaining time until a timer fires. If the timer is active,
1910then this time is relative to the current event loop time, otherwise it's
1911the timeout value currently configured.
1912
1913That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1914C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
1915will return C<4>. When the timer expires and is restarted, it will return
1916roughly C<7> (likely slightly less as callback invocation takes some time,
1917too), and so on.
1789 1918
1790=item ev_tstamp repeat [read-write] 1919=item ev_tstamp repeat [read-write]
1791 1920
1792The current C<repeat> value. Will be used each time the watcher times out 1921The current C<repeat> value. Will be used each time the watcher times out
1793or C<ev_timer_again> is called, and determines the next timeout (if any), 1922or C<ev_timer_again> is called, and determines the next timeout (if any),
2029Signal watchers will trigger an event when the process receives a specific 2158Signal watchers will trigger an event when the process receives a specific
2030signal one or more times. Even though signals are very asynchronous, libev 2159signal one or more times. Even though signals are very asynchronous, libev
2031will try it's best to deliver signals synchronously, i.e. as part of the 2160will try it's best to deliver signals synchronously, i.e. as part of the
2032normal event processing, like any other event. 2161normal event processing, like any other event.
2033 2162
2034If you want signals asynchronously, just use C<sigaction> as you would 2163If you want signals to be delivered truly asynchronously, just use
2035do without libev and forget about sharing the signal. You can even use 2164C<sigaction> as you would do without libev and forget about sharing
2036C<ev_async> from a signal handler to synchronously wake up an event loop. 2165the signal. You can even use C<ev_async> from a signal handler to
2166synchronously wake up an event loop.
2037 2167
2038You can configure as many watchers as you like per signal. Only when the 2168You can configure as many watchers as you like for the same signal, but
2169only within the same loop, i.e. you can watch for C<SIGINT> in your
2170default loop and for C<SIGIO> in another loop, but you cannot watch for
2171C<SIGINT> in both the default loop and another loop at the same time. At
2172the moment, C<SIGCHLD> is permanently tied to the default loop.
2173
2039first watcher gets started will libev actually register a signal handler 2174When the first watcher gets started will libev actually register something
2040with the kernel (thus it coexists with your own signal handlers as long as 2175with the kernel (thus it coexists with your own signal handlers as long as
2041you don't register any with libev for the same signal). Similarly, when 2176you don't register any with libev for the same signal).
2042the last signal watcher for a signal is stopped, libev will reset the
2043signal handler to SIG_DFL (regardless of what it was set to before).
2044 2177
2045If possible and supported, libev will install its handlers with 2178If possible and supported, libev will install its handlers with
2046C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2179C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2047interrupted. If you have a problem with system calls getting interrupted by 2180not be unduly interrupted. If you have a problem with system calls getting
2048signals you can block all signals in an C<ev_check> watcher and unblock 2181interrupted by signals you can block all signals in an C<ev_check> watcher
2049them in an C<ev_prepare> watcher. 2182and unblock them in an C<ev_prepare> watcher.
2183
2184=head3 The special problem of inheritance over fork/execve/pthread_create
2185
2186Both the signal mask (C<sigprocmask>) and the signal disposition
2187(C<sigaction>) are unspecified after starting a signal watcher (and after
2188stopping it again), that is, libev might or might not block the signal,
2189and might or might not set or restore the installed signal handler.
2190
2191While this does not matter for the signal disposition (libev never
2192sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2193C<execve>), this matters for the signal mask: many programs do not expect
2194certain signals to be blocked.
2195
2196This means that before calling C<exec> (from the child) you should reset
2197the signal mask to whatever "default" you expect (all clear is a good
2198choice usually).
2199
2200The simplest way to ensure that the signal mask is reset in the child is
2201to install a fork handler with C<pthread_atfork> that resets it. That will
2202catch fork calls done by libraries (such as the libc) as well.
2203
2204In current versions of libev, the signal will not be blocked indefinitely
2205unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2206the window of opportunity for problems, it will not go away, as libev
2207I<has> to modify the signal mask, at least temporarily.
2208
2209So I can't stress this enough: I<If you do not reset your signal mask when
2210you expect it to be empty, you have a race condition in your code>. This
2211is not a libev-specific thing, this is true for most event libraries.
2050 2212
2051=head3 Watcher-Specific Functions and Data Members 2213=head3 Watcher-Specific Functions and Data Members
2052 2214
2053=over 4 2215=over 4
2054 2216
2099libev) 2261libev)
2100 2262
2101=head3 Process Interaction 2263=head3 Process Interaction
2102 2264
2103Libev grabs C<SIGCHLD> as soon as the default event loop is 2265Libev grabs C<SIGCHLD> as soon as the default event loop is
2104initialised. This is necessary to guarantee proper behaviour even if 2266initialised. This is necessary to guarantee proper behaviour even if the
2105the first child watcher is started after the child exits. The occurrence 2267first child watcher is started after the child exits. The occurrence
2106of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2268of C<SIGCHLD> is recorded asynchronously, but child reaping is done
2107synchronously as part of the event loop processing. Libev always reaps all 2269synchronously as part of the event loop processing. Libev always reaps all
2108children, even ones not watched. 2270children, even ones not watched.
2109 2271
2110=head3 Overriding the Built-In Processing 2272=head3 Overriding the Built-In Processing
2120=head3 Stopping the Child Watcher 2282=head3 Stopping the Child Watcher
2121 2283
2122Currently, the child watcher never gets stopped, even when the 2284Currently, the child watcher never gets stopped, even when the
2123child terminates, so normally one needs to stop the watcher in the 2285child terminates, so normally one needs to stop the watcher in the
2124callback. Future versions of libev might stop the watcher automatically 2286callback. Future versions of libev might stop the watcher automatically
2125when a child exit is detected. 2287when a child exit is detected (calling C<ev_child_stop> twice is not a
2288problem).
2126 2289
2127=head3 Watcher-Specific Functions and Data Members 2290=head3 Watcher-Specific Functions and Data Members
2128 2291
2129=over 4 2292=over 4
2130 2293
2870=head3 Queueing 3033=head3 Queueing
2871 3034
2872C<ev_async> does not support queueing of data in any way. The reason 3035C<ev_async> does not support queueing of data in any way. The reason
2873is that the author does not know of a simple (or any) algorithm for a 3036is that the author does not know of a simple (or any) algorithm for a
2874multiple-writer-single-reader queue that works in all cases and doesn't 3037multiple-writer-single-reader queue that works in all cases and doesn't
2875need elaborate support such as pthreads. 3038need elaborate support such as pthreads or unportable memory access
3039semantics.
2876 3040
2877That means that if you want to queue data, you have to provide your own 3041That means that if you want to queue data, you have to provide your own
2878queue. But at least I can tell you how to implement locking around your 3042queue. But at least I can tell you how to implement locking around your
2879queue: 3043queue:
2880 3044
3019 3183
3020If C<timeout> is less than 0, then no timeout watcher will be 3184If C<timeout> is less than 0, then no timeout watcher will be
3021started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3185started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3022repeat = 0) will be started. C<0> is a valid timeout. 3186repeat = 0) will be started. C<0> is a valid timeout.
3023 3187
3024The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3188The callback has the type C<void (*cb)(int revents, void *arg)> and is
3025passed an C<revents> set like normal event callbacks (a combination of 3189passed an C<revents> set like normal event callbacks (a combination of
3026C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3190C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
3027value passed to C<ev_once>. Note that it is possible to receive I<both> 3191value passed to C<ev_once>. Note that it is possible to receive I<both>
3028a timeout and an io event at the same time - you probably should give io 3192a timeout and an io event at the same time - you probably should give io
3029events precedence. 3193events precedence.
3030 3194
3031Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3195Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3032 3196
3033 static void stdin_ready (int revents, void *arg) 3197 static void stdin_ready (int revents, void *arg)
3034 { 3198 {
3035 if (revents & EV_READ) 3199 if (revents & EV_READ)
3036 /* stdin might have data for us, joy! */; 3200 /* stdin might have data for us, joy! */;
3037 else if (revents & EV_TIMEOUT) 3201 else if (revents & EV_TIMER)
3038 /* doh, nothing entered */; 3202 /* doh, nothing entered */;
3039 } 3203 }
3040 3204
3041 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3205 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3042 3206
3043=item ev_feed_event (struct ev_loop *, watcher *, int revents)
3044
3045Feeds the given event set into the event loop, as if the specified event
3046had happened for the specified watcher (which must be a pointer to an
3047initialised but not necessarily started event watcher).
3048
3049=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3207=item ev_feed_fd_event (loop, int fd, int revents)
3050 3208
3051Feed an event on the given fd, as if a file descriptor backend detected 3209Feed an event on the given fd, as if a file descriptor backend detected
3052the given events it. 3210the given events it.
3053 3211
3054=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3212=item ev_feed_signal_event (loop, int signum)
3055 3213
3056Feed an event as if the given signal occurred (C<loop> must be the default 3214Feed an event as if the given signal occurred (C<loop> must be the default
3057loop!). 3215loop!).
3058 3216
3059=back 3217=back
3139 3297
3140=over 4 3298=over 4
3141 3299
3142=item ev::TYPE::TYPE () 3300=item ev::TYPE::TYPE ()
3143 3301
3144=item ev::TYPE::TYPE (struct ev_loop *) 3302=item ev::TYPE::TYPE (loop)
3145 3303
3146=item ev::TYPE::~TYPE 3304=item ev::TYPE::~TYPE
3147 3305
3148The constructor (optionally) takes an event loop to associate the watcher 3306The constructor (optionally) takes an event loop to associate the watcher
3149with. If it is omitted, it will use C<EV_DEFAULT>. 3307with. If it is omitted, it will use C<EV_DEFAULT>.
3226Example: Use a plain function as callback. 3384Example: Use a plain function as callback.
3227 3385
3228 static void io_cb (ev::io &w, int revents) { } 3386 static void io_cb (ev::io &w, int revents) { }
3229 iow.set <io_cb> (); 3387 iow.set <io_cb> ();
3230 3388
3231=item w->set (struct ev_loop *) 3389=item w->set (loop)
3232 3390
3233Associates 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
3234do this when the watcher is inactive (and not pending either). 3392do this when the watcher is inactive (and not pending either).
3235 3393
3236=item w->set ([arguments]) 3394=item w->set ([arguments])
3333=item Ocaml 3491=item Ocaml
3334 3492
3335Erkki Seppala has written Ocaml bindings for libev, to be found at 3493Erkki Seppala has written Ocaml bindings for libev, to be found at
3336L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3494L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3337 3495
3496=item Lua
3497
3498Brian Maher has written a partial interface to libev for lua (at the
3499time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3500L<http://github.com/brimworks/lua-ev>.
3501
3338=back 3502=back
3339 3503
3340 3504
3341=head1 MACRO MAGIC 3505=head1 MACRO MAGIC
3342 3506
3495 libev.m4 3659 libev.m4
3496 3660
3497=head2 PREPROCESSOR SYMBOLS/MACROS 3661=head2 PREPROCESSOR SYMBOLS/MACROS
3498 3662
3499Libev can be configured via a variety of preprocessor symbols you have to 3663Libev can be configured via a variety of preprocessor symbols you have to
3500define before including any of its files. The default in the absence of 3664define before including (or compiling) any of its files. The default in
3501autoconf is documented for every option. 3665the absence of autoconf is documented for every option.
3666
3667Symbols marked with "(h)" do not change the ABI, and can have different
3668values when compiling libev vs. including F<ev.h>, so it is permissible
3669to redefine them before including F<ev.h> without breaking compatibility
3670to a compiled library. All other symbols change the ABI, which means all
3671users of libev and the libev code itself must be compiled with compatible
3672settings.
3502 3673
3503=over 4 3674=over 4
3504 3675
3505=item EV_STANDALONE 3676=item EV_STANDALONE (h)
3506 3677
3507Must always be C<1> if you do not use autoconf configuration, which 3678Must always be C<1> if you do not use autoconf configuration, which
3508keeps libev from including F<config.h>, and it also defines dummy 3679keeps libev from including F<config.h>, and it also defines dummy
3509implementations for some libevent functions (such as logging, which is not 3680implementations for some libevent functions (such as logging, which is not
3510supported). It will also not define any of the structs usually found in 3681supported). It will also not define any of the structs usually found in
3511F<event.h> that are not directly supported by the libev core alone. 3682F<event.h> that are not directly supported by the libev core alone.
3512 3683
3513In stanbdalone mode, libev will still try to automatically deduce the 3684In standalone mode, libev will still try to automatically deduce the
3514configuration, but has to be more conservative. 3685configuration, but has to be more conservative.
3515 3686
3516=item EV_USE_MONOTONIC 3687=item EV_USE_MONOTONIC
3517 3688
3518If defined to be C<1>, libev will try to detect the availability of the 3689If defined to be C<1>, libev will try to detect the availability of the
3583be used is the winsock select). This means that it will call 3754be used is the winsock select). This means that it will call
3584C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3755C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3585it is assumed that all these functions actually work on fds, even 3756it is assumed that all these functions actually work on fds, even
3586on win32. Should not be defined on non-win32 platforms. 3757on win32. Should not be defined on non-win32 platforms.
3587 3758
3588=item EV_FD_TO_WIN32_HANDLE 3759=item EV_FD_TO_WIN32_HANDLE(fd)
3589 3760
3590If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3761If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3591file descriptors to socket handles. When not defining this symbol (the 3762file descriptors to socket handles. When not defining this symbol (the
3592default), then libev will call C<_get_osfhandle>, which is usually 3763default), then libev will call C<_get_osfhandle>, which is usually
3593correct. In some cases, programs use their own file descriptor management, 3764correct. In some cases, programs use their own file descriptor management,
3594in which case they can provide this function to map fds to socket handles. 3765in which case they can provide this function to map fds to socket handles.
3766
3767=item EV_WIN32_HANDLE_TO_FD(handle)
3768
3769If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3770using the standard C<_open_osfhandle> function. For programs implementing
3771their own fd to handle mapping, overwriting this function makes it easier
3772to do so. This can be done by defining this macro to an appropriate value.
3773
3774=item EV_WIN32_CLOSE_FD(fd)
3775
3776If programs implement their own fd to handle mapping on win32, then this
3777macro can be used to override the C<close> function, useful to unregister
3778file descriptors again. Note that the replacement function has to close
3779the underlying OS handle.
3595 3780
3596=item EV_USE_POLL 3781=item EV_USE_POLL
3597 3782
3598If defined to be C<1>, libev will compile in support for the C<poll>(2) 3783If defined to be C<1>, libev will compile in support for the C<poll>(2)
3599backend. Otherwise it will be enabled on non-win32 platforms. It 3784backend. Otherwise it will be enabled on non-win32 platforms. It
3646as well as for signal and thread safety in C<ev_async> watchers. 3831as well as for signal and thread safety in C<ev_async> watchers.
3647 3832
3648In the absence of this define, libev will use C<sig_atomic_t volatile> 3833In the absence of this define, libev will use C<sig_atomic_t volatile>
3649(from F<signal.h>), which is usually good enough on most platforms. 3834(from F<signal.h>), which is usually good enough on most platforms.
3650 3835
3651=item EV_H 3836=item EV_H (h)
3652 3837
3653The name of the F<ev.h> header file used to include it. The default if 3838The name of the F<ev.h> header file used to include it. The default if
3654undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 3839undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3655used to virtually rename the F<ev.h> header file in case of conflicts. 3840used to virtually rename the F<ev.h> header file in case of conflicts.
3656 3841
3657=item EV_CONFIG_H 3842=item EV_CONFIG_H (h)
3658 3843
3659If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3844If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3660F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3845F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3661C<EV_H>, above. 3846C<EV_H>, above.
3662 3847
3663=item EV_EVENT_H 3848=item EV_EVENT_H (h)
3664 3849
3665Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3850Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3666of how the F<event.h> header can be found, the default is C<"event.h">. 3851of how the F<event.h> header can be found, the default is C<"event.h">.
3667 3852
3668=item EV_PROTOTYPES 3853=item EV_PROTOTYPES (h)
3669 3854
3670If defined to be C<0>, then F<ev.h> will not define any function 3855If defined to be C<0>, then F<ev.h> will not define any function
3671prototypes, but still define all the structs and other symbols. This is 3856prototypes, but still define all the structs and other symbols. This is
3672occasionally useful if you want to provide your own wrapper functions 3857occasionally useful if you want to provide your own wrapper functions
3673around libev functions. 3858around libev functions.
3695fine. 3880fine.
3696 3881
3697If your embedding application does not need any priorities, defining these 3882If your embedding application does not need any priorities, defining these
3698both to C<0> will save some memory and CPU. 3883both to C<0> will save some memory and CPU.
3699 3884
3700=item EV_PERIODIC_ENABLE 3885=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3886EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3887EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3701 3888
3702If undefined or defined to be C<1>, then periodic timers are supported. If 3889If undefined or defined to be C<1> (and the platform supports it), then
3703defined to be C<0>, then they are not. Disabling them saves a few kB of 3890the respective watcher type is supported. If defined to be C<0>, then it
3704code. 3891is not. Disabling watcher types mainly saves codesize.
3705 3892
3706=item EV_IDLE_ENABLE 3893=item EV_FEATURES
3707
3708If undefined or defined to be C<1>, then idle watchers are supported. If
3709defined to be C<0>, then they are not. Disabling them saves a few kB of
3710code.
3711
3712=item EV_EMBED_ENABLE
3713
3714If undefined or defined to be C<1>, then embed watchers are supported. If
3715defined to be C<0>, then they are not. Embed watchers rely on most other
3716watcher types, which therefore must not be disabled.
3717
3718=item EV_STAT_ENABLE
3719
3720If undefined or defined to be C<1>, then stat watchers are supported. If
3721defined to be C<0>, then they are not.
3722
3723=item EV_FORK_ENABLE
3724
3725If undefined or defined to be C<1>, then fork watchers are supported. If
3726defined to be C<0>, then they are not.
3727
3728=item EV_ASYNC_ENABLE
3729
3730If undefined or defined to be C<1>, then async watchers are supported. If
3731defined to be C<0>, then they are not.
3732
3733=item EV_MINIMAL
3734 3894
3735If you need to shave off some kilobytes of code at the expense of some 3895If you need to shave off some kilobytes of code at the expense of some
3736speed (but with the full API), define this symbol to C<1>. Currently this 3896speed (but with the full API), you can define this symbol to request
3737is used to override some inlining decisions, saves roughly 30% code size 3897certain subsets of functionality. The default is to enable all features
3738on amd64. It also selects a much smaller 2-heap for timer management over 3898that can be enabled on the platform.
3739the default 4-heap.
3740 3899
3741You can save even more by disabling watcher types you do not need 3900A typical way to use this symbol is to define it to C<0> (or to a bitset
3742and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 3901with some broad features you want) and then selectively re-enable
3743(C<-DNDEBUG>) will usually reduce code size a lot. 3902additional parts you want, for example if you want everything minimal,
3903but multiple event loop support, async and child watchers and the poll
3904backend, use this:
3744 3905
3745Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 3906 #define EV_FEATURES 0
3746provide a bare-bones event library. See C<ev.h> for details on what parts 3907 #define EV_MULTIPLICITY 1
3747of the API are still available, and do not complain if this subset changes 3908 #define EV_USE_POLL 1
3748over time. 3909 #define EV_CHILD_ENABLE 1
3910 #define EV_ASYNC_ENABLE 1
3911
3912The actual value is a bitset, it can be a combination of the following
3913values:
3914
3915=over 4
3916
3917=item C<1> - faster/larger code
3918
3919Use larger code to speed up some operations.
3920
3921Currently this is used to override some inlining decisions (enlarging the roughly
392230% code size on amd64.
3923
3924When optimising for size, use of compiler flags such as C<-Os> with
3925gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
3926assertions.
3927
3928=item C<2> - faster/larger data structures
3929
3930Replaces the small 2-heap for timer management by a faster 4-heap, larger
3931hash table sizes and so on. This will usually further increase codesize
3932and can additionally have an effect on the size of data structures at
3933runtime.
3934
3935=item C<4> - full API configuration
3936
3937This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3938enables multiplicity (C<EV_MULTIPLICITY>=1).
3939
3940=item C<8> - full API
3941
3942This enables a lot of the "lesser used" API functions. See C<ev.h> for
3943details on which parts of the API are still available without this
3944feature, and do not complain if this subset changes over time.
3945
3946=item C<16> - enable all optional watcher types
3947
3948Enables all optional watcher types. If you want to selectively enable
3949only some watcher types other than I/O and timers (e.g. prepare,
3950embed, async, child...) you can enable them manually by defining
3951C<EV_watchertype_ENABLE> to C<1> instead.
3952
3953=item C<32> - enable all backends
3954
3955This enables all backends - without this feature, you need to enable at
3956least one backend manually (C<EV_USE_SELECT> is a good choice).
3957
3958=item C<64> - enable OS-specific "helper" APIs
3959
3960Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3961default.
3962
3963=back
3964
3965Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
3966reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
3967code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
3968watchers, timers and monotonic clock support.
3969
3970With an intelligent-enough linker (gcc+binutils are intelligent enough
3971when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
3972your program might be left out as well - a binary starting a timer and an
3973I/O watcher then might come out at only 5Kb.
3974
3975=item EV_AVOID_STDIO
3976
3977If this is set to C<1> at compiletime, then libev will avoid using stdio
3978functions (printf, scanf, perror etc.). This will increase the codesize
3979somewhat, but if your program doesn't otherwise depend on stdio and your
3980libc allows it, this avoids linking in the stdio library which is quite
3981big.
3982
3983Note that error messages might become less precise when this option is
3984enabled.
3985
3986=item EV_NSIG
3987
3988The highest supported signal number, +1 (or, the number of
3989signals): Normally, libev tries to deduce the maximum number of signals
3990automatically, but sometimes this fails, in which case it can be
3991specified. Also, using a lower number than detected (C<32> should be
3992good for about any system in existance) can save some memory, as libev
3993statically allocates some 12-24 bytes per signal number.
3749 3994
3750=item EV_PID_HASHSIZE 3995=item EV_PID_HASHSIZE
3751 3996
3752C<ev_child> watchers use a small hash table to distribute workload by 3997C<ev_child> watchers use a small hash table to distribute workload by
3753pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3998pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3754than enough. If you need to manage thousands of children you might want to 3999usually more than enough. If you need to manage thousands of children you
3755increase this value (I<must> be a power of two). 4000might want to increase this value (I<must> be a power of two).
3756 4001
3757=item EV_INOTIFY_HASHSIZE 4002=item EV_INOTIFY_HASHSIZE
3758 4003
3759C<ev_stat> watchers use a small hash table to distribute workload by 4004C<ev_stat> watchers use a small hash table to distribute workload by
3760inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4005inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3761usually more than enough. If you need to manage thousands of C<ev_stat> 4006disabled), usually more than enough. If you need to manage thousands of
3762watchers you might want to increase this value (I<must> be a power of 4007C<ev_stat> watchers you might want to increase this value (I<must> be a
3763two). 4008power of two).
3764 4009
3765=item EV_USE_4HEAP 4010=item EV_USE_4HEAP
3766 4011
3767Heaps are not very cache-efficient. To improve the cache-efficiency of the 4012Heaps are not very cache-efficient. To improve the cache-efficiency of the
3768timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4013timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3769to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4014to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3770faster performance with many (thousands) of watchers. 4015faster performance with many (thousands) of watchers.
3771 4016
3772The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4017The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3773(disabled). 4018will be C<0>.
3774 4019
3775=item EV_HEAP_CACHE_AT 4020=item EV_HEAP_CACHE_AT
3776 4021
3777Heaps are not very cache-efficient. To improve the cache-efficiency of the 4022Heaps are not very cache-efficient. To improve the cache-efficiency of the
3778timer and periodics heaps, libev can cache the timestamp (I<at>) within 4023timer and periodics heaps, libev can cache the timestamp (I<at>) within
3779the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4024the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3780which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4025which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3781but avoids random read accesses on heap changes. This improves performance 4026but avoids random read accesses on heap changes. This improves performance
3782noticeably with many (hundreds) of watchers. 4027noticeably with many (hundreds) of watchers.
3783 4028
3784The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4029The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3785(disabled). 4030will be C<0>.
3786 4031
3787=item EV_VERIFY 4032=item EV_VERIFY
3788 4033
3789Controls how much internal verification (see C<ev_loop_verify ()>) will 4034Controls how much internal verification (see C<ev_loop_verify ()>) will
3790be done: If set to C<0>, no internal verification code will be compiled 4035be done: If set to C<0>, no internal verification code will be compiled
3792called. If set to C<2>, then the internal verification code will be 4037called. If set to C<2>, then the internal verification code will be
3793called once per loop, which can slow down libev. If set to C<3>, then the 4038called once per loop, which can slow down libev. If set to C<3>, then the
3794verification code will be called very frequently, which will slow down 4039verification code will be called very frequently, which will slow down
3795libev considerably. 4040libev considerably.
3796 4041
3797The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4042The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3798C<0>. 4043will be C<0>.
3799 4044
3800=item EV_COMMON 4045=item EV_COMMON
3801 4046
3802By default, all watchers have a C<void *data> member. By redefining 4047By default, all watchers have a C<void *data> member. By redefining
3803this macro to a something else you can include more and other types of 4048this macro to a something else you can include more and other types of
3861file. 4106file.
3862 4107
3863The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4108The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3864that everybody includes and which overrides some configure choices: 4109that everybody includes and which overrides some configure choices:
3865 4110
3866 #define EV_MINIMAL 1 4111 #define EV_FEATURES 8
3867 #define EV_USE_POLL 0 4112 #define EV_USE_SELECT 1
3868 #define EV_MULTIPLICITY 0
3869 #define EV_PERIODIC_ENABLE 0 4113 #define EV_PREPARE_ENABLE 1
4114 #define EV_IDLE_ENABLE 1
3870 #define EV_STAT_ENABLE 0 4115 #define EV_SIGNAL_ENABLE 1
3871 #define EV_FORK_ENABLE 0 4116 #define EV_CHILD_ENABLE 1
4117 #define EV_USE_STDEXCEPT 0
3872 #define EV_CONFIG_H <config.h> 4118 #define EV_CONFIG_H <config.h>
3873 #define EV_MINPRI 0
3874 #define EV_MAXPRI 0
3875 4119
3876 #include "ev++.h" 4120 #include "ev++.h"
3877 4121
3878And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4122And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3879 4123
3998protecting the loop data, respectively. 4242protecting the loop data, respectively.
3999 4243
4000 static void 4244 static void
4001 l_release (EV_P) 4245 l_release (EV_P)
4002 { 4246 {
4003 udat *u = ev_userdata (EV_A); 4247 userdata *u = ev_userdata (EV_A);
4004 pthread_mutex_unlock (&u->lock); 4248 pthread_mutex_unlock (&u->lock);
4005 } 4249 }
4006 4250
4007 static void 4251 static void
4008 l_acquire (EV_P) 4252 l_acquire (EV_P)
4009 { 4253 {
4010 udat *u = ev_userdata (EV_A); 4254 userdata *u = ev_userdata (EV_A);
4011 pthread_mutex_lock (&u->lock); 4255 pthread_mutex_lock (&u->lock);
4012 } 4256 }
4013 4257
4014The event loop thread first acquires the mutex, and then jumps straight 4258The event loop thread first acquires the mutex, and then jumps straight
4015into C<ev_loop>: 4259into C<ev_loop>:
4028 } 4272 }
4029 4273
4030Instead of invoking all pending watchers, the C<l_invoke> callback will 4274Instead of invoking all pending watchers, the C<l_invoke> callback will
4031signal the main thread via some unspecified mechanism (signals? pipe 4275signal the main thread via some unspecified mechanism (signals? pipe
4032writes? C<Async::Interrupt>?) and then waits until all pending watchers 4276writes? C<Async::Interrupt>?) and then waits until all pending watchers
4033have been called: 4277have been called (in a while loop because a) spurious wakeups are possible
4278and b) skipping inter-thread-communication when there are no pending
4279watchers is very beneficial):
4034 4280
4035 static void 4281 static void
4036 l_invoke (EV_P) 4282 l_invoke (EV_P)
4037 { 4283 {
4038 udat *u = ev_userdata (EV_A); 4284 userdata *u = ev_userdata (EV_A);
4039 4285
4286 while (ev_pending_count (EV_A))
4287 {
4040 wake_up_other_thread_in_some_magic_or_not_so_magic_way (); 4288 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4041
4042 pthread_cond_wait (&u->invoke_cv, &u->lock); 4289 pthread_cond_wait (&u->invoke_cv, &u->lock);
4290 }
4043 } 4291 }
4044 4292
4045Now, whenever the main thread gets told to invoke pending watchers, it 4293Now, whenever the main thread gets told to invoke pending watchers, it
4046will grab the lock, call C<ev_invoke_pending> and then signal the loop 4294will grab the lock, call C<ev_invoke_pending> and then signal the loop
4047thread to continue: 4295thread to continue:
4048 4296
4049 static void 4297 static void
4050 real_invoke_pending (EV_P) 4298 real_invoke_pending (EV_P)
4051 { 4299 {
4052 udat *u = ev_userdata (EV_A); 4300 userdata *u = ev_userdata (EV_A);
4053 4301
4054 pthread_mutex_lock (&u->lock); 4302 pthread_mutex_lock (&u->lock);
4055 ev_invoke_pending (EV_A); 4303 ev_invoke_pending (EV_A);
4056 pthread_cond_signal (&u->invoke_cv); 4304 pthread_cond_signal (&u->invoke_cv);
4057 pthread_mutex_unlock (&u->lock); 4305 pthread_mutex_unlock (&u->lock);
4059 4307
4060Whenever you want to start/stop a watcher or do other modifications to an 4308Whenever you want to start/stop a watcher or do other modifications to an
4061event loop, you will now have to lock: 4309event loop, you will now have to lock:
4062 4310
4063 ev_timer timeout_watcher; 4311 ev_timer timeout_watcher;
4064 udat *u = ev_userdata (EV_A); 4312 userdata *u = ev_userdata (EV_A);
4065 4313
4066 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 4314 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4067 4315
4068 pthread_mutex_lock (&u->lock); 4316 pthread_mutex_lock (&u->lock);
4069 ev_timer_start (EV_A_ &timeout_watcher); 4317 ev_timer_start (EV_A_ &timeout_watcher);
4078=head3 COROUTINES 4326=head3 COROUTINES
4079 4327
4080Libev is very accommodating to coroutines ("cooperative threads"): 4328Libev is very accommodating to coroutines ("cooperative threads"):
4081libev fully supports nesting calls to its functions from different 4329libev fully supports nesting calls to its functions from different
4082coroutines (e.g. you can call C<ev_loop> on the same loop from two 4330coroutines (e.g. you can call C<ev_loop> on the same loop from two
4083different coroutines, and switch freely between both coroutines running the 4331different coroutines, and switch freely between both coroutines running
4084loop, as long as you don't confuse yourself). The only exception is that 4332the loop, as long as you don't confuse yourself). The only exception is
4085you must not do this from C<ev_periodic> reschedule callbacks. 4333that you must not do this from C<ev_periodic> reschedule callbacks.
4086 4334
4087Care has been taken to ensure that libev does not keep local state inside 4335Care has been taken to ensure that libev does not keep local state inside
4088C<ev_loop>, and other calls do not usually allow for coroutine switches as 4336C<ev_loop>, and other calls do not usually allow for coroutine switches as
4089they do not call any callbacks. 4337they do not call any callbacks.
4090 4338
4377involves iterating over all running async watchers or all signal numbers. 4625involves iterating over all running async watchers or all signal numbers.
4378 4626
4379=back 4627=back
4380 4628
4381 4629
4630=head1 PORTING FROM LIBEV 3.X TO 4.X
4631
4632The major version 4 introduced some minor incompatible changes to the API.
4633
4634At the moment, the C<ev.h> header file tries to implement superficial
4635compatibility, so most programs should still compile. Those might be
4636removed in later versions of libev, so better update early than late.
4637
4638=over 4
4639
4640=item C<ev_loop_count> renamed to C<ev_iteration>
4641
4642=item C<ev_loop_depth> renamed to C<ev_depth>
4643
4644=item C<ev_loop_verify> renamed to C<ev_verify>
4645
4646Most functions working on C<struct ev_loop> objects don't have an
4647C<ev_loop_> prefix, so it was removed. Note that C<ev_loop_fork> is
4648still called C<ev_loop_fork> because it would otherwise clash with the
4649C<ev_fork> typedef.
4650
4651=item C<EV_TIMEOUT> renamed to C<EV_TIMER> in C<revents>
4652
4653This is a simple rename - all other watcher types use their name
4654as revents flag, and now C<ev_timer> does, too.
4655
4656Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
4657and continue to be present for the forseeable future, so this is mostly a
4658documentation change.
4659
4660=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4661
4662The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4663mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4664and work, but the library code will of course be larger.
4665
4666=back
4667
4668
4382=head1 GLOSSARY 4669=head1 GLOSSARY
4383 4670
4384=over 4 4671=over 4
4385 4672
4386=item active 4673=item active
4407A change of state of some external event, such as data now being available 4694A change of state of some external event, such as data now being available
4408for reading on a file descriptor, time having passed or simply not having 4695for reading on a file descriptor, time having passed or simply not having
4409any other events happening anymore. 4696any other events happening anymore.
4410 4697
4411In libev, events are represented as single bits (such as C<EV_READ> or 4698In libev, events are represented as single bits (such as C<EV_READ> or
4412C<EV_TIMEOUT>). 4699C<EV_TIMER>).
4413 4700
4414=item event library 4701=item event library
4415 4702
4416A software package implementing an event model and loop. 4703A software package implementing an event model and loop.
4417 4704

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines