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

Comparing libev/ev.3 (file contents):
Revision 1.89 by root, Sat Mar 24 19:38:51 2012 UTC vs.
Revision 1.92 by root, Sun Apr 22 10:14:20 2012 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 "2012-03-23" "libev-4.11" "libev - high performance full featured event loop" 127.TH LIBEV 3 "2012-04-19" "libev-4.11" "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"
… …
367current system. To find which embeddable backends might be supported on 367current system. To find which embeddable backends might be supported on
368the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () 368the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends ()
369& ev_supported_backends ()\*(C'\fR, likewise for recommended ones. 369& ev_supported_backends ()\*(C'\fR, likewise for recommended ones.
370.Sp 370.Sp
371See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 371See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
372.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 372.IP "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())" 4
373.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" 373.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())"
374Sets the allocation function to use (the prototype is similar \- the 374Sets the allocation function to use (the prototype is similar \- the
375semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is 375semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is
376used to allocate and free memory (no surprises here). If it returns zero 376used to allocate and free memory (no surprises here). If it returns zero
377when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort 377when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort
378or take some potentially destructive action. 378or take some potentially destructive action.
… …
404\& } 404\& }
405\& 405\&
406\& ... 406\& ...
407\& ev_set_allocator (persistent_realloc); 407\& ev_set_allocator (persistent_realloc);
408.Ve 408.Ve
409.IP "ev_set_syserr_cb (void (*cb)(const char *msg))" 4 409.IP "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())" 4
410.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg))" 410.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg) throw ())"
411Set the callback function to call on a retryable system call error (such 411Set the callback function to call on a retryable system call error (such
412as failed select, poll, epoll_wait). The message is a printable string 412as failed select, poll, epoll_wait). The message is a printable string
413indicating the system call or subsystem causing the problem. If this 413indicating the system call or subsystem causing the problem. If this
414callback is set, then libev will expect it to remedy the situation, no 414callback is set, then libev will expect it to remedy the situation, no
415matter what, when it returns. That is, libev will generally retry the 415matter what, when it returns. That is, libev will generally retry the
… …
685.Sp 685.Sp
686It scales in the same way as the epoll backend, but the interface to the 686It scales in the same way as the epoll backend, but the interface to the
687kernel is more efficient (which says nothing about its actual speed, of 687kernel is more efficient (which says nothing about its actual speed, of
688course). While stopping, setting and starting an I/O watcher does never 688course). While stopping, setting and starting an I/O watcher does never
689cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 689cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
690two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (but 690two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
691sane, unlike epoll) and it drops fds silently in similarly hard-to-detect 691might have to leak fd's on fork, but it's more sane than epoll) and it
692cases 692drops fds silently in similarly hard-to-detect cases
693.Sp 693.Sp
694This backend usually performs well under most conditions. 694This backend usually performs well under most conditions.
695.Sp 695.Sp
696While nominally embeddable in other event loops, this doesn't work 696While nominally embeddable in other event loops, this doesn't work
697everywhere, so you might need to test for this. And since it is broken 697everywhere, so you might need to test for this. And since it is broken
… …
909given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR 909given loop other than \f(CW\*(C`ev_resume\*(C'\fR, and you \fBmust not\fR call \f(CW\*(C`ev_resume\*(C'\fR
910without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR. 910without a previous call to \f(CW\*(C`ev_suspend\*(C'\fR.
911.Sp 911.Sp
912Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the 912Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the
913event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). 913event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR).
914.IP "ev_run (loop, int flags)" 4 914.IP "bool ev_run (loop, int flags)" 4
915.IX Item "ev_run (loop, int flags)" 915.IX Item "bool ev_run (loop, int flags)"
916Finally, this is it, the event handler. This function usually is called 916Finally, this is it, the event handler. This function usually is called
917after you have initialised all your watchers and you want to start 917after you have initialised all your watchers and you want to start
918handling events. It will ask the operating system for any new events, call 918handling events. It will ask the operating system for any new events, call
919the watcher callbacks, an then repeat the whole process indefinitely: This 919the watcher callbacks, and then repeat the whole process indefinitely: This
920is why event loops are called \fIloops\fR. 920is why event loops are called \fIloops\fR.
921.Sp 921.Sp
922If the flags argument is specified as \f(CW0\fR, it will keep handling events 922If the flags argument is specified as \f(CW0\fR, it will keep handling events
923until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was 923until either no event watchers are active anymore or \f(CW\*(C`ev_break\*(C'\fR was
924called. 924called.
925.Sp
926The return value is false if there are no more active watchers (which
927usually means \*(L"all jobs done\*(R" or \*(L"deadlock\*(R"), and true in all other cases
928(which usually means " you should call \f(CW\*(C`ev_run\*(C'\fR again").
925.Sp 929.Sp
926Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than 930Please note that an explicit \f(CW\*(C`ev_break\*(C'\fR is usually better than
927relying on all watchers to be stopped when deciding when a program has 931relying on all watchers to be stopped when deciding when a program has
928finished (especially in interactive programs), but having a program 932finished (especially in interactive programs), but having a program
929that automatically loops as long as it has to and no longer by virtue 933that automatically loops as long as it has to and no longer by virtue
930of relying on its watchers stopping correctly, that is truly a thing of 934of relying on its watchers stopping correctly, that is truly a thing of
931beauty. 935beauty.
932.Sp 936.Sp
933This function is also \fImostly\fR exception-safe \- you can break out of 937This function is \fImostly\fR exception-safe \- you can break out of a
934a \f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+ 938\&\f(CW\*(C`ev_run\*(C'\fR call by calling \f(CW\*(C`longjmp\*(C'\fR in a callback, throwing a \*(C+
935exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor 939exception and so on. This does not decrement the \f(CW\*(C`ev_depth\*(C'\fR value, nor
936will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks. 940will it clear any outstanding \f(CW\*(C`EVBREAK_ONE\*(C'\fR breaks.
937.Sp 941.Sp
938A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle 942A flags value of \f(CW\*(C`EVRUN_NOWAIT\*(C'\fR will look for new events, will handle
939those events and any already outstanding ones, but will not wait and 943those events and any already outstanding ones, but will not wait and
… …
1136this callback instead. This is useful, for example, when you want to 1140this callback instead. This is useful, for example, when you want to
1137invoke the actual watchers inside another context (another thread etc.). 1141invoke the actual watchers inside another context (another thread etc.).
1138.Sp 1142.Sp
1139If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new 1143If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new
1140callback. 1144callback.
1141.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0), void (*acquire)(\s-1EV_P\s0))" 4 1145.IP "ev_set_loop_release_cb (loop, void (*release)(\s-1EV_P\s0) throw (), void (*acquire)(\s-1EV_P\s0) throw ())" 4
1142.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))" 1146.IX Item "ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())"
1143Sometimes you want to share the same loop between multiple threads. This 1147Sometimes you want to share the same loop between multiple threads. This
1144can be done relatively simply by putting mutex_lock/unlock calls around 1148can be done relatively simply by putting mutex_lock/unlock calls around
1145each call to a libev function. 1149each call to a libev function.
1146.Sp 1150.Sp
1147However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible 1151However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible
… …
4030.IP "\(bu" 4 4034.IP "\(bu" 4
4031The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need 4035The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need
4032to use the libev header file and library. 4036to use the libev header file and library.
4033.SH "\*(C+ SUPPORT" 4037.SH "\*(C+ SUPPORT"
4034.IX Header " SUPPORT" 4038.IX Header " SUPPORT"
4039.SS "C \s-1API\s0"
4040.IX Subsection "C API"
4041The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4042libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4043will work fine.
4044.PP
4045Proper exception specifications might have to be added to callbacks passed
4046to libev: exceptions may be thrown only from watcher callbacks, all
4047other callbacks (allocator, syserr, loop acquire/release and periodioc
4048reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw
4049()\*(C'\fR specification. If you have code that needs to be compiled as both C
4050and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this:
4051.PP
4052.Vb 6
4053\& static void
4054\& fatal_error (const char *msg) EV_THROW
4055\& {
4056\& perror (msg);
4057\& abort ();
4058\& }
4059\&
4060\& ...
4061\& ev_set_syserr_cb (fatal_error);
4062.Ve
4063.PP
4064The only \s-1API\s0 functions that can currently throw exceptions are \f(CW\*(C`ev_run\*(C'\fR,
4065\&\f(CW\*(C`ev_inoke\*(C'\fR, \f(CW\*(C`ev_invoke_pending\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR (the latter
4066because it runs cleanup watchers).
4067.PP
4068Throwing exceptions in watcher callbacks is only supported if libev itself
4069is compiled with a \*(C+ compiler or your C and \*(C+ environments allow
4070throwing exceptions through C libraries (most do).
4071.SS "\*(C+ \s-1API\s0"
4072.IX Subsection " API"
4035Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow 4073Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
4036you to use some convenience methods to start/stop watchers and also change 4074you to use some convenience methods to start/stop watchers and also change
4037the callback model to a model using method callbacks on objects. 4075the callback model to a model using method callbacks on objects.
4038.PP 4076.PP
4039To use it, 4077To use it,
… …
4722\& #define EV_CHILD_ENABLE 1 4760\& #define EV_CHILD_ENABLE 1
4723\& #define EV_ASYNC_ENABLE 1 4761\& #define EV_ASYNC_ENABLE 1
4724.Ve 4762.Ve
4725.Sp 4763.Sp
4726The actual value is a bitset, it can be a combination of the following 4764The actual value is a bitset, it can be a combination of the following
4727values: 4765values (by default, all of these are enabled):
4728.RS 4 4766.RS 4
4729.ie n .IP "1 \- faster/larger code" 4 4767.ie n .IP "1 \- faster/larger code" 4
4730.el .IP "\f(CW1\fR \- faster/larger code" 4 4768.el .IP "\f(CW1\fR \- faster/larger code" 4
4731.IX Item "1 - faster/larger code" 4769.IX Item "1 - faster/larger code"
4732Use larger code to speed up some operations. 4770Use larger code to speed up some operations.
… …
4735code size by roughly 30% on amd64). 4773code size by roughly 30% on amd64).
4736.Sp 4774.Sp
4737When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with 4775When optimising for size, use of compiler flags such as \f(CW\*(C`\-Os\*(C'\fR with
4738gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of 4776gcc is recommended, as well as \f(CW\*(C`\-DNDEBUG\*(C'\fR, as libev contains a number of
4739assertions. 4777assertions.
4778.Sp
4779The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4780(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4740.ie n .IP "2 \- faster/larger data structures" 4 4781.ie n .IP "2 \- faster/larger data structures" 4
4741.el .IP "\f(CW2\fR \- faster/larger data structures" 4 4782.el .IP "\f(CW2\fR \- faster/larger data structures" 4
4742.IX Item "2 - faster/larger data structures" 4783.IX Item "2 - faster/larger data structures"
4743Replaces the small 2\-heap for timer management by a faster 4\-heap, larger 4784Replaces the small 2\-heap for timer management by a faster 4\-heap, larger
4744hash table sizes and so on. This will usually further increase code size 4785hash table sizes and so on. This will usually further increase code size
4745and can additionally have an effect on the size of data structures at 4786and can additionally have an effect on the size of data structures at
4746runtime. 4787runtime.
4788.Sp
4789The default is off when \f(CW\*(C`_\|_OPTIMIZE_SIZE_\|_\*(C'\fR is defined by your compiler
4790(e.g. gcc with \f(CW\*(C`\-Os\*(C'\fR).
4747.ie n .IP "4 \- full \s-1API\s0 configuration" 4 4791.ie n .IP "4 \- full \s-1API\s0 configuration" 4
4748.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4 4792.el .IP "\f(CW4\fR \- full \s-1API\s0 configuration" 4
4749.IX Item "4 - full API configuration" 4793.IX Item "4 - full API configuration"
4750This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and 4794This enables priorities (sets \f(CW\*(C`EV_MAXPRI\*(C'\fR=2 and \f(CW\*(C`EV_MINPRI\*(C'\fR=\-2), and
4751enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1). 4795enables multiplicity (\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR=1).

Diff Legend

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