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

Comparing libev/ev.pod (file contents):
Revision 1.185 by root, Tue Sep 23 09:13:59 2008 UTC vs.
Revision 1.188 by root, Tue Sep 30 18:35:47 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
… …
1625 1625
1626=back 1626=back
1627 1627
1628=head3 Examples 1628=head3 Examples
1629 1629
1630Example: Try to exit cleanly on SIGINT and SIGTERM. 1630Example: Try to exit cleanly on SIGINT.
1631 1631
1632 static void 1632 static void
1633 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1633 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1634 { 1634 {
1635 ev_unloop (loop, EVUNLOOP_ALL); 1635 ev_unloop (loop, EVUNLOOP_ALL);
1636 } 1636 }
1637 1637
1638 struct ev_signal signal_watcher; 1638 struct ev_signal signal_watcher;
1639 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1639 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1640 ev_signal_start (loop, &sigint_cb); 1640 ev_signal_start (loop, &signal_watcher);
1641 1641
1642 1642
1643=head2 C<ev_child> - watch out for process status changes 1643=head2 C<ev_child> - watch out for process status changes
1644 1644
1645Child watchers trigger when your process receives a SIGCHLD in response to 1645Child watchers trigger when your process receives a SIGCHLD in response to
… …
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)
… …
3303 3311
3304=head1 THREADS AND COROUTINES 3312=head1 THREADS AND COROUTINES
3305 3313
3306=head2 THREADS 3314=head2 THREADS
3307 3315
3308Libev itself is thread-safe (unless the opposite is specifically 3316All libev functions are reentrant and thread-safe unless explicitly
3309documented for a function), but it uses no locking itself. This means that 3317documented otherwise, but it uses no locking itself. This means that you
3310you 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
3311thread 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
3312libev guarantees that different event loops share no data structures that 3321course): libev guarantees that different event loops share no data
3313need locking. 3322structures that need any locking.
3314 3323
3315Or 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
3316concurrently from multiple threads, calls with the same loop parameter 3325concurrently from multiple threads, calls with the same loop parameter
3317must 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
3318only 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
3319a mutex per loop). 3328a mutex per loop).
3320 3329
3321Specifically to support threads (and signal handlers), libev implements 3330Specifically to support threads (and signal handlers), libev implements
3322so-called C<ev_async> watchers, which allow some limited form of 3331so-called C<ev_async> watchers, which allow some limited form of
3323concurrency on the same event loop. 3332concurrency on the same event loop, namely waking it up "from the
3333outside".
3324 3334
3325If 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
3326without 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
3327help you. I can give some generic advice however: 3337help you, but here is some generic advice:
3328 3338
3329=over 4 3339=over 4
3330 3340
3331=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
3332in 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