… | |
… | |
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="Mon Nov 12 10:07:10 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 |
278 | <code>EVUNLOOP_ONCE</code>, which will make the innermost <code>ev_loop</code> call return, or |
298 | <code>EVUNLOOP_ONE</code>, which will make the innermost <code>ev_loop</code> call return, or |
279 | <code>EVUNLOOP_ALL</code>, which will make all nested <code>ev_loop</code> calls return.</p> |
299 | <code>EVUNLOOP_ALL</code>, which will make all nested <code>ev_loop</code> calls return.</p> |
280 | </dd> |
300 | </dd> |
281 | <dt>ev_ref (loop)</dt> |
301 | <dt>ev_ref (loop)</dt> |
282 | <dt>ev_unref (loop)</dt> |
302 | <dt>ev_unref (loop)</dt> |
283 | <dd> |
303 | <dd> |
… | |
… | |
442 | <p>I/O watchers check whether a file descriptor is readable or writable |
462 | <p>I/O watchers check whether a file descriptor is readable or writable |
443 | in each iteration of the event loop (This behaviour is called |
463 | in each iteration of the event loop (This behaviour is called |
444 | level-triggering because you keep receiving events as long as the |
464 | level-triggering because you keep receiving events as long as the |
445 | condition persists. Remember you can stop the watcher if you don't want to |
465 | condition persists. Remember you can stop the watcher if you don't want to |
446 | act on the event and neither want to receive future events).</p> |
466 | act on the event and neither want to receive future events).</p> |
447 | <p>In general you can register as many read and/or write event watchers oer |
467 | <p>In general you can register as many read and/or write event watchers per |
448 | fd as you want (as long as you don't confuse yourself). Setting all file |
468 | fd as you want (as long as you don't confuse yourself). Setting all file |
449 | descriptors to non-blocking mode is also usually a good idea (but not |
469 | descriptors to non-blocking mode is also usually a good idea (but not |
450 | required if you know what you are doing).</p> |
470 | required if you know what you are doing).</p> |
451 | <p>You have to be careful with dup'ed file descriptors, though. Some backends |
471 | <p>You have to be careful with dup'ed file descriptors, though. Some backends |
452 | (the linux epoll backend is a notable example) cannot handle dup'ed file |
472 | (the linux epoll backend is a notable example) cannot handle dup'ed file |
453 | descriptors correctly if you register interest in two or more fds pointing |
473 | descriptors correctly if you register interest in two or more fds pointing |
454 | to the same file/socket etc. description.</p> |
474 | to the same underlying file/socket etc. description (that is, they share |
|
|
475 | the same underlying "file open").</p> |
455 | <p>If you must do this, then force the use of a known-to-be-good backend |
476 | <p>If you must do this, then force the use of a known-to-be-good backend |
456 | (at the time of this writing, this includes only EVMETHOD_SELECT and |
477 | (at the time of this writing, this includes only EVMETHOD_SELECT and |
457 | EVMETHOD_POLL).</p> |
478 | EVMETHOD_POLL).</p> |
458 | <dl> |
479 | <dl> |
459 | <dt>ev_io_init (ev_io *, callback, int fd, int events)</dt> |
480 | <dt>ev_io_init (ev_io *, callback, int fd, int events)</dt> |
… | |
… | |
469 | <h2 id="code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring timeouts</h2> |
490 | <h2 id="code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring timeouts</h2> |
470 | <div id="code_ev_timer_code_relative_and_opti-2"> |
491 | <div id="code_ev_timer_code_relative_and_opti-2"> |
471 | <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 |
472 | given time, and optionally repeating in regular intervals after that.</p> |
493 | given time, and optionally repeating in regular intervals after that.</p> |
473 | <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 |
474 | times out after an hour and youreset your system clock to last years |
495 | times out after an hour and you reset your system clock to last years |
475 | 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 |
476 | detecting time jumps is hard, and soem inaccuracies are unavoidable (the |
497 | detecting time jumps is hard, and some inaccuracies are unavoidable (the |
477 | monotonic clock option helps a lot here).</p> |
498 | monotonic clock option helps a lot here).</p> |
478 | <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> |
479 | 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 |
480 | of the event triggering whatever timeout you are modifying/starting. If |
501 | of the event triggering whatever timeout you are modifying/starting. If |
481 | 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 |
482 | ion 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> |
483 | <pre> ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
504 | <pre> ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
484 | |
505 | |
485 | </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> |
486 | <dl> |
510 | <dl> |
487 | <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> |
488 | <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> |
489 | <dd> |
513 | <dd> |
490 | <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 |
… | |
… | |
492 | timer will automatically be configured to trigger again <code>repeat</code> seconds |
516 | timer will automatically be configured to trigger again <code>repeat</code> seconds |
493 | later, again, and again, until stopped manually.</p> |
517 | later, again, and again, until stopped manually.</p> |
494 | <p>The timer itself will do a best-effort at avoiding drift, that is, if you |
518 | <p>The timer itself will do a best-effort at avoiding drift, that is, if you |
495 | configure a timer to trigger every 10 seconds, then it will trigger at |
519 | configure a timer to trigger every 10 seconds, then it will trigger at |
496 | exactly 10 second intervals. If, however, your program cannot keep up with |
520 | exactly 10 second intervals. If, however, your program cannot keep up with |
497 | the timer (ecause it takes longer than those 10 seconds to do stuff) the |
521 | the timer (because it takes longer than those 10 seconds to do stuff) the |
498 | timer will not fire more than once per event loop iteration.</p> |
522 | timer will not fire more than once per event loop iteration.</p> |
499 | </dd> |
523 | </dd> |
500 | <dt>ev_timer_again (loop)</dt> |
524 | <dt>ev_timer_again (loop)</dt> |
501 | <dd> |
525 | <dd> |
502 | <p>This will act as if the timer timed out and restart it again if it is |
526 | <p>This will act as if the timer timed out and restart it again if it is |
… | |
… | |
528 | 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 |
529 | 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 |
530 | again).</p> |
554 | again).</p> |
531 | <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 |
532 | 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> |
533 | <dl> |
560 | <dl> |
534 | <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> |
535 | <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> |
536 | <dd> |
563 | <dd> |
537 | <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 |
538 | operation, and we will explain them from simplest to complex:</p> |
565 | operation, and we will explain them from simplest to complex:</p> |
539 | |
|
|
540 | |
|
|
541 | |
|
|
542 | |
|
|
543 | <p> |
566 | <p> |
544 | <dl> |
567 | <dl> |
545 | <dt>* absolute timer (interval = reschedule_cb = 0)</dt> |
568 | <dt>* absolute timer (interval = reschedule_cb = 0)</dt> |
546 | <dd> |
569 | <dd> |
547 | <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 |
… | |
… | |
717 | <dt>ev_once (loop, int fd, int events, ev_tstamp timeout, callback)</dt> |
740 | <dt>ev_once (loop, int fd, int events, ev_tstamp timeout, callback)</dt> |
718 | <dd> |
741 | <dd> |
719 | <p>This function combines a simple timer and an I/O watcher, calls your |
742 | <p>This function combines a simple timer and an I/O watcher, calls your |
720 | callback on whichever event happens first and automatically stop both |
743 | callback on whichever event happens first and automatically stop both |
721 | watchers. This is useful if you want to wait for a single event on an fd |
744 | watchers. This is useful if you want to wait for a single event on an fd |
722 | or timeout without havign to allocate/configure/start/stop/free one or |
745 | or timeout without having to allocate/configure/start/stop/free one or |
723 | more watchers yourself.</p> |
746 | more watchers yourself.</p> |
724 | <p>If <code>fd</code> is less than 0, then no I/O watcher will be started and events |
747 | <p>If <code>fd</code> is less than 0, then no I/O watcher will be started and events |
725 | is being ignored. Otherwise, an <code>ev_io</code> watcher for the given <code>fd</code> and |
748 | is being ignored. Otherwise, an <code>ev_io</code> watcher for the given <code>fd</code> and |
726 | <code>events</code> set will be craeted and started.</p> |
749 | <code>events</code> set will be craeted and started.</p> |
727 | <p>If <code>timeout</code> is less than 0, then no timeout watcher will be |
750 | <p>If <code>timeout</code> is less than 0, then no timeout watcher will be |
… | |
… | |
762 | </dl> |
785 | </dl> |
763 | |
786 | |
764 | </div> |
787 | </div> |
765 | <h1 id="LIBEVENT_EMULATION">LIBEVENT EMULATION</h1><p><a href="#TOP" class="toplink">Top</a></p> |
788 | <h1 id="LIBEVENT_EMULATION">LIBEVENT EMULATION</h1><p><a href="#TOP" class="toplink">Top</a></p> |
766 | <div id="LIBEVENT_EMULATION_CONTENT"> |
789 | <div id="LIBEVENT_EMULATION_CONTENT"> |
767 | <p>TBD.</p> |
790 | <p>Libev offers a compatibility emulation layer for libevent. It cannot |
|
|
791 | emulate the internals of libevent, so here are some usage hints:</p> |
|
|
792 | <dl> |
|
|
793 | <dt>* Use it by including <event.h>, as usual.</dt> |
|
|
794 | <dt>* The following members are fully supported: ev_base, ev_callback, |
|
|
795 | ev_arg, ev_fd, ev_res, ev_events.</dt> |
|
|
796 | <dt>* Avoid using ev_flags and the EVLIST_*-macros, while it is |
|
|
797 | maintained by libev, it does not work exactly the same way as in libevent (consider |
|
|
798 | it a private API).</dt> |
|
|
799 | <dt>* Priorities are not currently supported. Initialising priorities |
|
|
800 | will fail and all watchers will have the same priority, even though there |
|
|
801 | is an ev_pri field.</dt> |
|
|
802 | <dt>* Other members are not supported.</dt> |
|
|
803 | <dt>* The libev emulation is <i>not</i> ABI compatible to libevent, you need |
|
|
804 | to use the libev header file and library.</dt> |
|
|
805 | </dl> |
768 | |
806 | |
769 | </div> |
807 | </div> |
770 | <h1 id="C_SUPPORT">C++ SUPPORT</h1><p><a href="#TOP" class="toplink">Top</a></p> |
808 | <h1 id="C_SUPPORT">C++ SUPPORT</h1><p><a href="#TOP" class="toplink">Top</a></p> |
771 | <div id="C_SUPPORT_CONTENT"> |
809 | <div id="C_SUPPORT_CONTENT"> |
772 | <p>TBD.</p> |
810 | <p>TBD.</p> |