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

Comparing libev/ev.pod (file contents):
Revision 1.184 by root, Tue Sep 23 09:11:14 2008 UTC vs.
Revision 1.187 by root, Mon Sep 29 03:31:14 2008 UTC

… …
214C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 214C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
215recommended ones. 215recommended ones.
216 216
217See the description of C<ev_embed> watchers for more info. 217See the description of C<ev_embed> watchers for more info.
218 218
219=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 219=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
220 220
221Sets the allocation function to use (the prototype is similar - the 221Sets the allocation function to use (the prototype is similar - the
222semantics are identical to the C<realloc> C89/SuS/POSIX function). It is 222semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
223used to allocate and free memory (no surprises here). If it returns zero 223used to allocate and free memory (no surprises here). If it returns zero
224when memory needs to be allocated (C<size != 0>), the library might abort 224when memory needs to be allocated (C<size != 0>), the library might abort
… …
250 } 250 }
251 251
252 ... 252 ...
253 ev_set_allocator (persistent_realloc); 253 ev_set_allocator (persistent_realloc);
254 254
255=item ev_set_syserr_cb (void (*cb)(const char *msg)); 255=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
256 256
257Set the callback function to call on a retryable system call error (such 257Set the callback function to call on a retryable system call error (such
258as failed select, poll, epoll_wait). The message is a printable string 258as failed select, poll, epoll_wait). The message is a printable string
259indicating the system call or subsystem causing the problem. If this 259indicating the system call or subsystem causing the problem. If this
260callback is set, then libev will expect it to remedy the situation, no 260callback is set, then libev will expect it to remedy the situation, no
… …
2242So when you want to use this feature you will always have to be prepared 2242So when you want to use this feature you will always have to be prepared
2243that you cannot get an embeddable loop. The recommended way to get around 2243that you cannot get an embeddable loop. The recommended way to get around
2244this is to have a separate variables for your embeddable loop, try to 2244this is to have a separate variables for your embeddable loop, try to
2245create it, and if that fails, use the normal loop for everything. 2245create it, and if that fails, use the normal loop for everything.
2246 2246
2247=head3 C<ev_embed> and fork
2248
2249While the C<ev_embed> watcher is running, forks in the embedding loop will
2250automatically be applied to the embedded loop as well, so no special
2251fork handling is required in that case. When the watcher is not running,
2252however, it is still the task of the libev user to call C<ev_loop_fork ()>
2253as applicable.
2254
2247=head3 Watcher-Specific Functions and Data Members 2255=head3 Watcher-Specific Functions and Data Members
2248 2256
2249=over 4 2257=over 4
2250 2258
2251=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 2259=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
… …
3241definition and a statement, respectively. See the F<ev.h> header file for 3249definition and a statement, respectively. See the F<ev.h> header file for
3242their default definitions. One possible use for overriding these is to 3250their default definitions. One possible use for overriding these is to
3243avoid the C<struct ev_loop *> as first argument in all cases, or to use 3251avoid the C<struct ev_loop *> as first argument in all cases, or to use
3244method calls instead of plain function calls in C++. 3252method calls instead of plain function calls in C++.
3245 3253
3254=back
3255
3246=head2 EXPORTED API SYMBOLS 3256=head2 EXPORTED API SYMBOLS
3247 3257
3248If you need to re-export the API (e.g. via a DLL) and you need a list of 3258If you need to re-export the API (e.g. via a DLL) and you need a list of
3249exported symbols, you can use the provided F<Symbol.*> files which list 3259exported symbols, you can use the provided F<Symbol.*> files which list
3250all public symbols, one per line: 3260all public symbols, one per line:
… …
3301 3311
3302=head1 THREADS AND COROUTINES 3312=head1 THREADS AND COROUTINES
3303 3313
3304=head2 THREADS 3314=head2 THREADS
3305 3315
3306Libev itself is thread-safe (unless the opposite is specifically 3316All libev functions are reentrant and thread-safe unless explicitly
3307documented for a function), but it uses no locking itself. This means that 3317documented otherwise, but it uses no locking itself. This means that you
3308you can use as many loops as you want in parallel, as long as only one 3318can use as many loops as you want in parallel, as long as there are no
3309thread ever calls into one libev function with the same loop parameter: 3319concurrent calls into any libev function with the same loop parameter
3320(C<ev_default_*> calls have an implicit default loop parameter, of
3310libev guarantees that different event loops share no data structures that 3321course): libev guarantees that different event loops share no data
3311need locking. 3322structures that need any locking.
3312 3323
3313Or to put it differently: calls with different loop parameters can be done 3324Or to put it differently: calls with different loop parameters can be done
3314concurrently from multiple threads, calls with the same loop parameter 3325concurrently from multiple threads, calls with the same loop parameter
3315must be done serially (but can be done from different threads, as long as 3326must be done serially (but can be done from different threads, as long as
3316only one thread ever is inside a call at any point in time, e.g. by using 3327only one thread ever is inside a call at any point in time, e.g. by using
3317a mutex per loop). 3328a mutex per loop).
3318 3329
3319Specifically to support threads (and signal handlers), libev implements 3330Specifically to support threads (and signal handlers), libev implements
3320so-called C<ev_async> watchers, which allow some limited form of 3331so-called C<ev_async> watchers, which allow some limited form of
3321concurrency on the same event loop. 3332concurrency on the same event loop, namely waking it up "from the
3333outside".
3322 3334
3323If you want to know which design (one loop, locking, or multiple loops 3335If you want to know which design (one loop, locking, or multiple loops
3324without or something else still) is best for your problem, then I cannot 3336without or something else still) is best for your problem, then I cannot
3325help you. I can give some generic advice however: 3337help you, but here is some generic advice:
3326 3338
3327=over 4 3339=over 4
3328 3340
3329=item * most applications have a main thread: use the default libev loop 3341=item * most applications have a main thread: use the default libev loop
3330in that thread, or create a separate thread running only the default loop. 3342in that thread, or create a separate thread running only the default loop.

Diff Legend

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