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

Comparing libev/ev.3 (file contents):
Revision 1.59 by root, Tue Dec 25 07:16:53 2007 UTC vs.
Revision 1.60 by root, Mon Jan 28 12:23:02 2008 UTC

1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.35 1.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sh \" Subsection heading 5.de Sh \" Subsection heading
6.br 6.br
… …
23.ft R 23.ft R
24.fi 24.fi
25.. 25..
26.\" Set up some character translations and predefined strings. \*(-- will 26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left 27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a 28.\" double quote, and \*(R" will give a right double quote. \*(C+ will
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to 29.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' 30.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31.\" expand to `' in nroff, nothing in troff, for use with C<>. 31.\" nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr 32.tr \(*W-
33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34.ie n \{\ 34.ie n \{\
35. ds -- \(*W- 35. ds -- \(*W-
36. ds PI pi 36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch 37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
… …
46. ds PI \(*p 46. ds PI \(*p
47. ds L" `` 47. ds L" ``
48. ds R" '' 48. ds R" ''
49'br\} 49'br\}
50.\" 50.\"
51.\" Escape single quotes in literal strings from groff's Unicode transform.
52.ie \n(.g .ds Aq \(aq
53.el .ds Aq '
54.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for 55.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index 56.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the 57.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion. 58.\" output yourself in some meaningful fashion.
55.if \nF \{\ 59.ie \nF \{\
56. de IX 60. de IX
57. tm Index:\\$1\t\\n%\t"\\$2" 61. tm Index:\\$1\t\\n%\t"\\$2"
58.. 62..
59. nr % 0 63. nr % 0
60. rr F 64. rr F
61.\} 65.\}
62.\" 66.el \{\
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes 67. de IX
64.\" way too many mistakes in technical documents. 68..
65.hy 0 69.\}
66.if n .na
67.\" 70.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 71.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts. 72.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff 73. \" fudge factors for nroff and troff
71.if n \{\ 74.if n \{\
… …
127.\} 130.\}
128.rm #[ #] #H #V #F C 131.rm #[ #] #H #V #F C
129.\" ======================================================================== 132.\" ========================================================================
130.\" 133.\"
131.IX Title "EV 1" 134.IX Title "EV 1"
132.TH EV 1 "2007-12-25" "perl v5.8.8" "User Contributed Perl Documentation" 135.TH EV 1 "2008-01-28" "perl v5.10.0" "User Contributed Perl Documentation"
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents.
138.if n .ad l
139.nh
133.SH "NAME" 140.SH "NAME"
134libev \- a high performance full\-featured event loop written in C 141libev \- a high performance full\-featured event loop written in C
135.SH "SYNOPSIS" 142.SH "SYNOPSIS"
136.IX Header "SYNOPSIS" 143.IX Header "SYNOPSIS"
137.Vb 1 144.Vb 1
… …
139.Ve 146.Ve
140.Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0" 147.Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0"
141.IX Subsection "EXAMPLE PROGRAM" 148.IX Subsection "EXAMPLE PROGRAM"
142.Vb 1 149.Vb 1
143\& #include <ev.h> 150\& #include <ev.h>
144.Ve 151\&
145.PP
146.Vb 2
147\& ev_io stdin_watcher; 152\& ev_io stdin_watcher;
148\& ev_timer timeout_watcher; 153\& ev_timer timeout_watcher;
149.Ve 154\&
150.PP
151.Vb 8
152\& /* called when data readable on stdin */ 155\& /* called when data readable on stdin */
153\& static void 156\& static void
154\& stdin_cb (EV_P_ struct ev_io *w, int revents) 157\& stdin_cb (EV_P_ struct ev_io *w, int revents)
155\& { 158\& {
156\& /* puts ("stdin ready"); */ 159\& /* puts ("stdin ready"); */
157\& ev_io_stop (EV_A_ w); /* just a syntax example */ 160\& ev_io_stop (EV_A_ w); /* just a syntax example */
158\& ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */ 161\& ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
159\& } 162\& }
160.Ve 163\&
161.PP
162.Vb 6
163\& static void 164\& static void
164\& timeout_cb (EV_P_ struct ev_timer *w, int revents) 165\& timeout_cb (EV_P_ struct ev_timer *w, int revents)
165\& { 166\& {
166\& /* puts ("timeout"); */ 167\& /* puts ("timeout"); */
167\& ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */ 168\& ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
168\& } 169\& }
169.Ve 170\&
170.PP
171.Vb 4
172\& int 171\& int
173\& main (void) 172\& main (void)
174\& { 173\& {
175\& struct ev_loop *loop = ev_default_loop (0); 174\& struct ev_loop *loop = ev_default_loop (0);
176.Ve 175\&
177.PP
178.Vb 3
179\& /* initialise an io watcher, then start it */ 176\& /* initialise an io watcher, then start it */
180\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 177\& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
181\& ev_io_start (loop, &stdin_watcher); 178\& ev_io_start (loop, &stdin_watcher);
182.Ve 179\&
183.PP
184.Vb 3
185\& /* simple non-repeating 5.5 second timeout */ 180\& /* simple non\-repeating 5.5 second timeout */
186\& ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); 181\& ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
187\& ev_timer_start (loop, &timeout_watcher); 182\& ev_timer_start (loop, &timeout_watcher);
188.Ve 183\&
189.PP
190.Vb 2
191\& /* loop till timeout or data ready */ 184\& /* loop till timeout or data ready */
192\& ev_loop (loop, 0); 185\& ev_loop (loop, 0);
193.Ve 186\&
194.PP
195.Vb 2
196\& return 0; 187\& return 0;
197\& } 188\& }
198.Ve 189.Ve
199.SH "DESCRIPTION" 190.SH "DESCRIPTION"
200.IX Header "DESCRIPTION" 191.IX Header "DESCRIPTION"
… …
313(assuming you know what you are doing). This is the set of backends that 304(assuming you know what you are doing). This is the set of backends that
314libev will probe for if you specify no backends explicitly. 305libev will probe for if you specify no backends explicitly.
315.IP "unsigned int ev_embeddable_backends ()" 4 306.IP "unsigned int ev_embeddable_backends ()" 4
316.IX Item "unsigned int ev_embeddable_backends ()" 307.IX Item "unsigned int ev_embeddable_backends ()"
317Returns the set of backends that are embeddable in other event loops. This 308Returns the set of backends that are embeddable in other event loops. This
318is the theoretical, all\-platform, value. To find which backends 309is the theoretical, all-platform, value. To find which backends
319might be supported on the current system, you would need to look at 310might be supported on the current system, you would need to look at
320\&\f(CW\*(C`ev_embeddable_backends () & ev_supported_backends ()\*(C'\fR, likewise for 311\&\f(CW\*(C`ev_embeddable_backends () & ev_supported_backends ()\*(C'\fR, likewise for
321recommended ones. 312recommended ones.
322.Sp 313.Sp
323See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 314See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
… …
342\& persistent_realloc (void *ptr, size_t size) 333\& persistent_realloc (void *ptr, size_t size)
343\& { 334\& {
344\& for (;;) 335\& for (;;)
345\& { 336\& {
346\& void *newptr = realloc (ptr, size); 337\& void *newptr = realloc (ptr, size);
347.Ve 338\&
348.Sp
349.Vb 2
350\& if (newptr) 339\& if (newptr)
351\& return newptr; 340\& return newptr;
352.Ve 341\&
353.Sp
354.Vb 3
355\& sleep (60); 342\& sleep (60);
356\& } 343\& }
357\& } 344\& }
358.Ve 345\&
359.Sp
360.Vb 2
361\& ... 346\& ...
362\& ev_set_allocator (persistent_realloc); 347\& ev_set_allocator (persistent_realloc);
363.Ve 348.Ve
364.IP "ev_set_syserr_cb (void (*cb)(const char *msg));" 4 349.IP "ev_set_syserr_cb (void (*cb)(const char *msg));" 4
365.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg));" 350.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg));"
… …
378\& fatal_error (const char *msg) 363\& fatal_error (const char *msg)
379\& { 364\& {
380\& perror (msg); 365\& perror (msg);
381\& abort (); 366\& abort ();
382\& } 367\& }
383.Ve 368\&
384.Sp
385.Vb 2
386\& ... 369\& ...
387\& ev_set_syserr_cb (fatal_error); 370\& ev_set_syserr_cb (fatal_error);
388.Ve 371.Ve
389.SH "FUNCTIONS CONTROLLING THE EVENT LOOP" 372.SH "FUNCTIONS CONTROLLING THE EVENT LOOP"
390.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" 373.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP"
… …
405false. If it already was initialised it simply returns it (and ignores the 388false. If it already was initialised it simply returns it (and ignores the
406flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). 389flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards).
407.Sp 390.Sp
408If you don't know what event loop to use, use the one returned from this 391If you don't know what event loop to use, use the one returned from this
409function. 392function.
393.Sp
394The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and
395\&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler
396for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your app you can either
397create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you
398can simply overwrite the \f(CW\*(C`SIGCHLD\*(C'\fR signal handler \fIafter\fR calling
399\&\f(CW\*(C`ev_default_init\*(C'\fR.
410.Sp 400.Sp
411The flags argument can be used to specify special behaviour or specific 401The flags argument can be used to specify special behaviour or specific
412backends to use, and is usually specified as \f(CW0\fR (or \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). 402backends to use, and is usually specified as \f(CW0\fR (or \f(CW\*(C`EVFLAG_AUTO\*(C'\fR).
413.Sp 403.Sp
414The following flags are supported: 404The following flags are supported:
… …
452.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 442.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
453This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 443This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
454libev tries to roll its own fd_set with no limits on the number of fds, 444libev tries to roll its own fd_set with no limits on the number of fds,
455but if that fails, expect a fairly low limit on the number of fds when 445but if that fails, expect a fairly low limit on the number of fds when
456using this backend. It doesn't scale too well (O(highest_fd)), but its 446using this backend. It doesn't scale too well (O(highest_fd)), but its
457usually the fastest backend for a low number of (low\-numbered :) fds. 447usually the fastest backend for a low number of (low-numbered :) fds.
458.Sp 448.Sp
459To get good performance out of this backend you need a high amount of 449To get good performance out of this backend you need a high amount of
460parallelity (most of the file descriptors should be busy). If you are 450parallelity (most of the file descriptors should be busy). If you are
461writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many 451writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many
462connections as possible during one iteration. You might also want to have 452connections as possible during one iteration. You might also want to have
… …
547.Sp 537.Sp
548While this backend scales well, it requires one system call per active 538While this backend scales well, it requires one system call per active
549file descriptor per loop iteration. For small and medium numbers of file 539file descriptor per loop iteration. For small and medium numbers of file
550descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend 540descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend
551might perform better. 541might perform better.
542.Sp
543On the positive side, ignoring the spurious readyness notifications, this
544backend actually performed to specification in all tests and is fully
545embeddable, which is a rare feat among the OS-specific backends.
552.ie n .IP """EVBACKEND_ALL""" 4 546.ie n .IP """EVBACKEND_ALL""" 4
553.el .IP "\f(CWEVBACKEND_ALL\fR" 4 547.el .IP "\f(CWEVBACKEND_ALL\fR" 4
554.IX Item "EVBACKEND_ALL" 548.IX Item "EVBACKEND_ALL"
555Try all backends (even potentially broken ones that wouldn't be tried 549Try all backends (even potentially broken ones that wouldn't be tried
556with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as 550with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as
… …
559It is definitely not recommended to use this flag. 553It is definitely not recommended to use this flag.
560.RE 554.RE
561.RS 4 555.RS 4
562.Sp 556.Sp
563If one or more of these are ored into the flags value, then only these 557If one or more of these are ored into the flags value, then only these
564backends will be tried (in the reverse order as given here). If none are 558backends will be tried (in the reverse order as listed here). If none are
565specified, most compiled-in backend will be tried, usually in reverse 559specified, all backends in \f(CW\*(C`ev_recommended_backends ()\*(C'\fR will be tried.
566order of their flag values :)
567.Sp 560.Sp
568The most typical usage is like this: 561The most typical usage is like this:
569.Sp 562.Sp
570.Vb 2 563.Vb 2
571\& if (!ev_default_loop (0)) 564\& if (!ev_default_loop (0))
… …
623.IX Item "ev_loop_destroy (loop)" 616.IX Item "ev_loop_destroy (loop)"
624Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an 617Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an
625earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. 618earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR.
626.IP "ev_default_fork ()" 4 619.IP "ev_default_fork ()" 4
627.IX Item "ev_default_fork ()" 620.IX Item "ev_default_fork ()"
621This function sets a flag that causes subsequent \f(CW\*(C`ev_loop\*(C'\fR iterations
628This function reinitialises the kernel state for backends that have 622to reinitialise the kernel state for backends that have one. Despite the
629one. Despite the name, you can call it anytime, but it makes most sense 623name, you can call it anytime, but it makes most sense after forking, in
630after forking, in either the parent or child process (or both, but that 624the child process (or both child and parent, but that again makes little
631again makes little sense). 625sense). You \fImust\fR call it in the child before using any of the libev
626functions, and it will only take effect at the next \f(CW\*(C`ev_loop\*(C'\fR iteration.
632.Sp 627.Sp
633You \fImust\fR call this function in the child process after forking if and 628On the other hand, you only need to call this function in the child
634only if you want to use the event library in both processes. If you just 629process if and only if you want to use the event library in the child. If
635fork+exec, you don't have to call it. 630you just fork+exec, you don't have to call it at all.
636.Sp 631.Sp
637The function itself is quite fast and it's usually not a problem to call 632The function itself is quite fast and it's usually not a problem to call
638it just in case after a fork. To make this easy, the function will fit in 633it just in case after a fork. To make this easy, the function will fit in
639quite nicely into a call to \f(CW\*(C`pthread_atfork\*(C'\fR: 634quite nicely into a call to \f(CW\*(C`pthread_atfork\*(C'\fR:
640.Sp 635.Sp
641.Vb 1 636.Vb 1
642\& pthread_atfork (0, 0, ev_default_fork); 637\& pthread_atfork (0, 0, ev_default_fork);
643.Ve 638.Ve
644.Sp
645At the moment, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and \f(CW\*(C`EVBACKEND_POLL\*(C'\fR are safe to use
646without calling this function, so if you force one of those backends you
647do not need to care.
648.IP "ev_loop_fork (loop)" 4 639.IP "ev_loop_fork (loop)" 4
649.IX Item "ev_loop_fork (loop)" 640.IX Item "ev_loop_fork (loop)"
650Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by 641Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by
651\&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop 642\&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop
652after fork, and how you do this is entirely your own problem. 643after fork, and how you do this is entirely your own problem.
… …
697libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is 688libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is
698usually a better approach for this kind of thing. 689usually a better approach for this kind of thing.
699.Sp 690.Sp
700Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does: 691Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does:
701.Sp 692.Sp
702.Vb 19 693.Vb 10
703\& - Before the first iteration, call any pending watchers. 694\& \- Before the first iteration, call any pending watchers.
704\& * If there are no active watchers (reference count is zero), return. 695\& * If EVFLAG_FORKCHECK was used, check for a fork.
705\& - Queue all prepare watchers and then call all outstanding watchers. 696\& \- If a fork was detected, queue and call all fork watchers.
697\& \- Queue and call all prepare watchers.
706\& - If we have been forked, recreate the kernel state. 698\& \- If we have been forked, recreate the kernel state.
707\& - Update the kernel state with all outstanding changes. 699\& \- Update the kernel state with all outstanding changes.
708\& - Update the "event loop time". 700\& \- Update the "event loop time".
709\& - Calculate for how long to block. 701\& \- Calculate for how long to sleep or block, if at all
702\& (active idle watchers, EVLOOP_NONBLOCK or not having
703\& any active watchers at all will result in not sleeping).
704\& \- Sleep if the I/O and timer collect interval say so.
710\& - Block the process, waiting for any events. 705\& \- Block the process, waiting for any events.
711\& - Queue all outstanding I/O (fd) events. 706\& \- Queue all outstanding I/O (fd) events.
712\& - Update the "event loop time" and do time jump handling. 707\& \- Update the "event loop time" and do time jump handling.
713\& - Queue all outstanding timers. 708\& \- Queue all outstanding timers.
714\& - Queue all outstanding periodics. 709\& \- Queue all outstanding periodics.
715\& - If no events are pending now, queue all idle watchers. 710\& \- If no events are pending now, queue all idle watchers.
716\& - Queue all check watchers. 711\& \- Queue all check watchers.
717\& - Call all queued watchers in reverse order (i.e. check watchers first). 712\& \- Call all queued watchers in reverse order (i.e. check watchers first).
718\& Signals and child watchers are implemented as I/O watchers, and will 713\& Signals and child watchers are implemented as I/O watchers, and will
719\& be handled here by queueing them when their watcher gets executed. 714\& be handled here by queueing them when their watcher gets executed.
720\& - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 715\& \- If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
721\& were used, return, otherwise continue with step *. 716\& were used, or there are no active watchers, return, otherwise
717\& continue with step *.
722.Ve 718.Ve
723.Sp 719.Sp
724Example: Queue some jobs and then loop until no events are outsanding 720Example: Queue some jobs and then loop until no events are outstanding
725anymore. 721anymore.
726.Sp 722.Sp
727.Vb 4 723.Vb 4
728\& ... queue jobs here, make sure they register event watchers as long 724\& ... queue jobs here, make sure they register event watchers as long
729\& ... as they still have work to do (even an idle watcher will do..) 725\& ... as they still have work to do (even an idle watcher will do..)
… …
734.IX Item "ev_unloop (loop, how)" 730.IX Item "ev_unloop (loop, how)"
735Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it 731Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it
736has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either 732has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either
737\&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or 733\&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or
738\&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return. 734\&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return.
735.Sp
736This \*(L"unloop state\*(R" will be cleared when entering \f(CW\*(C`ev_loop\*(C'\fR again.
739.IP "ev_ref (loop)" 4 737.IP "ev_ref (loop)" 4
740.IX Item "ev_ref (loop)" 738.IX Item "ev_ref (loop)"
741.PD 0 739.PD 0
742.IP "ev_unref (loop)" 4 740.IP "ev_unref (loop)" 4
743.IX Item "ev_unref (loop)" 741.IX Item "ev_unref (loop)"
… …
749returning, \fIev_unref()\fR after starting, and \fIev_ref()\fR before stopping it. For 747returning, \fIev_unref()\fR after starting, and \fIev_ref()\fR before stopping it. For
750example, libev itself uses this for its internal signal pipe: It is not 748example, libev itself uses this for its internal signal pipe: It is not
751visible to the libev user and should not keep \f(CW\*(C`ev_loop\*(C'\fR from exiting if 749visible to the libev user and should not keep \f(CW\*(C`ev_loop\*(C'\fR from exiting if
752no event watchers registered by it are active. It is also an excellent 750no event watchers registered by it are active. It is also an excellent
753way to do this for generic recurring timers or from within third-party 751way to do this for generic recurring timers or from within third-party
754libraries. Just remember to \fIunref after start\fR and \fIref before stop\fR. 752libraries. Just remember to \fIunref after start\fR and \fIref before stop\fR
753(but only if the watcher wasn't active before, or was active before,
754respectively).
755.Sp 755.Sp
756Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR 756Example: Create a signal watcher, but keep it from keeping \f(CW\*(C`ev_loop\*(C'\fR
757running when nothing else is active. 757running when nothing else is active.
758.Sp 758.Sp
759.Vb 4 759.Vb 4
… …
816\& static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 816\& static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
817\& { 817\& {
818\& ev_io_stop (w); 818\& ev_io_stop (w);
819\& ev_unloop (loop, EVUNLOOP_ALL); 819\& ev_unloop (loop, EVUNLOOP_ALL);
820\& } 820\& }
821.Ve 821\&
822.PP
823.Vb 6
824\& struct ev_loop *loop = ev_default_loop (0); 822\& struct ev_loop *loop = ev_default_loop (0);
825\& struct ev_io stdin_watcher; 823\& struct ev_io stdin_watcher;
826\& ev_init (&stdin_watcher, my_cb); 824\& ev_init (&stdin_watcher, my_cb);
827\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 825\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
828\& ev_io_start (loop, &stdin_watcher); 826\& ev_io_start (loop, &stdin_watcher);
… …
1089In this case getting the pointer to \f(CW\*(C`my_biggy\*(C'\fR is a bit more complicated, 1087In this case getting the pointer to \f(CW\*(C`my_biggy\*(C'\fR is a bit more complicated,
1090you need to use \f(CW\*(C`offsetof\*(C'\fR: 1088you need to use \f(CW\*(C`offsetof\*(C'\fR:
1091.PP 1089.PP
1092.Vb 1 1090.Vb 1
1093\& #include <stddef.h> 1091\& #include <stddef.h>
1094.Ve 1092\&
1095.PP
1096.Vb 6
1097\& static void 1093\& static void
1098\& t1_cb (EV_P_ struct ev_timer *w, int revents) 1094\& t1_cb (EV_P_ struct ev_timer *w, int revents)
1099\& { 1095\& {
1100\& struct my_biggy big = (struct my_biggy * 1096\& struct my_biggy big = (struct my_biggy *
1101\& (((char *)w) - offsetof (struct my_biggy, t1)); 1097\& (((char *)w) \- offsetof (struct my_biggy, t1));
1102\& } 1098\& }
1103.Ve 1099\&
1104.PP
1105.Vb 6
1106\& static void 1100\& static void
1107\& t2_cb (EV_P_ struct ev_timer *w, int revents) 1101\& t2_cb (EV_P_ struct ev_timer *w, int revents)
1108\& { 1102\& {
1109\& struct my_biggy big = (struct my_biggy * 1103\& struct my_biggy big = (struct my_biggy *
1110\& (((char *)w) - offsetof (struct my_biggy, t2)); 1104\& (((char *)w) \- offsetof (struct my_biggy, t2));
1111\& } 1105\& }
1112.Ve 1106.Ve
1113.SH "WATCHER TYPES" 1107.SH "WATCHER TYPES"
1114.IX Header "WATCHER TYPES" 1108.IX Header "WATCHER TYPES"
1115This section describes each watcher in detail, but will not repeat 1109This section describes each watcher in detail, but will not repeat
… …
1221The file descriptor being watched. 1215The file descriptor being watched.
1222.IP "int events [read\-only]" 4 1216.IP "int events [read\-only]" 4
1223.IX Item "int events [read-only]" 1217.IX Item "int events [read-only]"
1224The events being watched. 1218The events being watched.
1225.PP 1219.PP
1220\fIExamples\fR
1221.IX Subsection "Examples"
1222.PP
1226Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well 1223Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well
1227readable, but only once. Since it is likely line\-buffered, you could 1224readable, but only once. Since it is likely line-buffered, you could
1228attempt to read a whole line in the callback. 1225attempt to read a whole line in the callback.
1229.PP 1226.PP
1230.Vb 6 1227.Vb 6
1231\& static void 1228\& static void
1232\& stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1229\& stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1233\& { 1230\& {
1234\& ev_io_stop (loop, w); 1231\& ev_io_stop (loop, w);
1235\& .. read from stdin here (or from w->fd) and haqndle any I/O errors 1232\& .. read from stdin here (or from w\->fd) and haqndle any I/O errors
1236\& } 1233\& }
1237.Ve 1234\&
1238.PP
1239.Vb 6
1240\& ... 1235\& ...
1241\& struct ev_loop *loop = ev_default_init (0); 1236\& struct ev_loop *loop = ev_default_init (0);
1242\& struct ev_io stdin_readable; 1237\& struct ev_io stdin_readable;
1243\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1238\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1244\& ev_io_start (loop, &stdin_readable); 1239\& ev_io_start (loop, &stdin_readable);
… …
1261of the event triggering whatever timeout you are modifying/starting. If 1256of the event triggering whatever timeout you are modifying/starting. If
1262you suspect event processing to be delayed and you \fIneed\fR to base the timeout 1257you suspect event processing to be delayed and you \fIneed\fR to base the timeout
1263on the current time, use something like this to adjust for this: 1258on the current time, use something like this to adjust for this:
1264.PP 1259.PP
1265.Vb 1 1260.Vb 1
1266\& ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1261\& ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.);
1267.Ve 1262.Ve
1268.PP 1263.PP
1269The callback is guarenteed to be invoked only when its timeout has passed, 1264The callback is guarenteed to be invoked only when its timeout has passed,
1270but if multiple timers become ready during the same loop iteration then 1265but if multiple timers become ready during the same loop iteration then
1271order of execution is undefined. 1266order of execution is undefined.
… …
1315.Sp 1310.Sp
1316.Vb 8 1311.Vb 8
1317\& ev_timer_init (timer, callback, 0., 5.); 1312\& ev_timer_init (timer, callback, 0., 5.);
1318\& ev_timer_again (loop, timer); 1313\& ev_timer_again (loop, timer);
1319\& ... 1314\& ...
1320\& timer->again = 17.; 1315\& timer\->again = 17.;
1321\& ev_timer_again (loop, timer); 1316\& ev_timer_again (loop, timer);
1322\& ... 1317\& ...
1323\& timer->again = 10.; 1318\& timer\->again = 10.;
1324\& ev_timer_again (loop, timer); 1319\& ev_timer_again (loop, timer);
1325.Ve 1320.Ve
1326.Sp 1321.Sp
1327This is more slightly efficient then stopping/starting the timer each time 1322This is more slightly efficient then stopping/starting the timer each time
1328you want to modify its timeout value. 1323you want to modify its timeout value.
… …
1330.IX Item "ev_tstamp repeat [read-write]" 1325.IX Item "ev_tstamp repeat [read-write]"
1331The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out 1326The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out
1332or \f(CW\*(C`ev_timer_again\*(C'\fR is called and determines the next timeout (if any), 1327or \f(CW\*(C`ev_timer_again\*(C'\fR is called and determines the next timeout (if any),
1333which is also when any modifications are taken into account. 1328which is also when any modifications are taken into account.
1334.PP 1329.PP
1330\fIExamples\fR
1331.IX Subsection "Examples"
1332.PP
1335Example: Create a timer that fires after 60 seconds. 1333Example: Create a timer that fires after 60 seconds.
1336.PP 1334.PP
1337.Vb 5 1335.Vb 5
1338\& static void 1336\& static void
1339\& one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1337\& one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
1340\& { 1338\& {
1341\& .. one minute over, w is actually stopped right here 1339\& .. one minute over, w is actually stopped right here
1342\& } 1340\& }
1343.Ve 1341\&
1344.PP
1345.Vb 3
1346\& struct ev_timer mytimer; 1342\& struct ev_timer mytimer;
1347\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.); 1343\& ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1348\& ev_timer_start (loop, &mytimer); 1344\& ev_timer_start (loop, &mytimer);
1349.Ve 1345.Ve
1350.PP 1346.PP
… …
1355\& static void 1351\& static void
1356\& timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1352\& timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
1357\& { 1353\& {
1358\& .. ten seconds without any activity 1354\& .. ten seconds without any activity
1359\& } 1355\& }
1360.Ve 1356\&
1361.PP
1362.Vb 4
1363\& struct ev_timer mytimer; 1357\& struct ev_timer mytimer;
1364\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 1358\& ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1365\& ev_timer_again (&mytimer); /* start timer */ 1359\& ev_timer_again (&mytimer); /* start timer */
1366\& ev_loop (loop, 0); 1360\& ev_loop (loop, 0);
1367.Ve 1361\&
1368.PP
1369.Vb 3
1370\& // and in some piece of code that gets executed on any "activity": 1362\& // and in some piece of code that gets executed on any "activity":
1371\& // reset the timeout to start ticking again at 10 seconds 1363\& // reset the timeout to start ticking again at 10 seconds
1372\& ev_timer_again (&mytimer); 1364\& ev_timer_again (&mytimer);
1373.Ve 1365.Ve
1374.ie n .Sh """ev_periodic"" \- to cron or not to cron?" 1366.ie n .Sh """ev_periodic"" \- to cron or not to cron?"
… …
1402.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 1394.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)"
1403.PD 1395.PD
1404Lots of arguments, lets sort it out... There are basically three modes of 1396Lots of arguments, lets sort it out... There are basically three modes of
1405operation, and we will explain them from simplest to complex: 1397operation, and we will explain them from simplest to complex:
1406.RS 4 1398.RS 4
1399.IP "\(bu" 4
1407.IP "* absolute timer (at = time, interval = reschedule_cb = 0)" 4 1400absolute timer (at = time, interval = reschedule_cb = 0)
1408.IX Item "absolute timer (at = time, interval = reschedule_cb = 0)" 1401.Sp
1409In this configuration the watcher triggers an event at the wallclock time 1402In this configuration the watcher triggers an event at the wallclock time
1410\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs, 1403\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs,
1411that is, if it is to be run at January 1st 2011 then it will run when the 1404that is, if it is to be run at January 1st 2011 then it will run when the
1412system time reaches or surpasses this time. 1405system time reaches or surpasses this time.
1406.IP "\(bu" 4
1413.IP "* non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)" 4 1407non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1414.IX Item "non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)" 1408.Sp
1415In this mode the watcher will always be scheduled to time out at the next 1409In this mode the watcher will always be scheduled to time out at the next
1416\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative) 1410\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative)
1417and then repeat, regardless of any time jumps. 1411and then repeat, regardless of any time jumps.
1418.Sp 1412.Sp
1419This can be used to create timers that do not drift with respect to system 1413This can be used to create timers that do not drift with respect to system
… …
1433time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps. 1427time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps.
1434.Sp 1428.Sp
1435For numerical stability it is preferable that the \f(CW\*(C`at\*(C'\fR value is near 1429For numerical stability it is preferable that the \f(CW\*(C`at\*(C'\fR value is near
1436\&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for 1430\&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for
1437this value. 1431this value.
1432.IP "\(bu" 4
1438.IP "* manual reschedule mode (at and interval ignored, reschedule_cb = callback)" 4 1433manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1439.IX Item "manual reschedule mode (at and interval ignored, reschedule_cb = callback)" 1434.Sp
1440In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being 1435In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being
1441ignored. Instead, each time the periodic watcher gets scheduled, the 1436ignored. Instead, each time the periodic watcher gets scheduled, the
1442reschedule callback will be called with the watcher as first, and the 1437reschedule callback will be called with the watcher as first, and the
1443current time as second argument. 1438current time as second argument.
1444.Sp 1439.Sp
… …
1499.IP "ev_tstamp at [read\-only]" 4 1494.IP "ev_tstamp at [read\-only]" 4
1500.IX Item "ev_tstamp at [read-only]" 1495.IX Item "ev_tstamp at [read-only]"
1501When active, contains the absolute time that the watcher is supposed to 1496When active, contains the absolute time that the watcher is supposed to
1502trigger next. 1497trigger next.
1503.PP 1498.PP
1499\fIExamples\fR
1500.IX Subsection "Examples"
1501.PP
1504Example: Call a callback every hour, or, more precisely, whenever the 1502Example: Call a callback every hour, or, more precisely, whenever the
1505system clock is divisible by 3600. The callback invocation times have 1503system clock is divisible by 3600. The callback invocation times have
1506potentially a lot of jittering, but good long-term stability. 1504potentially a lot of jittering, but good long-term stability.
1507.PP 1505.PP
1508.Vb 5 1506.Vb 5
1509\& static void 1507\& static void
1510\& clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1508\& clock_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1511\& { 1509\& {
1512\& ... its now a full hour (UTC, or TAI or whatever your clock follows) 1510\& ... its now a full hour (UTC, or TAI or whatever your clock follows)
1513\& } 1511\& }
1514.Ve 1512\&
1515.PP
1516.Vb 3
1517\& struct ev_periodic hourly_tick; 1513\& struct ev_periodic hourly_tick;
1518\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); 1514\& ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1519\& ev_periodic_start (loop, &hourly_tick); 1515\& ev_periodic_start (loop, &hourly_tick);
1520.Ve 1516.Ve
1521.PP 1517.PP
1522Example: The same as above, but use a reschedule callback to do it: 1518Example: The same as above, but use a reschedule callback to do it:
1523.PP 1519.PP
1524.Vb 1 1520.Vb 1
1525\& #include <math.h> 1521\& #include <math.h>
1526.Ve 1522\&
1527.PP
1528.Vb 5
1529\& static ev_tstamp 1523\& static ev_tstamp
1530\& my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 1524\& my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
1531\& { 1525\& {
1532\& return fmod (now, 3600.) + 3600.; 1526\& return fmod (now, 3600.) + 3600.;
1533\& } 1527\& }
1534.Ve 1528\&
1535.PP
1536.Vb 1
1537\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); 1529\& ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1538.Ve 1530.Ve
1539.PP 1531.PP
1540Example: Call a callback every hour, starting now: 1532Example: Call a callback every hour, starting now:
1541.PP 1533.PP
… …
1579Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to 1571Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to
1580some child status changes (most typically when a child of yours dies). 1572some child status changes (most typically when a child of yours dies).
1581.PP 1573.PP
1582\fIWatcher-Specific Functions and Data Members\fR 1574\fIWatcher-Specific Functions and Data Members\fR
1583.IX Subsection "Watcher-Specific Functions and Data Members" 1575.IX Subsection "Watcher-Specific Functions and Data Members"
1584.IP "ev_child_init (ev_child *, callback, int pid)" 4 1576.IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4
1585.IX Item "ev_child_init (ev_child *, callback, int pid)" 1577.IX Item "ev_child_init (ev_child *, callback, int pid, int trace)"
1586.PD 0 1578.PD 0
1587.IP "ev_child_set (ev_child *, int pid)" 4 1579.IP "ev_child_set (ev_child *, int pid, int trace)" 4
1588.IX Item "ev_child_set (ev_child *, int pid)" 1580.IX Item "ev_child_set (ev_child *, int pid, int trace)"
1589.PD 1581.PD
1590Configures the watcher to wait for status changes of process \f(CW\*(C`pid\*(C'\fR (or 1582Configures the watcher to wait for status changes of process \f(CW\*(C`pid\*(C'\fR (or
1591\&\fIany\fR process if \f(CW\*(C`pid\*(C'\fR is specified as \f(CW0\fR). The callback can look 1583\&\fIany\fR process if \f(CW\*(C`pid\*(C'\fR is specified as \f(CW0\fR). The callback can look
1592at the \f(CW\*(C`rstatus\*(C'\fR member of the \f(CW\*(C`ev_child\*(C'\fR watcher structure to see 1584at the \f(CW\*(C`rstatus\*(C'\fR member of the \f(CW\*(C`ev_child\*(C'\fR watcher structure to see
1593the status word (use the macros from \f(CW\*(C`sys/wait.h\*(C'\fR and see your systems 1585the status word (use the macros from \f(CW\*(C`sys/wait.h\*(C'\fR and see your systems
1594\&\f(CW\*(C`waitpid\*(C'\fR documentation). The \f(CW\*(C`rpid\*(C'\fR member contains the pid of the 1586\&\f(CW\*(C`waitpid\*(C'\fR documentation). The \f(CW\*(C`rpid\*(C'\fR member contains the pid of the
1595process causing the status change. 1587process causing the status change. \f(CW\*(C`trace\*(C'\fR must be either \f(CW0\fR (only
1588activate the watcher when the process terminates) or \f(CW1\fR (additionally
1589activate the watcher when the process is stopped or continued).
1596.IP "int pid [read\-only]" 4 1590.IP "int pid [read\-only]" 4
1597.IX Item "int pid [read-only]" 1591.IX Item "int pid [read-only]"
1598The process id this watcher watches out for, or \f(CW0\fR, meaning any process id. 1592The process id this watcher watches out for, or \f(CW0\fR, meaning any process id.
1599.IP "int rpid [read\-write]" 4 1593.IP "int rpid [read\-write]" 4
1600.IX Item "int rpid [read-write]" 1594.IX Item "int rpid [read-write]"
… …
1602.IP "int rstatus [read\-write]" 4 1596.IP "int rstatus [read\-write]" 4
1603.IX Item "int rstatus [read-write]" 1597.IX Item "int rstatus [read-write]"
1604The process exit/trace status caused by \f(CW\*(C`rpid\*(C'\fR (see your systems 1598The process exit/trace status caused by \f(CW\*(C`rpid\*(C'\fR (see your systems
1605\&\f(CW\*(C`waitpid\*(C'\fR and \f(CW\*(C`sys/wait.h\*(C'\fR documentation for details). 1599\&\f(CW\*(C`waitpid\*(C'\fR and \f(CW\*(C`sys/wait.h\*(C'\fR documentation for details).
1606.PP 1600.PP
1601\fIExamples\fR
1602.IX Subsection "Examples"
1603.PP
1607Example: Try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0. 1604Example: Try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0.
1608.PP 1605.PP
1609.Vb 5 1606.Vb 5
1610\& static void 1607\& static void
1611\& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1608\& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1612\& { 1609\& {
1613\& ev_unloop (loop, EVUNLOOP_ALL); 1610\& ev_unloop (loop, EVUNLOOP_ALL);
1614\& } 1611\& }
1615.Ve 1612\&
1616.PP
1617.Vb 3
1618\& struct ev_signal signal_watcher; 1613\& struct ev_signal signal_watcher;
1619\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1614\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1620\& ev_signal_start (loop, &sigint_cb); 1615\& ev_signal_start (loop, &sigint_cb);
1621.Ve 1616.Ve
1622.ie n .Sh """ev_stat"" \- did the file attributes just change?" 1617.ie n .Sh """ev_stat"" \- did the file attributes just change?"
… …
1644impose a minimum interval which is currently around \f(CW0.1\fR, but thats 1639impose a minimum interval which is currently around \f(CW0.1\fR, but thats
1645usually overkill. 1640usually overkill.
1646.PP 1641.PP
1647This watcher type is not meant for massive numbers of stat watchers, 1642This watcher type is not meant for massive numbers of stat watchers,
1648as even with OS-supported change notifications, this can be 1643as even with OS-supported change notifications, this can be
1649resource\-intensive. 1644resource-intensive.
1650.PP 1645.PP
1651At the time of this writing, only the Linux inotify interface is 1646At the time of this writing, only the Linux inotify interface is
1652implemented (implementing kqueue support is left as an exercise for the 1647implemented (implementing kqueue support is left as an exercise for the
1653reader). Inotify will be used to give hints only and should not change the 1648reader). Inotify will be used to give hints only and should not change the
1654semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs 1649semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs
… …
1734\fIExamples\fR 1729\fIExamples\fR
1735.IX Subsection "Examples" 1730.IX Subsection "Examples"
1736.PP 1731.PP
1737Example: Watch \f(CW\*(C`/etc/passwd\*(C'\fR for attribute changes. 1732Example: Watch \f(CW\*(C`/etc/passwd\*(C'\fR for attribute changes.
1738.PP 1733.PP
1739.Vb 15 1734.Vb 10
1740\& static void 1735\& static void
1741\& passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 1736\& passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1742\& { 1737\& {
1743\& /* /etc/passwd changed in some way */ 1738\& /* /etc/passwd changed in some way */
1744\& if (w->attr.st_nlink) 1739\& if (w\->attr.st_nlink)
1745\& { 1740\& {
1746\& printf ("passwd current size %ld\en", (long)w->attr.st_size); 1741\& printf ("passwd current size %ld\en", (long)w\->attr.st_size);
1747\& printf ("passwd current atime %ld\en", (long)w->attr.st_mtime); 1742\& printf ("passwd current atime %ld\en", (long)w\->attr.st_mtime);
1748\& printf ("passwd current mtime %ld\en", (long)w->attr.st_mtime); 1743\& printf ("passwd current mtime %ld\en", (long)w\->attr.st_mtime);
1749\& } 1744\& }
1750\& else 1745\& else
1751\& /* you shalt not abuse printf for puts */ 1746\& /* you shalt not abuse printf for puts */
1752\& puts ("wow, /etc/passwd is not there, expect problems. " 1747\& puts ("wow, /etc/passwd is not there, expect problems. "
1753\& "if this is windows, they already arrived\en"); 1748\& "if this is windows, they already arrived\en");
1754\& } 1749\& }
1755.Ve 1750\&
1756.PP
1757.Vb 2
1758\& ... 1751\& ...
1759\& ev_stat passwd; 1752\& ev_stat passwd;
1760.Ve 1753\&
1761.PP
1762.Vb 2
1763\& ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.); 1754\& ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1764\& ev_stat_start (loop, &passwd); 1755\& ev_stat_start (loop, &passwd);
1765.Ve 1756.Ve
1766.PP 1757.PP
1767Example: Like above, but additionally use a one-second delay so we do not 1758Example: Like above, but additionally use a one-second delay so we do not
… …
1770\&\f(CW\*(C`ev_timer\*(C'\fR callback invocation). 1761\&\f(CW\*(C`ev_timer\*(C'\fR callback invocation).
1771.PP 1762.PP
1772.Vb 2 1763.Vb 2
1773\& static ev_stat passwd; 1764\& static ev_stat passwd;
1774\& static ev_timer timer; 1765\& static ev_timer timer;
1775.Ve 1766\&
1776.PP
1777.Vb 4
1778\& static void 1767\& static void
1779\& timer_cb (EV_P_ ev_timer *w, int revents) 1768\& timer_cb (EV_P_ ev_timer *w, int revents)
1780\& { 1769\& {
1781\& ev_timer_stop (EV_A_ w); 1770\& ev_timer_stop (EV_A_ w);
1782.Ve 1771\&
1783.PP
1784.Vb 2
1785\& /* now it's one second after the most recent passwd change */ 1772\& /* now it\*(Aqs one second after the most recent passwd change */
1786\& } 1773\& }
1787.Ve 1774\&
1788.PP
1789.Vb 6
1790\& static void 1775\& static void
1791\& stat_cb (EV_P_ ev_stat *w, int revents) 1776\& stat_cb (EV_P_ ev_stat *w, int revents)
1792\& { 1777\& {
1793\& /* reset the one-second timer */ 1778\& /* reset the one\-second timer */
1794\& ev_timer_again (EV_A_ &timer); 1779\& ev_timer_again (EV_A_ &timer);
1795\& } 1780\& }
1796.Ve 1781\&
1797.PP
1798.Vb 4
1799\& ... 1782\& ...
1800\& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); 1783\& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1801\& ev_stat_start (loop, &passwd); 1784\& ev_stat_start (loop, &passwd);
1802\& ev_timer_init (&timer, timer_cb, 0., 1.01); 1785\& ev_timer_init (&timer, timer_cb, 0., 1.01);
1803.Ve 1786.Ve
… …
1818The most noteworthy effect is that as long as any idle watchers are 1801The most noteworthy effect is that as long as any idle watchers are
1819active, the process will not block when waiting for new events. 1802active, the process will not block when waiting for new events.
1820.PP 1803.PP
1821Apart from keeping your process non-blocking (which is a useful 1804Apart from keeping your process non-blocking (which is a useful
1822effect on its own sometimes), idle watchers are a good place to do 1805effect on its own sometimes), idle watchers are a good place to do
1823\&\*(L"pseudo\-background processing\*(R", or delay processing stuff to after the 1806\&\*(L"pseudo-background processing\*(R", or delay processing stuff to after the
1824event loop has handled all outstanding events. 1807event loop has handled all outstanding events.
1825.PP 1808.PP
1826\fIWatcher-Specific Functions and Data Members\fR 1809\fIWatcher-Specific Functions and Data Members\fR
1827.IX Subsection "Watcher-Specific Functions and Data Members" 1810.IX Subsection "Watcher-Specific Functions and Data Members"
1828.IP "ev_idle_init (ev_signal *, callback)" 4 1811.IP "ev_idle_init (ev_signal *, callback)" 4
1829.IX Item "ev_idle_init (ev_signal *, callback)" 1812.IX Item "ev_idle_init (ev_signal *, callback)"
1830Initialises and configures the idle watcher \- it has no parameters of any 1813Initialises and configures the idle watcher \- it has no parameters of any
1831kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless, 1814kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless,
1832believe me. 1815believe me.
1833.PP 1816.PP
1817\fIExamples\fR
1818.IX Subsection "Examples"
1819.PP
1834Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the 1820Example: Dynamically allocate an \f(CW\*(C`ev_idle\*(C'\fR watcher, start it, and in the
1835callback, free it. Also, use no error checking, as usual. 1821callback, free it. Also, use no error checking, as usual.
1836.PP 1822.PP
1837.Vb 7 1823.Vb 7
1838\& static void 1824\& static void
1839\& idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) 1825\& idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
1840\& { 1826\& {
1841\& free (w); 1827\& free (w);
1842\& // now do something you wanted to do when the program has 1828\& // now do something you wanted to do when the program has
1843\& // no longer asnything immediate to do. 1829\& // no longer anything immediate to do.
1844\& } 1830\& }
1845.Ve 1831\&
1846.PP
1847.Vb 3
1848\& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 1832\& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1849\& ev_idle_init (idle_watcher, idle_cb); 1833\& ev_idle_init (idle_watcher, idle_cb);
1850\& ev_idle_start (loop, idle_cb); 1834\& ev_idle_start (loop, idle_cb);
1851.Ve 1835.Ve
1852.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!" 1836.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!"
… …
1894priority, to ensure that they are being run before any other watchers 1878priority, to ensure that they are being run before any other watchers
1895after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, 1879after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers,
1896too) should not activate (\*(L"feed\*(R") events into libev. While libev fully 1880too) should not activate (\*(L"feed\*(R") events into libev. While libev fully
1897supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers 1881supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers
1898did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other 1882did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other
1899(non\-libev) event loops those other event loops might be in an unusable 1883(non-libev) event loops those other event loops might be in an unusable
1900state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to 1884state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to
1901coexist peacefully with others). 1885coexist peacefully with others).
1902.PP 1886.PP
1903\fIWatcher-Specific Functions and Data Members\fR 1887\fIWatcher-Specific Functions and Data Members\fR
1904.IX Subsection "Watcher-Specific Functions and Data Members" 1888.IX Subsection "Watcher-Specific Functions and Data Members"
… …
1910.PD 1894.PD
1911Initialises and configures the prepare or check watcher \- they have no 1895Initialises and configures the prepare or check watcher \- they have no
1912parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR 1896parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR
1913macros, but using them is utterly, utterly and completely pointless. 1897macros, but using them is utterly, utterly and completely pointless.
1914.PP 1898.PP
1899\fIExamples\fR
1900.IX Subsection "Examples"
1901.PP
1915There are a number of principal ways to embed other event loops or modules 1902There are a number of principal ways to embed other event loops or modules
1916into libev. Here are some ideas on how to include libadns into libev 1903into libev. Here are some ideas on how to include libadns into libev
1917(there is a Perl module named \f(CW\*(C`EV::ADNS\*(C'\fR that does this, which you could 1904(there is a Perl module named \f(CW\*(C`EV::ADNS\*(C'\fR that does this, which you could
1918use for an actually working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR 1905use for an actually working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR
1919embeds a Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 1906embeds a Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0
… …
1926the callbacks for the IO/timeout watchers might not have been called yet. 1913the callbacks for the IO/timeout watchers might not have been called yet.
1927.PP 1914.PP
1928.Vb 2 1915.Vb 2
1929\& static ev_io iow [nfd]; 1916\& static ev_io iow [nfd];
1930\& static ev_timer tw; 1917\& static ev_timer tw;
1931.Ve 1918\&
1932.PP
1933.Vb 4
1934\& static void 1919\& static void
1935\& io_cb (ev_loop *loop, ev_io *w, int revents) 1920\& io_cb (ev_loop *loop, ev_io *w, int revents)
1936\& { 1921\& {
1937\& } 1922\& }
1938.Ve 1923\&
1939.PP
1940.Vb 8
1941\& // create io watchers for each fd and a timer before blocking 1924\& // create io watchers for each fd and a timer before blocking
1942\& static void 1925\& static void
1943\& adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 1926\& adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1944\& { 1927\& {
1945\& int timeout = 3600000; 1928\& int timeout = 3600000;
1946\& struct pollfd fds [nfd]; 1929\& struct pollfd fds [nfd];
1947\& // actual code will need to loop here and realloc etc. 1930\& // actual code will need to loop here and realloc etc.
1948\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 1931\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1949.Ve 1932\&
1950.PP
1951.Vb 3
1952\& /* the callback is illegal, but won't be called as we stop during check */ 1933\& /* the callback is illegal, but won\*(Aqt be called as we stop during check */
1953\& ev_timer_init (&tw, 0, timeout * 1e-3); 1934\& ev_timer_init (&tw, 0, timeout * 1e\-3);
1954\& ev_timer_start (loop, &tw); 1935\& ev_timer_start (loop, &tw);
1955.Ve 1936\&
1956.PP
1957.Vb 6
1958\& // create one ev_io per pollfd 1937\& // create one ev_io per pollfd
1959\& for (int i = 0; i < nfd; ++i) 1938\& for (int i = 0; i < nfd; ++i)
1960\& { 1939\& {
1961\& ev_io_init (iow + i, io_cb, fds [i].fd, 1940\& ev_io_init (iow + i, io_cb, fds [i].fd,
1962\& ((fds [i].events & POLLIN ? EV_READ : 0) 1941\& ((fds [i].events & POLLIN ? EV_READ : 0)
1963\& | (fds [i].events & POLLOUT ? EV_WRITE : 0))); 1942\& | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1964.Ve 1943\&
1965.PP
1966.Vb 4
1967\& fds [i].revents = 0; 1944\& fds [i].revents = 0;
1968\& ev_io_start (loop, iow + i); 1945\& ev_io_start (loop, iow + i);
1969\& } 1946\& }
1970\& } 1947\& }
1971.Ve 1948\&
1972.PP
1973.Vb 5
1974\& // stop all watchers after blocking 1949\& // stop all watchers after blocking
1975\& static void 1950\& static void
1976\& adns_check_cb (ev_loop *loop, ev_check *w, int revents) 1951\& adns_check_cb (ev_loop *loop, ev_check *w, int revents)
1977\& { 1952\& {
1978\& ev_timer_stop (loop, &tw); 1953\& ev_timer_stop (loop, &tw);
1979.Ve 1954\&
1980.PP
1981.Vb 8
1982\& for (int i = 0; i < nfd; ++i) 1955\& for (int i = 0; i < nfd; ++i)
1983\& { 1956\& {
1984\& // set the relevant poll flags 1957\& // set the relevant poll flags
1985\& // could also call adns_processreadable etc. here 1958\& // could also call adns_processreadable etc. here
1986\& struct pollfd *fd = fds + i; 1959\& struct pollfd *fd = fds + i;
1987\& int revents = ev_clear_pending (iow + i); 1960\& int revents = ev_clear_pending (iow + i);
1988\& if (revents & EV_READ ) fd->revents |= fd->events & POLLIN; 1961\& if (revents & EV_READ ) fd\->revents |= fd\->events & POLLIN;
1989\& if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT; 1962\& if (revents & EV_WRITE) fd\->revents |= fd\->events & POLLOUT;
1990.Ve 1963\&
1991.PP
1992.Vb 3
1993\& // now stop the watcher 1964\& // now stop the watcher
1994\& ev_io_stop (loop, iow + i); 1965\& ev_io_stop (loop, iow + i);
1995\& } 1966\& }
1996.Ve 1967\&
1997.PP
1998.Vb 2
1999\& adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); 1968\& adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
2000\& } 1969\& }
2001.Ve 1970.Ve
2002.PP 1971.PP
2003Method 2: This would be just like method 1, but you run \f(CW\*(C`adns_afterpoll\*(C'\fR 1972Method 2: This would be just like method 1, but you run \f(CW\*(C`adns_afterpoll\*(C'\fR
… …
2009.PP 1978.PP
2010.Vb 5 1979.Vb 5
2011\& static void 1980\& static void
2012\& timer_cb (EV_P_ ev_timer *w, int revents) 1981\& timer_cb (EV_P_ ev_timer *w, int revents)
2013\& { 1982\& {
2014\& adns_state ads = (adns_state)w->data; 1983\& adns_state ads = (adns_state)w\->data;
2015\& update_now (EV_A); 1984\& update_now (EV_A);
2016.Ve 1985\&
2017.PP
2018.Vb 2
2019\& adns_processtimeouts (ads, &tv_now); 1986\& adns_processtimeouts (ads, &tv_now);
2020\& } 1987\& }
2021.Ve 1988\&
2022.PP
2023.Vb 5
2024\& static void 1989\& static void
2025\& io_cb (EV_P_ ev_io *w, int revents) 1990\& io_cb (EV_P_ ev_io *w, int revents)
2026\& { 1991\& {
2027\& adns_state ads = (adns_state)w->data; 1992\& adns_state ads = (adns_state)w\->data;
2028\& update_now (EV_A); 1993\& update_now (EV_A);
2029.Ve 1994\&
2030.PP
2031.Vb 3
2032\& if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now); 1995\& if (revents & EV_READ ) adns_processreadable (ads, w\->fd, &tv_now);
2033\& if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now); 1996\& if (revents & EV_WRITE) adns_processwriteable (ads, w\->fd, &tv_now);
2034\& } 1997\& }
2035.Ve 1998\&
2036.PP
2037.Vb 1
2038\& // do not ever call adns_afterpoll 1999\& // do not ever call adns_afterpoll
2039.Ve 2000.Ve
2040.PP 2001.PP
2041Method 4: Do not use a prepare or check watcher because the module you 2002Method 4: Do not use a prepare or check watcher because the module you
2042want to embed is too inflexible to support it. Instead, youc na override 2003want to embed is too inflexible to support it. Instead, youc na override
… …
2047.Vb 4 2008.Vb 4
2048\& static gint 2009\& static gint
2049\& event_poll_func (GPollFD *fds, guint nfds, gint timeout) 2010\& event_poll_func (GPollFD *fds, guint nfds, gint timeout)
2050\& { 2011\& {
2051\& int got_events = 0; 2012\& int got_events = 0;
2052.Ve 2013\&
2053.PP
2054.Vb 2
2055\& for (n = 0; n < nfds; ++n) 2014\& for (n = 0; n < nfds; ++n)
2056\& // create/start io watcher that sets the relevant bits in fds[n] and increment got_events 2015\& // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
2057.Ve 2016\&
2058.PP
2059.Vb 2
2060\& if (timeout >= 0) 2017\& if (timeout >= 0)
2061\& // create/start timer 2018\& // create/start timer
2062.Ve 2019\&
2063.PP
2064.Vb 2
2065\& // poll 2020\& // poll
2066\& ev_loop (EV_A_ 0); 2021\& ev_loop (EV_A_ 0);
2067.Ve 2022\&
2068.PP
2069.Vb 3
2070\& // stop timer again 2023\& // stop timer again
2071\& if (timeout >= 0) 2024\& if (timeout >= 0)
2072\& ev_timer_stop (EV_A_ &to); 2025\& ev_timer_stop (EV_A_ &to);
2073.Ve 2026\&
2074.PP
2075.Vb 3
2076\& // stop io watchers again - their callbacks should have set 2027\& // stop io watchers again \- their callbacks should have set
2077\& for (n = 0; n < nfds; ++n) 2028\& for (n = 0; n < nfds; ++n)
2078\& ev_io_stop (EV_A_ iow [n]); 2029\& ev_io_stop (EV_A_ iow [n]);
2079.Ve 2030\&
2080.PP
2081.Vb 2
2082\& return got_events; 2031\& return got_events;
2083\& } 2032\& }
2084.Ve 2033.Ve
2085.ie n .Sh """ev_embed"" \- when one backend isn't enough..." 2034.ie n .Sh """ev_embed"" \- when one backend isn't enough..."
2086.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..." 2035.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."
… …
2130portable one. 2079portable one.
2131.PP 2080.PP
2132So when you want to use this feature you will always have to be prepared 2081So when you want to use this feature you will always have to be prepared
2133that you cannot get an embeddable loop. The recommended way to get around 2082that you cannot get an embeddable loop. The recommended way to get around
2134this is to have a separate variables for your embeddable loop, try to 2083this is to have a separate variables for your embeddable loop, try to
2135create it, and if that fails, use the normal loop for everything: 2084create it, and if that fails, use the normal loop for everything.
2136.PP
2137.Vb 3
2138\& struct ev_loop *loop_hi = ev_default_init (0);
2139\& struct ev_loop *loop_lo = 0;
2140\& struct ev_embed embed;
2141.Ve
2142.PP
2143.Vb 5
2144\& // see if there is a chance of getting one that works
2145\& // (remember that a flags value of 0 means autodetection)
2146\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2147\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2148\& : 0;
2149.Ve
2150.PP
2151.Vb 8
2152\& // if we got one, then embed it, otherwise default to loop_hi
2153\& if (loop_lo)
2154\& {
2155\& ev_embed_init (&embed, 0, loop_lo);
2156\& ev_embed_start (loop_hi, &embed);
2157\& }
2158\& else
2159\& loop_lo = loop_hi;
2160.Ve
2161.PP 2085.PP
2162\fIWatcher-Specific Functions and Data Members\fR 2086\fIWatcher-Specific Functions and Data Members\fR
2163.IX Subsection "Watcher-Specific Functions and Data Members" 2087.IX Subsection "Watcher-Specific Functions and Data Members"
2164.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 2088.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
2165.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 2089.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"
… …
2178similarly to \f(CW\*(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\*(C'\fR, but in the most 2102similarly to \f(CW\*(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\*(C'\fR, but in the most
2179apropriate way for embedded loops. 2103apropriate way for embedded loops.
2180.IP "struct ev_loop *other [read\-only]" 4 2104.IP "struct ev_loop *other [read\-only]" 4
2181.IX Item "struct ev_loop *other [read-only]" 2105.IX Item "struct ev_loop *other [read-only]"
2182The embedded event loop. 2106The embedded event loop.
2107.PP
2108\fIExamples\fR
2109.IX Subsection "Examples"
2110.PP
2111Example: Try to get an embeddable event loop and embed it into the default
2112event loop. If that is not possible, use the default loop. The default
2113loop is stored in \f(CW\*(C`loop_hi\*(C'\fR, while the mebeddable loop is stored in
2114\&\f(CW\*(C`loop_lo\*(C'\fR (which is \f(CW\*(C`loop_hi\*(C'\fR in the acse no embeddable loop can be
2115used).
2116.PP
2117.Vb 3
2118\& struct ev_loop *loop_hi = ev_default_init (0);
2119\& struct ev_loop *loop_lo = 0;
2120\& struct ev_embed embed;
2121\&
2122\& // see if there is a chance of getting one that works
2123\& // (remember that a flags value of 0 means autodetection)
2124\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2125\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2126\& : 0;
2127\&
2128\& // if we got one, then embed it, otherwise default to loop_hi
2129\& if (loop_lo)
2130\& {
2131\& ev_embed_init (&embed, 0, loop_lo);
2132\& ev_embed_start (loop_hi, &embed);
2133\& }
2134\& else
2135\& loop_lo = loop_hi;
2136.Ve
2137.PP
2138Example: Check if kqueue is available but not recommended and create
2139a kqueue backend for use with sockets (which usually work with any
2140kqueue implementation). Store the kqueue/socket\-only event loop in
2141\&\f(CW\*(C`loop_socket\*(C'\fR. (One might optionally use \f(CW\*(C`EVFLAG_NOENV\*(C'\fR, too).
2142.PP
2143.Vb 3
2144\& struct ev_loop *loop = ev_default_init (0);
2145\& struct ev_loop *loop_socket = 0;
2146\& struct ev_embed embed;
2147\&
2148\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2149\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2150\& {
2151\& ev_embed_init (&embed, 0, loop_socket);
2152\& ev_embed_start (loop, &embed);
2153\& }
2154\&
2155\& if (!loop_socket)
2156\& loop_socket = loop;
2157\&
2158\& // now use loop_socket for all sockets, and loop for everything else
2159.Ve
2183.ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork" 2160.ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork"
2184.el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" 2161.el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork"
2185.IX Subsection "ev_fork - the audacity to resume the event loop after a fork" 2162.IX Subsection "ev_fork - the audacity to resume the event loop after a fork"
2186Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because 2163Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
2187whoever is a good citizen cared to tell libev about it by calling 2164whoever is a good citizen cared to tell libev about it by calling
… …
2229\& if (revents & EV_TIMEOUT) 2206\& if (revents & EV_TIMEOUT)
2230\& /* doh, nothing entered */; 2207\& /* doh, nothing entered */;
2231\& else if (revents & EV_READ) 2208\& else if (revents & EV_READ)
2232\& /* stdin might have data for us, joy! */; 2209\& /* stdin might have data for us, joy! */;
2233\& } 2210\& }
2234.Ve 2211\&
2235.Sp
2236.Vb 1
2237\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 2212\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2238.Ve 2213.Ve
2239.IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4 2214.IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4
2240.IX Item "ev_feed_event (ev_loop *, watcher *, int revents)" 2215.IX Item "ev_feed_event (ev_loop *, watcher *, int revents)"
2241Feeds the given event set into the event loop, as if the specified event 2216Feeds the given event set into the event loop, as if the specified event
… …
2251loop!). 2226loop!).
2252.SH "LIBEVENT EMULATION" 2227.SH "LIBEVENT EMULATION"
2253.IX Header "LIBEVENT EMULATION" 2228.IX Header "LIBEVENT EMULATION"
2254Libev offers a compatibility emulation layer for libevent. It cannot 2229Libev offers a compatibility emulation layer for libevent. It cannot
2255emulate the internals of libevent, so here are some usage hints: 2230emulate the internals of libevent, so here are some usage hints:
2231.IP "\(bu" 4
2256.IP "* Use it by including <event.h>, as usual." 4 2232Use it by including <event.h>, as usual.
2257.IX Item "Use it by including <event.h>, as usual." 2233.IP "\(bu" 4
2258.PD 0 2234The following members are fully supported: ev_base, ev_callback,
2259.IP "* The following members are fully supported: ev_base, ev_callback, ev_arg, ev_fd, ev_res, ev_events." 4 2235ev_arg, ev_fd, ev_res, ev_events.
2260.IX Item "The following members are fully supported: ev_base, ev_callback, ev_arg, ev_fd, ev_res, ev_events." 2236.IP "\(bu" 4
2261.IP "* Avoid using ev_flags and the EVLIST_*\-macros, while it is maintained by libev, it does not work exactly the same way as in libevent (consider it a private \s-1API\s0)." 4 2237Avoid using ev_flags and the EVLIST_*\-macros, while it is
2262.IX Item "Avoid using ev_flags and the EVLIST_*-macros, while it is maintained by libev, it does not work exactly the same way as in libevent (consider it a private API)." 2238maintained by libev, it does not work exactly the same way as in libevent (consider
2263.IP "* Priorities are not currently supported. Initialising priorities will fail and all watchers will have the same priority, even though there is an ev_pri field." 4 2239it a private \s-1API\s0).
2264.IX Item "Priorities are not currently supported. Initialising priorities will fail and all watchers will have the same priority, even though there is an ev_pri field." 2240.IP "\(bu" 4
2241Priorities are not currently supported. Initialising priorities
2242will fail and all watchers will have the same priority, even though there
2243is an ev_pri field.
2244.IP "\(bu" 4
2265.IP "* Other members are not supported." 4 2245Other members are not supported.
2266.IX Item "Other members are not supported." 2246.IP "\(bu" 4
2267.IP "* The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need to use the libev header file and library." 4 2247The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need
2268.IX Item "The libev emulation is not ABI compatible to libevent, you need to use the libev header file and library." 2248to use the libev header file and library.
2269.PD
2270.SH "\*(C+ SUPPORT" 2249.SH "\*(C+ SUPPORT"
2271.IX Header " SUPPORT" 2250.IX Header " SUPPORT"
2272Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow 2251Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
2273you to use some convinience methods to start/stop watchers and also change 2252you to use some convinience methods to start/stop watchers and also change
2274the callback model to a model using method callbacks on objects. 2253the callback model to a model using method callbacks on objects.
… …
2354.Vb 4 2333.Vb 4
2355\& struct myclass 2334\& struct myclass
2356\& { 2335\& {
2357\& void io_cb (ev::io &w, int revents) { } 2336\& void io_cb (ev::io &w, int revents) { }
2358\& } 2337\& }
2359.Ve 2338\&
2360.Sp
2361.Vb 3
2362\& myclass obj; 2339\& myclass obj;
2363\& ev::io iow; 2340\& ev::io iow;
2364\& iow.set <myclass, &myclass::io_cb> (&obj); 2341\& iow.set <myclass, &myclass::io_cb> (&obj);
2365.Ve 2342.Ve
2366.IP "w\->set<function> (void *data = 0)" 4 2343.IP "w\->set<function> (void *data = 0)" 4
… …
2417the constructor. 2394the constructor.
2418.PP 2395.PP
2419.Vb 4 2396.Vb 4
2420\& class myclass 2397\& class myclass
2421\& { 2398\& {
2422\& ev_io io; void io_cb (ev::io &w, int revents); 2399\& ev::io io; void io_cb (ev::io &w, int revents);
2423\& ev_idle idle void idle_cb (ev::idle &w, int revents); 2400\& ev:idle idle void idle_cb (ev::idle &w, int revents);
2424.Ve 2401\&
2425.PP
2426.Vb 2
2427\& myclass (); 2402\& myclass (int fd)
2428\& }
2429.Ve
2430.PP
2431.Vb 4
2432\& myclass::myclass (int fd)
2433\& { 2403\& {
2434\& io .set <myclass, &myclass::io_cb > (this); 2404\& io .set <myclass, &myclass::io_cb > (this);
2435\& idle.set <myclass, &myclass::idle_cb> (this); 2405\& idle.set <myclass, &myclass::idle_cb> (this);
2436.Ve 2406\&
2437.PP
2438.Vb 2
2439\& io.start (fd, ev::READ); 2407\& io.start (fd, ev::READ);
2408\& }
2440\& } 2409\& };
2441.Ve 2410.Ve
2442.SH "MACRO MAGIC" 2411.SH "MACRO MAGIC"
2443.IX Header "MACRO MAGIC" 2412.IX Header "MACRO MAGIC"
2444Libev can be compiled with a variety of options, the most fundamantal 2413Libev can be compiled with a variety of options, the most fundamantal
2445of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 2414of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
… …
2470\&\f(CW\*(C`EV_P_\*(C'\fR is used when other parameters are following. Example: 2439\&\f(CW\*(C`EV_P_\*(C'\fR is used when other parameters are following. Example:
2471.Sp 2440.Sp
2472.Vb 2 2441.Vb 2
2473\& // this is how ev_unref is being declared 2442\& // this is how ev_unref is being declared
2474\& static void ev_unref (EV_P); 2443\& static void ev_unref (EV_P);
2475.Ve 2444\&
2476.Sp
2477.Vb 2
2478\& // this is how you can declare your typical callback 2445\& // this is how you can declare your typical callback
2479\& static void cb (EV_P_ ev_timer *w, int revents) 2446\& static void cb (EV_P_ ev_timer *w, int revents)
2480.Ve 2447.Ve
2481.Sp 2448.Sp
2482It declares a parameter \f(CW\*(C`loop\*(C'\fR of type \f(CW\*(C`struct ev_loop *\*(C'\fR, quite 2449It declares a parameter \f(CW\*(C`loop\*(C'\fR of type \f(CW\*(C`struct ev_loop *\*(C'\fR, quite
… …
2495\& static void 2462\& static void
2496\& check_cb (EV_P_ ev_timer *w, int revents) 2463\& check_cb (EV_P_ ev_timer *w, int revents)
2497\& { 2464\& {
2498\& ev_check_stop (EV_A_ w); 2465\& ev_check_stop (EV_A_ w);
2499\& } 2466\& }
2500.Ve 2467\&
2501.PP
2502.Vb 4
2503\& ev_check check; 2468\& ev_check check;
2504\& ev_check_init (&check, check_cb); 2469\& ev_check_init (&check, check_cb);
2505\& ev_check_start (EV_DEFAULT_ &check); 2470\& ev_check_start (EV_DEFAULT_ &check);
2506\& ev_loop (EV_DEFAULT_ 0); 2471\& ev_loop (EV_DEFAULT_ 0);
2507.Ve 2472.Ve
2508.SH "EMBEDDING" 2473.SH "EMBEDDING"
2509.IX Header "EMBEDDING" 2474.IX Header "EMBEDDING"
2510Libev can (and often is) directly embedded into host 2475Libev can (and often is) directly embedded into host
2511applications. Examples of applications that embed it include the Deliantra 2476applications. Examples of applications that embed it include the Deliantra
2512Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe) 2477Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe)
2513and rxvt\-unicode. 2478and rxvt-unicode.
2514.PP 2479.PP
2515The goal is to enable you to just copy the necessary files into your 2480The goal is to enable you to just copy the necessary files into your
2516source directory without having to change even a single line in them, so 2481source directory without having to change even a single line in them, so
2517you can easily upgrade by simply copying (or having a checked-out copy of 2482you can easily upgrade by simply copying (or having a checked-out copy of
2518libev somewhere in your source tree). 2483libev somewhere in your source tree).
… …
2553.Vb 4 2518.Vb 4
2554\& ev.h 2519\& ev.h
2555\& ev.c 2520\& ev.c
2556\& ev_vars.h 2521\& ev_vars.h
2557\& ev_wrap.h 2522\& ev_wrap.h
2558.Ve 2523\&
2559.PP
2560.Vb 1
2561\& ev_win32.c required on win32 platforms only 2524\& ev_win32.c required on win32 platforms only
2562.Ve 2525\&
2563.PP
2564.Vb 5
2565\& ev_select.c only when select backend is enabled (which is enabled by default) 2526\& ev_select.c only when select backend is enabled (which is enabled by default)
2566\& ev_poll.c only when poll backend is enabled (disabled by default) 2527\& ev_poll.c only when poll backend is enabled (disabled by default)
2567\& ev_epoll.c only when the epoll backend is enabled (disabled by default) 2528\& ev_epoll.c only when the epoll backend is enabled (disabled by default)
2568\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 2529\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
2569\& ev_port.c only when the solaris port backend is enabled (disabled by default) 2530\& ev_port.c only when the solaris port backend is enabled (disabled by default)
… …
2664wants osf handles on win32 (this is the case when the select to 2625wants osf handles on win32 (this is the case when the select to
2665be used is the winsock select). This means that it will call 2626be used is the winsock select). This means that it will call
2666\&\f(CW\*(C`_get_osfhandle\*(C'\fR on the fd to convert it to an \s-1OS\s0 handle. Otherwise, 2627\&\f(CW\*(C`_get_osfhandle\*(C'\fR on the fd to convert it to an \s-1OS\s0 handle. Otherwise,
2667it is assumed that all these functions actually work on fds, even 2628it is assumed that all these functions actually work on fds, even
2668on win32. Should not be defined on non\-win32 platforms. 2629on win32. Should not be defined on non\-win32 platforms.
2630.IP "\s-1EV_FD_TO_WIN32_HANDLE\s0" 4
2631.IX Item "EV_FD_TO_WIN32_HANDLE"
2632If \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR is enabled, then libev needs a way to map
2633file descriptors to socket handles. When not defining this symbol (the
2634default), then libev will call \f(CW\*(C`_get_osfhandle\*(C'\fR, which is usually
2635correct. In some cases, programs use their own file descriptor management,
2636in which case they can provide this function to map fds to socket handles.
2669.IP "\s-1EV_USE_POLL\s0" 4 2637.IP "\s-1EV_USE_POLL\s0" 4
2670.IX Item "EV_USE_POLL" 2638.IX Item "EV_USE_POLL"
2671If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) 2639If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2)
2672backend. Otherwise it will be enabled on non\-win32 platforms. It 2640backend. Otherwise it will be enabled on non\-win32 platforms. It
2673takes precedence over select. 2641takes precedence over select.
… …
2703interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will 2671interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will
2704be detected at runtime. 2672be detected at runtime.
2705.IP "\s-1EV_H\s0" 4 2673.IP "\s-1EV_H\s0" 4
2706.IX Item "EV_H" 2674.IX Item "EV_H"
2707The name of the \fIev.h\fR header file used to include it. The default if 2675The name of the \fIev.h\fR header file used to include it. The default if
2708undefined is \f(CW"ev.h"\fR in \fIevent.h\fR and \fIev.c\fR. This can be used to 2676undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
2709virtually rename the \fIev.h\fR header file in case of conflicts. 2677used to virtually rename the \fIev.h\fR header file in case of conflicts.
2710.IP "\s-1EV_CONFIG_H\s0" 4 2678.IP "\s-1EV_CONFIG_H\s0" 4
2711.IX Item "EV_CONFIG_H" 2679.IX Item "EV_CONFIG_H"
2712If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 2680If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
2713\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 2681\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
2714\&\f(CW\*(C`EV_H\*(C'\fR, above. 2682\&\f(CW\*(C`EV_H\*(C'\fR, above.
2715.IP "\s-1EV_EVENT_H\s0" 4 2683.IP "\s-1EV_EVENT_H\s0" 4
2716.IX Item "EV_EVENT_H" 2684.IX Item "EV_EVENT_H"
2717Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 2685Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
2718of how the \fIevent.h\fR header can be found, the dfeault is \f(CW"event.h"\fR. 2686of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
2719.IP "\s-1EV_PROTOTYPES\s0" 4 2687.IP "\s-1EV_PROTOTYPES\s0" 4
2720.IX Item "EV_PROTOTYPES" 2688.IX Item "EV_PROTOTYPES"
2721If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 2689If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
2722prototypes, but still define all the structs and other symbols. This is 2690prototypes, but still define all the structs and other symbols. This is
2723occasionally useful if you want to provide your own wrapper functions 2691occasionally useful if you want to provide your own wrapper functions
… …
2818.Sh "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0" 2786.Sh "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0"
2819.IX Subsection "EXPORTED API SYMBOLS" 2787.IX Subsection "EXPORTED API SYMBOLS"
2820If you need to re-export the \s-1API\s0 (e.g. via a dll) and you need a list of 2788If you need to re-export the \s-1API\s0 (e.g. via a dll) and you need a list of
2821exported symbols, you can use the provided \fISymbol.*\fR files which list 2789exported symbols, you can use the provided \fISymbol.*\fR files which list
2822all public symbols, one per line: 2790all public symbols, one per line:
2823.Sp 2791.PP
2824.Vb 2 2792.Vb 2
2825\& Symbols.ev for libev proper 2793\& Symbols.ev for libev proper
2826\& Symbols.event for the libevent emulation 2794\& Symbols.event for the libevent emulation
2827.Ve 2795.Ve
2828.Sp 2796.PP
2829This can also be used to rename all public symbols to avoid clashes with 2797This can also be used to rename all public symbols to avoid clashes with
2830multiple versions of libev linked together (which is obviously bad in 2798multiple versions of libev linked together (which is obviously bad in
2831itself, but sometimes it is inconvinient to avoid this). 2799itself, but sometimes it is inconvinient to avoid this).
2832.Sp 2800.PP
2833A sed command like this will create wrapper \f(CW\*(C`#define\*(C'\fR's that you need to 2801A sed command like this will create wrapper \f(CW\*(C`#define\*(C'\fR's that you need to
2834include before including \fIev.h\fR: 2802include before including \fIev.h\fR:
2835.Sp 2803.PP
2836.Vb 1 2804.Vb 1
2837\& <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h 2805\& <Symbols.ev sed \-e "s/.*/#define & myprefix_&/" >wrap.h
2838.Ve 2806.Ve
2839.Sp 2807.PP
2840This would create a file \fIwrap.h\fR which essentially looks like this: 2808This would create a file \fIwrap.h\fR which essentially looks like this:
2841.Sp 2809.PP
2842.Vb 4 2810.Vb 4
2843\& #define ev_backend myprefix_ev_backend 2811\& #define ev_backend myprefix_ev_backend
2844\& #define ev_check_start myprefix_ev_check_start 2812\& #define ev_check_start myprefix_ev_check_start
2845\& #define ev_check_stop myprefix_ev_check_stop 2813\& #define ev_check_stop myprefix_ev_check_stop
2846\& ... 2814\& ...
… …
2852(<http://software.schmorp.de/pkg/EV.html>). It has the libev files in 2820(<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
2853the \fIlibev/\fR subdirectory and includes them in the \fI\s-1EV/EVAPI\s0.h\fR (public 2821the \fIlibev/\fR subdirectory and includes them in the \fI\s-1EV/EVAPI\s0.h\fR (public
2854interface) and \fI\s-1EV\s0.xs\fR (implementation) files. Only the \fI\s-1EV\s0.xs\fR file 2822interface) and \fI\s-1EV\s0.xs\fR (implementation) files. Only the \fI\s-1EV\s0.xs\fR file
2855will be compiled. It is pretty complex because it provides its own header 2823will be compiled. It is pretty complex because it provides its own header
2856file. 2824file.
2857.Sp 2825.PP
2858The usage in rxvt-unicode is simpler. It has a \fIev_cpp.h\fR header file 2826The usage in rxvt-unicode is simpler. It has a \fIev_cpp.h\fR header file
2859that everybody includes and which overrides some configure choices: 2827that everybody includes and which overrides some configure choices:
2860.Sp 2828.PP
2861.Vb 9 2829.Vb 9
2862\& #define EV_MINIMAL 1 2830\& #define EV_MINIMAL 1
2863\& #define EV_USE_POLL 0 2831\& #define EV_USE_POLL 0
2864\& #define EV_MULTIPLICITY 0 2832\& #define EV_MULTIPLICITY 0
2865\& #define EV_PERIODIC_ENABLE 0 2833\& #define EV_PERIODIC_ENABLE 0
2866\& #define EV_STAT_ENABLE 0 2834\& #define EV_STAT_ENABLE 0
2867\& #define EV_FORK_ENABLE 0 2835\& #define EV_FORK_ENABLE 0
2868\& #define EV_CONFIG_H <config.h> 2836\& #define EV_CONFIG_H <config.h>
2869\& #define EV_MINPRI 0 2837\& #define EV_MINPRI 0
2870\& #define EV_MAXPRI 0 2838\& #define EV_MAXPRI 0
2871.Ve 2839\&
2872.Sp
2873.Vb 1
2874\& #include "ev++.h" 2840\& #include "ev++.h"
2875.Ve 2841.Ve
2876.Sp 2842.PP
2877And a \fIev_cpp.C\fR implementation file that contains libev proper and is compiled: 2843And a \fIev_cpp.C\fR implementation file that contains libev proper and is compiled:
2878.Sp 2844.PP
2879.Vb 2 2845.Vb 2
2880\& #include "ev_cpp.h" 2846\& #include "ev_cpp.h"
2881\& #include "ev.c" 2847\& #include "ev.c"
2882.Ve 2848.Ve
2883.SH "COMPLEXITIES" 2849.SH "COMPLEXITIES"
2884.IX Header "COMPLEXITIES" 2850.IX Header "COMPLEXITIES"
2885In this section the complexities of (many of) the algorithms used inside 2851In this section the complexities of (many of) the algorithms used inside
2886libev will be explained. For complexity discussions about backends see the 2852libev will be explained. For complexity discussions about backends see the
2887documentation for \f(CW\*(C`ev_default_init\*(C'\fR. 2853documentation for \f(CW\*(C`ev_default_init\*(C'\fR.
2888.Sp 2854.PP
2889All of the following are about amortised time: If an array needs to be 2855All of the following are about amortised time: If an array needs to be
2890extended, libev needs to realloc and move the whole array, but this 2856extended, libev needs to realloc and move the whole array, but this
2891happens asymptotically never with higher number of elements, so O(1) might 2857happens asymptotically never with higher number of elements, so O(1) might
2892mean it might do a lengthy realloc operation in rare cases, but on average 2858mean it might do a lengthy realloc operation in rare cases, but on average
2893it is much faster and asymptotically approaches constant time. 2859it is much faster and asymptotically approaches constant time.
2894.RS 4
2895.IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4 2860.IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4
2896.IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 2861.IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)"
2897This means that, when you have a watcher that triggers in one hour and 2862This means that, when you have a watcher that triggers in one hour and
2898there are 100 watchers that would trigger before that then inserting will 2863there are 100 watchers that would trigger before that then inserting will
2899have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers. 2864have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers.
… …
2930.PD 2895.PD
2931Priorities are implemented by allocating some space for each 2896Priorities are implemented by allocating some space for each
2932priority. When doing priority-based operations, libev usually has to 2897priority. When doing priority-based operations, libev usually has to
2933linearly search all the priorities, but starting/stopping and activating 2898linearly search all the priorities, but starting/stopping and activating
2934watchers becomes O(1) w.r.t. prioritiy handling. 2899watchers becomes O(1) w.r.t. prioritiy handling.
2935.RE 2900.SH "Win32 platform limitations and workarounds"
2936.RS 4 2901.IX Header "Win32 platform limitations and workarounds"
2902Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev
2903requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0
2904model. Libev still offers limited functionality on this platform in
2905the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket
2906descriptors. This only applies when using Win32 natively, not when using
2907e.g. cygwin.
2908.PP
2909There is no supported compilation method available on windows except
2910embedding it into other applications.
2911.PP
2912Due to the many, low, and arbitrary limits on the win32 platform and the
2913abysmal performance of winsockets, using a large number of sockets is not
2914recommended (and not reasonable). If your program needs to use more than
2915a hundred or so sockets, then likely it needs to use a totally different
2916implementation for windows, as libev offers the \s-1POSIX\s0 model, which cannot
2917be implemented efficiently on windows (microsoft monopoly games).
2918.IP "The winsocket select function" 4
2919.IX Item "The winsocket select function"
2920The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it requires
2921socket \fIhandles\fR and not socket \fIfile descriptors\fR. This makes select
2922very inefficient, and also requires a mapping from file descriptors
2923to socket handles. See the discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR,
2924\&\f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and \f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor
2925symbols for more info.
2926.Sp
2927The configuration for a \*(L"naked\*(R" win32 using the microsoft runtime
2928libraries and raw winsocket select is:
2929.Sp
2930.Vb 2
2931\& #define EV_USE_SELECT 1
2932\& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
2933.Ve
2934.Sp
2935Note that winsockets handling of fd sets is O(n), so you can easily get a
2936complexity in the O(nA\*^X) range when using win32.
2937.IP "Limited number of file descriptors" 4
2938.IX Item "Limited number of file descriptors"
2939Windows has numerous arbitrary (and low) limits on things. Early versions
2940of winsocket's select only supported waiting for a max. of \f(CW64\fR handles
2941(probably owning to the fact that all windows kernels can only wait for
2942\&\f(CW64\fR things at the same time internally; microsoft recommends spawning a
2943chain of threads and wait for 63 handles and the previous thread in each).
2944.Sp
2945Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR
2946to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select
2947call (which might be in libev or elsewhere, for example, perl does its own
2948select emulation on windows).
2949.Sp
2950Another limit is the number of file descriptors in the microsoft runtime
2951libraries, which by default is \f(CW64\fR (there must be a hidden \fI64\fR fetish
2952or something like this inside microsoft). You can increase this by calling
2953\&\f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR (another
2954arbitrary limit), but is broken in many versions of the microsoft runtime
2955libraries.
2956.Sp
2957This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on
2958windows version and/or the phase of the moon). To get more, you need to
2959wrap all I/O functions and provide your own fd management, but the cost of
2960calling select (O(nA\*^X)) will likely make this unworkable.
2937.SH "AUTHOR" 2961.SH "AUTHOR"
2938.IX Header "AUTHOR" 2962.IX Header "AUTHOR"
2939Marc Lehmann <libev@schmorp.de>. 2963Marc Lehmann <libev@schmorp.de>.
2964.SH "POD ERRORS"
2965.IX Header "POD ERRORS"
2966Hey! \fBThe above document had some coding errors, which are explained below:\fR
2967.IP "Around line 2686:" 4
2968.IX Item "Around line 2686:"
2969You forgot a '=back' before '=head2'

Diff Legend

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