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

Comparing libev/ev.pod (file contents):
Revision 1.337 by root, Sun Oct 31 20:20:20 2010 UTC vs.
Revision 1.341 by root, Fri Nov 5 22:08:09 2010 UTC

… …
241the current system, you would need to look at C<ev_embeddable_backends () 241the current system, you would need to look at C<ev_embeddable_backends ()
242& ev_supported_backends ()>, likewise for recommended ones. 242& ev_supported_backends ()>, likewise for recommended ones.
243 243
244See the description of C<ev_embed> watchers for more info. 244See the description of C<ev_embed> watchers for more info.
245 245
246=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT] 246=item ev_set_allocator (void *(*cb)(void *ptr, long size))
247 247
248Sets the allocation function to use (the prototype is similar - the 248Sets the allocation function to use (the prototype is similar - the
249semantics are identical to the C<realloc> C89/SuS/POSIX function). It is 249semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
250used to allocate and free memory (no surprises here). If it returns zero 250used to allocate and free memory (no surprises here). If it returns zero
251when memory needs to be allocated (C<size != 0>), the library might abort 251when memory needs to be allocated (C<size != 0>), the library might abort
… …
277 } 277 }
278 278
279 ... 279 ...
280 ev_set_allocator (persistent_realloc); 280 ev_set_allocator (persistent_realloc);
281 281
282=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT] 282=item ev_set_syserr_cb (void (*cb)(const char *msg))
283 283
284Set the callback function to call on a retryable system call error (such 284Set the callback function to call on a retryable system call error (such
285as failed select, poll, epoll_wait). The message is a printable string 285as failed select, poll, epoll_wait). The message is a printable string
286indicating the system call or subsystem causing the problem. If this 286indicating the system call or subsystem causing the problem. If this
287callback is set, then libev will expect it to remedy the situation, no 287callback is set, then libev will expect it to remedy the situation, no
… …
402environment variable. 402environment variable.
403 403
404=item C<EVFLAG_NOINOTIFY> 404=item C<EVFLAG_NOINOTIFY>
405 405
406When this flag is specified, then libev will not attempt to use the 406When this flag is specified, then libev will not attempt to use the
407I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and 407I<inotify> API for its C<ev_stat> watchers. Apart from debugging and
408testing, this flag can be useful to conserve inotify file descriptors, as 408testing, this flag can be useful to conserve inotify file descriptors, as
409otherwise each loop using C<ev_stat> watchers consumes one inotify handle. 409otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
410 410
411=item C<EVFLAG_SIGNALFD> 411=item C<EVFLAG_SIGNALFD>
412 412
413When this flag is specified, then libev will attempt to use the 413When this flag is specified, then libev will attempt to use the
414I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API 414I<signalfd> API for its C<ev_signal> (and C<ev_child>) watchers. This API
415delivers signals synchronously, which makes it both faster and might make 415delivers signals synchronously, which makes it both faster and might make
416it possible to get the queued signal data. It can also simplify signal 416it possible to get the queued signal data. It can also simplify signal
417handling with threads, as long as you properly block signals in your 417handling with threads, as long as you properly block signals in your
418threads that are not interested in handling them. 418threads that are not interested in handling them.
419 419
… …
464 464
465The epoll mechanism deserves honorable mention as the most misdesigned 465The epoll mechanism deserves honorable mention as the most misdesigned
466of the more advanced event mechanisms: mere annoyances include silently 466of the more advanced event mechanisms: mere annoyances include silently
467dropping file descriptors, requiring a system call per change per file 467dropping file descriptors, requiring a system call per change per file
468descriptor (and unnecessary guessing of parameters), problems with dup, 468descriptor (and unnecessary guessing of parameters), problems with dup,
469returning before the timeout value requiring additional iterations and so 469returning before the timeout value, resulting in additional iterations
470(and only giving 5ms accuracy while select on the same platform gives
470on. The biggest issue is fork races, however - if a program forks then 4710.1ms) and so on. The biggest issue is fork races, however - if a program
471I<both> parent and child process have to recreate the epoll set, which can 472forks then I<both> parent and child process have to recreate the epoll
472take considerable time (one syscall per file descriptor) and is of course 473set, which can take considerable time (one syscall per file descriptor)
473hard to detect. 474and is of course hard to detect.
474 475
475Epoll is also notoriously buggy - embedding epoll fds I<should> work, but 476Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
476of course I<doesn't>, and epoll just loves to report events for totally 477of course I<doesn't>, and epoll just loves to report events for totally
477I<different> file descriptors (even already closed ones, so one cannot 478I<different> file descriptors (even already closed ones, so one cannot
478even remove them from the set) than registered in the set (especially 479even remove them from the set) than registered in the set (especially
… …
480employing an additional generation counter and comparing that against the 481employing an additional generation counter and comparing that against the
481events to filter out spurious ones, recreating the set when required. Last 482events to filter out spurious ones, recreating the set when required. Last
482not least, it also refuses to work with some file descriptors which work 483not least, it also refuses to work with some file descriptors which work
483perfectly fine with C<select> (files, many character devices...). 484perfectly fine with C<select> (files, many character devices...).
484 485
486Epoll is truly the train wreck analog among event poll mechanisms.
487
485While stopping, setting and starting an I/O watcher in the same iteration 488While stopping, setting and starting an I/O watcher in the same iteration
486will result in some caching, there is still a system call per such 489will result in some caching, there is still a system call per such
487incident (because the same I<file descriptor> could point to a different 490incident (because the same I<file descriptor> could point to a different
488I<file description> now), so its best to avoid that. Also, C<dup ()>'ed 491I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
489file descriptors might not work very well if you register events for both 492file descriptors might not work very well if you register events for both
… …
616This function is normally used on loop objects allocated by 619This function is normally used on loop objects allocated by
617C<ev_loop_new>, but it can also be used on the default loop returned by 620C<ev_loop_new>, but it can also be used on the default loop returned by
618C<ev_default_loop>, in which case it is not thread-safe. 621C<ev_default_loop>, in which case it is not thread-safe.
619 622
620Note that it is not advisable to call this function on the default loop 623Note that it is not advisable to call this function on the default loop
621except in the rare occasion where you really need to free it's resources. 624except in the rare occasion where you really need to free its resources.
622If you need dynamically allocated loops it is better to use C<ev_loop_new> 625If you need dynamically allocated loops it is better to use C<ev_loop_new>
623and C<ev_loop_destroy>. 626and C<ev_loop_destroy>.
624 627
625=item ev_loop_fork (loop) 628=item ev_loop_fork (loop)
626 629
… …
2257 2260
2258=head2 C<ev_signal> - signal me when a signal gets signalled! 2261=head2 C<ev_signal> - signal me when a signal gets signalled!
2259 2262
2260Signal watchers will trigger an event when the process receives a specific 2263Signal watchers will trigger an event when the process receives a specific
2261signal one or more times. Even though signals are very asynchronous, libev 2264signal one or more times. Even though signals are very asynchronous, libev
2262will try it's best to deliver signals synchronously, i.e. as part of the 2265will try its best to deliver signals synchronously, i.e. as part of the
2263normal event processing, like any other event. 2266normal event processing, like any other event.
2264 2267
2265If you want signals to be delivered truly asynchronously, just use 2268If you want signals to be delivered truly asynchronously, just use
2266C<sigaction> as you would do without libev and forget about sharing 2269C<sigaction> as you would do without libev and forget about sharing
2267the signal. You can even use C<ev_async> from a signal handler to 2270the signal. You can even use C<ev_async> from a signal handler to
… …
3378=item * Priorities are not currently supported. Initialising priorities 3381=item * Priorities are not currently supported. Initialising priorities
3379will fail and all watchers will have the same priority, even though there 3382will fail and all watchers will have the same priority, even though there
3380is an ev_pri field. 3383is an ev_pri field.
3381 3384
3382=item * In libevent, the last base created gets the signals, in libev, the 3385=item * In libevent, the last base created gets the signals, in libev, the
3383first base created (== the default loop) gets the signals. 3386base that registered the signal gets the signals.
3384 3387
3385=item * Other members are not supported. 3388=item * Other members are not supported.
3386 3389
3387=item * The libev emulation is I<not> ABI compatible to libevent, you need 3390=item * The libev emulation is I<not> ABI compatible to libevent, you need
3388to use the libev header file and library. 3391to use the libev header file and library.

Diff Legend

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