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.21 by root, Mon Nov 12 09:07:10 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 I<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
573is, again, up to you (but it is not trivial). 592you do this is, again, up to you (but it is not trivial, which is the main
593reason I omitted it as an example).
574 594
575=back 595=back
576 596
577=item ev_periodic_again (loop, ev_periodic *) 597=item ev_periodic_again (loop, ev_periodic *)
578 598
581a different time than the last time it was called (e.g. in a crond like 601a different time than the last time it was called (e.g. in a crond like
582program when the crontabs have changed). 602program when the crontabs have changed).
583 603
584=back 604=back
585 605
586=head2 ev_signal - signal me when a signal gets signalled 606=head2 C<ev_signal> - signal me when a signal gets signalled
587 607
588Signal watchers will trigger an event when the process receives a specific 608Signal watchers will trigger an event when the process receives a specific
589signal one or more times. Even though signals are very asynchronous, libev 609signal 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 610will try it's best to deliver signals synchronously, i.e. as part of the
591normal event processing, like any other event. 611normal event processing, like any other event.
592 612
593You cna configure as many watchers as you like per signal. Only when the 613You can configure as many watchers as you like per signal. Only when the
594first watcher gets started will libev actually register a signal watcher 614first watcher gets started will libev actually register a signal watcher
595with the kernel (thus it coexists with your own signal handlers as long 615with 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 616as 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 617watcher for a signal is stopped libev will reset the signal handler to
598SIG_DFL (regardless of what it was set to before). 618SIG_DFL (regardless of what it was set to before).
606Configures the watcher to trigger on the given signal number (usually one 626Configures the watcher to trigger on the given signal number (usually one
607of the C<SIGxxx> constants). 627of the C<SIGxxx> constants).
608 628
609=back 629=back
610 630
611=head2 ev_child - wait for pid status changes 631=head2 C<ev_child> - wait for pid status changes
612 632
613Child watchers trigger when your process receives a SIGCHLD in response to 633Child watchers trigger when your process receives a SIGCHLD in response to
614some child status changes (most typically when a child of yours dies). 634some child status changes (most typically when a child of yours dies).
615 635
616=over 4 636=over 4
620=item ev_child_set (ev_child *, int pid) 640=item ev_child_set (ev_child *, int pid)
621 641
622Configures the watcher to wait for status changes of process C<pid> (or 642Configures 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 643I<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 644at 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 645the status word (use the macros from C<sys/wait.h> and see your systems
626contains the pid of the process causing the status change. 646C<waitpid> documentation). The C<rpid> member contains the pid of the
647process causing the status change.
627 648
628=back 649=back
629 650
630=head2 ev_idle - when you've got nothing better to do 651=head2 C<ev_idle> - when you've got nothing better to do
631 652
632Idle watchers trigger events when there are no other I/O or timer (or 653Idle watchers trigger events when there are no other events are pending
633periodic) events pending. That is, as long as your process is busy 654(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 655as your process is busy handling sockets or timeouts (or even signals,
635is idle all idle watchers are being called again and again - until 656imagine) it will not be triggered. But when your process is idle all idle
657watchers are being called again and again, once per event loop iteration -
636stopped, that is, or your process receives more events. 658until stopped, that is, or your process receives more events and becomes
659busy.
637 660
638The most noteworthy effect is that as long as any idle watchers are 661The most noteworthy effect is that as long as any idle watchers are
639active, the process will not block when waiting for new events. 662active, the process will not block when waiting for new events.
640 663
641Apart from keeping your process non-blocking (which is a useful 664Apart 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, 674kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
652believe me. 675believe me.
653 676
654=back 677=back
655 678
656=head2 prepare and check - your hooks into the event loop 679=head2 C<ev_prepare> and C<ev_check> - customise your event loop
657 680
658Prepare and check watchers usually (but not always) are used in 681Prepare and check watchers are usually (but not always) used in tandem:
659tandom. Prepare watchers get invoked before the process blocks and check 682prepare watchers get invoked before the process blocks and check watchers
660watchers afterwards. 683afterwards.
661 684
662Their main purpose is to integrate other event mechanisms into libev. This 685Their main purpose is to integrate other event mechanisms into libev. This
663could be used, for example, to track variable changes, implement your own 686could be used, for example, to track variable changes, implement your own
664watchers, integrate net-snmp or a coroutine library and lots more. 687watchers, integrate net-snmp or a coroutine library and lots more.
665 688
666This is done by examining in each prepare call which file descriptors need 689This 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 690to be watched by the other library, registering C<ev_io> watchers for
668and starting an ev_timer watcher for any timeouts (many libraries provide 691them and starting an C<ev_timer> watcher for any timeouts (many libraries
669just this functionality). Then, in the check watcher you check for any 692provide just this functionality). Then, in the check watcher you check for
670events that occured (by making your callbacks set soem flags for example) 693any events that occured (by checking the pending status of all watchers
671and call back into the library. 694and stopping them) and call back into the library. The I/O and timer
695callbacks will never actually be called (but must be valid nevertheless,
696because you never know, you know?).
672 697
673As another example, the perl Coro module uses these hooks to integrate 698As another example, the Perl Coro module uses these hooks to integrate
674coroutines into libev programs, by yielding to other active coroutines 699coroutines into libev programs, by yielding to other active coroutines
675during each prepare and only letting the process block if no coroutines 700during each prepare and only letting the process block if no coroutines
676are ready to run. 701are ready to run (it's actually more complicated: it only runs coroutines
702with priority higher than or equal to the event loop and one coroutine
703of lower priority, but only once, using idle watchers to keep the event
704loop from blocking if lower-priority coroutines are active, thus mapping
705low-priority coroutines to idle/background tasks).
677 706
678=over 4 707=over 4
679 708
680=item ev_prepare_init (ev_prepare *, callback) 709=item ev_prepare_init (ev_prepare *, callback)
681 710
682=item ev_check_init (ev_check *, callback) 711=item ev_check_init (ev_check *, callback)
683 712
684Initialises and configures the prepare or check watcher - they have no 713Initialises 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> 714parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
686macros, but using them is utterly, utterly pointless. 715macros, but using them is utterly, utterly and completely pointless.
687 716
688=back 717=back
689 718
690=head1 OTHER FUNCTIONS 719=head1 OTHER FUNCTIONS
691 720
692There are some other fucntions of possible interest. Described. Here. Now. 721There are some other functions of possible interest. Described. Here. Now.
693 722
694=over 4 723=over 4
695 724
696=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 725=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
697 726
699callback on whichever event happens first and automatically stop both 728callback 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 729watchers. 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 730or timeout without havign to allocate/configure/start/stop/free one or
702more watchers yourself. 731more watchers yourself.
703 732
704If C<fd> is less than 0, then no I/O watcher will be started and events is 733If 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 734is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
706will be craeted and started. 735C<events> set will be craeted and started.
707 736
708If C<timeout> is less than 0, then no timeout watcher will be 737If C<timeout> is less than 0, then no timeout watcher will be
709started. Otherwise an ev_timer watcher with after = C<timeout> (and repeat 738started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
710= 0) will be started. 739repeat = 0) will be started. While C<0> is a valid timeout, it is of
740dubious value.
711 741
712The callback has the type C<void (*cb)(int revents, void *arg)> and 742The 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, 743passed an C<revents> set like normal event callbacks (a combination of
714EV_WRITE or EV_TIMEOUT) and the C<arg> value passed to C<ev_once>: 744C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
745value passed to C<ev_once>:
715 746
716 static void stdin_ready (int revents, void *arg) 747 static void stdin_ready (int revents, void *arg)
717 { 748 {
718 if (revents & EV_TIMEOUT) 749 if (revents & EV_TIMEOUT)
719 /* doh, nothing entered */ 750 /* doh, nothing entered */;
720 else if (revents & EV_READ) 751 else if (revents & EV_READ)
721 /* stdin might have data for us, joy! */ 752 /* stdin might have data for us, joy! */;
722 } 753 }
723 754
724 ev_once (STDIN_FILENO, EV_READm 10., stdin_ready, 0); 755 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
725 756
726=item ev_feed_event (loop, watcher, int events) 757=item ev_feed_event (loop, watcher, int events)
727 758
728Feeds the given event set into the event loop, as if the specified event 759Feeds 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 760had happened for the specified watcher (which must be a pointer to an
730initialised but not necessarily active event watcher). 761initialised but not necessarily started event watcher).
731 762
732=item ev_feed_fd_event (loop, int fd, int revents) 763=item ev_feed_fd_event (loop, int fd, int revents)
733 764
734Feed an event on the given fd, as if a file descriptor backend detected it. 765Feed an event on the given fd, as if a file descriptor backend detected
766the given events it.
735 767
736=item ev_feed_signal_event (loop, int signum) 768=item ev_feed_signal_event (loop, int signum)
737 769
738Feed an event as if the given signal occured (loop must be the default loop!). 770Feed an event as if the given signal occured (loop must be the default loop!).
739 771
740=back 772=back
741 773
774=head1 LIBEVENT EMULATION
775
776TBD.
777
778=head1 C++ SUPPORT
779
780TBD.
781
742=head1 AUTHOR 782=head1 AUTHOR
743 783
744Marc Lehmann <libev@schmorp.de>. 784Marc Lehmann <libev@schmorp.de>.
745 785

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines