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

Comparing libev/ev.3 (file contents):
Revision 1.72 by root, Tue Oct 21 20:06:52 2008 UTC vs.
Revision 1.73 by root, Thu Oct 30 08:09:30 2008 UTC

… …
130.\} 130.\}
131.rm #[ #] #H #V #F C 131.rm #[ #] #H #V #F C
132.\" ======================================================================== 132.\" ========================================================================
133.\" 133.\"
134.IX Title "LIBEV 3" 134.IX Title "LIBEV 3"
135.TH LIBEV 3 "2008-10-21" "libev-3.45" "libev - high performance full featured event loop" 135.TH LIBEV 3 "2008-10-30" "libev-3.48" "libev - high performance full featured event loop"
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes 136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents. 137.\" way too many mistakes in technical documents.
138.if n .ad l 138.if n .ad l
139.nh 139.nh
140.SH "NAME" 140.SH "NAME"
… …
149.Vb 2 149.Vb 2
150\& // a single header file is required 150\& // a single header file is required
151\& #include <ev.h> 151\& #include <ev.h>
152\& 152\&
153\& // every watcher type has its own typedef\*(Aqd struct 153\& // every watcher type has its own typedef\*(Aqd struct
154\& // with the name ev_<type> 154\& // with the name ev_TYPE
155\& ev_io stdin_watcher; 155\& ev_io stdin_watcher;
156\& ev_timer timeout_watcher; 156\& ev_timer timeout_watcher;
157\& 157\&
158\& // all watcher callbacks have a similar signature 158\& // all watcher callbacks have a similar signature
159\& // this callback is called when data is readable on stdin 159\& // this callback is called when data is readable on stdin
160\& static void 160\& static void
161\& stdin_cb (EV_P_ struct ev_io *w, int revents) 161\& stdin_cb (EV_P_ ev_io *w, int revents)
162\& { 162\& {
163\& puts ("stdin ready"); 163\& puts ("stdin ready");
164\& // for one\-shot events, one must manually stop the watcher 164\& // for one\-shot events, one must manually stop the watcher
165\& // with its corresponding stop function. 165\& // with its corresponding stop function.
166\& ev_io_stop (EV_A_ w); 166\& ev_io_stop (EV_A_ w);
… …
169\& ev_unloop (EV_A_ EVUNLOOP_ALL); 169\& ev_unloop (EV_A_ EVUNLOOP_ALL);
170\& } 170\& }
171\& 171\&
172\& // another callback, this time for a time\-out 172\& // another callback, this time for a time\-out
173\& static void 173\& static void
174\& timeout_cb (EV_P_ struct ev_timer *w, int revents) 174\& timeout_cb (EV_P_ ev_timer *w, int revents)
175\& { 175\& {
176\& puts ("timeout"); 176\& puts ("timeout");
177\& // this causes the innermost ev_loop to stop iterating 177\& // this causes the innermost ev_loop to stop iterating
178\& ev_unloop (EV_A_ EVUNLOOP_ONE); 178\& ev_unloop (EV_A_ EVUNLOOP_ONE);
179\& } 179\& }
180\& 180\&
181\& int 181\& int
182\& main (void) 182\& main (void)
183\& { 183\& {
184\& // use the default event loop unless you have special needs 184\& // use the default event loop unless you have special needs
185\& struct ev_loop *loop = ev_default_loop (0); 185\& ev_loop *loop = ev_default_loop (0);
186\& 186\&
187\& // initialise an io watcher, then start it 187\& // initialise an io watcher, then start it
188\& // this one will watch for stdin to become readable 188\& // this one will watch for stdin to become readable
189\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 189\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
190\& ev_io_start (loop, &stdin_watcher); 190\& ev_io_start (loop, &stdin_watcher);
… …
240Libev is very configurable. In this manual the default (and most common) 240Libev is very configurable. In this manual the default (and most common)
241configuration will be described, which supports multiple event loops. For 241configuration will be described, which supports multiple event loops. For
242more info about various configuration options please have a look at 242more info about various configuration options please have a look at
243\&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support 243\&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support
244for multiple event loops, then all functions taking an initial argument of 244for multiple event loops, then all functions taking an initial argument of
245name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have 245name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`ev_loop *\*(C'\fR) will not have
246this argument. 246this argument.
247.Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0" 247.Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0"
248.IX Subsection "TIME REPRESENTATION" 248.IX Subsection "TIME REPRESENTATION"
249Libev represents time as a single floating point number, representing the 249Libev represents time as a single floating point number, representing the
250(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near 250(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near
… …
406\& ... 406\& ...
407\& ev_set_syserr_cb (fatal_error); 407\& ev_set_syserr_cb (fatal_error);
408.Ve 408.Ve
409.SH "FUNCTIONS CONTROLLING THE EVENT LOOP" 409.SH "FUNCTIONS CONTROLLING THE EVENT LOOP"
410.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" 410.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP"
411An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two 411An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR (the \f(CW\*(C`struct\*(C'\fR
412types of such loops, the \fIdefault\fR loop, which supports signals and child 412is \fInot\fR optional in this case, as there is also an \f(CW\*(C`ev_loop\*(C'\fR
413events, and dynamically created loops which do not. 413\&\fIfunction\fR).
414.PP
415The library knows two types of such loops, the \fIdefault\fR loop, which
416supports signals and child events, and dynamically created loops which do
417not.
414.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 418.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4
415.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" 419.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)"
416This will initialise the default event loop if it hasn't been initialised 420This will initialise the default event loop if it hasn't been initialised
417yet and return it. If the default loop could not be initialised, returns 421yet and return it. If the default loop could not be initialised, returns
418false. If it already was initialised it simply returns it (and ignores the 422false. If it already was initialised it simply returns it (and ignores the
… …
421If you don't know what event loop to use, use the one returned from this 425If you don't know what event loop to use, use the one returned from this
422function. 426function.
423.Sp 427.Sp
424Note that this function is \fInot\fR thread-safe, so if you want to use it 428Note that this function is \fInot\fR thread-safe, so if you want to use it
425from multiple threads, you have to lock (note also that this is unlikely, 429from multiple threads, you have to lock (note also that this is unlikely,
426as loops cannot bes hared easily between threads anyway). 430as loops cannot be shared easily between threads anyway).
427.Sp 431.Sp
428The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and 432The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and
429\&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler 433\&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler
430for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your application you can either 434for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your application you can either
431create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you 435create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you
… …
506.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 510.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
507.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 511.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
508For few fds, this backend is a bit little slower than poll and select, 512For few fds, this backend is a bit little slower than poll and select,
509but it scales phenomenally better. While poll and select usually scale 513but it scales phenomenally better. While poll and select usually scale
510like O(total_fds) where n is the total number of fds (or the highest fd), 514like O(total_fds) where n is the total number of fds (or the highest fd),
511epoll scales either O(1) or O(active_fds). The epoll design has a number 515epoll scales either O(1) or O(active_fds).
512of shortcomings, such as silently dropping events in some hard-to-detect 516.Sp
513cases and requiring a system call per fd change, no fork support and bad 517The epoll mechanism deserves honorable mention as the most misdesigned
514support for dup. 518of the more advanced event mechanisms: mere annoyances include silently
519dropping file descriptors, requiring a system call per change per file
520descriptor (and unnecessary guessing of parameters), problems with dup and
521so on. The biggest issue is fork races, however \- if a program forks then
522\&\fIboth\fR parent and child process have to recreate the epoll set, which can
523take considerable time (one syscall per file descriptor) and is of course
524hard to detect.
525.Sp
526Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but
527of course \fIdoesn't\fR, and epoll just loves to report events for totally
528\&\fIdifferent\fR file descriptors (even already closed ones, so one cannot
529even remove them from the set) than registered in the set (especially
530on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by
531employing an additional generation counter and comparing that against the
532events to filter out spurious ones, recreating the set when required.
515.Sp 533.Sp
516While stopping, setting and starting an I/O watcher in the same iteration 534While stopping, setting and starting an I/O watcher in the same iteration
517will result in some caching, there is still a system call per such incident 535will result in some caching, there is still a system call per such
518(because the fd could point to a different file description now), so its 536incident (because the same \fIfile descriptor\fR could point to a different
519best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work 537\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed
520very well if you register events for both fds. 538file descriptors might not work very well if you register events for both
521.Sp 539file descriptors.
522Please note that epoll sometimes generates spurious notifications, so you
523need to use non-blocking I/O or other means to avoid blocking when no data
524(or space) is available.
525.Sp 540.Sp
526Best performance from this backend is achieved by not unregistering all 541Best performance from this backend is achieved by not unregistering all
527watchers for a file descriptor until it has been closed, if possible, 542watchers for a file descriptor until it has been closed, if possible,
528i.e. keep at least one watcher active per fd at all times. Stopping and 543i.e. keep at least one watcher active per fd at all times. Stopping and
529starting a watcher (without re-setting it) also usually doesn't cause 544starting a watcher (without re-setting it) also usually doesn't cause
530extra overhead. 545extra overhead. A fork can both result in spurious notifications as well
546as in libev having to destroy and recreate the epoll object, which can
547take considerable time and thus should be avoided.
531.Sp 548.Sp
532While nominally embeddable in other event loops, this feature is broken in 549While nominally embeddable in other event loops, this feature is broken in
533all kernel versions tested so far. 550all kernel versions tested so far.
534.Sp 551.Sp
535This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 552This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
536\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 553\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
537.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 554.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
538.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 555.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
539.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 556.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
540Kqueue deserves special mention, as at the time of this writing, it was 557Kqueue deserves special mention, as at the time of this writing, it
541broken on all BSDs except NetBSD (usually it doesn't work reliably with 558was broken on all BSDs except NetBSD (usually it doesn't work reliably
542anything but sockets and pipes, except on Darwin, where of course it's 559with anything but sockets and pipes, except on Darwin, where of course
543completely useless). For this reason it's not being \*(L"auto-detected\*(R" unless 560it's completely useless). Unlike epoll, however, whose brokenness
544you explicitly specify it in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or 561is by design, these kqueue bugs can (and eventually will) be fixed
545libev was compiled on a known-to-be-good (\-enough) system like NetBSD. 562without \s-1API\s0 changes to existing programs. For this reason it's not being
563\&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using
564\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough)
565system like NetBSD.
546.Sp 566.Sp
547You still can embed kqueue into a normal poll or select backend and use it 567You still can embed kqueue into a normal poll or select backend and use it
548only for sockets (after having made sure that sockets work with kqueue on 568only for sockets (after having made sure that sockets work with kqueue on
549the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 569the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
550.Sp 570.Sp
551It scales in the same way as the epoll backend, but the interface to the 571It scales in the same way as the epoll backend, but the interface to the
552kernel is more efficient (which says nothing about its actual speed, of 572kernel is more efficient (which says nothing about its actual speed, of
553course). While stopping, setting and starting an I/O watcher does never 573course). While stopping, setting and starting an I/O watcher does never
554cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 574cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
555two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it 575two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but
556drops fds silently in similarly hard-to-detect cases. 576sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
577cases
557.Sp 578.Sp
558This backend usually performs well under most conditions. 579This backend usually performs well under most conditions.
559.Sp 580.Sp
560While nominally embeddable in other event loops, this doesn't work 581While nominally embeddable in other event loops, this doesn't work
561everywhere, so you might need to test for this. And since it is broken 582everywhere, so you might need to test for this. And since it is broken
… …
590might perform better. 611might perform better.
591.Sp 612.Sp
592On the positive side, with the exception of the spurious readiness 613On the positive side, with the exception of the spurious readiness
593notifications, this backend actually performed fully to specification 614notifications, this backend actually performed fully to specification
594in all tests and is fully embeddable, which is a rare feat among the 615in all tests and is fully embeddable, which is a rare feat among the
595OS-specific backends. 616OS-specific backends (I vastly prefer correctness over speed hacks).
596.Sp 617.Sp
597This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 618This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
598\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 619\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
599.ie n .IP """EVBACKEND_ALL""" 4 620.ie n .IP """EVBACKEND_ALL""" 4
600.el .IP "\f(CWEVBACKEND_ALL\fR" 4 621.el .IP "\f(CWEVBACKEND_ALL\fR" 4
… …
660responsibility to either stop all watchers cleanly yourself \fIbefore\fR 681responsibility to either stop all watchers cleanly yourself \fIbefore\fR
661calling this function, or cope with the fact afterwards (which is usually 682calling this function, or cope with the fact afterwards (which is usually
662the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them 683the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them
663for example). 684for example).
664.Sp 685.Sp
665Note that certain global state, such as signal state, will not be freed by 686Note that certain global state, such as signal state (and installed signal
666this function, and related watchers (such as signal and child watchers) 687handlers), will not be freed by this function, and related watchers (such
667would need to be stopped manually. 688as signal and child watchers) would need to be stopped manually.
668.Sp 689.Sp
669In general it is not advisable to call this function except in the 690In general it is not advisable to call this function except in the
670rare occasion where you really need to free e.g. the signal handling 691rare occasion where you really need to free e.g. the signal handling
671pipe fds. If you need dynamically allocated loops it is better to use 692pipe fds. If you need dynamically allocated loops it is better to use
672\&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR). 693\&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR).
… …
757the loop. 778the loop.
758.Sp 779.Sp
759A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if 780A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if
760necessary) and will handle those and any already outstanding ones. It 781necessary) and will handle those and any already outstanding ones. It
761will block your process until at least one new event arrives (which could 782will block your process until at least one new event arrives (which could
762be an event internal to libev itself, so there is no guarentee that a 783be an event internal to libev itself, so there is no guarantee that a
763user-registered callback will be called), and will return after one 784user-registered callback will be called), and will return after one
764iteration of the loop. 785iteration of the loop.
765.Sp 786.Sp
766This is useful if you are waiting for some external event in conjunction 787This is useful if you are waiting for some external event in conjunction
767with something not expressible using other libev watchers (i.e. "roll your 788with something not expressible using other libev watchers (i.e. "roll your
… …
841.Sp 862.Sp
842Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR 863Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR
843running when nothing else is active. 864running when nothing else is active.
844.Sp 865.Sp
845.Vb 4 866.Vb 4
846\& struct ev_signal exitsig; 867\& ev_signal exitsig;
847\& ev_signal_init (&exitsig, sig_cb, SIGINT); 868\& ev_signal_init (&exitsig, sig_cb, SIGINT);
848\& ev_signal_start (loop, &exitsig); 869\& ev_signal_start (loop, &exitsig);
849\& evf_unref (loop); 870\& evf_unref (loop);
850.Ve 871.Ve
851.Sp 872.Sp
… …
902reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure 923reduce iterations/wake\-ups is to use \f(CW\*(C`ev_periodic\*(C'\fR watchers and make sure
903they fire on, say, one-second boundaries only. 924they fire on, say, one-second boundaries only.
904.IP "ev_loop_verify (loop)" 4 925.IP "ev_loop_verify (loop)" 4
905.IX Item "ev_loop_verify (loop)" 926.IX Item "ev_loop_verify (loop)"
906This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been 927This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been
907compiled in. which is the default for non-minimal builds. It tries to go 928compiled in, which is the default for non-minimal builds. It tries to go
908through all internal structures and checks them for validity. If anything 929through all internal structures and checks them for validity. If anything
909is found to be inconsistent, it will print an error message to standard 930is found to be inconsistent, it will print an error message to standard
910error and call \f(CW\*(C`abort ()\*(C'\fR. 931error and call \f(CW\*(C`abort ()\*(C'\fR.
911.Sp 932.Sp
912This can be used to catch bugs inside libev itself: under normal 933This can be used to catch bugs inside libev itself: under normal
913circumstances, this function will never abort as of course libev keeps its 934circumstances, this function will never abort as of course libev keeps its
914data structures consistent. 935data structures consistent.
915.SH "ANATOMY OF A WATCHER" 936.SH "ANATOMY OF A WATCHER"
916.IX Header "ANATOMY OF A WATCHER" 937.IX Header "ANATOMY OF A WATCHER"
938In the following description, uppercase \f(CW\*(C`TYPE\*(C'\fR in names stands for the
939watcher type, e.g. \f(CW\*(C`ev_TYPE_start\*(C'\fR can mean \f(CW\*(C`ev_timer_start\*(C'\fR for timer
940watchers and \f(CW\*(C`ev_io_start\*(C'\fR for I/O watchers.
941.PP
917A watcher is a structure that you create and register to record your 942A watcher is a structure that you create and register to record your
918interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to 943interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to
919become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: 944become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that:
920.PP 945.PP
921.Vb 5 946.Vb 5
922\& static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 947\& static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
923\& { 948\& {
924\& ev_io_stop (w); 949\& ev_io_stop (w);
925\& ev_unloop (loop, EVUNLOOP_ALL); 950\& ev_unloop (loop, EVUNLOOP_ALL);
926\& } 951\& }
927\& 952\&
928\& struct ev_loop *loop = ev_default_loop (0); 953\& struct ev_loop *loop = ev_default_loop (0);
954\&
929\& struct ev_io stdin_watcher; 955\& ev_io stdin_watcher;
956\&
930\& ev_init (&stdin_watcher, my_cb); 957\& ev_init (&stdin_watcher, my_cb);
931\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 958\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
932\& ev_io_start (loop, &stdin_watcher); 959\& ev_io_start (loop, &stdin_watcher);
960\&
933\& ev_loop (loop, 0); 961\& ev_loop (loop, 0);
934.Ve 962.Ve
935.PP 963.PP
936As you can see, you are responsible for allocating the memory for your 964As you can see, you are responsible for allocating the memory for your
937watcher structures (and it is usually a bad idea to do this on the stack, 965watcher structures (and it is \fIusually\fR a bad idea to do this on the
938although this can sometimes be quite valid). 966stack).
967.PP
968Each watcher has an associated watcher structure (called \f(CW\*(C`struct ev_TYPE\*(C'\fR
969or simply \f(CW\*(C`ev_TYPE\*(C'\fR, as typedefs are provided for all watcher structs).
939.PP 970.PP
940Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init 971Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init
941(watcher *, callback)\*(C'\fR, which expects a callback to be provided. This 972(watcher *, callback)\*(C'\fR, which expects a callback to be provided. This
942callback gets invoked each time the event occurs (or, in the case of I/O 973callback gets invoked each time the event occurs (or, in the case of I/O
943watchers, each time the event loop detects that the file descriptor given 974watchers, each time the event loop detects that the file descriptor given
944is readable and/or writable). 975is readable and/or writable).
945.PP 976.PP
946Each watcher type has its own \f(CW\*(C`ev_<type>_set (watcher *, ...)\*(C'\fR macro 977Each watcher type further has its own \f(CW\*(C`ev_TYPE_set (watcher *, ...)\*(C'\fR
947with arguments specific to this watcher type. There is also a macro 978macro to configure it, with arguments specific to the watcher type. There
948to combine initialisation and setting in one call: \f(CW\*(C`ev_<type>_init 979is also a macro to combine initialisation and setting in one call: \f(CW\*(C`ev_TYPE_init (watcher *, callback, ...)\*(C'\fR.
949(watcher *, callback, ...)\*(C'\fR.
950.PP 980.PP
951To make the watcher actually watch out for events, you have to start it 981To make the watcher actually watch out for events, you have to start it
952with a watcher-specific start function (\f(CW\*(C`ev_<type>_start (loop, watcher 982with a watcher-specific start function (\f(CW\*(C`ev_TYPE_start (loop, watcher
953*)\*(C'\fR), and you can stop watching for events at any time by calling the 983*)\*(C'\fR), and you can stop watching for events at any time by calling the
954corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR. 984corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR.
955.PP 985.PP
956As long as your watcher is active (has been started but not stopped) you 986As long as your watcher is active (has been started but not stopped) you
957must not touch the values stored in it. Most specifically you must never 987must not touch the values stored in it. Most specifically you must never
958reinitialise it or call its \f(CW\*(C`set\*(C'\fR macro. 988reinitialise it or call its \f(CW\*(C`ev_TYPE_set\*(C'\fR macro.
959.PP 989.PP
960Each and every callback receives the event loop pointer as first, the 990Each and every callback receives the event loop pointer as first, the
961registered watcher structure as second, and a bitset of received events as 991registered watcher structure as second, and a bitset of received events as
962third argument. 992third argument.
963.PP 993.PP
… …
1030.el .IP "\f(CWEV_ERROR\fR" 4 1060.el .IP "\f(CWEV_ERROR\fR" 4
1031.IX Item "EV_ERROR" 1061.IX Item "EV_ERROR"
1032An unspecified error has occurred, the watcher has been stopped. This might 1062An unspecified error has occurred, the watcher has been stopped. This might
1033happen because the watcher could not be properly started because libev 1063happen because the watcher could not be properly started because libev
1034ran out of memory, a file descriptor was found to be closed or any other 1064ran out of memory, a file descriptor was found to be closed or any other
1065problem. Libev considers these application bugs.
1066.Sp
1035problem. You best act on it by reporting the problem and somehow coping 1067You best act on it by reporting the problem and somehow coping with the
1036with the watcher being stopped. 1068watcher being stopped. Note that well-written programs should not receive
1069an error ever, so when your watcher receives it, this usually indicates a
1070bug in your program.
1037.Sp 1071.Sp
1038Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for 1072Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for
1039example it might indicate that a fd is readable or writable, and if your 1073example it might indicate that a fd is readable or writable, and if your
1040callbacks is well-written it can just attempt the operation and cope with 1074callbacks is well-written it can just attempt the operation and cope with
1041the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded 1075the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded
1042programs, though, as the fd could already be closed and reused for another 1076programs, though, as the fd could already be closed and reused for another
1043thing, so beware. 1077thing, so beware.
1044.Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" 1078.Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0"
1045.IX Subsection "GENERIC WATCHER FUNCTIONS" 1079.IX Subsection "GENERIC WATCHER FUNCTIONS"
1046In the following description, \f(CW\*(C`TYPE\*(C'\fR stands for the watcher type,
1047e.g. \f(CW\*(C`timer\*(C'\fR for \f(CW\*(C`ev_timer\*(C'\fR watchers and \f(CW\*(C`io\*(C'\fR for \f(CW\*(C`ev_io\*(C'\fR watchers.
1048.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1080.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
1049.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 1081.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
1050.IX Item "ev_init (ev_TYPE *watcher, callback)" 1082.IX Item "ev_init (ev_TYPE *watcher, callback)"
1051This macro initialises the generic portion of a watcher. The contents 1083This macro initialises the generic portion of a watcher. The contents
1052of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only 1084of the watcher object can be arbitrary (so \f(CW\*(C`malloc\*(C'\fR will do). Only
… …
1056which rolls both calls into one. 1088which rolls both calls into one.
1057.Sp 1089.Sp
1058You can reinitialise a watcher at any time as long as it has been stopped 1090You can reinitialise a watcher at any time as long as it has been stopped
1059(or never started) and there are no pending events outstanding. 1091(or never started) and there are no pending events outstanding.
1060.Sp 1092.Sp
1061The callback is always of type \f(CW\*(C`void (*)(ev_loop *loop, ev_TYPE *watcher, 1093The callback is always of type \f(CW\*(C`void (*)(struct ev_loop *loop, ev_TYPE *watcher,
1062int revents)\*(C'\fR. 1094int revents)\*(C'\fR.
1063.Sp 1095.Sp
1064Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps. 1096Example: Initialise an \f(CW\*(C`ev_io\*(C'\fR watcher in two steps.
1065.Sp 1097.Sp
1066.Vb 3 1098.Vb 3
… …
1162The default priority used by watchers when no priority has been set is 1194The default priority used by watchers when no priority has been set is
1163always \f(CW0\fR, which is supposed to not be too high and not be too low :). 1195always \f(CW0\fR, which is supposed to not be too high and not be too low :).
1164.Sp 1196.Sp
1165Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is 1197Setting a priority outside the range of \f(CW\*(C`EV_MINPRI\*(C'\fR to \f(CW\*(C`EV_MAXPRI\*(C'\fR is
1166fine, as long as you do not mind that the priority value you query might 1198fine, as long as you do not mind that the priority value you query might
1167or might not have been adjusted to be within valid range. 1199or might not have been clamped to the valid range.
1168.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4 1200.IP "ev_invoke (loop, ev_TYPE *watcher, int revents)" 4
1169.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)" 1201.IX Item "ev_invoke (loop, ev_TYPE *watcher, int revents)"
1170Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither 1202Invoke the \f(CW\*(C`watcher\*(C'\fR with the given \f(CW\*(C`loop\*(C'\fR and \f(CW\*(C`revents\*(C'\fR. Neither
1171\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback 1203\&\f(CW\*(C`loop\*(C'\fR nor \f(CW\*(C`revents\*(C'\fR need to be valid as long as the watcher callback
1172can deal with that fact, as both are simply passed through to the 1204can deal with that fact, as both are simply passed through to the
… …
1189data: 1221data:
1190.PP 1222.PP
1191.Vb 7 1223.Vb 7
1192\& struct my_io 1224\& struct my_io
1193\& { 1225\& {
1194\& struct ev_io io; 1226\& ev_io io;
1195\& int otherfd; 1227\& int otherfd;
1196\& void *somedata; 1228\& void *somedata;
1197\& struct whatever *mostinteresting; 1229\& struct whatever *mostinteresting;
1198\& }; 1230\& };
1199\& 1231\&
… …
1204.PP 1236.PP
1205And since your callback will be called with a pointer to the watcher, you 1237And since your callback will be called with a pointer to the watcher, you
1206can cast it back to your own type: 1238can cast it back to your own type:
1207.PP 1239.PP
1208.Vb 5 1240.Vb 5
1209\& static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) 1241\& static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
1210\& { 1242\& {
1211\& struct my_io *w = (struct my_io *)w_; 1243\& struct my_io *w = (struct my_io *)w_;
1212\& ... 1244\& ...
1213\& } 1245\& }
1214.Ve 1246.Ve
… …
1236.PP 1268.PP
1237.Vb 1 1269.Vb 1
1238\& #include <stddef.h> 1270\& #include <stddef.h>
1239\& 1271\&
1240\& static void 1272\& static void
1241\& t1_cb (EV_P_ struct ev_timer *w, int revents) 1273\& t1_cb (EV_P_ ev_timer *w, int revents)
1242\& { 1274\& {
1243\& struct my_biggy big = (struct my_biggy * 1275\& struct my_biggy big = (struct my_biggy *
1244\& (((char *)w) \- offsetof (struct my_biggy, t1)); 1276\& (((char *)w) \- offsetof (struct my_biggy, t1));
1245\& } 1277\& }
1246\& 1278\&
1247\& static void 1279\& static void
1248\& t2_cb (EV_P_ struct ev_timer *w, int revents) 1280\& t2_cb (EV_P_ ev_timer *w, int revents)
1249\& { 1281\& {
1250\& struct my_biggy big = (struct my_biggy * 1282\& struct my_biggy big = (struct my_biggy *
1251\& (((char *)w) \- offsetof (struct my_biggy, t2)); 1283\& (((char *)w) \- offsetof (struct my_biggy, t2));
1252\& } 1284\& }
1253.Ve 1285.Ve
… …
1387readable, but only once. Since it is likely line-buffered, you could 1419readable, but only once. Since it is likely line-buffered, you could
1388attempt to read a whole line in the callback. 1420attempt to read a whole line in the callback.
1389.PP 1421.PP
1390.Vb 6 1422.Vb 6
1391\& static void 1423\& static void
1392\& stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1424\& stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents)
1393\& { 1425\& {
1394\& ev_io_stop (loop, w); 1426\& ev_io_stop (loop, w);
1395\& .. read from stdin here (or from w\->fd) and handle any I/O errors 1427\& .. read from stdin here (or from w\->fd) and handle any I/O errors
1396\& } 1428\& }
1397\& 1429\&
1398\& ... 1430\& ...
1399\& struct ev_loop *loop = ev_default_init (0); 1431\& struct ev_loop *loop = ev_default_init (0);
1400\& struct ev_io stdin_readable; 1432\& ev_io stdin_readable;
1401\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1433\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1402\& ev_io_start (loop, &stdin_readable); 1434\& ev_io_start (loop, &stdin_readable);
1403\& ev_loop (loop, 0); 1435\& ev_loop (loop, 0);
1404.Ve 1436.Ve
1405.ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts" 1437.ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts"
… …
1415monotonic clock option helps a lot here). 1447monotonic clock option helps a lot here).
1416.PP 1448.PP
1417The callback is guaranteed to be invoked only \fIafter\fR its timeout has 1449The callback is guaranteed to be invoked only \fIafter\fR its timeout has
1418passed, but if multiple timers become ready during the same loop iteration 1450passed, but if multiple timers become ready during the same loop iteration
1419then order of execution is undefined. 1451then order of execution is undefined.
1452.PP
1453\fIBe smart about timeouts\fR
1454.IX Subsection "Be smart about timeouts"
1455.PP
1456Many real-world problems involve some kind of timeout, usually for error
1457recovery. A typical example is an \s-1HTTP\s0 request \- if the other side hangs,
1458you want to raise some error after a while.
1459.PP
1460What follows are some ways to handle this problem, from obvious and
1461inefficient to smart and efficient.
1462.PP
1463In the following, a 60 second activity timeout is assumed \- a timeout that
1464gets reset to 60 seconds each time there is activity (e.g. each time some
1465data or other life sign was received).
1466.IP "1. Use a timer and stop, reinitialise and start it on activity." 4
1467.IX Item "1. Use a timer and stop, reinitialise and start it on activity."
1468This is the most obvious, but not the most simple way: In the beginning,
1469start the watcher:
1470.Sp
1471.Vb 2
1472\& ev_timer_init (timer, callback, 60., 0.);
1473\& ev_timer_start (loop, timer);
1474.Ve
1475.Sp
1476Then, each time there is some activity, \f(CW\*(C`ev_timer_stop\*(C'\fR it, initialise it
1477and start it again:
1478.Sp
1479.Vb 3
1480\& ev_timer_stop (loop, timer);
1481\& ev_timer_set (timer, 60., 0.);
1482\& ev_timer_start (loop, timer);
1483.Ve
1484.Sp
1485This is relatively simple to implement, but means that each time there is
1486some activity, libev will first have to remove the timer from its internal
1487data structure and then add it again. Libev tries to be fast, but it's
1488still not a constant-time operation.
1489.ie n .IP "2. Use a timer and re-start it with ""ev_timer_again"" inactivity." 4
1490.el .IP "2. Use a timer and re-start it with \f(CWev_timer_again\fR inactivity." 4
1491.IX Item "2. Use a timer and re-start it with ev_timer_again inactivity."
1492This is the easiest way, and involves using \f(CW\*(C`ev_timer_again\*(C'\fR instead of
1493\&\f(CW\*(C`ev_timer_start\*(C'\fR.
1494.Sp
1495To implement this, configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value
1496of \f(CW60\fR and then call \f(CW\*(C`ev_timer_again\*(C'\fR at start and each time you
1497successfully read or write some data. If you go into an idle state where
1498you do not expect data to travel on the socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR
1499the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will automatically restart it if need be.
1500.Sp
1501That means you can ignore both the \f(CW\*(C`ev_timer_start\*(C'\fR function and the
1502\&\f(CW\*(C`after\*(C'\fR argument to \f(CW\*(C`ev_timer_set\*(C'\fR, and only ever use the \f(CW\*(C`repeat\*(C'\fR
1503member and \f(CW\*(C`ev_timer_again\*(C'\fR.
1504.Sp
1505At start:
1506.Sp
1507.Vb 3
1508\& ev_timer_init (timer, callback);
1509\& timer\->repeat = 60.;
1510\& ev_timer_again (loop, timer);
1511.Ve
1512.Sp
1513Each time there is some activity:
1514.Sp
1515.Vb 1
1516\& ev_timer_again (loop, timer);
1517.Ve
1518.Sp
1519It is even possible to change the time-out on the fly, regardless of
1520whether the watcher is active or not:
1521.Sp
1522.Vb 2
1523\& timer\->repeat = 30.;
1524\& ev_timer_again (loop, timer);
1525.Ve
1526.Sp
1527This is slightly more efficient then stopping/starting the timer each time
1528you want to modify its timeout value, as libev does not have to completely
1529remove and re-insert the timer from/into its internal data structure.
1530.Sp
1531It is, however, even simpler than the \*(L"obvious\*(R" way to do it.
1532.IP "3. Let the timer time out, but then re-arm it as required." 4
1533.IX Item "3. Let the timer time out, but then re-arm it as required."
1534This method is more tricky, but usually most efficient: Most timeouts are
1535relatively long compared to the intervals between other activity \- in
1536our example, within 60 seconds, there are usually many I/O events with
1537associated activity resets.
1538.Sp
1539In this case, it would be more efficient to leave the \f(CW\*(C`ev_timer\*(C'\fR alone,
1540but remember the time of last activity, and check for a real timeout only
1541within the callback:
1542.Sp
1543.Vb 1
1544\& ev_tstamp last_activity; // time of last activity
1545\&
1546\& static void
1547\& callback (EV_P_ ev_timer *w, int revents)
1548\& {
1549\& ev_tstamp now = ev_now (EV_A);
1550\& ev_tstamp timeout = last_activity + 60.;
1551\&
1552\& // if last_activity + 60. is older than now, we did time out
1553\& if (timeout < now)
1554\& {
1555\& // timeout occured, take action
1556\& }
1557\& else
1558\& {
1559\& // callback was invoked, but there was some activity, re\-arm
1560\& // the watcher to fire in last_activity + 60, which is
1561\& // guaranteed to be in the future, so "again" is positive:
1562\& w\->again = timeout \- now;
1563\& ev_timer_again (EV_A_ w);
1564\& }
1565\& }
1566.Ve
1567.Sp
1568To summarise the callback: first calculate the real timeout (defined
1569as \*(L"60 seconds after the last activity\*(R"), then check if that time has
1570been reached, which means something \fIdid\fR, in fact, time out. Otherwise
1571the callback was invoked too early (\f(CW\*(C`timeout\*(C'\fR is in the future), so
1572re-schedule the timer to fire at that future time, to see if maybe we have
1573a timeout then.
1574.Sp
1575Note how \f(CW\*(C`ev_timer_again\*(C'\fR is used, taking advantage of the
1576\&\f(CW\*(C`ev_timer_again\*(C'\fR optimisation when the timer is already running.
1577.Sp
1578This scheme causes more callback invocations (about one every 60 seconds
1579minus half the average time between activity), but virtually no calls to
1580libev to change the timeout.
1581.Sp
1582To start the timer, simply initialise the watcher and set \f(CW\*(C`last_activity\*(C'\fR
1583to the current time (meaning we just have some activity :), then call the
1584callback, which will \*(L"do the right thing\*(R" and start the timer:
1585.Sp
1586.Vb 3
1587\& ev_timer_init (timer, callback);
1588\& last_activity = ev_now (loop);
1589\& callback (loop, timer, EV_TIMEOUT);
1590.Ve
1591.Sp
1592And when there is some activity, simply store the current time in
1593\&\f(CW\*(C`last_activity\*(C'\fR, no libev calls at all:
1594.Sp
1595.Vb 1
1596\& last_actiivty = ev_now (loop);
1597.Ve
1598.Sp
1599This technique is slightly more complex, but in most cases where the
1600time-out is unlikely to be triggered, much more efficient.
1601.Sp
1602Changing the timeout is trivial as well (if it isn't hard-coded in the
1603callback :) \- just change the timeout and invoke the callback, which will
1604fix things for you.
1605.IP "4. Wee, just use a double-linked list for your timeouts." 4
1606.IX Item "4. Wee, just use a double-linked list for your timeouts."
1607If there is not one request, but many thousands (millions...), all
1608employing some kind of timeout with the same timeout value, then one can
1609do even better:
1610.Sp
1611When starting the timeout, calculate the timeout value and put the timeout
1612at the \fIend\fR of the list.
1613.Sp
1614Then use an \f(CW\*(C`ev_timer\*(C'\fR to fire when the timeout at the \fIbeginning\fR of
1615the list is expected to fire (for example, using the technique #3).
1616.Sp
1617When there is some activity, remove the timer from the list, recalculate
1618the timeout, append it to the end of the list again, and make sure to
1619update the \f(CW\*(C`ev_timer\*(C'\fR if it was taken from the beginning of the list.
1620.Sp
1621This way, one can manage an unlimited number of timeouts in O(1) time for
1622starting, stopping and updating the timers, at the expense of a major
1623complication, and having to use a constant timeout. The constant timeout
1624ensures that the list stays sorted.
1625.PP
1626So which method the best?
1627.PP
1628Method #2 is a simple no-brain-required solution that is adequate in most
1629situations. Method #3 requires a bit more thinking, but handles many cases
1630better, and isn't very complicated either. In most case, choosing either
1631one is fine, with #3 being better in typical situations.
1632.PP
1633Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1634rather complicated, but extremely efficient, something that really pays
1635off after the first million or so of active timers, i.e. it's usually
1636overkill :)
1420.PP 1637.PP
1421\fIThe special problem of time updates\fR 1638\fIThe special problem of time updates\fR
1422.IX Subsection "The special problem of time updates" 1639.IX Subsection "The special problem of time updates"
1423.PP 1640.PP
1424Establishing the current time is a costly operation (it usually takes at 1641Establishing the current time is a costly operation (it usually takes at
… …
1470If the timer is started but non-repeating, stop it (as if it timed out). 1687If the timer is started but non-repeating, stop it (as if it timed out).
1471.Sp 1688.Sp
1472If the timer is repeating, either start it if necessary (with the 1689If the timer is repeating, either start it if necessary (with the
1473\&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value. 1690\&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value.
1474.Sp 1691.Sp
1475This sounds a bit complicated, but here is a useful and typical 1692This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a
1476example: Imagine you have a \s-1TCP\s0 connection and you want a so-called idle 1693usage example.
1477timeout, that is, you want to be called when there have been, say, 60
1478seconds of inactivity on the socket. The easiest way to do this is to
1479configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value of \f(CW60\fR and then call
1480\&\f(CW\*(C`ev_timer_again\*(C'\fR each time you successfully read or write some data. If
1481you go into an idle state where you do not expect data to travel on the
1482socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will
1483automatically restart it if need be.
1484.Sp
1485That means you can ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR
1486altogether and only ever use the \f(CW\*(C`repeat\*(C'\fR value and \f(CW\*(C`ev_timer_again\*(C'\fR:
1487.Sp
1488.Vb 8
1489\& ev_timer_init (timer, callback, 0., 5.);
1490\& ev_timer_again (loop, timer);
1491\& ...
1492\& timer\->again = 17.;
1493\& ev_timer_again (loop, timer);
1494\& ...
1495\& timer\->again = 10.;
1496\& ev_timer_again (loop, timer);
1497.Ve
1498.Sp
1499This is more slightly efficient then stopping/starting the timer each time
1500you want to modify its timeout value.
1501.Sp
1502Note, however, that it is often even more efficient to remember the
1503time of the last activity and let the timer time-out naturally. In the
1504callback, you then check whether the time-out is real, or, if there was
1505some activity, you reschedule the watcher to time-out in \*(L"last_activity +
1506timeout \- ev_now ()\*(R" seconds.
1507.IP "ev_tstamp repeat [read\-write]" 4 1694.IP "ev_tstamp repeat [read\-write]" 4
1508.IX Item "ev_tstamp repeat [read-write]" 1695.IX Item "ev_tstamp repeat [read-write]"
1509The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out 1696The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out
1510or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any), 1697or \f(CW\*(C`ev_timer_again\*(C'\fR is called, and determines the next timeout (if any),
1511which is also when any modifications are taken into account. 1698which is also when any modifications are taken into account.
… …
1515.PP 1702.PP
1516Example: Create a timer that fires after 60 seconds. 1703Example: Create a timer that fires after 60 seconds.
1517.PP 1704.PP
1518.Vb 5 1705.Vb 5
1519\& static void 1706\& static void
1520\& one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1707\& one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents)
1521\& { 1708\& {
1522\& .. one minute over, w is actually stopped right here 1709\& .. one minute over, w is actually stopped right here
1523\& } 1710\& }
1524\& 1711\&
1525\& struct ev_timer mytimer; 1712\& ev_timer mytimer;
1526\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); 1713\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1527\& ev_timer_start (loop, &mytimer); 1714\& ev_timer_start (loop, &mytimer);
1528.Ve 1715.Ve
1529.PP 1716.PP
1530Example: Create a timeout timer that times out after 10 seconds of 1717Example: Create a timeout timer that times out after 10 seconds of
1531inactivity. 1718inactivity.
1532.PP 1719.PP
1533.Vb 5 1720.Vb 5
1534\& static void 1721\& static void
1535\& timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1722\& timeout_cb (struct ev_loop *loop, ev_timer *w, int revents)
1536\& { 1723\& {
1537\& .. ten seconds without any activity 1724\& .. ten seconds without any activity
1538\& } 1725\& }
1539\& 1726\&
1540\& struct ev_timer mytimer; 1727\& ev_timer mytimer;
1541\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 1728\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1542\& ev_timer_again (&mytimer); /* start timer */ 1729\& ev_timer_again (&mytimer); /* start timer */
1543\& ev_loop (loop, 0); 1730\& ev_loop (loop, 0);
1544\& 1731\&
1545\& // and in some piece of code that gets executed on any "activity": 1732\& // and in some piece of code that gets executed on any "activity":
… …
1632.Sp 1819.Sp
1633If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 1820If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
1634it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the 1821it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
1635only event loop modification you are allowed to do). 1822only event loop modification you are allowed to do).
1636.Sp 1823.Sp
1637The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic 1824The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(ev_periodic
1638*w, ev_tstamp now)\*(C'\fR, e.g.: 1825*w, ev_tstamp now)\*(C'\fR, e.g.:
1639.Sp 1826.Sp
1640.Vb 4 1827.Vb 5
1828\& static ev_tstamp
1641\& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1829\& my_rescheduler (ev_periodic *w, ev_tstamp now)
1642\& { 1830\& {
1643\& return now + 60.; 1831\& return now + 60.;
1644\& } 1832\& }
1645.Ve 1833.Ve
1646.Sp 1834.Sp
… …
1680.IP "ev_tstamp interval [read\-write]" 4 1868.IP "ev_tstamp interval [read\-write]" 4
1681.IX Item "ev_tstamp interval [read-write]" 1869.IX Item "ev_tstamp interval [read-write]"
1682The current interval value. Can be modified any time, but changes only 1870The current interval value. Can be modified any time, but changes only
1683take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being 1871take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being
1684called. 1872called.
1685.IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4 1873.IP "ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read\-write]" 4
1686.IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]" 1874.IX Item "ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]"
1687The current reschedule callback, or \f(CW0\fR, if this functionality is 1875The current reschedule callback, or \f(CW0\fR, if this functionality is
1688switched off. Can be changed any time, but changes only take effect when 1876switched off. Can be changed any time, but changes only take effect when
1689the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. 1877the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called.
1690.PP 1878.PP
1691\fIExamples\fR 1879\fIExamples\fR
… …
1695system time is divisible by 3600. The callback invocation times have 1883system time is divisible by 3600. The callback invocation times have
1696potentially a lot of jitter, but good long-term stability. 1884potentially a lot of jitter, but good long-term stability.
1697.PP 1885.PP
1698.Vb 5 1886.Vb 5
1699\& static void 1887\& static void
1700\& clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1888\& clock_cb (struct ev_loop *loop, ev_io *w, int revents)
1701\& { 1889\& {
1702\& ... its now a full hour (UTC, or TAI or whatever your clock follows) 1890\& ... its now a full hour (UTC, or TAI or whatever your clock follows)
1703\& } 1891\& }
1704\& 1892\&
1705\& struct ev_periodic hourly_tick; 1893\& ev_periodic hourly_tick;
1706\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); 1894\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1707\& ev_periodic_start (loop, &hourly_tick); 1895\& ev_periodic_start (loop, &hourly_tick);
1708.Ve 1896.Ve
1709.PP 1897.PP
1710Example: The same as above, but use a reschedule callback to do it: 1898Example: The same as above, but use a reschedule callback to do it:
1711.PP 1899.PP
1712.Vb 1 1900.Vb 1
1713\& #include <math.h> 1901\& #include <math.h>
1714\& 1902\&
1715\& static ev_tstamp 1903\& static ev_tstamp
1716\& my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 1904\& my_scheduler_cb (ev_periodic *w, ev_tstamp now)
1717\& { 1905\& {
1718\& return now + (3600. \- fmod (now, 3600.)); 1906\& return now + (3600. \- fmod (now, 3600.));
1719\& } 1907\& }
1720\& 1908\&
1721\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); 1909\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1722.Ve 1910.Ve
1723.PP 1911.PP
1724Example: Call a callback every hour, starting now: 1912Example: Call a callback every hour, starting now:
1725.PP 1913.PP
1726.Vb 4 1914.Vb 4
1727\& struct ev_periodic hourly_tick; 1915\& ev_periodic hourly_tick;
1728\& ev_periodic_init (&hourly_tick, clock_cb, 1916\& ev_periodic_init (&hourly_tick, clock_cb,
1729\& fmod (ev_now (loop), 3600.), 3600., 0); 1917\& fmod (ev_now (loop), 3600.), 3600., 0);
1730\& ev_periodic_start (loop, &hourly_tick); 1918\& ev_periodic_start (loop, &hourly_tick);
1731.Ve 1919.Ve
1732.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled!" 1920.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled!"
… …
1773.PP 1961.PP
1774Example: Try to exit cleanly on \s-1SIGINT\s0. 1962Example: Try to exit cleanly on \s-1SIGINT\s0.
1775.PP 1963.PP
1776.Vb 5 1964.Vb 5
1777\& static void 1965\& static void
1778\& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1966\& sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
1779\& { 1967\& {
1780\& ev_unloop (loop, EVUNLOOP_ALL); 1968\& ev_unloop (loop, EVUNLOOP_ALL);
1781\& } 1969\& }
1782\& 1970\&
1783\& struct ev_signal signal_watcher; 1971\& ev_signal signal_watcher;
1784\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1972\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1785\& ev_signal_start (loop, &signal_watcher); 1973\& ev_signal_start (loop, &signal_watcher);
1786.Ve 1974.Ve
1787.ie n .Sh """ev_child"" \- watch out for process status changes" 1975.ie n .Sh """ev_child"" \- watch out for process status changes"
1788.el .Sh "\f(CWev_child\fP \- watch out for process status changes" 1976.el .Sh "\f(CWev_child\fP \- watch out for process status changes"
… …
1863.PP 2051.PP
1864.Vb 1 2052.Vb 1
1865\& ev_child cw; 2053\& ev_child cw;
1866\& 2054\&
1867\& static void 2055\& static void
1868\& child_cb (EV_P_ struct ev_child *w, int revents) 2056\& child_cb (EV_P_ ev_child *w, int revents)
1869\& { 2057\& {
1870\& ev_child_stop (EV_A_ w); 2058\& ev_child_stop (EV_A_ w);
1871\& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus); 2059\& printf ("process %d exited with status %x\en", w\->rpid, w\->rstatus);
1872\& } 2060\& }
1873\& 2061\&
… …
1888.Ve 2076.Ve
1889.ie n .Sh """ev_stat"" \- did the file attributes just change?" 2077.ie n .Sh """ev_stat"" \- did the file attributes just change?"
1890.el .Sh "\f(CWev_stat\fP \- did the file attributes just change?" 2078.el .Sh "\f(CWev_stat\fP \- did the file attributes just change?"
1891.IX Subsection "ev_stat - did the file attributes just change?" 2079.IX Subsection "ev_stat - did the file attributes just change?"
1892This watches a file system path for attribute changes. That is, it calls 2080This watches a file system path for attribute changes. That is, it calls
1893\&\f(CW\*(C`stat\*(C'\fR regularly (or when the \s-1OS\s0 says it changed) and sees if it changed 2081\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed)
1894compared to the last time, invoking the callback if it did. 2082and sees if it changed compared to the last time, invoking the callback if
2083it did.
1895.PP 2084.PP
1896The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does 2085The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does
1897not exist\*(R" is a status change like any other. The condition \*(L"path does 2086not exist\*(R" is a status change like any other. The condition \*(L"path does
1898not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is 2087not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is
1899otherwise always forced to be at least one) and all the other fields of 2088otherwise always forced to be at least one) and all the other fields of
1900the stat buffer having unspecified contents. 2089the stat buffer having unspecified contents.
1901.PP 2090.PP
1902The path \fIshould\fR be absolute and \fImust not\fR end in a slash. If it is 2091The path \fImust not\fR end in a slash or contain special components such as
2092\&\f(CW\*(C`.\*(C'\fR or \f(CW\*(C`..\*(C'\fR. The path \fIshould\fR be absolute: If it is relative and
1903relative and your working directory changes, the behaviour is undefined. 2093your working directory changes, then the behaviour is undefined.
1904.PP 2094.PP
1905Since there is no standard kernel interface to do this, the portable 2095Since there is no portable change notification interface available, the
1906implementation simply calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if 2096portable implementation simply calls \f(CWstat(2)\fR regularly on the path
1907it changed somehow. You can specify a recommended polling interval for 2097to see if it changed somehow. You can specify a recommended polling
1908this case. If you specify a polling interval of \f(CW0\fR (highly recommended!) 2098interval for this case. If you specify a polling interval of \f(CW0\fR (highly
1909then a \fIsuitable, unspecified default\fR value will be used (which 2099recommended!) then a \fIsuitable, unspecified default\fR value will be used
1910you can expect to be around five seconds, although this might change 2100(which you can expect to be around five seconds, although this might
1911dynamically). Libev will also impose a minimum interval which is currently 2101change dynamically). Libev will also impose a minimum interval which is
1912around \f(CW0.1\fR, but thats usually overkill. 2102currently around \f(CW0.1\fR, but that's usually overkill.
1913.PP 2103.PP
1914This watcher type is not meant for massive numbers of stat watchers, 2104This watcher type is not meant for massive numbers of stat watchers,
1915as even with OS-supported change notifications, this can be 2105as even with OS-supported change notifications, this can be
1916resource-intensive. 2106resource-intensive.
1917.PP 2107.PP
… …
1928support disabled by default, you get the 32 bit version of the stat 2118support disabled by default, you get the 32 bit version of the stat
1929structure. When using the library from programs that change the \s-1ABI\s0 to 2119structure. When using the library from programs that change the \s-1ABI\s0 to
1930use 64 bit file offsets the programs will fail. In that case you have to 2120use 64 bit file offsets the programs will fail. In that case you have to
1931compile libev with the same flags to get binary compatibility. This is 2121compile libev with the same flags to get binary compatibility. This is
1932obviously the case with any flags that change the \s-1ABI\s0, but the problem is 2122obviously the case with any flags that change the \s-1ABI\s0, but the problem is
1933most noticeably disabled with ev_stat and large file support. 2123most noticeably displayed with ev_stat and large file support.
1934.PP 2124.PP
1935The solution for this is to lobby your distribution maker to make large 2125The solution for this is to lobby your distribution maker to make large
1936file interfaces available by default (as e.g. FreeBSD does) and not 2126file interfaces available by default (as e.g. FreeBSD does) and not
1937optional. Libev cannot simply switch on large file support because it has 2127optional. Libev cannot simply switch on large file support because it has
1938to exchange stat structures with application programs compiled using the 2128to exchange stat structures with application programs compiled using the
… …
1959etc. is difficult. 2149etc. is difficult.
1960.PP 2150.PP
1961\fIThe special problem of stat time resolution\fR 2151\fIThe special problem of stat time resolution\fR
1962.IX Subsection "The special problem of stat time resolution" 2152.IX Subsection "The special problem of stat time resolution"
1963.PP 2153.PP
1964The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably, and 2154The \f(CW\*(C`stat ()\*(C'\fR system call only supports full-second resolution portably,
1965even on systems where the resolution is higher, most file systems still 2155and even on systems where the resolution is higher, most file systems
1966only support whole seconds. 2156still only support whole seconds.
1967.PP 2157.PP
1968That means that, if the time is the only thing that changes, you can 2158That means that, if the time is the only thing that changes, you can
1969easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and 2159easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and
1970calls your callback, which does something. When there is another update 2160calls your callback, which does something. When there is another update
1971within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the 2161within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect unless the
… …
2123Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the 2313Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the
2124callback, free it. Also, use no error checking, as usual. 2314callback, free it. Also, use no error checking, as usual.
2125.PP 2315.PP
2126.Vb 7 2316.Vb 7
2127\& static void 2317\& static void
2128\& idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) 2318\& idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
2129\& { 2319\& {
2130\& free (w); 2320\& free (w);
2131\& // now do something you wanted to do when the program has 2321\& // now do something you wanted to do when the program has
2132\& // no longer anything immediate to do. 2322\& // no longer anything immediate to do.
2133\& } 2323\& }
2134\& 2324\&
2135\& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 2325\& ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2136\& ev_idle_init (idle_watcher, idle_cb); 2326\& ev_idle_init (idle_watcher, idle_cb);
2137\& ev_idle_start (loop, idle_cb); 2327\& ev_idle_start (loop, idle_cb);
2138.Ve 2328.Ve
2139.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!" 2329.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!"
2140.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!" 2330.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!"
… …
2221.Vb 2 2411.Vb 2
2222\& static ev_io iow [nfd]; 2412\& static ev_io iow [nfd];
2223\& static ev_timer tw; 2413\& static ev_timer tw;
2224\& 2414\&
2225\& static void 2415\& static void
2226\& io_cb (ev_loop *loop, ev_io *w, int revents) 2416\& io_cb (struct ev_loop *loop, ev_io *w, int revents)
2227\& { 2417\& {
2228\& } 2418\& }
2229\& 2419\&
2230\& // create io watchers for each fd and a timer before blocking 2420\& // create io watchers for each fd and a timer before blocking
2231\& static void 2421\& static void
2232\& adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 2422\& adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents)
2233\& { 2423\& {
2234\& int timeout = 3600000; 2424\& int timeout = 3600000;
2235\& struct pollfd fds [nfd]; 2425\& struct pollfd fds [nfd];
2236\& // actual code will need to loop here and realloc etc. 2426\& // actual code will need to loop here and realloc etc.
2237\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2427\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
… …
2252\& } 2442\& }
2253\& } 2443\& }
2254\& 2444\&
2255\& // stop all watchers after blocking 2445\& // stop all watchers after blocking
2256\& static void 2446\& static void
2257\& adns_check_cb (ev_loop *loop, ev_check *w, int revents) 2447\& adns_check_cb (struct ev_loop *loop, ev_check *w, int revents)
2258\& { 2448\& {
2259\& ev_timer_stop (loop, &tw); 2449\& ev_timer_stop (loop, &tw);
2260\& 2450\&
2261\& for (int i = 0; i < nfd; ++i) 2451\& for (int i = 0; i < nfd; ++i)
2262\& { 2452\& {
… …
2433used). 2623used).
2434.PP 2624.PP
2435.Vb 3 2625.Vb 3
2436\& struct ev_loop *loop_hi = ev_default_init (0); 2626\& struct ev_loop *loop_hi = ev_default_init (0);
2437\& struct ev_loop *loop_lo = 0; 2627\& struct ev_loop *loop_lo = 0;
2438\& struct ev_embed embed; 2628\& ev_embed embed;
2439\& 2629\&
2440\& // see if there is a chance of getting one that works 2630\& // see if there is a chance of getting one that works
2441\& // (remember that a flags value of 0 means autodetection) 2631\& // (remember that a flags value of 0 means autodetection)
2442\& loop_lo = ev_embeddable_backends () & ev_recommended_backends () 2632\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2443\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 2633\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
… …
2459\&\f(CW\*(C`loop_socket\*(C'\fR. (One might optionally use \f(CW\*(C`EVFLAG_NOENV\*(C'\fR, too). 2649\&\f(CW\*(C`loop_socket\*(C'\fR. (One might optionally use \f(CW\*(C`EVFLAG_NOENV\*(C'\fR, too).
2460.PP 2650.PP
2461.Vb 3 2651.Vb 3
2462\& struct ev_loop *loop = ev_default_init (0); 2652\& struct ev_loop *loop = ev_default_init (0);
2463\& struct ev_loop *loop_socket = 0; 2653\& struct ev_loop *loop_socket = 0;
2464\& struct ev_embed embed; 2654\& ev_embed embed;
2465\& 2655\&
2466\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 2656\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2467\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 2657\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2468\& { 2658\& {
2469\& ev_embed_init (&embed, 0, loop_socket); 2659\& ev_embed_init (&embed, 0, loop_socket);
… …
2601\fIWatcher-Specific Functions and Data Members\fR 2791\fIWatcher-Specific Functions and Data Members\fR
2602.IX Subsection "Watcher-Specific Functions and Data Members" 2792.IX Subsection "Watcher-Specific Functions and Data Members"
2603.IP "ev_async_init (ev_async *, callback)" 4 2793.IP "ev_async_init (ev_async *, callback)" 4
2604.IX Item "ev_async_init (ev_async *, callback)" 2794.IX Item "ev_async_init (ev_async *, callback)"
2605Initialises and configures the async watcher \- it has no parameters of any 2795Initialises and configures the async watcher \- it has no parameters of any
2606kind. There is a \f(CW\*(C`ev_asynd_set\*(C'\fR macro, but using it is utterly pointless, 2796kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless,
2607trust me. 2797trust me.
2608.IP "ev_async_send (loop, ev_async *)" 4 2798.IP "ev_async_send (loop, ev_async *)" 4
2609.IX Item "ev_async_send (loop, ev_async *)" 2799.IX Item "ev_async_send (loop, ev_async *)"
2610Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds 2800Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds
2611an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike 2801an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike
… …
2666\& /* doh, nothing entered */; 2856\& /* doh, nothing entered */;
2667\& } 2857\& }
2668\& 2858\&
2669\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 2859\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2670.Ve 2860.Ve
2671.IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4 2861.IP "ev_feed_event (struct ev_loop *, watcher *, int revents)" 4
2672.IX Item "ev_feed_event (ev_loop *, watcher *, int revents)" 2862.IX Item "ev_feed_event (struct ev_loop *, watcher *, int revents)"
2673Feeds the given event set into the event loop, as if the specified event 2863Feeds the given event set into the event loop, as if the specified event
2674had happened for the specified watcher (which must be a pointer to an 2864had happened for the specified watcher (which must be a pointer to an
2675initialised but not necessarily started event watcher). 2865initialised but not necessarily started event watcher).
2676.IP "ev_feed_fd_event (ev_loop *, int fd, int revents)" 4 2866.IP "ev_feed_fd_event (struct ev_loop *, int fd, int revents)" 4
2677.IX Item "ev_feed_fd_event (ev_loop *, int fd, int revents)" 2867.IX Item "ev_feed_fd_event (struct ev_loop *, int fd, int revents)"
2678Feed an event on the given fd, as if a file descriptor backend detected 2868Feed an event on the given fd, as if a file descriptor backend detected
2679the given events it. 2869the given events it.
2680.IP "ev_feed_signal_event (ev_loop *loop, int signum)" 4 2870.IP "ev_feed_signal_event (struct ev_loop *loop, int signum)" 4
2681.IX Item "ev_feed_signal_event (ev_loop *loop, int signum)" 2871.IX Item "ev_feed_signal_event (struct ev_loop *loop, int signum)"
2682Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default 2872Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default
2683loop!). 2873loop!).
2684.SH "LIBEVENT EMULATION" 2874.SH "LIBEVENT EMULATION"
2685.IX Header "LIBEVENT EMULATION" 2875.IX Header "LIBEVENT EMULATION"
2686Libev offers a compatibility emulation layer for libevent. It cannot 2876Libev offers a compatibility emulation layer for libevent. It cannot
… …
2901<http://rev.rubyforge.org/>. 3091<http://rev.rubyforge.org/>.
2902.IP "D" 4 3092.IP "D" 4
2903.IX Item "D" 3093.IX Item "D"
2904Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to 3094Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to
2905be found at <http://proj.llucax.com.ar/wiki/evd>. 3095be found at <http://proj.llucax.com.ar/wiki/evd>.
3096.IP "Ocaml" 4
3097.IX Item "Ocaml"
3098Erkki Seppala has written Ocaml bindings for libev, to be found at
3099<http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>.
2906.SH "MACRO MAGIC" 3100.SH "MACRO MAGIC"
2907.IX Header "MACRO MAGIC" 3101.IX Header "MACRO MAGIC"
2908Libev can be compiled with a variety of options, the most fundamental 3102Libev can be compiled with a variety of options, the most fundamental
2909of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 3103of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
2910functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 3104functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
… …
3012\& #define EV_STANDALONE 1 3206\& #define EV_STANDALONE 1
3013\& #include "ev.h" 3207\& #include "ev.h"
3014.Ve 3208.Ve
3015.PP 3209.PP
3016Both header files and implementation files can be compiled with a \*(C+ 3210Both header files and implementation files can be compiled with a \*(C+
3017compiler (at least, thats a stated goal, and breakage will be treated 3211compiler (at least, that's a stated goal, and breakage will be treated
3018as a bug). 3212as a bug).
3019.PP 3213.PP
3020You need the following files in your source tree, or in a directory 3214You need the following files in your source tree, or in a directory
3021in your include path (e.g. in libev/ when using \-Ilibev): 3215in your include path (e.g. in libev/ when using \-Ilibev):
3022.PP 3216.PP
… …
3476loop, as long as you don't confuse yourself). The only exception is that 3670loop, as long as you don't confuse yourself). The only exception is that
3477you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. 3671you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
3478.PP 3672.PP
3479Care has been taken to ensure that libev does not keep local state inside 3673Care has been taken to ensure that libev does not keep local state inside
3480\&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow for coroutine switches as 3674\&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow for coroutine switches as
3481they do not clal any callbacks. 3675they do not call any callbacks.
3482.Sh "\s-1COMPILER\s0 \s-1WARNINGS\s0" 3676.Sh "\s-1COMPILER\s0 \s-1WARNINGS\s0"
3483.IX Subsection "COMPILER WARNINGS" 3677.IX Subsection "COMPILER WARNINGS"
3484Depending on your compiler and compiler settings, you might get no or a 3678Depending on your compiler and compiler settings, you might get no or a
3485lot of warnings when compiling libev code. Some people are apparently 3679lot of warnings when compiling libev code. Some people are apparently
3486scared by this. 3680scared by this.
… …
3519\& ==2274== possibly lost: 0 bytes in 0 blocks. 3713\& ==2274== possibly lost: 0 bytes in 0 blocks.
3520\& ==2274== still reachable: 256 bytes in 1 blocks. 3714\& ==2274== still reachable: 256 bytes in 1 blocks.
3521.Ve 3715.Ve
3522.PP 3716.PP
3523Then there is no memory leak, just as memory accounted to global variables 3717Then there is no memory leak, just as memory accounted to global variables
3524is not a memleak \- the memory is still being refernced, and didn't leak. 3718is not a memleak \- the memory is still being referenced, and didn't leak.
3525.PP 3719.PP
3526Similarly, under some circumstances, valgrind might report kernel bugs 3720Similarly, under some circumstances, valgrind might report kernel bugs
3527as if it were a bug in libev (e.g. in realloc or in the poll backend, 3721as if it were a bug in libev (e.g. in realloc or in the poll backend,
3528although an acceptable workaround has been found here), or it might be 3722although an acceptable workaround has been found here), or it might be
3529confused. 3723confused.
… …
3749Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR 3943Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR
3750calls in the current loop iteration. Checking for async and signal events 3944calls in the current loop iteration. Checking for async and signal events
3751involves iterating over all running async watchers or all signal numbers. 3945involves iterating over all running async watchers or all signal numbers.
3752.SH "AUTHOR" 3946.SH "AUTHOR"
3753.IX Header "AUTHOR" 3947.IX Header "AUTHOR"
3754Marc Lehmann <libev@schmorp.de>. 3948Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.

Diff Legend

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