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

Comparing libev/ev.3 (file contents):
Revision 1.91 by root, Mon Apr 2 23:46:27 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-04-03" "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
1140this callback instead. This is useful, for example, when you want to 1140this callback instead. This is useful, for example, when you want to
1141invoke the actual watchers inside another context (another thread etc.). 1141invoke the actual watchers inside another context (another thread etc.).
1142.Sp 1142.Sp
1143If 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
1144callback. 1144callback.
1145.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
1146.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 ())"
1147Sometimes you want to share the same loop between multiple threads. This 1147Sometimes you want to share the same loop between multiple threads. This
1148can be done relatively simply by putting mutex_lock/unlock calls around 1148can be done relatively simply by putting mutex_lock/unlock calls around
1149each call to a libev function. 1149each call to a libev function.
1150.Sp 1150.Sp
1151However, \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
4034.IP "\(bu" 4 4034.IP "\(bu" 4
4035The 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
4036to use the libev header file and library. 4036to use the libev header file and library.
4037.SH "\*(C+ SUPPORT" 4037.SH "\*(C+ SUPPORT"
4038.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"
4039Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow 4073Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
4040you 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
4041the callback model to a model using method callbacks on objects. 4075the callback model to a model using method callbacks on objects.
4042.PP 4076.PP
4043To use it, 4077To use it,

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines