… | |
… | |
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" |
… | |
… | |
367 | current system. To find which embeddable backends might be supported on |
367 | current system. To find which embeddable backends might be supported on |
368 | the current system, you would need to look at \f(CW\*(C`ev_embeddable_backends () |
368 | the 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 |
371 | See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
371 | See 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 ())" |
374 | Sets the allocation function to use (the prototype is similar \- the |
374 | Sets the allocation function to use (the prototype is similar \- the |
375 | semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is |
375 | semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is |
376 | used to allocate and free memory (no surprises here). If it returns zero |
376 | used to allocate and free memory (no surprises here). If it returns zero |
377 | when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort |
377 | when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort |
378 | or take some potentially destructive action. |
378 | or 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 ())" |
411 | Set the callback function to call on a retryable system call error (such |
411 | Set the callback function to call on a retryable system call error (such |
412 | as failed select, poll, epoll_wait). The message is a printable string |
412 | as failed select, poll, epoll_wait). The message is a printable string |
413 | indicating the system call or subsystem causing the problem. If this |
413 | indicating the system call or subsystem causing the problem. If this |
414 | callback is set, then libev will expect it to remedy the situation, no |
414 | callback is set, then libev will expect it to remedy the situation, no |
415 | matter what, when it returns. That is, libev will generally retry the |
415 | matter what, when it returns. That is, libev will generally retry the |
… | |
… | |
1140 | this callback instead. This is useful, for example, when you want to |
1140 | this callback instead. This is useful, for example, when you want to |
1141 | invoke the actual watchers inside another context (another thread etc.). |
1141 | invoke the actual watchers inside another context (another thread etc.). |
1142 | .Sp |
1142 | .Sp |
1143 | If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new |
1143 | If you want to reset the callback, use \f(CW\*(C`ev_invoke_pending\*(C'\fR as new |
1144 | callback. |
1144 | callback. |
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 ())" |
1147 | Sometimes you want to share the same loop between multiple threads. This |
1147 | Sometimes you want to share the same loop between multiple threads. This |
1148 | can be done relatively simply by putting mutex_lock/unlock calls around |
1148 | can be done relatively simply by putting mutex_lock/unlock calls around |
1149 | each call to a libev function. |
1149 | each call to a libev function. |
1150 | .Sp |
1150 | .Sp |
1151 | However, \f(CW\*(C`ev_run\*(C'\fR can run an indefinite time, so it is not feasible |
1151 | However, \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 |
4035 | The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need |
4035 | The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need |
4036 | to use the libev header file and library. |
4036 | to 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" |
|
|
4041 | The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the |
|
|
4042 | libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 |
|
|
4043 | will work fine. |
|
|
4044 | .PP |
|
|
4045 | Proper exception specifications might have to be added to callbacks passed |
|
|
4046 | to libev: exceptions may be thrown only from watcher callbacks, all |
|
|
4047 | other callbacks (allocator, syserr, loop acquire/release and periodioc |
|
|
4048 | reschedule 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 |
|
|
4050 | and \*(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 |
|
|
4064 | The 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 |
|
|
4066 | because it runs cleanup watchers). |
|
|
4067 | .PP |
|
|
4068 | Throwing exceptions in watcher callbacks is only supported if libev itself |
|
|
4069 | is compiled with a \*(C+ compiler or your C and \*(C+ environments allow |
|
|
4070 | throwing exceptions through C libraries (most do). |
|
|
4071 | .SS "\*(C+ \s-1API\s0" |
|
|
4072 | .IX Subsection " API" |
4039 | Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow |
4073 | Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow |
4040 | you to use some convenience methods to start/stop watchers and also change |
4074 | you to use some convenience methods to start/stop watchers and also change |
4041 | the callback model to a model using method callbacks on objects. |
4075 | the callback model to a model using method callbacks on objects. |
4042 | .PP |
4076 | .PP |
4043 | To use it, |
4077 | To use it, |