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

Comparing libev/ev.3 (file contents):
Revision 1.83 by root, Mon Oct 25 11:30:45 2010 UTC vs.
Revision 1.84 by root, Fri Nov 5 22:28:54 2010 UTC

… …
122.\} 122.\}
123.rm #[ #] #H #V #F C 123.rm #[ #] #H #V #F C
124.\" ======================================================================== 124.\" ========================================================================
125.\" 125.\"
126.IX Title "LIBEV 3" 126.IX Title "LIBEV 3"
127.TH LIBEV 3 "2010-10-25" "libev-4.00" "libev - high performance full featured event loop" 127.TH LIBEV 3 "2010-11-03" "libev-4.01" "libev - high performance full featured event loop"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 129.\" way too many mistakes in technical documents.
130.if n .ad l 130.if n .ad l
131.nh 131.nh
132.SH "NAME" 132.SH "NAME"
… …
361current system. To find which embeddable backends might be supported on 361current system. To find which embeddable backends might be supported on
362the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () 362the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends ()
363& ev_supported_backends ()\*(C'\fR, likewise for recommended ones. 363& ev_supported_backends ()\*(C'\fR, likewise for recommended ones.
364.Sp 364.Sp
365See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 365See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
366.IP "ev_set_allocator (void *(*cb)(void *ptr, long size)) [\s-1NOT\s0 \s-1REENTRANT\s0]" 4 366.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4
367.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]" 367.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))"
368Sets the allocation function to use (the prototype is similar \- the 368Sets the allocation function to use (the prototype is similar \- the
369semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is 369semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is
370used to allocate and free memory (no surprises here). If it returns zero 370used to allocate and free memory (no surprises here). If it returns zero
371when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort 371when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort
372or take some potentially destructive action. 372or take some potentially destructive action.
… …
398\& } 398\& }
399\& 399\&
400\& ... 400\& ...
401\& ev_set_allocator (persistent_realloc); 401\& ev_set_allocator (persistent_realloc);
402.Ve 402.Ve
403.IP "ev_set_syserr_cb (void (*cb)(const char *msg)); [\s-1NOT\s0 \s-1REENTRANT\s0]" 4 403.IP "ev_set_syserr_cb (void (*cb)(const char *msg))" 4
404.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]" 404.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg))"
405Set the callback function to call on a retryable system call error (such 405Set the callback function to call on a retryable system call error (such
406as failed select, poll, epoll_wait). The message is a printable string 406as failed select, poll, epoll_wait). The message is a printable string
407indicating the system call or subsystem causing the problem. If this 407indicating the system call or subsystem causing the problem. If this
408callback is set, then libev will expect it to remedy the situation, no 408callback is set, then libev will expect it to remedy the situation, no
409matter what, when it returns. That is, libev will generally retry the 409matter what, when it returns. That is, libev will generally retry the
… …
521environment variable. 521environment variable.
522.ie n .IP """EVFLAG_NOINOTIFY""" 4 522.ie n .IP """EVFLAG_NOINOTIFY""" 4
523.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 523.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4
524.IX Item "EVFLAG_NOINOTIFY" 524.IX Item "EVFLAG_NOINOTIFY"
525When this flag is specified, then libev will not attempt to use the 525When this flag is specified, then libev will not attempt to use the
526\&\fIinotify\fR \s-1API\s0 for it's \f(CW\*(C`ev_stat\*(C'\fR watchers. Apart from debugging and 526\&\fIinotify\fR \s-1API\s0 for its \f(CW\*(C`ev_stat\*(C'\fR watchers. Apart from debugging and
527testing, this flag can be useful to conserve inotify file descriptors, as 527testing, this flag can be useful to conserve inotify file descriptors, as
528otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle. 528otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle.
529.ie n .IP """EVFLAG_SIGNALFD""" 4 529.ie n .IP """EVFLAG_SIGNALFD""" 4
530.el .IP "\f(CWEVFLAG_SIGNALFD\fR" 4 530.el .IP "\f(CWEVFLAG_SIGNALFD\fR" 4
531.IX Item "EVFLAG_SIGNALFD" 531.IX Item "EVFLAG_SIGNALFD"
532When this flag is specified, then libev will attempt to use the 532When this flag is specified, then libev will attempt to use the
533\&\fIsignalfd\fR \s-1API\s0 for it's \f(CW\*(C`ev_signal\*(C'\fR (and \f(CW\*(C`ev_child\*(C'\fR) watchers. This \s-1API\s0 533\&\fIsignalfd\fR \s-1API\s0 for its \f(CW\*(C`ev_signal\*(C'\fR (and \f(CW\*(C`ev_child\*(C'\fR) watchers. This \s-1API\s0
534delivers signals synchronously, which makes it both faster and might make 534delivers signals synchronously, which makes it both faster and might make
535it possible to get the queued signal data. It can also simplify signal 535it possible to get the queued signal data. It can also simplify signal
536handling with threads, as long as you properly block signals in your 536handling with threads, as long as you properly block signals in your
537threads that are not interested in handling them. 537threads that are not interested in handling them.
538.Sp 538.Sp
… …
582epoll scales either O(1) or O(active_fds). 582epoll scales either O(1) or O(active_fds).
583.Sp 583.Sp
584The epoll mechanism deserves honorable mention as the most misdesigned 584The epoll mechanism deserves honorable mention as the most misdesigned
585of the more advanced event mechanisms: mere annoyances include silently 585of the more advanced event mechanisms: mere annoyances include silently
586dropping file descriptors, requiring a system call per change per file 586dropping file descriptors, requiring a system call per change per file
587descriptor (and unnecessary guessing of parameters), problems with dup and 587descriptor (and unnecessary guessing of parameters), problems with dup,
588returning before the timeout value, resulting in additional iterations
589(and only giving 5ms accuracy while select on the same platform gives
588so on. The biggest issue is fork races, however \- if a program forks then 5900.1ms) and so on. The biggest issue is fork races, however \- if a program
589\&\fIboth\fR parent and child process have to recreate the epoll set, which can 591forks then \fIboth\fR parent and child process have to recreate the epoll
590take considerable time (one syscall per file descriptor) and is of course 592set, which can take considerable time (one syscall per file descriptor)
591hard to detect. 593and is of course hard to detect.
592.Sp 594.Sp
593Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but 595Epoll is also notoriously buggy \- embedding epoll fds \fIshould\fR work, but
594of course \fIdoesn't\fR, and epoll just loves to report events for totally 596of course \fIdoesn't\fR, and epoll just loves to report events for totally
595\&\fIdifferent\fR file descriptors (even already closed ones, so one cannot 597\&\fIdifferent\fR file descriptors (even already closed ones, so one cannot
596even remove them from the set) than registered in the set (especially 598even remove them from the set) than registered in the set (especially
597on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by 599on \s-1SMP\s0 systems). Libev tries to counter these spurious notifications by
598employing an additional generation counter and comparing that against the 600employing an additional generation counter and comparing that against the
599events to filter out spurious ones, recreating the set when required. Last 601events to filter out spurious ones, recreating the set when required. Last
600not least, it also refuses to work with some file descriptors which work 602not least, it also refuses to work with some file descriptors which work
601perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...). 603perfectly fine with \f(CW\*(C`select\*(C'\fR (files, many character devices...).
604.Sp
605Epoll is truly the train wreck analog among event poll mechanisms.
602.Sp 606.Sp
603While stopping, setting and starting an I/O watcher in the same iteration 607While stopping, setting and starting an I/O watcher in the same iteration
604will result in some caching, there is still a system call per such 608will result in some caching, there is still a system call per such
605incident (because the same \fIfile descriptor\fR could point to a different 609incident (because the same \fIfile descriptor\fR could point to a different
606\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed 610\&\fIfile description\fR now), so its best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed
… …
738This function is normally used on loop objects allocated by 742This function is normally used on loop objects allocated by
739\&\f(CW\*(C`ev_loop_new\*(C'\fR, but it can also be used on the default loop returned by 743\&\f(CW\*(C`ev_loop_new\*(C'\fR, but it can also be used on the default loop returned by
740\&\f(CW\*(C`ev_default_loop\*(C'\fR, in which case it is not thread-safe. 744\&\f(CW\*(C`ev_default_loop\*(C'\fR, in which case it is not thread-safe.
741.Sp 745.Sp
742Note that it is not advisable to call this function on the default loop 746Note that it is not advisable to call this function on the default loop
743except in the rare occasion where you really need to free it's resources. 747except in the rare occasion where you really need to free its resources.
744If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR 748If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR
745and \f(CW\*(C`ev_loop_destroy\*(C'\fR. 749and \f(CW\*(C`ev_loop_destroy\*(C'\fR.
746.IP "ev_loop_fork (loop)" 4 750.IP "ev_loop_fork (loop)" 4
747.IX Item "ev_loop_fork (loop)" 751.IX Item "ev_loop_fork (loop)"
748This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations to 752This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations to
… …
2391.ie n .SS """ev_signal"" \- signal me when a signal gets signalled!" 2395.ie n .SS """ev_signal"" \- signal me when a signal gets signalled!"
2392.el .SS "\f(CWev_signal\fP \- signal me when a signal gets signalled!" 2396.el .SS "\f(CWev_signal\fP \- signal me when a signal gets signalled!"
2393.IX Subsection "ev_signal - signal me when a signal gets signalled!" 2397.IX Subsection "ev_signal - signal me when a signal gets signalled!"
2394Signal watchers will trigger an event when the process receives a specific 2398Signal watchers will trigger an event when the process receives a specific
2395signal one or more times. Even though signals are very asynchronous, libev 2399signal one or more times. Even though signals are very asynchronous, libev
2396will try it's best to deliver signals synchronously, i.e. as part of the 2400will try its best to deliver signals synchronously, i.e. as part of the
2397normal event processing, like any other event. 2401normal event processing, like any other event.
2398.PP 2402.PP
2399If you want signals to be delivered truly asynchronously, just use 2403If you want signals to be delivered truly asynchronously, just use
2400\&\f(CW\*(C`sigaction\*(C'\fR as you would do without libev and forget about sharing 2404\&\f(CW\*(C`sigaction\*(C'\fR as you would do without libev and forget about sharing
2401the signal. You can even use \f(CW\*(C`ev_async\*(C'\fR from a signal handler to 2405the signal. You can even use \f(CW\*(C`ev_async\*(C'\fR from a signal handler to

Diff Legend

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