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

Comparing libev/ev.pod (file contents):
Revision 1.32 by root, Fri Nov 23 08:36:35 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
… …
198=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 198=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
199 199
200Kqueue deserves special mention, as at the time of this writing, it 200Kqueue deserves special mention, as at the time of this writing, it
201was 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
202anything but sockets and pipes, except on Darwin, where of course its 202anything but sockets and pipes, except on Darwin, where of course its
203completely useless). For this reason its not being "autodetected" unless 203completely useless). For this reason its not being "autodetected"
204you 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>).
205 206
206It 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
207kernel is more efficient (which says nothing about its actual speed, of 208kernel is more efficient (which says nothing about its actual speed, of
208course). 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
209extra 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
… …
233If 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
234backends 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
235specified, most compiled-in backend will be tried, usually in reverse 236specified, most compiled-in backend will be tried, usually in reverse
236order of their flag values :) 237order of their flag values :)
237 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);
254
238=item struct ev_loop *ev_loop_new (unsigned int flags) 255=item struct ev_loop *ev_loop_new (unsigned int flags)
239 256
240Similar 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
241always distinct from the default loop. Unlike the default loop, it cannot 258always distinct from the default loop. Unlike the default loop, it cannot
242handle signal and child watchers, and attempts to do so will be greeted by 259handle signal and child watchers, and attempts to do so will be greeted by
… …
297 314
298Finally, this is it, the event handler. This function usually is called 315Finally, this is it, the event handler. This function usually is called
299after you initialised all your watchers and you want to start handling 316after you initialised all your watchers and you want to start handling
300events. 317events.
301 318
302If 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
303no event watchers are active anymore or C<ev_unloop> was called. 320either no event watchers are active anymore or C<ev_unloop> was called.
304 321
305A 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
306those 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
307case 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.
308 325
309A 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
310neccessary) and will handle those and any outstanding ones. It will block 327neccessary) and will handle those and any outstanding ones. It will block
311your 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
312one 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.
313 333
314This flags value could be used to implement alternative looping
315constructs, but the C<prepare> and C<check> watchers provide a better and
316more generic mechanism.
317
318Here are the gory details of what ev_loop does: 334Here are the gory details of what C<ev_loop> does:
319 335
320 1. If there are no active watchers (reference count is zero), return. 336 * If there are no active watchers (reference count is zero), return.
321 2. Queue and immediately call all prepare watchers. 337 - Queue prepare watchers and then call all outstanding watchers.
322 3. If we have been forked, recreate the kernel state. 338 - If we have been forked, recreate the kernel state.
323 4. Update the kernel state with all outstanding changes. 339 - Update the kernel state with all outstanding changes.
324 5. Update the "event loop time". 340 - Update the "event loop time".
325 6. Calculate for how long to block. 341 - Calculate for how long to block.
326 7. Block the process, waiting for events. 342 - Block the process, waiting for any events.
343 - Queue all outstanding I/O (fd) events.
327 8. Update the "event loop time" and do time jump handling. 344 - Update the "event loop time" and do time jump handling.
328 9. Queue all outstanding timers. 345 - Queue all outstanding timers.
329 10. Queue all outstanding periodics. 346 - Queue all outstanding periodics.
330 11. If no events are pending now, queue all idle watchers. 347 - If no events are pending now, queue all idle watchers.
331 12. Queue all check watchers. 348 - Queue all check watchers.
332 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.
333 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
334 was used, return, otherwise continue with step #1. 353 were used, return, otherwise continue with step *.
335 354
336=item ev_unloop (loop, how) 355=item ev_unloop (loop, how)
337 356
338Can 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
339has processed all outstanding events). The C<how> argument must be either 358has processed all outstanding events). The C<how> argument must be either

Diff Legend

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