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

Comparing libev/ev.pod (file contents):
Revision 1.9 by root, Mon Nov 12 08:29:11 2007 UTC vs.
Revision 1.10 by root, Mon Nov 12 08:32:27 2007 UTC

… …
124 124
125It supports the following flags: 125It supports the following flags:
126 126
127=over 4 127=over 4
128 128
129=item EVFLAG_AUTO 129=item C<EVFLAG_AUTO>
130 130
131The default flags value. Use this if you have no clue (it's the right 131The default flags value. Use this if you have no clue (it's the right
132thing, believe me). 132thing, believe me).
133 133
134=item EVFLAG_NOENV 134=item C<EVFLAG_NOENV>
135 135
136If this flag bit is ored into the flag value (or the program runs setuid 136If 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 137or setgid) then libev will I<not> look at the environment variable
138C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 138C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
139override the flags completely if it is found in the environment. This is 139override 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 140useful to try out specific backends to test their performance, or to work
141around bugs. 141around bugs.
142 142
143=item EVMETHOD_SELECT (portable select backend) 143=item C<EVMETHOD_SELECT> (portable select backend)
144 144
145=item EVMETHOD_POLL (poll backend, available everywhere except on windows) 145=item C<EVMETHOD_POLL> (poll backend, available everywhere except on windows)
146 146
147=item EVMETHOD_EPOLL (linux only) 147=item C<EVMETHOD_EPOLL> (linux only)
148 148
149=item EVMETHOD_KQUEUE (some bsds only) 149=item C<EVMETHOD_KQUEUE> (some bsds only)
150 150
151=item EVMETHOD_DEVPOLL (solaris 8 only) 151=item C<EVMETHOD_DEVPOLL> (solaris 8 only)
152 152
153=item EVMETHOD_PORT (solaris 10 only) 153=item C<EVMETHOD_PORT> (solaris 10 only)
154 154
155If one or more of these are ored into the flags value, then only these 155If 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 156backends will be tried (in the reverse order as given here). If one are
157specified, any backend will do. 157specified, any backend will do.
158 158
… …
260 260
261=head1 ANATOMY OF A WATCHER 261=head1 ANATOMY OF A WATCHER
262 262
263A watcher is a structure that you create and register to record your 263A watcher is a structure that you create and register to record your
264interest in some event. For instance, if you want to wait for STDIN to 264interest in some event. For instance, if you want to wait for STDIN to
265become readable, you would create an ev_io watcher for that: 265become readable, you would create an C<ev_io> watcher for that:
266 266
267 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 267 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
268 { 268 {
269 ev_io_stop (w); 269 ev_io_stop (w);
270 ev_unloop (loop, EVUNLOOP_ALL); 270 ev_unloop (loop, EVUNLOOP_ALL);
… …
314(you can receive multiple events at the same time). The possible bit masks 314(you can receive multiple events at the same time). The possible bit masks
315are: 315are:
316 316
317=over 4 317=over 4
318 318
319=item EV_READ 319=item C<EV_READ>
320 320
321=item EV_WRITE 321=item C<EV_WRITE>
322 322
323The file descriptor in the ev_io watcher has become readable and/or 323The file descriptor in the C<ev_io> watcher has become readable and/or
324writable. 324writable.
325 325
326=item EV_TIMEOUT 326=item C<EV_TIMEOUT>
327 327
328The ev_timer watcher has timed out. 328The C<ev_timer> watcher has timed out.
329 329
330=item EV_PERIODIC 330=item C<EV_PERIODIC>
331 331
332The ev_periodic watcher has timed out. 332The C<ev_periodic> watcher has timed out.
333 333
334=item EV_SIGNAL 334=item C<EV_SIGNAL>
335 335
336The signal specified in the ev_signal watcher has been received by a thread. 336The signal specified in the C<ev_signal> watcher has been received by a thread.
337 337
338=item EV_CHILD 338=item C<EV_CHILD>
339 339
340The pid specified in the ev_child watcher has received a status change. 340The pid specified in the C<ev_child> watcher has received a status change.
341 341
342=item EV_IDLE 342=item C<EV_IDLE>
343 343
344The ev_idle watcher has determined that you have nothing better to do. 344The C<ev_idle> watcher has determined that you have nothing better to do.
345 345
346=item EV_PREPARE 346=item C<EV_PREPARE>
347 347
348=item EV_CHECK 348=item C<EV_CHECK>
349 349
350All ev_prepare watchers are invoked just I<before> C<ev_loop> starts 350All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts
351to gather new events, and all ev_check watchers are invoked just after 351to gather new events, and all C<ev_check> watchers are invoked just after
352C<ev_loop> has gathered them, but before it invokes any callbacks for any 352C<ev_loop> has gathered them, but before it invokes any callbacks for any
353received events. Callbacks of both watcher types can start and stop as 353received events. Callbacks of both watcher types can start and stop as
354many watchers as they want, and all of them will be taken into account 354many watchers as they want, and all of them will be taken into account
355(for example, a ev_prepare watcher might start an idle watcher to keep 355(for example, a C<ev_prepare> watcher might start an idle watcher to keep
356C<ev_loop> from blocking). 356C<ev_loop> from blocking).
357 357
358=item EV_ERROR 358=item C<EV_ERROR>
359 359
360An unspecified error has occured, the watcher has been stopped. This might 360An unspecified error has occured, the watcher has been stopped. This might
361happen because the watcher could not be properly started because libev 361happen because the watcher could not be properly started because libev
362ran out of memory, a file descriptor was found to be closed or any other 362ran out of memory, a file descriptor was found to be closed or any other
363problem. You best act on it by reporting the problem and somehow coping 363problem. You best act on it by reporting the problem and somehow coping
… …
404=head1 WATCHER TYPES 404=head1 WATCHER TYPES
405 405
406This section describes each watcher in detail, but will not repeat 406This section describes each watcher in detail, but will not repeat
407information given in the last section. 407information given in the last section.
408 408
409=head2 struct ev_io - is my file descriptor readable or writable 409=head2 C<ev_io> - is my file descriptor readable or writable
410 410
411I/O watchers check whether a file descriptor is readable or writable 411I/O watchers check whether a file descriptor is readable or writable
412in each iteration of the event loop (This behaviour is called 412in each iteration of the event loop (This behaviour is called
413level-triggering because you keep receiving events as long as the 413level-triggering because you keep receiving events as long as the
414condition persists. Remember you cna stop the watcher if you don't want to 414condition persists. Remember you cna stop the watcher if you don't want to
… …
432 432
433=item ev_io_init (ev_io *, callback, int fd, int events) 433=item ev_io_init (ev_io *, callback, int fd, int events)
434 434
435=item ev_io_set (ev_io *, int fd, int events) 435=item ev_io_set (ev_io *, int fd, int events)
436 436
437Configures an ev_io watcher. The fd is the file descriptor to rceeive 437Configures an C<ev_io> watcher. The fd is the file descriptor to rceeive
438events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ | 438events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ |
439EV_WRITE> to receive the given events. 439EV_WRITE> to receive the given events.
440 440
441=back 441=back
442 442
443=head2 struct ev_timer - relative and optionally recurring timeouts 443=head2 C<ev_timer> - relative and optionally recurring timeouts
444 444
445Timer watchers are simple relative timers that generate an event after a 445Timer watchers are simple relative timers that generate an event after a
446given time, and optionally repeating in regular intervals after that. 446given time, and optionally repeating in regular intervals after that.
447 447
448The timers are based on real time, that is, if you register an event that 448The timers are based on real time, that is, if you register an event that
… …
488 488
489This sounds a bit complicated, but here is a useful and typical 489This sounds a bit complicated, but here is a useful and typical
490example: Imagine you have a tcp connection and you want a so-called idle 490example: Imagine you have a tcp connection and you want a so-called idle
491timeout, that is, you want to be called when there have been, say, 60 491timeout, that is, you want to be called when there have been, say, 60
492seconds of inactivity on the socket. The easiest way to do this is to 492seconds of inactivity on the socket. The easiest way to do this is to
493configure an ev_timer with after=repeat=60 and calling ev_timer_again each 493configure an C<ev_timer> with after=repeat=60 and calling ev_timer_again each
494time you successfully read or write some data. If you go into an idle 494time you successfully read or write some data. If you go into an idle
495state where you do not expect data to travel on the socket, you can stop 495state where you do not expect data to travel on the socket, you can stop
496the timer, and again will automatically restart it if need be. 496the timer, and again will automatically restart it if need be.
497 497
498=back 498=back
499 499
500=head2 ev_periodic - to cron or not to cron it 500=head2 C<ev_periodic> - to cron or not to cron it
501 501
502Periodic watchers are also timers of a kind, but they are very versatile 502Periodic watchers are also timers of a kind, but they are very versatile
503(and unfortunately a bit complex). 503(and unfortunately a bit complex).
504 504
505Unlike ev_timer's, they are not based on real time (or relative time) 505Unlike C<ev_timer>'s, they are not based on real time (or relative time)
506but on wallclock time (absolute time). You can tell a periodic watcher 506but on wallclock time (absolute time). You can tell a periodic watcher
507to trigger "at" some specific point in time. For example, if you tell a 507to trigger "at" some specific point in time. For example, if you tell a
508periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now () 508periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now ()
509+ 10.>) and then reset your system clock to the last year, then it will 509+ 10.>) and then reset your system clock to the last year, then it will
510take a year to trigger the event (unlike an ev_timer, which would trigger 510take a year to trigger the event (unlike an C<ev_timer>, which would trigger
511roughly 10 seconds later and of course not if you reset your system time 511roughly 10 seconds later and of course not if you reset your system time
512again). 512again).
513 513
514They can also be used to implement vastly more complex timers, such as 514They can also be used to implement vastly more complex timers, such as
515triggering an event on eahc midnight, local time. 515triggering an event on eahc midnight, local time.
… …
548but only that the the callback will be called when the system time shows a 548but only that the the callback will be called when the system time shows a
549full hour (UTC), or more correct, when the system time is evenly divisible 549full hour (UTC), or more correct, when the system time is evenly divisible
550by 3600. 550by 3600.
551 551
552Another way to think about it (for the mathematically inclined) is that 552Another way to think about it (for the mathematically inclined) is that
553ev_periodic will try to run the callback in this mode at the next possible 553C<ev_periodic> will try to run the callback in this mode at the next possible
554time where C<time = at (mod interval)>, regardless of any time jumps. 554time where C<time = at (mod interval)>, regardless of any time jumps.
555 555
556=item * manual reschedule mode (reschedule_cb = callback) 556=item * manual reschedule mode (reschedule_cb = callback)
557 557
558In this mode the values for C<interval> and C<at> are both being 558In this mode the values for C<interval> and C<at> are both being
… …
591a different time than the last time it was called (e.g. in a crond like 591a different time than the last time it was called (e.g. in a crond like
592program when the crontabs have changed). 592program when the crontabs have changed).
593 593
594=back 594=back
595 595
596=head2 ev_signal - signal me when a signal gets signalled 596=head2 C<ev_signal> - signal me when a signal gets signalled
597 597
598Signal watchers will trigger an event when the process receives a specific 598Signal watchers will trigger an event when the process receives a specific
599signal one or more times. Even though signals are very asynchronous, libev 599signal one or more times. Even though signals are very asynchronous, libev
600will try it's best to deliver signals synchronously, i.e. as part of the 600will try it's best to deliver signals synchronously, i.e. as part of the
601normal event processing, like any other event. 601normal event processing, like any other event.
… …
616Configures the watcher to trigger on the given signal number (usually one 616Configures the watcher to trigger on the given signal number (usually one
617of the C<SIGxxx> constants). 617of the C<SIGxxx> constants).
618 618
619=back 619=back
620 620
621=head2 ev_child - wait for pid status changes 621=head2 C<ev_child> - wait for pid status changes
622 622
623Child watchers trigger when your process receives a SIGCHLD in response to 623Child watchers trigger when your process receives a SIGCHLD in response to
624some child status changes (most typically when a child of yours dies). 624some child status changes (most typically when a child of yours dies).
625 625
626=over 4 626=over 4
… …
635the status word (use the macros from C<sys/wait.h>). The C<rpid> member 635the status word (use the macros from C<sys/wait.h>). The C<rpid> member
636contains the pid of the process causing the status change. 636contains the pid of the process causing the status change.
637 637
638=back 638=back
639 639
640=head2 ev_idle - when you've got nothing better to do 640=head2 C<ev_idle> - when you've got nothing better to do
641 641
642Idle watchers trigger events when there are no other I/O or timer (or 642Idle watchers trigger events when there are no other I/O or timer (or
643periodic) events pending. That is, as long as your process is busy 643periodic) events pending. That is, as long as your process is busy
644handling sockets or timeouts it will not be called. But when your process 644handling sockets or timeouts it will not be called. But when your process
645is idle all idle watchers are being called again and again - until 645is idle all idle watchers are being called again and again - until
… …
672Their main purpose is to integrate other event mechanisms into libev. This 672Their main purpose is to integrate other event mechanisms into libev. This
673could be used, for example, to track variable changes, implement your own 673could be used, for example, to track variable changes, implement your own
674watchers, integrate net-snmp or a coroutine library and lots more. 674watchers, integrate net-snmp or a coroutine library and lots more.
675 675
676This is done by examining in each prepare call which file descriptors need 676This is done by examining in each prepare call which file descriptors need
677to be watched by the other library, registering ev_io watchers for them 677to be watched by the other library, registering C<ev_io> watchers for them
678and starting an ev_timer watcher for any timeouts (many libraries provide 678and starting an C<ev_timer> watcher for any timeouts (many libraries provide
679just this functionality). Then, in the check watcher you check for any 679just this functionality). Then, in the check watcher you check for any
680events that occured (by making your callbacks set soem flags for example) 680events that occured (by making your callbacks set soem flags for example)
681and call back into the library. 681and call back into the library.
682 682
683As another example, the perl Coro module uses these hooks to integrate 683As another example, the perl Coro module uses these hooks to integrate
… …
710watchers. This is useful if you want to wait for a single event on an fd 710watchers. This is useful if you want to wait for a single event on an fd
711or timeout without havign to allocate/configure/start/stop/free one or 711or timeout without havign to allocate/configure/start/stop/free one or
712more watchers yourself. 712more watchers yourself.
713 713
714If C<fd> is less than 0, then no I/O watcher will be started and events is 714If C<fd> is less than 0, then no I/O watcher will be started and events is
715ignored. Otherwise, an ev_io watcher for the given C<fd> and C<events> set 715ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and C<events> set
716will be craeted and started. 716will be craeted and started.
717 717
718If C<timeout> is less than 0, then no timeout watcher will be 718If C<timeout> is less than 0, then no timeout watcher will be
719started. Otherwise an ev_timer watcher with after = C<timeout> (and repeat 719started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and repeat
720= 0) will be started. 720= 0) will be started.
721 721
722The callback has the type C<void (*cb)(int revents, void *arg)> and 722The callback has the type C<void (*cb)(int revents, void *arg)> and
723gets passed an events set (normally a combination of EV_ERROR, EV_READ, 723gets passed an events set (normally a combination of C<EV_ERROR>, C<EV_READ>,
724EV_WRITE or EV_TIMEOUT) and the C<arg> value passed to C<ev_once>: 724C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> value passed to C<ev_once>:
725 725
726 static void stdin_ready (int revents, void *arg) 726 static void stdin_ready (int revents, void *arg)
727 { 727 {
728 if (revents & EV_TIMEOUT) 728 if (revents & EV_TIMEOUT)
729 /* doh, nothing entered */ 729 /* doh, nothing entered */

Diff Legend

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