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

Comparing libev/ev.pod (file contents):
Revision 1.8 by root, Mon Nov 12 08:20:02 2007 UTC vs.
Revision 1.18 by root, Mon Nov 12 09:01:12 2007 UTC

39F<README.embed> in the libev distribution. If libev was configured without 39F<README.embed> in the libev distribution. If libev was configured without
40support for multiple event loops, then all functions taking an initial 40support for multiple event loops, then all functions taking an initial
41argument of name C<loop> (which is always of type C<struct ev_loop *>) 41argument of name C<loop> (which is always of type C<struct ev_loop *>)
42will not have this argument. 42will not have this argument.
43 43
44=head1 TIME AND OTHER GLOBAL FUNCTIONS 44=head1 TIME REPRESENTATION
45 45
46Libev represents time as a single floating point number, representing the 46Libev represents time as a single floating point number, representing the
47(fractional) number of seconds since the (POSIX) epoch (somewhere near 47(fractional) number of seconds since the (POSIX) epoch (somewhere near
48the beginning of 1970, details are complicated, don't ask). This type is 48the beginning of 1970, details are complicated, don't ask). This type is
49called C<ev_tstamp>, which is what you should use too. It usually aliases 49called C<ev_tstamp>, which is what you should use too. It usually aliases
50to the double type in C. 50to the double type in C.
51 51
52=head1 GLOBAL FUNCTIONS
53
54These functions can be called anytime, even before initialising the
55library in any way.
56
52=over 4 57=over 4
53 58
54=item ev_tstamp ev_time () 59=item ev_tstamp ev_time ()
55 60
56Returns the current time as libev would use it. 61Returns the current time as libev would use it.
63you linked against by calling the functions C<ev_version_major> and 68you linked against by calling the functions C<ev_version_major> and
64C<ev_version_minor>. If you want, you can compare against the global 69C<ev_version_minor>. If you want, you can compare against the global
65symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the 70symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
66version of the library your program was compiled against. 71version of the library your program was compiled against.
67 72
68Usually, its a good idea to terminate if the major versions mismatch, 73Usually, it's a good idea to terminate if the major versions mismatch,
69as this indicates an incompatible change. Minor versions are usually 74as this indicates an incompatible change. Minor versions are usually
70compatible to older versions, so a larger minor version alone is usually 75compatible to older versions, so a larger minor version alone is usually
71not a problem. 76not a problem.
72 77
73=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 78=item ev_set_allocator (void *(*cb)(void *ptr, long size))
99An event loop is described by a C<struct ev_loop *>. The library knows two 104An event loop is described by a C<struct ev_loop *>. The library knows two
100types of such loops, the I<default> loop, which supports signals and child 105types of such loops, the I<default> loop, which supports signals and child
101events, and dynamically created loops which do not. 106events, and dynamically created loops which do not.
102 107
103If you use threads, a common model is to run the default event loop 108If you use threads, a common model is to run the default event loop
104in your main thread (or in a separate thrad) and for each thread you 109in your main thread (or in a separate thread) and for each thread you
105create, you also create another event loop. Libev itself does no locking 110create, you also create another event loop. Libev itself does no locking
106whatsoever, so if you mix calls to the same event loop in different 111whatsoever, so if you mix calls to the same event loop in different
107threads, make sure you lock (this is usually a bad idea, though, even if 112threads, make sure you lock (this is usually a bad idea, though, even if
108done correctly, because its hideous and inefficient). 113done correctly, because it's hideous and inefficient).
109 114
110=over 4 115=over 4
111 116
112=item struct ev_loop *ev_default_loop (unsigned int flags) 117=item struct ev_loop *ev_default_loop (unsigned int flags)
113 118
124 129
125It supports the following flags: 130It supports the following flags:
126 131
127=over 4 132=over 4
128 133
129=item EVFLAG_AUTO 134=item C<EVFLAG_AUTO>
130 135
131The default flags value. Use this if you have no clue (its the right 136The default flags value. Use this if you have no clue (it's the right
132thing, believe me). 137thing, believe me).
133 138
134=item EVFLAG_NOENV 139=item C<EVFLAG_NOENV>
135 140
136If this flag bit is ored into the flag value (or the program runs setuid 141If this flag bit is ored into the flag value (or the program runs setuid
137or setgid) then libev will I<not> look at the environment variable 142or setgid) then libev will I<not> look at the environment variable
138C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 143C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
139override the flags completely if it is found in the environment. This is 144override the flags completely if it is found in the environment. This is
140useful to try out specific backends to test their performance, or to work 145useful to try out specific backends to test their performance, or to work
141around bugs. 146around bugs.
142 147
143=item EVMETHOD_SELECT portable select backend 148=item C<EVMETHOD_SELECT> (portable select backend)
144 149
145=item EVMETHOD_POLL poll backend (everywhere except windows) 150=item C<EVMETHOD_POLL> (poll backend, available everywhere except on windows)
146 151
147=item EVMETHOD_EPOLL linux only 152=item C<EVMETHOD_EPOLL> (linux only)
148 153
149=item EVMETHOD_KQUEUE some bsds only 154=item C<EVMETHOD_KQUEUE> (some bsds only)
150 155
151=item EVMETHOD_DEVPOLL solaris 8 only 156=item C<EVMETHOD_DEVPOLL> (solaris 8 only)
152 157
153=item EVMETHOD_PORT solaris 10 only 158=item C<EVMETHOD_PORT> (solaris 10 only)
154 159
155If one or more of these are ored into the flags value, then only these 160If one or more of these are ored into the flags value, then only these
156backends will be tried (in the reverse order as given here). If one are 161backends will be tried (in the reverse order as given here). If one are
157specified, any backend will do. 162specified, any backend will do.
158 163
167 172
168=item ev_default_destroy () 173=item ev_default_destroy ()
169 174
170Destroys the default loop again (frees all memory and kernel state 175Destroys the default loop again (frees all memory and kernel state
171etc.). This stops all registered event watchers (by not touching them in 176etc.). This stops all registered event watchers (by not touching them in
172any way whatsoever, although you cnanot rely on this :). 177any way whatsoever, although you cannot rely on this :).
173 178
174=item ev_loop_destroy (loop) 179=item ev_loop_destroy (loop)
175 180
176Like C<ev_default_destroy>, but destroys an event loop created by an 181Like C<ev_default_destroy>, but destroys an event loop created by an
177earlier call to C<ev_loop_new>. 182earlier call to C<ev_loop_new>.
185 190
186You I<must> call this function after forking if and only if you want to 191You I<must> call this function after forking if and only if you want to
187use the event library in both processes. If you just fork+exec, you don't 192use the event library in both processes. If you just fork+exec, you don't
188have to call it. 193have to call it.
189 194
190The function itself is quite fast and its usually not a problem to call 195The function itself is quite fast and it's usually not a problem to call
191it just in case after a fork. To make this easy, the function will fit in 196it just in case after a fork. To make this easy, the function will fit in
192quite nicely into a call to C<pthread_atfork>: 197quite nicely into a call to C<pthread_atfork>:
193 198
194 pthread_atfork (0, 0, ev_default_fork); 199 pthread_atfork (0, 0, ev_default_fork);
195 200
202=item unsigned int ev_method (loop) 207=item unsigned int ev_method (loop)
203 208
204Returns one of the C<EVMETHOD_*> flags indicating the event backend in 209Returns one of the C<EVMETHOD_*> flags indicating the event backend in
205use. 210use.
206 211
207=item ev_tstamp = ev_now (loop) 212=item ev_tstamp ev_now (loop)
208 213
209Returns the current "event loop time", which is the time the event loop 214Returns the current "event loop time", which is the time the event loop
210got events and started processing them. This timestamp does not change 215got events and started processing them. This timestamp does not change
211as long as callbacks are being processed, and this is also the base time 216as long as callbacks are being processed, and this is also the base time
212used for relative timers. You can treat it as the timestamp of the event 217used for relative timers. You can treat it as the timestamp of the event
221If the flags argument is specified as 0, it will not return until either 226If the flags argument is specified as 0, it will not return until either
222no event watchers are active anymore or C<ev_unloop> was called. 227no event watchers are active anymore or C<ev_unloop> was called.
223 228
224A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 229A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
225those events and any outstanding ones, but will not block your process in 230those events and any outstanding ones, but will not block your process in
226case there are no events. 231case there are no events and will return after one iteration of the loop.
227 232
228A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 233A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
229neccessary) and will handle those and any outstanding ones. It will block 234neccessary) and will handle those and any outstanding ones. It will block
230your process until at least one new event arrives. 235your process until at least one new event arrives, and will return after
236one iteration of the loop.
231 237
232This flags value could be used to implement alternative looping 238This flags value could be used to implement alternative looping
233constructs, but the C<prepare> and C<check> watchers provide a better and 239constructs, but the C<prepare> and C<check> watchers provide a better and
234more generic mechanism. 240more generic mechanism.
235 241
236=item ev_unloop (loop, how) 242=item ev_unloop (loop, how)
237 243
238Can be used to make a call to C<ev_loop> return early. The C<how> argument 244Can be used to make a call to C<ev_loop> return early (but only after it
245has processed all outstanding events). The C<how> argument must be either
239must be either C<EVUNLOOP_ONCE>, which will make the innermost C<ev_loop> 246C<EVUNLOOP_ONCE>, which will make the innermost C<ev_loop> call return, or
240call return, or C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> 247C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
241calls return.
242 248
243=item ev_ref (loop) 249=item ev_ref (loop)
244 250
245=item ev_unref (loop) 251=item ev_unref (loop)
246 252
247Ref/unref can be used to add or remove a refcount on the event loop: Every 253Ref/unref can be used to add or remove a reference count on the event
248watcher keeps one reference. If you have a long-runing watcher you never 254loop: Every watcher keeps one reference, and as long as the reference
249unregister that should not keep ev_loop from running, ev_unref() after 255count is nonzero, C<ev_loop> will not return on its own. If you have
250starting, and ev_ref() before stopping it. Libev itself uses this for 256a watcher you never unregister that should not keep C<ev_loop> from
251example for its internal signal pipe: It is not visible to you as a user 257returning, ev_unref() after starting, and ev_ref() before stopping it. For
252and should not keep C<ev_loop> from exiting if the work is done. It is 258example, libev itself uses this for its internal signal pipe: It is not
253also an excellent way to do this for generic recurring timers or from 259visible to the libev user and should not keep C<ev_loop> from exiting if
254within third-party libraries. Just remember to unref after start and ref 260no event watchers registered by it are active. It is also an excellent
255before stop. 261way to do this for generic recurring timers or from within third-party
262libraries. Just remember to I<unref after start> and I<ref before stop>.
256 263
257=back 264=back
258 265
259=head1 ANATOMY OF A WATCHER 266=head1 ANATOMY OF A WATCHER
260 267
261A watcher is a structure that you create and register to record your 268A watcher is a structure that you create and register to record your
262interest in some event. For instance, if you want to wait for STDIN to 269interest in some event. For instance, if you want to wait for STDIN to
263become readable, you would create an ev_io watcher for that: 270become readable, you would create an C<ev_io> watcher for that:
264 271
265 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 272 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
266 { 273 {
267 ev_io_stop (w); 274 ev_io_stop (w);
268 ev_unloop (loop, EVUNLOOP_ALL); 275 ev_unloop (loop, EVUNLOOP_ALL);
297 304
298As long as your watcher is active (has been started but not stopped) you 305As long as your watcher is active (has been started but not stopped) you
299must not touch the values stored in it. Most specifically you must never 306must not touch the values stored in it. Most specifically you must never
300reinitialise it or call its set method. 307reinitialise it or call its set method.
301 308
302You cna check whether an event is active by calling the C<ev_is_active 309You can check whether an event is active by calling the C<ev_is_active
303(watcher *)> macro. To see whether an event is outstanding (but the 310(watcher *)> macro. To see whether an event is outstanding (but the
304callback for it has not been called yet) you cna use the C<ev_is_pending 311callback for it has not been called yet) you can use the C<ev_is_pending
305(watcher *)> macro. 312(watcher *)> macro.
306 313
307Each and every callback receives the event loop pointer as first, the 314Each and every callback receives the event loop pointer as first, the
308registered watcher structure as second, and a bitset of received events as 315registered watcher structure as second, and a bitset of received events as
309third argument. 316third argument.
310 317
311The rceeived events usually include a single bit per event type received 318The received events usually include a single bit per event type received
312(you can receive multiple events at the same time). The possible bit masks 319(you can receive multiple events at the same time). The possible bit masks
313are: 320are:
314 321
315=over 4 322=over 4
316 323
317=item EV_READ 324=item C<EV_READ>
318 325
319=item EV_WRITE 326=item C<EV_WRITE>
320 327
321The file descriptor in the ev_io watcher has become readable and/or 328The file descriptor in the C<ev_io> watcher has become readable and/or
322writable. 329writable.
323 330
324=item EV_TIMEOUT 331=item C<EV_TIMEOUT>
325 332
326The ev_timer watcher has timed out. 333The C<ev_timer> watcher has timed out.
327 334
328=item EV_PERIODIC 335=item C<EV_PERIODIC>
329 336
330The ev_periodic watcher has timed out. 337The C<ev_periodic> watcher has timed out.
331 338
332=item EV_SIGNAL 339=item C<EV_SIGNAL>
333 340
334The signal specified in the ev_signal watcher has been received by a thread. 341The signal specified in the C<ev_signal> watcher has been received by a thread.
335 342
336=item EV_CHILD 343=item C<EV_CHILD>
337 344
338The pid specified in the ev_child watcher has received a status change. 345The pid specified in the C<ev_child> watcher has received a status change.
339 346
340=item EV_IDLE 347=item C<EV_IDLE>
341 348
342The ev_idle watcher has determined that you have nothing better to do. 349The C<ev_idle> watcher has determined that you have nothing better to do.
343 350
344=item EV_PREPARE 351=item C<EV_PREPARE>
345 352
346=item EV_CHECK 353=item C<EV_CHECK>
347 354
348All ev_prepare watchers are invoked just I<before> C<ev_loop> starts 355All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts
349to gather new events, and all ev_check watchers are invoked just after 356to gather new events, and all C<ev_check> watchers are invoked just after
350C<ev_loop> has gathered them, but before it invokes any callbacks for any 357C<ev_loop> has gathered them, but before it invokes any callbacks for any
351received events. Callbacks of both watcher types can start and stop as 358received events. Callbacks of both watcher types can start and stop as
352many watchers as they want, and all of them will be taken into account 359many watchers as they want, and all of them will be taken into account
353(for example, a ev_prepare watcher might start an idle watcher to keep 360(for example, a C<ev_prepare> watcher might start an idle watcher to keep
354C<ev_loop> from blocking). 361C<ev_loop> from blocking).
355 362
356=item EV_ERROR 363=item C<EV_ERROR>
357 364
358An unspecified error has occured, the watcher has been stopped. This might 365An unspecified error has occured, the watcher has been stopped. This might
359happen because the watcher could not be properly started because libev 366happen because the watcher could not be properly started because libev
360ran out of memory, a file descriptor was found to be closed or any other 367ran out of memory, a file descriptor was found to be closed or any other
361problem. You best act on it by reporting the problem and somehow coping 368problem. You best act on it by reporting the problem and somehow coping
370=back 377=back
371 378
372=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 379=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
373 380
374Each watcher has, by default, a member C<void *data> that you can change 381Each watcher has, by default, a member C<void *data> that you can change
375and read at any time, libev will completely ignore it. This cna be used 382and read at any time, libev will completely ignore it. This can be used
376to associate arbitrary data with your watcher. If you need more data and 383to associate arbitrary data with your watcher. If you need more data and
377don't want to allocate memory and store a pointer to it in that data 384don't want to allocate memory and store a pointer to it in that data
378member, you can also "subclass" the watcher type and provide your own 385member, you can also "subclass" the watcher type and provide your own
379data: 386data:
380 387
402=head1 WATCHER TYPES 409=head1 WATCHER TYPES
403 410
404This section describes each watcher in detail, but will not repeat 411This section describes each watcher in detail, but will not repeat
405information given in the last section. 412information given in the last section.
406 413
407=head2 struct ev_io - is my file descriptor readable or writable 414=head2 C<ev_io> - is this file descriptor readable or writable
408 415
409I/O watchers check whether a file descriptor is readable or writable 416I/O watchers check whether a file descriptor is readable or writable
410in each iteration of the event loop (This behaviour is called 417in each iteration of the event loop (This behaviour is called
411level-triggering because you keep receiving events as long as the 418level-triggering because you keep receiving events as long as the
412condition persists. Remember you cna stop the watcher if you don't want to 419condition persists. Remember you can stop the watcher if you don't want to
413act on the event and neither want to receive future events). 420act on the event and neither want to receive future events).
414 421
415In general you can register as many read and/or write event watchers oer 422In general you can register as many read and/or write event watchers oer
416fd as you want (as long as you don't confuse yourself). Setting all file 423fd as you want (as long as you don't confuse yourself). Setting all file
417descriptors to non-blocking mode is also usually a good idea (but not 424descriptors to non-blocking mode is also usually a good idea (but not
430 437
431=item ev_io_init (ev_io *, callback, int fd, int events) 438=item ev_io_init (ev_io *, callback, int fd, int events)
432 439
433=item ev_io_set (ev_io *, int fd, int events) 440=item ev_io_set (ev_io *, int fd, int events)
434 441
435Configures an ev_io watcher. The fd is the file descriptor to rceeive 442Configures an C<ev_io> watcher. The fd is the file descriptor to rceeive
436events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ | 443events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ |
437EV_WRITE> to receive the given events. 444EV_WRITE> to receive the given events.
438 445
439=back 446=back
440 447
441=head2 struct ev_timer - relative and optionally recurring timeouts 448=head2 C<ev_timer> - relative and optionally recurring timeouts
442 449
443Timer watchers are simple relative timers that generate an event after a 450Timer watchers are simple relative timers that generate an event after a
444given time, and optionally repeating in regular intervals after that. 451given time, and optionally repeating in regular intervals after that.
445 452
446The timers are based on real time, that is, if you register an event that 453The timers are based on real time, that is, if you register an event that
447times out after an hour and youreset your system clock to last years 454times out after an hour and youreset your system clock to last years
448time, it will still time out after (roughly) and hour. "Roughly" because 455time, it will still time out after (roughly) and hour. "Roughly" because
449detecting time jumps is hard, and soem inaccuracies are unavoidable (the 456detecting time jumps is hard, and soem inaccuracies are unavoidable (the
450monotonic clock option helps a lot here). 457monotonic clock option helps a lot here).
451 458
459The relative timeouts are calculated relative to the C<ev_now ()>
460time. This is usually the right thing as this timestamp refers to the time
461of the event triggering whatever timeout you are modifying/starting. If
462you suspect event processing to be delayed and you *need* to base the timeout
463ion the current time, use something like this to adjust for this:
464
465 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
466
452=over 4 467=over 4
453 468
454=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 469=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
455 470
456=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) 471=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
478 493
479This sounds a bit complicated, but here is a useful and typical 494This sounds a bit complicated, but here is a useful and typical
480example: Imagine you have a tcp connection and you want a so-called idle 495example: Imagine you have a tcp connection and you want a so-called idle
481timeout, that is, you want to be called when there have been, say, 60 496timeout, that is, you want to be called when there have been, say, 60
482seconds of inactivity on the socket. The easiest way to do this is to 497seconds of inactivity on the socket. The easiest way to do this is to
483configure an ev_timer with after=repeat=60 and calling ev_timer_again each 498configure an C<ev_timer> with after=repeat=60 and calling ev_timer_again each
484time you successfully read or write some data. If you go into an idle 499time you successfully read or write some data. If you go into an idle
485state where you do not expect data to travel on the socket, you can stop 500state where you do not expect data to travel on the socket, you can stop
486the timer, and again will automatically restart it if need be. 501the timer, and again will automatically restart it if need be.
487 502
488=back 503=back
489 504
490=head2 ev_periodic - to cron or not to cron it 505=head2 C<ev_periodic> - to cron or not to cron
491 506
492Periodic watchers are also timers of a kind, but they are very versatile 507Periodic watchers are also timers of a kind, but they are very versatile
493(and unfortunately a bit complex). 508(and unfortunately a bit complex).
494 509
495Unlike ev_timer's, they are not based on real time (or relative time) 510Unlike C<ev_timer>'s, they are not based on real time (or relative time)
496but on wallclock time (absolute time). You can tell a periodic watcher 511but on wallclock time (absolute time). You can tell a periodic watcher
497to trigger "at" some specific point in time. For example, if you tell a 512to trigger "at" some specific point in time. For example, if you tell a
498periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now () 513periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now ()
499+ 10.>) and then reset your system clock to the last year, then it will 514+ 10.>) and then reset your system clock to the last year, then it will
500take a year to trigger the event (unlike an ev_timer, which would trigger 515take a year to trigger the event (unlike an C<ev_timer>, which would trigger
501roughly 10 seconds later and of course not if you reset your system time 516roughly 10 seconds later and of course not if you reset your system time
502again). 517again).
503 518
504They can also be used to implement vastly more complex timers, such as 519They can also be used to implement vastly more complex timers, such as
505triggering an event on eahc midnight, local time. 520triggering an event on eahc midnight, local time.
534 549
535 ev_periodic_set (&periodic, 0., 3600., 0); 550 ev_periodic_set (&periodic, 0., 3600., 0);
536 551
537This doesn't mean there will always be 3600 seconds in between triggers, 552This doesn't mean there will always be 3600 seconds in between triggers,
538but only that the the callback will be called when the system time shows a 553but only that the the callback will be called when the system time shows a
539full hour (UTC), or more correct, when the system time is evenly divisible 554full hour (UTC), or more correctly, when the system time is evenly divisible
540by 3600. 555by 3600.
541 556
542Another way to think about it (for the mathematically inclined) is that 557Another way to think about it (for the mathematically inclined) is that
543ev_periodic will try to run the callback in this mode at the next possible 558C<ev_periodic> will try to run the callback in this mode at the next possible
544time where C<time = at (mod interval)>, regardless of any time jumps. 559time where C<time = at (mod interval)>, regardless of any time jumps.
545 560
546=item * manual reschedule mode (reschedule_cb = callback) 561=item * manual reschedule mode (reschedule_cb = callback)
547 562
548In this mode the values for C<interval> and C<at> are both being 563In this mode the values for C<interval> and C<at> are both being
549ignored. Instead, each time the periodic watcher gets scheduled, the 564ignored. Instead, each time the periodic watcher gets scheduled, the
550reschedule callback will be called with the watcher as first, and the 565reschedule callback will be called with the watcher as first, and the
551current time as second argument. 566current time as second argument.
552 567
553NOTE: I<This callback MUST NOT stop or destroy the periodic or any other 568NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
554periodic watcher, ever, or make any event loop modificstions>. If you need 569ever, or make any event loop modifications>. If you need to stop it,
555to stop it, return 1e30 (or so, fudge fudge) and stop it afterwards. 570return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
571starting a prepare watcher).
556 572
557Its prototype is c<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 573Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
558ev_tstamp now)>, e.g.: 574ev_tstamp now)>, e.g.:
559 575
560 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 576 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
561 { 577 {
562 return now + 60.; 578 return now + 60.;
565It must return the next time to trigger, based on the passed time value 581It must return the next time to trigger, based on the passed time value
566(that is, the lowest time value larger than to the second argument). It 582(that is, the lowest time value larger than to the second argument). It
567will usually be called just before the callback will be triggered, but 583will usually be called just before the callback will be triggered, but
568might be called at other times, too. 584might be called at other times, too.
569 585
586NOTE: I<< This callback must always return a time that is later than the
587passed C<now> value >>. Not even C<now> itself will do, it must be larger.
588
570This can be used to create very complex timers, such as a timer that 589This can be used to create very complex timers, such as a timer that
571triggers on each midnight, local time. To do this, you would calculate the 590triggers on each midnight, local time. To do this, you would calculate the
572next midnight after C<now> and return the timestamp value for this. How you do this 591next midnight after C<now> and return the timestamp value for this. How you do this
573is, again, up to you (but it is not trivial). 592is, again, up to you (but it is not trivial).
574 593
581a different time than the last time it was called (e.g. in a crond like 600a different time than the last time it was called (e.g. in a crond like
582program when the crontabs have changed). 601program when the crontabs have changed).
583 602
584=back 603=back
585 604
586=head2 ev_signal - signal me when a signal gets signalled 605=head2 C<ev_signal> - signal me when a signal gets signalled
587 606
588Signal watchers will trigger an event when the process receives a specific 607Signal watchers will trigger an event when the process receives a specific
589signal one or more times. Even though signals are very asynchronous, libev 608signal one or more times. Even though signals are very asynchronous, libev
590will try its best to deliver signals synchronously, i.e. as part of the 609will try it's best to deliver signals synchronously, i.e. as part of the
591normal event processing, like any other event. 610normal event processing, like any other event.
592 611
593You cna configure as many watchers as you like per signal. Only when the 612You can configure as many watchers as you like per signal. Only when the
594first watcher gets started will libev actually register a signal watcher 613first watcher gets started will libev actually register a signal watcher
595with the kernel (thus it coexists with your own signal handlers as long 614with the kernel (thus it coexists with your own signal handlers as long
596as you don't register any with libev). Similarly, when the last signal 615as you don't register any with libev). Similarly, when the last signal
597watcher for a signal is stopped libev will reset the signal handler to 616watcher for a signal is stopped libev will reset the signal handler to
598SIG_DFL (regardless of what it was set to before). 617SIG_DFL (regardless of what it was set to before).
606Configures the watcher to trigger on the given signal number (usually one 625Configures the watcher to trigger on the given signal number (usually one
607of the C<SIGxxx> constants). 626of the C<SIGxxx> constants).
608 627
609=back 628=back
610 629
611=head2 ev_child - wait for pid status changes 630=head2 C<ev_child> - wait for pid status changes
612 631
613Child watchers trigger when your process receives a SIGCHLD in response to 632Child watchers trigger when your process receives a SIGCHLD in response to
614some child status changes (most typically when a child of yours dies). 633some child status changes (most typically when a child of yours dies).
615 634
616=over 4 635=over 4
620=item ev_child_set (ev_child *, int pid) 639=item ev_child_set (ev_child *, int pid)
621 640
622Configures the watcher to wait for status changes of process C<pid> (or 641Configures the watcher to wait for status changes of process C<pid> (or
623I<any> process if C<pid> is specified as C<0>). The callback can look 642I<any> process if C<pid> is specified as C<0>). The callback can look
624at the C<rstatus> member of the C<ev_child> watcher structure to see 643at the C<rstatus> member of the C<ev_child> watcher structure to see
625the status word (use the macros from C<sys/wait.h>). The C<rpid> member 644the status word (use the macros from C<sys/wait.h> and see your systems
626contains the pid of the process causing the status change. 645C<waitpid> documentation). The C<rpid> member contains the pid of the
646process causing the status change.
627 647
628=back 648=back
629 649
630=head2 ev_idle - when you've got nothing better to do 650=head2 C<ev_idle> - when you've got nothing better to do
631 651
632Idle watchers trigger events when there are no other I/O or timer (or 652Idle watchers trigger events when there are no other events are pending
633periodic) events pending. That is, as long as your process is busy 653(prepare, check and other idle watchers do not count). That is, as long
634handling sockets or timeouts it will not be called. But when your process 654as your process is busy handling sockets or timeouts (or even signals,
635is idle all idle watchers are being called again and again - until 655imagine) it will not be triggered. But when your process is idle all idle
656watchers are being called again and again, once per event loop iteration -
636stopped, that is, or your process receives more events. 657until stopped, that is, or your process receives more events and becomes
658busy.
637 659
638The most noteworthy effect is that as long as any idle watchers are 660The most noteworthy effect is that as long as any idle watchers are
639active, the process will not block when waiting for new events. 661active, the process will not block when waiting for new events.
640 662
641Apart from keeping your process non-blocking (which is a useful 663Apart from keeping your process non-blocking (which is a useful
651kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 673kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
652believe me. 674believe me.
653 675
654=back 676=back
655 677
656=head2 prepare and check - your hooks into the event loop 678=head2 C<ev_prepare> and C<ev_check> - customise your event loop
657 679
658Prepare and check watchers usually (but not always) are used in 680Prepare and check watchers are usually (but not always) used in tandem:
659tandom. Prepare watchers get invoked before the process blocks and check 681Prepare watchers get invoked before the process blocks and check watchers
660watchers afterwards. 682afterwards.
661 683
662Their main purpose is to integrate other event mechanisms into libev. This 684Their main purpose is to integrate other event mechanisms into libev. This
663could be used, for example, to track variable changes, implement your own 685could be used, for example, to track variable changes, implement your own
664watchers, integrate net-snmp or a coroutine library and lots more. 686watchers, integrate net-snmp or a coroutine library and lots more.
665 687
666This is done by examining in each prepare call which file descriptors need 688This is done by examining in each prepare call which file descriptors need
667to be watched by the other library, registering ev_io watchers for them 689to be watched by the other library, registering C<ev_io> watchers for
668and starting an ev_timer watcher for any timeouts (many libraries provide 690them and starting an C<ev_timer> watcher for any timeouts (many libraries
669just this functionality). Then, in the check watcher you check for any 691provide just this functionality). Then, in the check watcher you check for
670events that occured (by making your callbacks set soem flags for example) 692any events that occured (by checking the pending status of all watchers
671and call back into the library. 693and stopping them) and call back into the library. The I/O and timer
694callbacks will never actually be called (but must be valid neverthelles,
695because you never know, you know?).
672 696
673As another example, the perl Coro module uses these hooks to integrate 697As another example, the Perl Coro module uses these hooks to integrate
674coroutines into libev programs, by yielding to other active coroutines 698coroutines into libev programs, by yielding to other active coroutines
675during each prepare and only letting the process block if no coroutines 699during each prepare and only letting the process block if no coroutines
676are ready to run. 700are ready to run (its actually more complicated, it only runs coroutines
701with priority higher than the event loop and one lower priority once,
702using idle watchers to keep the event loop from blocking if lower-priority
703coroutines exist, thus mapping low-priority coroutines to idle/background
704tasks).
677 705
678=over 4 706=over 4
679 707
680=item ev_prepare_init (ev_prepare *, callback) 708=item ev_prepare_init (ev_prepare *, callback)
681 709
682=item ev_check_init (ev_check *, callback) 710=item ev_check_init (ev_check *, callback)
683 711
684Initialises and configures the prepare or check watcher - they have no 712Initialises and configures the prepare or check watcher - they have no
685parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 713parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
686macros, but using them is utterly, utterly pointless. 714macros, but using them is utterly, utterly and completely pointless.
687 715
688=back 716=back
689 717
690=head1 OTHER FUNCTIONS 718=head1 OTHER FUNCTIONS
691 719
692There are some other fucntions of possible interest. Described. Here. Now. 720There are some other functions of possible interest. Described. Here. Now.
693 721
694=over 4 722=over 4
695 723
696=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 724=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
697 725
699callback on whichever event happens first and automatically stop both 727callback on whichever event happens first and automatically stop both
700watchers. This is useful if you want to wait for a single event on an fd 728watchers. This is useful if you want to wait for a single event on an fd
701or timeout without havign to allocate/configure/start/stop/free one or 729or timeout without havign to allocate/configure/start/stop/free one or
702more watchers yourself. 730more watchers yourself.
703 731
704If C<fd> is less than 0, then no I/O watcher will be started and events is 732If C<fd> is less than 0, then no I/O watcher will be started and events
705ignored. Otherwise, an ev_io watcher for the given C<fd> and C<events> set 733is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
706will be craeted and started. 734C<events> set will be craeted and started.
707 735
708If C<timeout> is less than 0, then no timeout watcher will be 736If C<timeout> is less than 0, then no timeout watcher will be
709started. Otherwise an ev_timer watcher with after = C<timeout> (and repeat 737started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
710= 0) will be started. 738repeat = 0) will be started. While C<0> is a valid timeout, it is of
739dubious value.
711 740
712The callback has the type C<void (*cb)(int revents, void *arg)> and 741The callback has the type C<void (*cb)(int revents, void *arg)> and gets
713gets passed an events set (normally a combination of EV_ERROR, EV_READ, 742passed an events set like normal event callbacks (with a combination of
714EV_WRITE or EV_TIMEOUT) and the C<arg> value passed to C<ev_once>: 743C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
744value passed to C<ev_once>:
715 745
716 static void stdin_ready (int revents, void *arg) 746 static void stdin_ready (int revents, void *arg)
717 { 747 {
718 if (revents & EV_TIMEOUT) 748 if (revents & EV_TIMEOUT)
719 /* doh, nothing entered */ 749 /* doh, nothing entered */;
720 else if (revents & EV_READ) 750 else if (revents & EV_READ)
721 /* stdin might have data for us, joy! */ 751 /* stdin might have data for us, joy! */;
722 } 752 }
723 753
724 ev_once (STDIN_FILENO, EV_READm 10., stdin_ready, 0); 754 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
725 755
726=item ev_feed_event (loop, watcher, int events) 756=item ev_feed_event (loop, watcher, int events)
727 757
728Feeds the given event set into the event loop, as if the specified event 758Feeds the given event set into the event loop, as if the specified event
729has happened for the specified watcher (which must be a pointer to an 759had happened for the specified watcher (which must be a pointer to an
730initialised but not necessarily active event watcher). 760initialised but not necessarily started event watcher).
731 761
732=item ev_feed_fd_event (loop, int fd, int revents) 762=item ev_feed_fd_event (loop, int fd, int revents)
733 763
734Feed an event on the given fd, as if a file descriptor backend detected it. 764Feed an event on the given fd, as if a file descriptor backend detected
765the given events it.
735 766
736=item ev_feed_signal_event (loop, int signum) 767=item ev_feed_signal_event (loop, int signum)
737 768
738Feed an event as if the given signal occured (loop must be the default loop!). 769Feed an event as if the given signal occured (loop must be the default loop!).
739 770

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines