… | |
… | |
4 | <head> |
4 | <head> |
5 | <title>libev</title> |
5 | <title>libev</title> |
6 | <meta name="description" content="Pod documentation for libev" /> |
6 | <meta name="description" content="Pod documentation for libev" /> |
7 | <meta name="inputfile" content="<standard input>" /> |
7 | <meta name="inputfile" content="<standard input>" /> |
8 | <meta name="outputfile" content="<standard output>" /> |
8 | <meta name="outputfile" content="<standard output>" /> |
9 | <meta name="created" content="Tue Nov 13 04:04:09 2007" /> |
9 | <meta name="created" content="Sun Nov 18 04:43:20 2007" /> |
10 | <meta name="generator" content="Pod::Xhtml 1.57" /> |
10 | <meta name="generator" content="Pod::Xhtml 1.57" /> |
11 | <link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head> |
11 | <link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head> |
12 | <body> |
12 | <body> |
13 | <div class="pod"> |
13 | <div class="pod"> |
14 | <!-- INDEX START --> |
14 | <!-- INDEX START --> |
… | |
… | |
106 | <p>These functions can be called anytime, even before initialising the |
106 | <p>These functions can be called anytime, even before initialising the |
107 | library in any way.</p> |
107 | library in any way.</p> |
108 | <dl> |
108 | <dl> |
109 | <dt>ev_tstamp ev_time ()</dt> |
109 | <dt>ev_tstamp ev_time ()</dt> |
110 | <dd> |
110 | <dd> |
111 | <p>Returns the current time as libev would use it.</p> |
111 | <p>Returns the current time as libev would use it. Please note that the |
|
|
112 | <code>ev_now</code> function is usually faster and also often returns the timestamp |
|
|
113 | you actually want to know.</p> |
112 | </dd> |
114 | </dd> |
113 | <dt>int ev_version_major ()</dt> |
115 | <dt>int ev_version_major ()</dt> |
114 | <dt>int ev_version_minor ()</dt> |
116 | <dt>int ev_version_minor ()</dt> |
115 | <dd> |
117 | <dd> |
116 | <p>You can find out the major and minor version numbers of the library |
118 | <p>You can find out the major and minor version numbers of the library |
… | |
… | |
268 | your process until at least one new event arrives, and will return after |
270 | your process until at least one new event arrives, and will return after |
269 | one iteration of the loop.</p> |
271 | one iteration of the loop.</p> |
270 | <p>This flags value could be used to implement alternative looping |
272 | <p>This flags value could be used to implement alternative looping |
271 | constructs, but the <code>prepare</code> and <code>check</code> watchers provide a better and |
273 | constructs, but the <code>prepare</code> and <code>check</code> watchers provide a better and |
272 | more generic mechanism.</p> |
274 | more generic mechanism.</p> |
|
|
275 | <p>Here are the gory details of what ev_loop does:</p> |
|
|
276 | <pre> 1. If there are no active watchers (reference count is zero), return. |
|
|
277 | 2. Queue and immediately call all prepare watchers. |
|
|
278 | 3. If we have been forked, recreate the kernel state. |
|
|
279 | 4. Update the kernel state with all outstanding changes. |
|
|
280 | 5. Update the "event loop time". |
|
|
281 | 6. Calculate for how long to block. |
|
|
282 | 7. Block the process, waiting for events. |
|
|
283 | 8. Update the "event loop time" and do time jump handling. |
|
|
284 | 9. Queue all outstanding timers. |
|
|
285 | 10. Queue all outstanding periodics. |
|
|
286 | 11. If no events are pending now, queue all idle watchers. |
|
|
287 | 12. Queue all check watchers. |
|
|
288 | 13. Call all queued watchers in reverse order (i.e. check watchers first). |
|
|
289 | 14. If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
|
|
290 | was used, return, otherwise continue with step #1. |
|
|
291 | |
|
|
292 | </pre> |
273 | </dd> |
293 | </dd> |
274 | <dt>ev_unloop (loop, how)</dt> |
294 | <dt>ev_unloop (loop, how)</dt> |
275 | <dd> |
295 | <dd> |
276 | <p>Can be used to make a call to <code>ev_loop</code> return early (but only after it |
296 | <p>Can be used to make a call to <code>ev_loop</code> return early (but only after it |
277 | has processed all outstanding events). The <code>how</code> argument must be either |
297 | has processed all outstanding events). The <code>how</code> argument must be either |
… | |
… | |
472 | <p>Timer watchers are simple relative timers that generate an event after a |
492 | <p>Timer watchers are simple relative timers that generate an event after a |
473 | given time, and optionally repeating in regular intervals after that.</p> |
493 | given time, and optionally repeating in regular intervals after that.</p> |
474 | <p>The timers are based on real time, that is, if you register an event that |
494 | <p>The timers are based on real time, that is, if you register an event that |
475 | times out after an hour and you reset your system clock to last years |
495 | times out after an hour and you reset your system clock to last years |
476 | time, it will still time out after (roughly) and hour. "Roughly" because |
496 | time, it will still time out after (roughly) and hour. "Roughly" because |
477 | detecting time jumps is hard, and soem inaccuracies are unavoidable (the |
497 | detecting time jumps is hard, and some inaccuracies are unavoidable (the |
478 | monotonic clock option helps a lot here).</p> |
498 | monotonic clock option helps a lot here).</p> |
479 | <p>The relative timeouts are calculated relative to the <code>ev_now ()</code> |
499 | <p>The relative timeouts are calculated relative to the <code>ev_now ()</code> |
480 | time. This is usually the right thing as this timestamp refers to the time |
500 | time. This is usually the right thing as this timestamp refers to the time |
481 | of the event triggering whatever timeout you are modifying/starting. If |
501 | of the event triggering whatever timeout you are modifying/starting. If |
482 | you suspect event processing to be delayed and you *need* to base the timeout |
502 | you suspect event processing to be delayed and you <i>need</i> to base the timeout |
483 | on the current time, use something like this to adjust for this:</p> |
503 | on the current time, use something like this to adjust for this:</p> |
484 | <pre> ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
504 | <pre> ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
485 | |
505 | |
486 | </pre> |
506 | </pre> |
|
|
507 | <p>The callback is guarenteed to be invoked only when its timeout has passed, |
|
|
508 | but if multiple timers become ready during the same loop iteration then |
|
|
509 | order of execution is undefined.</p> |
487 | <dl> |
510 | <dl> |
488 | <dt>ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)</dt> |
511 | <dt>ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)</dt> |
489 | <dt>ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)</dt> |
512 | <dt>ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)</dt> |
490 | <dd> |
513 | <dd> |
491 | <p>Configure the timer to trigger after <code>after</code> seconds. If <code>repeat</code> is |
514 | <p>Configure the timer to trigger after <code>after</code> seconds. If <code>repeat</code> is |
… | |
… | |
529 | take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger |
552 | take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger |
530 | roughly 10 seconds later and of course not if you reset your system time |
553 | roughly 10 seconds later and of course not if you reset your system time |
531 | again).</p> |
554 | again).</p> |
532 | <p>They can also be used to implement vastly more complex timers, such as |
555 | <p>They can also be used to implement vastly more complex timers, such as |
533 | triggering an event on eahc midnight, local time.</p> |
556 | triggering an event on eahc midnight, local time.</p> |
|
|
557 | <p>As with timers, the callback is guarenteed to be invoked only when the |
|
|
558 | time (<code>at</code>) has been passed, but if multiple periodic timers become ready |
|
|
559 | during the same loop iteration then order of execution is undefined.</p> |
534 | <dl> |
560 | <dl> |
535 | <dt>ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)</dt> |
561 | <dt>ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)</dt> |
536 | <dt>ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)</dt> |
562 | <dt>ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)</dt> |
537 | <dd> |
563 | <dd> |
538 | <p>Lots of arguments, lets sort it out... There are basically three modes of |
564 | <p>Lots of arguments, lets sort it out... There are basically three modes of |
539 | operation, and we will explain them from simplest to complex:</p> |
565 | operation, and we will explain them from simplest to complex:</p> |
540 | |
|
|
541 | |
|
|
542 | |
|
|
543 | |
|
|
544 | <p> |
566 | <p> |
545 | <dl> |
567 | <dl> |
546 | <dt>* absolute timer (interval = reschedule_cb = 0)</dt> |
568 | <dt>* absolute timer (interval = reschedule_cb = 0)</dt> |
547 | <dd> |
569 | <dd> |
548 | <p>In this configuration the watcher triggers an event at the wallclock time |
570 | <p>In this configuration the watcher triggers an event at the wallclock time |