… | |
… | |
127 | .\} |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
129 | .\" ======================================================================== |
130 | .\" |
130 | .\" |
131 | .IX Title ""<STANDARD INPUT>" 1" |
131 | .IX Title ""<STANDARD INPUT>" 1" |
132 | .TH "<STANDARD INPUT>" 1 "2007-11-13" "perl v5.8.8" "User Contributed Perl Documentation" |
132 | .TH "<STANDARD INPUT>" 1 "2007-11-18" "perl v5.8.8" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
133 | .SH "NAME" |
134 | libev \- a high performance full\-featured event loop written in C |
134 | libev \- a high performance full\-featured event loop written in C |
135 | .SH "SYNOPSIS" |
135 | .SH "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
137 | .Vb 1 |
137 | .Vb 1 |
… | |
… | |
180 | .IX Header "GLOBAL FUNCTIONS" |
180 | .IX Header "GLOBAL FUNCTIONS" |
181 | These functions can be called anytime, even before initialising the |
181 | These functions can be called anytime, even before initialising the |
182 | library in any way. |
182 | library in any way. |
183 | .IP "ev_tstamp ev_time ()" 4 |
183 | .IP "ev_tstamp ev_time ()" 4 |
184 | .IX Item "ev_tstamp ev_time ()" |
184 | .IX Item "ev_tstamp ev_time ()" |
185 | Returns the current time as libev would use it. |
185 | Returns the current time as libev would use it. Please note that the |
|
|
186 | \&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp |
|
|
187 | you actually want to know. |
186 | .IP "int ev_version_major ()" 4 |
188 | .IP "int ev_version_major ()" 4 |
187 | .IX Item "int ev_version_major ()" |
189 | .IX Item "int ev_version_major ()" |
188 | .PD 0 |
190 | .PD 0 |
189 | .IP "int ev_version_minor ()" 4 |
191 | .IP "int ev_version_minor ()" 4 |
190 | .IX Item "int ev_version_minor ()" |
192 | .IX Item "int ev_version_minor ()" |
… | |
… | |
354 | one iteration of the loop. |
356 | one iteration of the loop. |
355 | .Sp |
357 | .Sp |
356 | This flags value could be used to implement alternative looping |
358 | This flags value could be used to implement alternative looping |
357 | constructs, but the \f(CW\*(C`prepare\*(C'\fR and \f(CW\*(C`check\*(C'\fR watchers provide a better and |
359 | constructs, but the \f(CW\*(C`prepare\*(C'\fR and \f(CW\*(C`check\*(C'\fR watchers provide a better and |
358 | more generic mechanism. |
360 | more generic mechanism. |
|
|
361 | .Sp |
|
|
362 | Here are the gory details of what ev_loop does: |
|
|
363 | .Sp |
|
|
364 | .Vb 15 |
|
|
365 | \& 1. If there are no active watchers (reference count is zero), return. |
|
|
366 | \& 2. Queue and immediately call all prepare watchers. |
|
|
367 | \& 3. If we have been forked, recreate the kernel state. |
|
|
368 | \& 4. Update the kernel state with all outstanding changes. |
|
|
369 | \& 5. Update the "event loop time". |
|
|
370 | \& 6. Calculate for how long to block. |
|
|
371 | \& 7. Block the process, waiting for events. |
|
|
372 | \& 8. Update the "event loop time" and do time jump handling. |
|
|
373 | \& 9. Queue all outstanding timers. |
|
|
374 | \& 10. Queue all outstanding periodics. |
|
|
375 | \& 11. If no events are pending now, queue all idle watchers. |
|
|
376 | \& 12. Queue all check watchers. |
|
|
377 | \& 13. Call all queued watchers in reverse order (i.e. check watchers first). |
|
|
378 | \& 14. If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
|
|
379 | \& was used, return, otherwise continue with step #1. |
|
|
380 | .Ve |
359 | .IP "ev_unloop (loop, how)" 4 |
381 | .IP "ev_unloop (loop, how)" 4 |
360 | .IX Item "ev_unloop (loop, how)" |
382 | .IX Item "ev_unloop (loop, how)" |
361 | Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it |
383 | Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it |
362 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
384 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
363 | \&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or |
385 | \&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or |
… | |
… | |
571 | given time, and optionally repeating in regular intervals after that. |
593 | given time, and optionally repeating in regular intervals after that. |
572 | .PP |
594 | .PP |
573 | The timers are based on real time, that is, if you register an event that |
595 | The timers are based on real time, that is, if you register an event that |
574 | times out after an hour and you reset your system clock to last years |
596 | times out after an hour and you reset your system clock to last years |
575 | time, it will still time out after (roughly) and hour. \*(L"Roughly\*(R" because |
597 | time, it will still time out after (roughly) and hour. \*(L"Roughly\*(R" because |
576 | detecting time jumps is hard, and soem inaccuracies are unavoidable (the |
598 | detecting time jumps is hard, and some inaccuracies are unavoidable (the |
577 | monotonic clock option helps a lot here). |
599 | monotonic clock option helps a lot here). |
578 | .PP |
600 | .PP |
579 | The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR |
601 | The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR |
580 | time. This is usually the right thing as this timestamp refers to the time |
602 | time. This is usually the right thing as this timestamp refers to the time |
581 | of the event triggering whatever timeout you are modifying/starting. If |
603 | of the event triggering whatever timeout you are modifying/starting. If |
582 | you suspect event processing to be delayed and you *need* to base the timeout |
604 | you suspect event processing to be delayed and you \fIneed\fR to base the timeout |
583 | on the current time, use something like this to adjust for this: |
605 | on the current time, use something like this to adjust for this: |
584 | .PP |
606 | .PP |
585 | .Vb 1 |
607 | .Vb 1 |
586 | \& ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
608 | \& ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
587 | .Ve |
609 | .Ve |
|
|
610 | .PP |
|
|
611 | The callback is guarenteed to be invoked only when its timeout has passed, |
|
|
612 | but if multiple timers become ready during the same loop iteration then |
|
|
613 | order of execution is undefined. |
588 | .IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4 |
614 | .IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4 |
589 | .IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" |
615 | .IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" |
590 | .PD 0 |
616 | .PD 0 |
591 | .IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 |
617 | .IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 |
592 | .IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" |
618 | .IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" |
… | |
… | |
634 | roughly 10 seconds later and of course not if you reset your system time |
660 | roughly 10 seconds later and of course not if you reset your system time |
635 | again). |
661 | again). |
636 | .PP |
662 | .PP |
637 | They can also be used to implement vastly more complex timers, such as |
663 | They can also be used to implement vastly more complex timers, such as |
638 | triggering an event on eahc midnight, local time. |
664 | triggering an event on eahc midnight, local time. |
|
|
665 | .PP |
|
|
666 | As with timers, the callback is guarenteed to be invoked only when the |
|
|
667 | time (\f(CW\*(C`at\*(C'\fR) has been passed, but if multiple periodic timers become ready |
|
|
668 | during the same loop iteration then order of execution is undefined. |
639 | .IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4 |
669 | .IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4 |
640 | .IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" |
670 | .IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" |
641 | .PD 0 |
671 | .PD 0 |
642 | .IP "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 4 |
672 | .IP "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 4 |
643 | .IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" |
673 | .IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" |