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

Comparing libev/ev.pod (file contents):
Revision 1.30 by root, Fri Nov 23 04:36:03 2007 UTC vs.
Revision 1.33 by root, Fri Nov 23 15:26:08 2007 UTC

… …
75Usually, it's a good idea to terminate if the major versions mismatch, 75Usually, it's a good idea to terminate if the major versions mismatch,
76as this indicates an incompatible change. Minor versions are usually 76as this indicates an incompatible change. Minor versions are usually
77compatible to older versions, so a larger minor version alone is usually 77compatible to older versions, so a larger minor version alone is usually
78not a problem. 78not a problem.
79 79
80=item unsigned int ev_supported_backends ()
81
82Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
83value) compiled into this binary of libev (independent of their
84availability on the system you are running on). See C<ev_default_loop> for
85a description of the set values.
86
87=item unsigned int ev_recommended_backends ()
88
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
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
93(assuming you know what you are doing). This is the set of backends that
94libev will probe for if you specify no backends explicitly.
95
80=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 96=item ev_set_allocator (void *(*cb)(void *ptr, long size))
81 97
82Sets the allocation function to use (the prototype is similar to the 98Sets the allocation function to use (the prototype is similar to the
83realloc C function, the semantics are identical). It is used to allocate 99realloc C function, the semantics are identical). It is used to allocate
84and free memory (no surprises here). If it returns zero when memory 100and free memory (no surprises here). If it returns zero when memory
… …
119=item struct ev_loop *ev_default_loop (unsigned int flags) 135=item struct ev_loop *ev_default_loop (unsigned int flags)
120 136
121This will initialise the default event loop if it hasn't been initialised 137This will initialise the default event loop if it hasn't been initialised
122yet and return it. If the default loop could not be initialised, returns 138yet and return it. If the default loop could not be initialised, returns
123false. If it already was initialised it simply returns it (and ignores the 139false. If it already was initialised it simply returns it (and ignores the
124flags). 140flags. If that is troubling you, check C<ev_backend ()> afterwards).
125 141
126If 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
127function. 143function.
128 144
129The flags argument can be used to specify special behaviour or specific 145The flags argument can be used to specify special behaviour or specific
130backends to use, and is usually specified as 0 (or EVFLAG_AUTO). 146backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
131 147
132It supports the following flags: 148The following flags are supported:
133 149
134=over 4 150=over 4
135 151
136=item C<EVFLAG_AUTO> 152=item C<EVFLAG_AUTO>
137 153
… …
145C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 161C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
146override the flags completely if it is found in the environment. This is 162override the flags completely if it is found in the environment. This is
147useful to try out specific backends to test their performance, or to work 163useful to try out specific backends to test their performance, or to work
148around bugs. 164around bugs.
149 165
150=item C<EVMETHOD_SELECT> (value 1, portable select backend) 166=item C<EVBACKEND_SELECT> (value 1, portable select backend)
151 167
152This is your standard select(2) backend. Not I<completely> standard, as 168This is your standard select(2) backend. Not I<completely> standard, as
153libev tries to roll its own fd_set with no limits on the number of fds, 169libev tries to roll its own fd_set with no limits on the number of fds,
154but if that fails, expect a fairly low limit on the number of fds when 170but if that fails, expect a fairly low limit on the number of fds when
155using this backend. It doesn't scale too well (O(highest_fd)), but its usually 171using this backend. It doesn't scale too well (O(highest_fd)), but its usually
156the fastest backend for a low number of fds. 172the fastest backend for a low number of fds.
157 173
158=item C<EVMETHOD_POLL> (value 2, poll backend, available everywhere except on windows) 174=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
159 175
160And this is your standard poll(2) backend. It's more complicated than 176And this is your standard poll(2) backend. It's more complicated than
161select, but handles sparse fds better and has no artificial limit on the 177select, but handles sparse fds better and has no artificial limit on the
162number of fds you can use (except it will slow down considerably with a 178number of fds you can use (except it will slow down considerably with a
163lot of inactive fds). It scales similarly to select, i.e. O(total_fds). 179lot of inactive fds). It scales similarly to select, i.e. O(total_fds).
164 180
165=item C<EVMETHOD_EPOLL> (value 4, Linux) 181=item C<EVBACKEND_EPOLL> (value 4, Linux)
166 182
167For few fds, this backend is a bit little slower than poll and select, 183For few fds, this backend is a bit little slower than poll and select,
168but it scales phenomenally better. While poll and select usually scale like 184but it scales phenomenally better. While poll and select usually scale like
169O(total_fds) where n is the total number of fds (or the highest fd), epoll scales 185O(total_fds) where n is the total number of fds (or the highest fd), epoll scales
170either O(1) or O(active_fds). 186either O(1) or O(active_fds).
… …
173result in some caching, there is still a syscall per such incident 189result in some caching, there is still a syscall per such incident
174(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
175best 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
176well if you register events for both fds. 192well if you register events for both fds.
177 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
178=item C<EVMETHOD_KQUEUE> (value 8, most BSD clones) 198=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
179 199
180Kqueue deserves special mention, as at the time of this writing, it 200Kqueue deserves special mention, as at the time of this writing, it
181was 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
182anything but sockets and pipes, except on Darwin, where of course its 202anything but sockets and pipes, except on Darwin, where of course its
183completely useless). For this reason its not being "autodetected" unless 203completely useless). For this reason its not being "autodetected"
184you 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>).
185 206
186It 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
187kernel is more efficient (which says nothing about its actual speed, of 208kernel is more efficient (which says nothing about its actual speed, of
188course). 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
189extra 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
190incident, so its best to avoid that. 211incident, so its best to avoid that.
191 212
192=item C<EVMETHOD_DEVPOLL> (value 16, Solaris 8) 213=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
193 214
194This is not implemented yet (and might never be). 215This is not implemented yet (and might never be).
195 216
196=item C<EVMETHOD_PORT> (value 32, Solaris 10) 217=item C<EVBACKEND_PORT> (value 32, Solaris 10)
197 218
198This uses the Solaris 10 port mechanism. As with everything on Solaris, 219This uses the Solaris 10 port mechanism. As with everything on Solaris,
199it'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)).
200 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
201=item C<EVMETHOD_ALL> 226=item C<EVBACKEND_ALL>
202 227
203Try all backends (even potentially broken ones that wouldn't be tried 228Try all backends (even potentially broken ones that wouldn't be tried
204with 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
205C<EVMETHOD_ALL & ~EVMETHOD_KQUEUE>. 230C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
206 231
207=back 232=back
208 233
209If 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
210backends 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
211specified, most compiled-in backend will be tried, usually in reverse 236specified, most compiled-in backend will be tried, usually in reverse
212order of their flag values :) 237order of their flag values :)
213 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
214=item struct ev_loop *ev_loop_new (unsigned int flags) 255=item struct ev_loop *ev_loop_new (unsigned int flags)
215 256
216Similar 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
217always distinct from the default loop. Unlike the default loop, it cannot 258always distinct from the default loop. Unlike the default loop, it cannot
218handle 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
… …
244it just in case after a fork. To make this easy, the function will fit in 285it just in case after a fork. To make this easy, the function will fit in
245quite nicely into a call to C<pthread_atfork>: 286quite nicely into a call to C<pthread_atfork>:
246 287
247 pthread_atfork (0, 0, ev_default_fork); 288 pthread_atfork (0, 0, ev_default_fork);
248 289
290At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
291without calling this function, so if you force one of those backends you
292do not need to care.
293
249=item ev_loop_fork (loop) 294=item ev_loop_fork (loop)
250 295
251Like C<ev_default_fork>, but acts on an event loop created by 296Like C<ev_default_fork>, but acts on an event loop created by
252C<ev_loop_new>. Yes, you have to call this on every allocated event loop 297C<ev_loop_new>. Yes, you have to call this on every allocated event loop
253after fork, and how you do this is entirely your own problem. 298after fork, and how you do this is entirely your own problem.
254 299
255=item unsigned int ev_method (loop) 300=item unsigned int ev_backend (loop)
256 301
257Returns one of the C<EVMETHOD_*> flags indicating the event backend in 302Returns one of the C<EVBACKEND_*> flags indicating the event backend in
258use. 303use.
259 304
260=item ev_tstamp ev_now (loop) 305=item ev_tstamp ev_now (loop)
261 306
262Returns the current "event loop time", which is the time the event loop 307Returns the current "event loop time", which is the time the event loop
… …
269 314
270Finally, this is it, the event handler. This function usually is called 315Finally, this is it, the event handler. This function usually is called
271after you initialised all your watchers and you want to start handling 316after you initialised all your watchers and you want to start handling
272events. 317events.
273 318
274If 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
275no event watchers are active anymore or C<ev_unloop> was called. 320either no event watchers are active anymore or C<ev_unloop> was called.
276 321
277A 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
278those 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
279case 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.
280 325
281A 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
282neccessary) and will handle those and any outstanding ones. It will block 327neccessary) and will handle those and any outstanding ones. It will block
283your 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
284one 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.
285 333
286This flags value could be used to implement alternative looping
287constructs, but the C<prepare> and C<check> watchers provide a better and
288more generic mechanism.
289
290Here are the gory details of what ev_loop does: 334Here are the gory details of what C<ev_loop> does:
291 335
292 1. If there are no active watchers (reference count is zero), return. 336 * If there are no active watchers (reference count is zero), return.
293 2. Queue and immediately call all prepare watchers. 337 - Queue prepare watchers and then call all outstanding watchers.
294 3. If we have been forked, recreate the kernel state. 338 - If we have been forked, recreate the kernel state.
295 4. Update the kernel state with all outstanding changes. 339 - Update the kernel state with all outstanding changes.
296 5. Update the "event loop time". 340 - Update the "event loop time".
297 6. Calculate for how long to block. 341 - Calculate for how long to block.
298 7. Block the process, waiting for events. 342 - Block the process, waiting for any events.
343 - Queue all outstanding I/O (fd) events.
299 8. Update the "event loop time" and do time jump handling. 344 - Update the "event loop time" and do time jump handling.
300 9. Queue all outstanding timers. 345 - Queue all outstanding timers.
301 10. Queue all outstanding periodics. 346 - Queue all outstanding periodics.
302 11. If no events are pending now, queue all idle watchers. 347 - If no events are pending now, queue all idle watchers.
303 12. Queue all check watchers. 348 - Queue all check watchers.
304 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.
305 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
306 was used, return, otherwise continue with step #1. 353 were used, return, otherwise continue with step *.
307 354
308=item ev_unloop (loop, how) 355=item ev_unloop (loop, how)
309 356
310Can 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
311has processed all outstanding events). The C<how> argument must be either 358has processed all outstanding events). The C<how> argument must be either
… …
368*) >>), and you can stop watching for events at any time by calling the 415*) >>), and you can stop watching for events at any time by calling the
369corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>. 416corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
370 417
371As long as your watcher is active (has been started but not stopped) you 418As long as your watcher is active (has been started but not stopped) you
372must not touch the values stored in it. Most specifically you must never 419must not touch the values stored in it. Most specifically you must never
373reinitialise it or call its set method. 420reinitialise it or call its set macro.
374 421
375You can check whether an event is active by calling the C<ev_is_active 422You can check whether an event is active by calling the C<ev_is_active
376(watcher *)> macro. To see whether an event is outstanding (but the 423(watcher *)> macro. To see whether an event is outstanding (but the
377callback for it has not been called yet) you can use the C<ev_is_pending 424callback for it has not been called yet) you can use the C<ev_is_pending
378(watcher *)> macro. 425(watcher *)> macro.
… …
495descriptors correctly if you register interest in two or more fds pointing 542descriptors correctly if you register interest in two or more fds pointing
496to the same underlying file/socket etc. description (that is, they share 543to the same underlying file/socket etc. description (that is, they share
497the same underlying "file open"). 544the same underlying "file open").
498 545
499If you must do this, then force the use of a known-to-be-good backend 546If you must do this, then force the use of a known-to-be-good backend
500(at the time of this writing, this includes only EVMETHOD_SELECT and 547(at the time of this writing, this includes only C<EVBACKEND_SELECT> and
501EVMETHOD_POLL). 548C<EVBACKEND_POLL>).
502 549
503=over 4 550=over 4
504 551
505=item ev_io_init (ev_io *, callback, int fd, int events) 552=item ev_io_init (ev_io *, callback, int fd, int events)
506 553
507=item ev_io_set (ev_io *, int fd, int events) 554=item ev_io_set (ev_io *, int fd, int events)
508 555
509Configures 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
510events 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 |
511EV_WRITE> to receive the given events. 558EV_WRITE> to receive the given events.
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.
512 570
513=back 571=back
514 572
515=head2 C<ev_timer> - relative and optionally recurring timeouts 573=head2 C<ev_timer> - relative and optionally recurring timeouts
516 574

Diff Legend

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