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

Comparing libev/ev.pod (file contents):
Revision 1.31 by root, Fri Nov 23 05:00:45 2007 UTC vs.
Revision 1.33 by root, Fri Nov 23 15:26:08 2007 UTC

… …
89Return the set of all backends compiled into this binary of libev and also 89Return the set of all backends compiled into this binary of libev and also
90recommended for this platform. This set is often smaller than the one 90recommended for this platform. This set is often smaller than the one
91returned by C<ev_supported_backends>, as for example kqueue is broken on 91returned by C<ev_supported_backends>, as for example kqueue is broken on
92most BSDs and will not be autodetected unless you explicitly request it 92most BSDs and will not be autodetected unless you explicitly request it
93(assuming you know what you are doing). This is the set of backends that 93(assuming you know what you are doing). This is the set of backends that
94C<EVFLAG_AUTO> will probe for. 94libev will probe for if you specify no backends explicitly.
95 95
96=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 96=item ev_set_allocator (void *(*cb)(void *ptr, long size))
97 97
98Sets the allocation function to use (the prototype is similar to the 98Sets the allocation function to use (the prototype is similar to the
99realloc C function, the semantics are identical). It is used to allocate 99realloc C function, the semantics are identical). It is used to allocate
… …
141 141
142If you don't know what event loop to use, use the one returned from this 142If you don't know what event loop to use, use the one returned from this
143function. 143function.
144 144
145The flags argument can be used to specify special behaviour or specific 145The flags argument can be used to specify special behaviour or specific
146backends to use, and is usually specified as C<0> (or EVFLAG_AUTO). 146backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
147 147
148It supports the following flags: 148The following flags are supported:
149 149
150=over 4 150=over 4
151 151
152=item C<EVFLAG_AUTO> 152=item C<EVFLAG_AUTO>
153 153
… …
189result in some caching, there is still a syscall per such incident 189result in some caching, there is still a syscall per such incident
190(because the fd could point to a different file description now), so its 190(because the fd could point to a different file description now), so its
191best to avoid that. Also, dup()ed file descriptors might not work very 191best to avoid that. Also, dup()ed file descriptors might not work very
192well if you register events for both fds. 192well if you register events for both fds.
193 193
194Please note that epoll sometimes generates spurious notifications, so you
195need to use non-blocking I/O or other means to avoid blocking when no data
196(or space) is available.
197
194=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 198=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
195 199
196Kqueue deserves special mention, as at the time of this writing, it 200Kqueue deserves special mention, as at the time of this writing, it
197was broken on all BSDs except NetBSD (usually it doesn't work with 201was broken on all BSDs except NetBSD (usually it doesn't work with
198anything but sockets and pipes, except on Darwin, where of course its 202anything but sockets and pipes, except on Darwin, where of course its
199completely useless). For this reason its not being "autodetected" unless 203completely useless). For this reason its not being "autodetected"
200you explicitly specify the flags (i.e. you don't use EVFLAG_AUTO). 204unless you explicitly specify it explicitly in the flags (i.e. using
205C<EVBACKEND_KQUEUE>).
201 206
202It scales in the same way as the epoll backend, but the interface to the 207It scales in the same way as the epoll backend, but the interface to the
203kernel is more efficient (which says nothing about its actual speed, of 208kernel is more efficient (which says nothing about its actual speed, of
204course). While starting and stopping an I/O watcher does not cause an 209course). While starting and stopping an I/O watcher does not cause an
205extra syscall as with epoll, it still adds up to four event changes per 210extra syscall as with epoll, it still adds up to four event changes per
… …
212=item C<EVBACKEND_PORT> (value 32, Solaris 10) 217=item C<EVBACKEND_PORT> (value 32, Solaris 10)
213 218
214This uses the Solaris 10 port mechanism. As with everything on Solaris, 219This uses the Solaris 10 port mechanism. As with everything on Solaris,
215it's really slow, but it still scales very well (O(active_fds)). 220it's really slow, but it still scales very well (O(active_fds)).
216 221
222Please note that solaris ports can result in a lot of spurious
223notifications, so you need to use non-blocking I/O or other means to avoid
224blocking when no data (or space) is available.
225
217=item C<EVBACKEND_ALL> 226=item C<EVBACKEND_ALL>
218 227
219Try all backends (even potentially broken ones that wouldn't be tried 228Try all backends (even potentially broken ones that wouldn't be tried
220with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 229with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
221C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 230C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
… …
224 233
225If one or more of these are ored into the flags value, then only these 234If one or more of these are ored into the flags value, then only these
226backends will be tried (in the reverse order as given here). If none are 235backends will be tried (in the reverse order as given here). If none are
227specified, most compiled-in backend will be tried, usually in reverse 236specified, most compiled-in backend will be tried, usually in reverse
228order of their flag values :) 237order of their flag values :)
238
239The most typical usage is like this:
240
241 if (!ev_default_loop (0))
242 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
243
244Restrict libev to the select and poll backends, and do not allow
245environment settings to be taken into account:
246
247 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
248
249Use whatever libev has to offer, but make sure that kqueue is used if
250available (warning, breaks stuff, best use only with your own private
251event loop and only if you know the OS supports your types of fds):
252
253 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
229 254
230=item struct ev_loop *ev_loop_new (unsigned int flags) 255=item struct ev_loop *ev_loop_new (unsigned int flags)
231 256
232Similar to C<ev_default_loop>, but always creates a new event loop that is 257Similar to C<ev_default_loop>, but always creates a new event loop that is
233always distinct from the default loop. Unlike the default loop, it cannot 258always distinct from the default loop. Unlike the default loop, it cannot
… …
289 314
290Finally, this is it, the event handler. This function usually is called 315Finally, this is it, the event handler. This function usually is called
291after you initialised all your watchers and you want to start handling 316after you initialised all your watchers and you want to start handling
292events. 317events.
293 318
294If the flags argument is specified as 0, it will not return until either 319If the flags argument is specified as C<0>, it will not return until
295no event watchers are active anymore or C<ev_unloop> was called. 320either no event watchers are active anymore or C<ev_unloop> was called.
296 321
297A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 322A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
298those events and any outstanding ones, but will not block your process in 323those events and any outstanding ones, but will not block your process in
299case there are no events and will return after one iteration of the loop. 324case there are no events and will return after one iteration of the loop.
300 325
301A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 326A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
302neccessary) and will handle those and any outstanding ones. It will block 327neccessary) and will handle those and any outstanding ones. It will block
303your process until at least one new event arrives, and will return after 328your process until at least one new event arrives, and will return after
304one iteration of the loop. 329one iteration of the loop. This is useful if you are waiting for some
330external event in conjunction with something not expressible using other
331libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
332usually a better approach for this kind of thing.
305 333
306This flags value could be used to implement alternative looping
307constructs, but the C<prepare> and C<check> watchers provide a better and
308more generic mechanism.
309
310Here are the gory details of what ev_loop does: 334Here are the gory details of what C<ev_loop> does:
311 335
312 1. If there are no active watchers (reference count is zero), return. 336 * If there are no active watchers (reference count is zero), return.
313 2. Queue and immediately call all prepare watchers. 337 - Queue prepare watchers and then call all outstanding watchers.
314 3. If we have been forked, recreate the kernel state. 338 - If we have been forked, recreate the kernel state.
315 4. Update the kernel state with all outstanding changes. 339 - Update the kernel state with all outstanding changes.
316 5. Update the "event loop time". 340 - Update the "event loop time".
317 6. Calculate for how long to block. 341 - Calculate for how long to block.
318 7. Block the process, waiting for events. 342 - Block the process, waiting for any events.
343 - Queue all outstanding I/O (fd) events.
319 8. Update the "event loop time" and do time jump handling. 344 - Update the "event loop time" and do time jump handling.
320 9. Queue all outstanding timers. 345 - Queue all outstanding timers.
321 10. Queue all outstanding periodics. 346 - Queue all outstanding periodics.
322 11. If no events are pending now, queue all idle watchers. 347 - If no events are pending now, queue all idle watchers.
323 12. Queue all check watchers. 348 - Queue all check watchers.
324 13. Call all queued watchers in reverse order (i.e. check watchers first). 349 - Call all queued watchers in reverse order (i.e. check watchers first).
350 Signals and child watchers are implemented as I/O watchers, and will
351 be handled here by queueing them when their watcher gets executed.
325 14. If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 352 - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
326 was used, return, otherwise continue with step #1. 353 were used, return, otherwise continue with step *.
327 354
328=item ev_unloop (loop, how) 355=item ev_unloop (loop, how)
329 356
330Can be used to make a call to C<ev_loop> return early (but only after it 357Can be used to make a call to C<ev_loop> return early (but only after it
331has processed all outstanding events). The C<how> argument must be either 358has processed all outstanding events). The C<how> argument must be either
… …
528 555
529Configures an C<ev_io> watcher. The fd is the file descriptor to rceeive 556Configures an C<ev_io> watcher. The fd is the file descriptor to rceeive
530events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ | 557events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ |
531EV_WRITE> to receive the given events. 558EV_WRITE> to receive the given events.
532 559
560Please note that most of the more scalable backend mechanisms (for example
561epoll and solaris ports) can result in spurious readyness notifications
562for file descriptors, so you practically need to use non-blocking I/O (and
563treat callback invocation as hint only), or retest separately with a safe
564interface before doing I/O (XLib can do this), or force the use of either
565C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>, which don't suffer from this
566problem. Also note that it is quite easy to have your callback invoked
567when the readyness condition is no longer valid even when employing
568typical ways of handling events, so its a good idea to use non-blocking
569I/O unconditionally.
570
533=back 571=back
534 572
535=head2 C<ev_timer> - relative and optionally recurring timeouts 573=head2 C<ev_timer> - relative and optionally recurring timeouts
536 574
537Timer watchers are simple relative timers that generate an event after a 575Timer watchers are simple relative timers that generate an event after a

Diff Legend

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