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.191 by root, Tue Sep 30 19:45:23 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)
2376=over 4 2384=over 4
2377 2385
2378=item queueing from a signal handler context 2386=item queueing from a signal handler context
2379 2387
2380To implement race-free queueing, you simply add to the queue in the signal 2388To implement race-free queueing, you simply add to the queue in the signal
2381handler but you block the signal handler in the watcher callback. Here is an example that does that for 2389handler but you block the signal handler in the watcher callback. Here is
2382some fictitious SIGUSR1 handler: 2390an example that does that for some fictitious SIGUSR1 handler:
2383 2391
2384 static ev_async mysig; 2392 static ev_async mysig;
2385 2393
2386 static void 2394 static void
2387 sigusr1_handler (void) 2395 sigusr1_handler (void)
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:
3296And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 3306And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3297 3307
3298 #include "ev_cpp.h" 3308 #include "ev_cpp.h"
3299 #include "ev.c" 3309 #include "ev.c"
3300 3310
3311=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
3301 3312
3302=head1 THREADS AND COROUTINES 3313=head2 THREADS AND COROUTINES
3303 3314
3304=head2 THREADS 3315=head3 THREADS
3305 3316
3306Libev itself is thread-safe (unless the opposite is specifically 3317All libev functions are reentrant and thread-safe unless explicitly
3307documented for a function), but it uses no locking itself. This means that 3318documented otherwise, but libev implements no locking itself. This means
3308you can use as many loops as you want in parallel, as long as only one 3319that you can use as many loops as you want in parallel, as long as there
3309thread ever calls into one libev function with the same loop parameter: 3320are no concurrent calls into any libev function with the same loop
3321parameter (C<ev_default_*> calls have an implicit default loop parameter,
3310libev guarantees that different event loops share no data structures that 3322of course): libev guarantees that different event loops share no data
3311need locking. 3323structures that need any locking.
3312 3324
3313Or to put it differently: calls with different loop parameters can be done 3325Or to put it differently: calls with different loop parameters can be done
3314concurrently from multiple threads, calls with the same loop parameter 3326concurrently from multiple threads, calls with the same loop parameter
3315must be done serially (but can be done from different threads, as long as 3327must 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 3328only one thread ever is inside a call at any point in time, e.g. by using
3317a mutex per loop). 3329a mutex per loop).
3318 3330
3319Specifically to support threads (and signal handlers), libev implements 3331Specifically to support threads (and signal handlers), libev implements
3320so-called C<ev_async> watchers, which allow some limited form of 3332so-called C<ev_async> watchers, which allow some limited form of
3321concurrency on the same event loop. 3333concurrency on the same event loop, namely waking it up "from the
3334outside".
3322 3335
3323If you want to know which design (one loop, locking, or multiple loops 3336If 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 3337without or something else still) is best for your problem, then I cannot
3325help you. I can give some generic advice however: 3338help you, but here is some generic advice:
3326 3339
3327=over 4 3340=over 4
3328 3341
3329=item * most applications have a main thread: use the default libev loop 3342=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. 3343in that thread, or create a separate thread running only the default loop.
3354default loop and triggering an C<ev_async> watcher from the default loop 3367default loop and triggering an C<ev_async> watcher from the default loop
3355watcher callback into the event loop interested in the signal. 3368watcher callback into the event loop interested in the signal.
3356 3369
3357=back 3370=back
3358 3371
3359=head2 COROUTINES 3372=head3 COROUTINES
3360 3373
3361Libev is much more accommodating to coroutines ("cooperative threads"): 3374Libev is very accommodating to coroutines ("cooperative threads"):
3362libev fully supports nesting calls to it's functions from different 3375libev fully supports nesting calls to its functions from different
3363coroutines (e.g. you can call C<ev_loop> on the same loop from two 3376coroutines (e.g. you can call C<ev_loop> on the same loop from two
3364different coroutines and switch freely between both coroutines running the 3377different coroutines, and switch freely between both coroutines running the
3365loop, as long as you don't confuse yourself). The only exception is that 3378loop, as long as you don't confuse yourself). The only exception is that
3366you must not do this from C<ev_periodic> reschedule callbacks. 3379you must not do this from C<ev_periodic> reschedule callbacks.
3367 3380
3368Care has been taken to ensure that libev does not keep local state inside 3381Care has been taken to ensure that libev does not keep local state inside
3369C<ev_loop>, and other calls do not usually allow coroutine switches. 3382C<ev_loop>, and other calls do not usually allow for coroutine switches as
3383they do not clal any callbacks.
3370 3384
3385=head2 COMPILER WARNINGS
3371 3386
3372=head1 COMPLEXITIES 3387Depending on your compiler and compiler settings, you might get no or a
3388lot of warnings when compiling libev code. Some people are apparently
3389scared by this.
3373 3390
3374In this section the complexities of (many of) the algorithms used inside 3391However, these are unavoidable for many reasons. For one, each compiler
3375libev will be explained. For complexity discussions about backends see the 3392has different warnings, and each user has different tastes regarding
3376documentation for C<ev_default_init>. 3393warning options. "Warn-free" code therefore cannot be a goal except when
3394targeting a specific compiler and compiler-version.
3377 3395
3378All of the following are about amortised time: If an array needs to be 3396Another reason is that some compiler warnings require elaborate
3379extended, libev needs to realloc and move the whole array, but this 3397workarounds, or other changes to the code that make it less clear and less
3380happens asymptotically never with higher number of elements, so O(1) might 3398maintainable.
3381mean it might do a lengthy realloc operation in rare cases, but on average
3382it is much faster and asymptotically approaches constant time.
3383 3399
3384=over 4 3400And of course, some compiler warnings are just plain stupid, or simply
3401wrong (because they don't actually warn about the condition their message
3402seems to warn about). For example, certain older gcc versions had some
3403warnings that resulted an extreme number of false positives. These have
3404been fixed, but some people still insist on making code warn-free with
3405such buggy versions.
3385 3406
3386=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 3407While libev is written to generate as few warnings as possible,
3408"warn-free" code is not a goal, and it is recommended not to build libev
3409with any compiler warnings enabled unless you are prepared to cope with
3410them (e.g. by ignoring them). Remember that warnings are just that:
3411warnings, not errors, or proof of bugs.
3387 3412
3388This means that, when you have a watcher that triggers in one hour and
3389there are 100 watchers that would trigger before that then inserting will
3390have to skip roughly seven (C<ld 100>) of these watchers.
3391 3413
3392=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) 3414=head2 VALGRIND
3393 3415
3394That means that changing a timer costs less than removing/adding them 3416Valgrind has a special section here because it is a popular tool that is
3395as only the relative motion in the event queue has to be paid for. 3417highly useful. Unfortunately, valgrind reports are very hard to interpret.
3396 3418
3397=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) 3419If you think you found a bug (memory leak, uninitialised data access etc.)
3420in libev, then check twice: If valgrind reports something like:
3398 3421
3399These just add the watcher into an array or at the head of a list. 3422 ==2274== definitely lost: 0 bytes in 0 blocks.
3423 ==2274== possibly lost: 0 bytes in 0 blocks.
3424 ==2274== still reachable: 256 bytes in 1 blocks.
3400 3425
3401=item Stopping check/prepare/idle/fork/async watchers: O(1) 3426Then there is no memory leak, just as memory accounted to global variables
3427is not a memleak - the memory is still being refernced, and didn't leak.
3402 3428
3403=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 3429Similarly, under some circumstances, valgrind might report kernel bugs
3430as if it were a bug in libev (e.g. in realloc or in the poll backend,
3431although an acceptable workaround has been found here), or it might be
3432confused.
3404 3433
3405These watchers are stored in lists then need to be walked to find the 3434Keep in mind that valgrind is a very good tool, but only a tool. Don't
3406correct watcher to remove. The lists are usually short (you don't usually 3435make it into some kind of religion.
3407have many watchers waiting for the same fd or signal).
3408 3436
3409=item Finding the next timer in each loop iteration: O(1) 3437If you are unsure about something, feel free to contact the mailing list
3438with the full valgrind report and an explanation on why you think this
3439is a bug in libev (best check the archives, too :). However, don't be
3440annoyed when you get a brisk "this is no bug" answer and take the chance
3441of learning how to interpret valgrind properly.
3410 3442
3411By virtue of using a binary or 4-heap, the next timer is always found at a 3443If you need, for some reason, empty reports from valgrind for your project
3412fixed position in the storage array. 3444I suggest using suppression lists.
3413 3445
3414=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
3415 3446
3416A change means an I/O watcher gets started or stopped, which requires 3447=head1 PORTABILITY NOTES
3417libev to recalculate its status (and possibly tell the kernel, depending
3418on backend and whether C<ev_io_set> was used).
3419 3448
3420=item Activating one watcher (putting it into the pending state): O(1)
3421
3422=item Priority handling: O(number_of_priorities)
3423
3424Priorities are implemented by allocating some space for each
3425priority. When doing priority-based operations, libev usually has to
3426linearly search all the priorities, but starting/stopping and activating
3427watchers becomes O(1) with respect to priority handling.
3428
3429=item Sending an ev_async: O(1)
3430
3431=item Processing ev_async_send: O(number_of_async_watchers)
3432
3433=item Processing signals: O(max_signal_number)
3434
3435Sending involves a system call I<iff> there were no other C<ev_async_send>
3436calls in the current loop iteration. Checking for async and signal events
3437involves iterating over all running async watchers or all signal numbers.
3438
3439=back
3440
3441
3442=head1 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 3449=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
3443 3450
3444Win32 doesn't support any of the standards (e.g. POSIX) that libev 3451Win32 doesn't support any of the standards (e.g. POSIX) that libev
3445requires, and its I/O model is fundamentally incompatible with the POSIX 3452requires, and its I/O model is fundamentally incompatible with the POSIX
3446model. Libev still offers limited functionality on this platform in 3453model. Libev still offers limited functionality on this platform in
3447the form of the C<EVBACKEND_SELECT> backend, and only supports socket 3454the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3534wrap all I/O functions and provide your own fd management, but the cost of 3541wrap all I/O functions and provide your own fd management, but the cost of
3535calling select (O(n²)) will likely make this unworkable. 3542calling select (O(n²)) will likely make this unworkable.
3536 3543
3537=back 3544=back
3538 3545
3539
3540=head1 PORTABILITY REQUIREMENTS 3546=head2 PORTABILITY REQUIREMENTS
3541 3547
3542In addition to a working ISO-C implementation, libev relies on a few 3548In addition to a working ISO-C implementation and of course the
3543additional extensions: 3549backend-specific APIs, libev relies on a few additional extensions:
3544 3550
3545=over 4 3551=over 4
3546 3552
3547=item C<void (*)(ev_watcher_type *, int revents)> must have compatible 3553=item C<void (*)(ev_watcher_type *, int revents)> must have compatible
3548calling conventions regardless of C<ev_watcher_type *>. 3554calling conventions regardless of C<ev_watcher_type *>.
3573except the initial one, and run the default loop in the initial thread as 3579except the initial one, and run the default loop in the initial thread as
3574well. 3580well.
3575 3581
3576=item C<long> must be large enough for common memory allocation sizes 3582=item C<long> must be large enough for common memory allocation sizes
3577 3583
3578To improve portability and simplify using libev, libev uses C<long> 3584To improve portability and simplify its API, libev uses C<long> internally
3579internally instead of C<size_t> when allocating its data structures. On 3585instead of C<size_t> when allocating its data structures. On non-POSIX
3580non-POSIX systems (Microsoft...) this might be unexpectedly low, but 3586systems (Microsoft...) this might be unexpectedly low, but is still at
3581is still at least 31 bits everywhere, which is enough for hundreds of 3587least 31 bits everywhere, which is enough for hundreds of millions of
3582millions of watchers. 3588watchers.
3583 3589
3584=item C<double> must hold a time value in seconds with enough accuracy 3590=item C<double> must hold a time value in seconds with enough accuracy
3585 3591
3586The type C<double> is used to represent timestamps. It is required to 3592The type C<double> is used to represent timestamps. It is required to
3587have at least 51 bits of mantissa (and 9 bits of exponent), which is good 3593have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3591=back 3597=back
3592 3598
3593If you know of other additional requirements drop me a note. 3599If you know of other additional requirements drop me a note.
3594 3600
3595 3601
3596=head1 COMPILER WARNINGS 3602=head1 ALGORITHMIC COMPLEXITIES
3597 3603
3598Depending on your compiler and compiler settings, you might get no or a 3604In this section the complexities of (many of) the algorithms used inside
3599lot of warnings when compiling libev code. Some people are apparently 3605libev will be documented. For complexity discussions about backends see
3600scared by this. 3606the documentation for C<ev_default_init>.
3601 3607
3602However, these are unavoidable for many reasons. For one, each compiler 3608All of the following are about amortised time: If an array needs to be
3603has different warnings, and each user has different tastes regarding 3609extended, libev needs to realloc and move the whole array, but this
3604warning options. "Warn-free" code therefore cannot be a goal except when 3610happens asymptotically rarer with higher number of elements, so O(1) might
3605targeting a specific compiler and compiler-version. 3611mean that libev does a lengthy realloc operation in rare cases, but on
3612average it is much faster and asymptotically approaches constant time.
3606 3613
3607Another reason is that some compiler warnings require elaborate 3614=over 4
3608workarounds, or other changes to the code that make it less clear and less
3609maintainable.
3610 3615
3611And of course, some compiler warnings are just plain stupid, or simply 3616=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
3612wrong (because they don't actually warn about the condition their message
3613seems to warn about).
3614 3617
3615While libev is written to generate as few warnings as possible, 3618This means that, when you have a watcher that triggers in one hour and
3616"warn-free" code is not a goal, and it is recommended not to build libev 3619there are 100 watchers that would trigger before that, then inserting will
3617with any compiler warnings enabled unless you are prepared to cope with 3620have to skip roughly seven (C<ld 100>) of these watchers.
3618them (e.g. by ignoring them). Remember that warnings are just that:
3619warnings, not errors, or proof of bugs.
3620 3621
3622=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
3621 3623
3622=head1 VALGRIND 3624That means that changing a timer costs less than removing/adding them,
3625as only the relative motion in the event queue has to be paid for.
3623 3626
3624Valgrind has a special section here because it is a popular tool that is 3627=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
3625highly useful, but valgrind reports are very hard to interpret.
3626 3628
3627If you think you found a bug (memory leak, uninitialised data access etc.) 3629These just add the watcher into an array or at the head of a list.
3628in libev, then check twice: If valgrind reports something like:
3629 3630
3630 ==2274== definitely lost: 0 bytes in 0 blocks. 3631=item Stopping check/prepare/idle/fork/async watchers: O(1)
3631 ==2274== possibly lost: 0 bytes in 0 blocks.
3632 ==2274== still reachable: 256 bytes in 1 blocks.
3633 3632
3634Then there is no memory leak. Similarly, under some circumstances, 3633=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
3635valgrind might report kernel bugs as if it were a bug in libev, or it
3636might be confused (it is a very good tool, but only a tool).
3637 3634
3638If you are unsure about something, feel free to contact the mailing list 3635These watchers are stored in lists, so they need to be walked to find the
3639with the full valgrind report and an explanation on why you think this is 3636correct watcher to remove. The lists are usually short (you don't usually
3640a bug in libev. However, don't be annoyed when you get a brisk "this is 3637have many watchers waiting for the same fd or signal: one is typical, two
3641no bug" answer and take the chance of learning how to interpret valgrind 3638is rare).
3642properly.
3643 3639
3644If you need, for some reason, empty reports from valgrind for your project 3640=item Finding the next timer in each loop iteration: O(1)
3645I suggest using suppression lists. 3641
3642By virtue of using a binary or 4-heap, the next timer is always found at a
3643fixed position in the storage array.
3644
3645=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
3646
3647A change means an I/O watcher gets started or stopped, which requires
3648libev to recalculate its status (and possibly tell the kernel, depending
3649on backend and whether C<ev_io_set> was used).
3650
3651=item Activating one watcher (putting it into the pending state): O(1)
3652
3653=item Priority handling: O(number_of_priorities)
3654
3655Priorities are implemented by allocating some space for each
3656priority. When doing priority-based operations, libev usually has to
3657linearly search all the priorities, but starting/stopping and activating
3658watchers becomes O(1) with respect to priority handling.
3659
3660=item Sending an ev_async: O(1)
3661
3662=item Processing ev_async_send: O(number_of_async_watchers)
3663
3664=item Processing signals: O(max_signal_number)
3665
3666Sending involves a system call I<iff> there were no other C<ev_async_send>
3667calls in the current loop iteration. Checking for async and signal events
3668involves iterating over all running async watchers or all signal numbers.
3669
3670=back
3646 3671
3647 3672
3648=head1 AUTHOR 3673=head1 AUTHOR
3649 3674
3650Marc Lehmann <libev@schmorp.de>. 3675Marc Lehmann <libev@schmorp.de>.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines