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

Comparing libev/ev.pod (file contents):
Revision 1.221 by root, Wed Dec 3 15:23:44 2008 UTC vs.
Revision 1.226 by root, Wed Mar 4 12:51:37 2009 UTC

… …
460 460
461While nominally embeddable in other event loops, this doesn't work 461While nominally embeddable in other event loops, this doesn't work
462everywhere, so you might need to test for this. And since it is broken 462everywhere, so you might need to test for this. And since it is broken
463almost everywhere, you should only use it when you have a lot of sockets 463almost everywhere, you should only use it when you have a lot of sockets
464(for which it usually works), by embedding it into another event loop 464(for which it usually works), by embedding it into another event loop
465(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it, 465(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
466using it only for sockets. 466also broken on OS X)) and, did I mention it, using it only for sockets.
467 467
468This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with 468This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
469C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with 469C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
470C<NOTE_EOF>. 470C<NOTE_EOF>.
471 471
… …
1619 1619
1620=over 4 1620=over 4
1621 1621
1622=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1622=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1623 1623
1624=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1624=item ev_periodic_set (ev_periodic *, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1625 1625
1626Lots of arguments, lets sort it out... There are basically three modes of 1626Lots of arguments, lets sort it out... There are basically three modes of
1627operation, and we will explain them from simplest to most complex: 1627operation, and we will explain them from simplest to most complex:
1628 1628
1629=over 4 1629=over 4
… …
1671ignored. Instead, each time the periodic watcher gets scheduled, the 1671ignored. Instead, each time the periodic watcher gets scheduled, the
1672reschedule callback will be called with the watcher as first, and the 1672reschedule callback will be called with the watcher as first, and the
1673current time as second argument. 1673current time as second argument.
1674 1674
1675NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1675NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1676ever, or make ANY event loop modifications whatsoever>. 1676ever, or make ANY other event loop modifications whatsoever>.
1677 1677
1678If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 1678If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1679it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 1679it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1680only event loop modification you are allowed to do). 1680only event loop modification you are allowed to do).
1681 1681
… …
2012the process. The exception are C<ev_stat> watchers - those call C<stat 2012the process. The exception are C<ev_stat> watchers - those call C<stat
2013()>, which is a synchronous operation. 2013()>, which is a synchronous operation.
2014 2014
2015For local paths, this usually doesn't matter: unless the system is very 2015For local paths, this usually doesn't matter: unless the system is very
2016busy or the intervals between stat's are large, a stat call will be fast, 2016busy or the intervals between stat's are large, a stat call will be fast,
2017as the path data is suually in memory already (except when starting the 2017as the path data is usually in memory already (except when starting the
2018watcher). 2018watcher).
2019 2019
2020For networked file systems, calling C<stat ()> can block an indefinite 2020For networked file systems, calling C<stat ()> can block an indefinite
2021time due to network issues, and even under good conditions, a stat call 2021time due to network issues, and even under good conditions, a stat call
2022often takes multiple milliseconds. 2022often takes multiple milliseconds.
… …
2179 2179
2180=head3 Watcher-Specific Functions and Data Members 2180=head3 Watcher-Specific Functions and Data Members
2181 2181
2182=over 4 2182=over 4
2183 2183
2184=item ev_idle_init (ev_signal *, callback) 2184=item ev_idle_init (ev_idle *, callback)
2185 2185
2186Initialises and configures the idle watcher - it has no parameters of any 2186Initialises and configures the idle watcher - it has no parameters of any
2187kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 2187kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
2188believe me. 2188believe me.
2189 2189
… …
2428some fds have to be watched and handled very quickly (with low latency), 2428some fds have to be watched and handled very quickly (with low latency),
2429and even priorities and idle watchers might have too much overhead. In 2429and even priorities and idle watchers might have too much overhead. In
2430this case you would put all the high priority stuff in one loop and all 2430this case you would put all the high priority stuff in one loop and all
2431the rest in a second one, and embed the second one in the first. 2431the rest in a second one, and embed the second one in the first.
2432 2432
2433As long as the watcher is active, the callback will be invoked every time 2433As long as the watcher is active, the callback will be invoked every
2434there might be events pending in the embedded loop. The callback must then 2434time there might be events pending in the embedded loop. The callback
2435call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2435must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
2436their callbacks (you could also start an idle watcher to give the embedded 2436sweep and invoke their callbacks (the callback doesn't need to invoke the
2437loop strictly lower priority for example). You can also set the callback 2437C<ev_embed_sweep> function directly, it could also start an idle watcher
2438to C<0>, in which case the embed watcher will automatically execute the 2438to give the embedded loop strictly lower priority for example).
2439embedded loop sweep.
2440 2439
2441As long as the watcher is started it will automatically handle events. The 2440You can also set the callback to C<0>, in which case the embed watcher
2442callback will be invoked whenever some events have been handled. You can 2441will automatically execute the embedded loop sweep whenever necessary.
2443set the callback to C<0> to avoid having to specify one if you are not
2444interested in that.
2445 2442
2446Also, there have not currently been made special provisions for forking: 2443Fork detection will be handled transparently while the C<ev_embed> watcher
2447when you fork, you not only have to call C<ev_loop_fork> on both loops, 2444is active, i.e., the embedded loop will automatically be forked when the
2448but you will also have to stop and restart any C<ev_embed> watchers 2445embedding loop forks. In other cases, the user is responsible for calling
2449yourself - but you can use a fork watcher to handle this automatically, 2446C<ev_loop_fork> on the embedded loop.
2450and future versions of libev might do just that.
2451 2447
2452Unfortunately, not all backends are embeddable: only the ones returned by 2448Unfortunately, not all backends are embeddable: only the ones returned by
2453C<ev_embeddable_backends> are, which, unfortunately, does not include any 2449C<ev_embeddable_backends> are, which, unfortunately, does not include any
2454portable one. 2450portable one.
2455 2451
… …
3233function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>. 3229function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
3234 3230
3235=item EV_USE_REALTIME 3231=item EV_USE_REALTIME
3236 3232
3237If defined to be C<1>, libev will try to detect the availability of the 3233If defined to be C<1>, libev will try to detect the availability of the
3238real-time clock option at compile time (and assume its availability at 3234real-time clock option at compile time (and assume its availability
3239runtime if successful). Otherwise no use of the real-time clock option will 3235at runtime if successful). Otherwise no use of the real-time clock
3240be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3236option will be attempted. This effectively replaces C<gettimeofday>
3241(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3237by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
3242note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3238correctness. See the note about libraries in the description of
3239C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
3240C<EV_USE_CLOCK_SYSCALL>.
3243 3241
3244=item EV_USE_CLOCK_SYSCALL 3242=item EV_USE_CLOCK_SYSCALL
3245 3243
3246If defined to be C<1>, libev will try to use a direct syscall instead 3244If defined to be C<1>, libev will try to use a direct syscall instead
3247of calling the system-provided C<clock_gettime> function. This option 3245of calling the system-provided C<clock_gettime> function. This option

Diff Legend

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