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

Comparing libev/ev.html (file contents):
Revision 1.27 by root, Tue Nov 13 03:11:57 2007 UTC vs.
Revision 1.28 by root, Sun Nov 18 03:43:24 2007 UTC

… …
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="&lt;standard input&gt;" /> 7 <meta name="inputfile" content="&lt;standard input&gt;" />
8 <meta name="outputfile" content="&lt;standard output&gt;" /> 8 <meta name="outputfile" content="&lt;standard output&gt;" />
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
107library in any way.</p> 107library 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
113you 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
… …
268your process until at least one new event arrives, and will return after 270your process until at least one new event arrives, and will return after
269one iteration of the loop.</p> 271one 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
271constructs, but the <code>prepare</code> and <code>check</code> watchers provide a better and 273constructs, but the <code>prepare</code> and <code>check</code> watchers provide a better and
272more generic mechanism.</p> 274more 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 &quot;event loop time&quot;.
281 6. Calculate for how long to block.
282 7. Block the process, waiting for events.
283 8. Update the &quot;event loop time&quot; 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
277has processed all outstanding events). The <code>how</code> argument must be either 297has 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
473given time, and optionally repeating in regular intervals after that.</p> 493given 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
475times out after an hour and you reset your system clock to last years 495times out after an hour and you reset your system clock to last years
476time, it will still time out after (roughly) and hour. &quot;Roughly&quot; because 496time, it will still time out after (roughly) and hour. &quot;Roughly&quot; because
477detecting time jumps is hard, and soem inaccuracies are unavoidable (the 497detecting time jumps is hard, and some inaccuracies are unavoidable (the
478monotonic clock option helps a lot here).</p> 498monotonic 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>
480time. This is usually the right thing as this timestamp refers to the time 500time. This is usually the right thing as this timestamp refers to the time
481of the event triggering whatever timeout you are modifying/starting. If 501of the event triggering whatever timeout you are modifying/starting. If
482you suspect event processing to be delayed and you *need* to base the timeout 502you suspect event processing to be delayed and you <i>need</i> to base the timeout
483on the current time, use something like this to adjust for this:</p> 503on the current time, use something like this to adjust for this:</p>
484<pre> ev_timer_set (&amp;timer, after + ev_now () - ev_time (), 0.); 504<pre> ev_timer_set (&amp;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,
508but if multiple timers become ready during the same loop iteration then
509order 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
… …
529take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger 552take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger
530roughly 10 seconds later and of course not if you reset your system time 553roughly 10 seconds later and of course not if you reset your system time
531again).</p> 554again).</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
533triggering an event on eahc midnight, local time.</p> 556triggering an event on eahc midnight, local time.</p>
557<p>As with timers, the callback is guarenteed to be invoked only when the
558time (<code>at</code>) has been passed, but if multiple periodic timers become ready
559during 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
539operation, and we will explain them from simplest to complex:</p> 565operation, 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

Diff Legend

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