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

Comparing libev/ev.pod (file contents):
Revision 1.188 by root, Tue Sep 30 18:35:47 2008 UTC vs.
Revision 1.189 by root, Tue Sep 30 19:33:33 2008 UTC

… …
3306And 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:
3307 3307
3308 #include "ev_cpp.h" 3308 #include "ev_cpp.h"
3309 #include "ev.c" 3309 #include "ev.c"
3310 3310
3311=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
3311 3312
3312=head1 THREADS AND COROUTINES 3313=head2 THREADS AND COROUTINES
3313 3314
3314=head2 THREADS 3315=head3 THREADS
3315 3316
3316All libev functions are reentrant and thread-safe unless explicitly 3317All libev functions are reentrant and thread-safe unless explicitly
3317documented otherwise, but it uses no locking itself. This means that you 3318documented otherwise, but it uses no locking itself. This means that you
3318can use as many loops as you want in parallel, as long as there are no 3319can use as many loops as you want in parallel, as long as there are no
3319concurrent calls into any libev function with the same loop parameter 3320concurrent calls into any libev function with the same loop parameter
… …
3366default 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
3367watcher callback into the event loop interested in the signal. 3368watcher callback into the event loop interested in the signal.
3368 3369
3369=back 3370=back
3370 3371
3371=head2 COROUTINES 3372=head3 COROUTINES
3372 3373
3373Libev is much more accommodating to coroutines ("cooperative threads"): 3374Libev is much more accommodating to coroutines ("cooperative threads"):
3374libev fully supports nesting calls to it's functions from different 3375libev fully supports nesting calls to it's functions from different
3375coroutines (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
3376different coroutines and switch freely between both coroutines running the 3377different coroutines and switch freely between both coroutines running the
… …
3378you must not do this from C<ev_periodic> reschedule callbacks. 3379you must not do this from C<ev_periodic> reschedule callbacks.
3379 3380
3380Care 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
3381C<ev_loop>, and other calls do not usually allow coroutine switches. 3382C<ev_loop>, and other calls do not usually allow coroutine switches.
3382 3383
3384=head2 COMPILER WARNINGS
3385
3386Depending on your compiler and compiler settings, you might get no or a
3387lot of warnings when compiling libev code. Some people are apparently
3388scared by this.
3389
3390However, these are unavoidable for many reasons. For one, each compiler
3391has different warnings, and each user has different tastes regarding
3392warning options. "Warn-free" code therefore cannot be a goal except when
3393targeting a specific compiler and compiler-version.
3394
3395Another reason is that some compiler warnings require elaborate
3396workarounds, or other changes to the code that make it less clear and less
3397maintainable.
3398
3399And of course, some compiler warnings are just plain stupid, or simply
3400wrong (because they don't actually warn about the condition their message
3401seems to warn about). For example, certain older gcc versions had some
3402warnings that resulted an extreme number of false positives. These have
3403been fixed, but some people still insist on making code warn-free with
3404such buggy versions.
3405
3406While libev is written to generate as few warnings as possible,
3407"warn-free" code is not a goal, and it is recommended not to build libev
3408with any compiler warnings enabled unless you are prepared to cope with
3409them (e.g. by ignoring them). Remember that warnings are just that:
3410warnings, not errors, or proof of bugs.
3411
3412
3413=head1 VALGRIND
3414
3415Valgrind has a special section here because it is a popular tool that is
3416highly useful. Unfortunately, valgrind reports are very hard to interpret.
3417
3418If you think you found a bug (memory leak, uninitialised data access etc.)
3419in libev, then check twice: If valgrind reports something like:
3420
3421 ==2274== definitely lost: 0 bytes in 0 blocks.
3422 ==2274== possibly lost: 0 bytes in 0 blocks.
3423 ==2274== still reachable: 256 bytes in 1 blocks.
3424
3425Then there is no memory leak, just as memory accounted to global variables
3426is not a memleak - the memory is still being refernced, and didn't leak.
3427
3428Similarly, under some circumstances, valgrind might report kernel bugs
3429as if it were a bug in libev (e.g. in realloc or in the poll backend,
3430although an acceptable workaround has been found here), or it might be
3431confused.
3432
3433Keep in mind that valgrind is a very good tool, but only a tool. Don't
3434make it into some kind of religion.
3435
3436If you are unsure about something, feel free to contact the mailing list
3437with the full valgrind report and an explanation on why you think this
3438is a bug in libev (best check the archives, too :). However, don't be
3439annoyed when you get a brisk "this is no bug" answer and take the chance
3440of learning how to interpret valgrind properly.
3441
3442If you need, for some reason, empty reports from valgrind for your project
3443I suggest using suppression lists.
3444
3445
3383 3446
3384=head1 COMPLEXITIES 3447=head1 COMPLEXITIES
3385 3448
3386In this section the complexities of (many of) the algorithms used inside 3449In this section the complexities of (many of) the algorithms used inside
3387libev will be explained. For complexity discussions about backends see the 3450libev will be explained. For complexity discussions about backends see the
… …
3449involves iterating over all running async watchers or all signal numbers. 3512involves iterating over all running async watchers or all signal numbers.
3450 3513
3451=back 3514=back
3452 3515
3453 3516
3517=head1 PORTABILITY
3518
3454=head1 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 3519=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
3455 3520
3456Win32 doesn't support any of the standards (e.g. POSIX) that libev 3521Win32 doesn't support any of the standards (e.g. POSIX) that libev
3457requires, and its I/O model is fundamentally incompatible with the POSIX 3522requires, and its I/O model is fundamentally incompatible with the POSIX
3458model. Libev still offers limited functionality on this platform in 3523model. Libev still offers limited functionality on this platform in
3459the form of the C<EVBACKEND_SELECT> backend, and only supports socket 3524the form of the C<EVBACKEND_SELECT> backend, and only supports socket
… …
3546wrap all I/O functions and provide your own fd management, but the cost of 3611wrap all I/O functions and provide your own fd management, but the cost of
3547calling select (O(n²)) will likely make this unworkable. 3612calling select (O(n²)) will likely make this unworkable.
3548 3613
3549=back 3614=back
3550 3615
3551
3552=head1 PORTABILITY REQUIREMENTS 3616=head2 PORTABILITY REQUIREMENTS
3553 3617
3554In addition to a working ISO-C implementation, libev relies on a few 3618In addition to a working ISO-C implementation and of course the
3555additional extensions: 3619backend-specific APIs, libev relies on a few additional extensions:
3556 3620
3557=over 4 3621=over 4
3558 3622
3559=item C<void (*)(ev_watcher_type *, int revents)> must have compatible 3623=item C<void (*)(ev_watcher_type *, int revents)> must have compatible
3560calling conventions regardless of C<ev_watcher_type *>. 3624calling conventions regardless of C<ev_watcher_type *>.
… …
3585except the initial one, and run the default loop in the initial thread as 3649except the initial one, and run the default loop in the initial thread as
3586well. 3650well.
3587 3651
3588=item C<long> must be large enough for common memory allocation sizes 3652=item C<long> must be large enough for common memory allocation sizes
3589 3653
3590To improve portability and simplify using libev, libev uses C<long> 3654To improve portability and simplify its API, libev uses C<long> internally
3591internally instead of C<size_t> when allocating its data structures. On 3655instead of C<size_t> when allocating its data structures. On non-POSIX
3592non-POSIX systems (Microsoft...) this might be unexpectedly low, but 3656systems (Microsoft...) this might be unexpectedly low, but is still at
3593is still at least 31 bits everywhere, which is enough for hundreds of 3657least 31 bits everywhere, which is enough for hundreds of millions of
3594millions of watchers. 3658watchers.
3595 3659
3596=item C<double> must hold a time value in seconds with enough accuracy 3660=item C<double> must hold a time value in seconds with enough accuracy
3597 3661
3598The type C<double> is used to represent timestamps. It is required to 3662The type C<double> is used to represent timestamps. It is required to
3599have at least 51 bits of mantissa (and 9 bits of exponent), which is good 3663have at least 51 bits of mantissa (and 9 bits of exponent), which is good
… …
3603=back 3667=back
3604 3668
3605If you know of other additional requirements drop me a note. 3669If you know of other additional requirements drop me a note.
3606 3670
3607 3671
3608=head1 COMPILER WARNINGS
3609
3610Depending on your compiler and compiler settings, you might get no or a
3611lot of warnings when compiling libev code. Some people are apparently
3612scared by this.
3613
3614However, these are unavoidable for many reasons. For one, each compiler
3615has different warnings, and each user has different tastes regarding
3616warning options. "Warn-free" code therefore cannot be a goal except when
3617targeting a specific compiler and compiler-version.
3618
3619Another reason is that some compiler warnings require elaborate
3620workarounds, or other changes to the code that make it less clear and less
3621maintainable.
3622
3623And of course, some compiler warnings are just plain stupid, or simply
3624wrong (because they don't actually warn about the condition their message
3625seems to warn about).
3626
3627While libev is written to generate as few warnings as possible,
3628"warn-free" code is not a goal, and it is recommended not to build libev
3629with any compiler warnings enabled unless you are prepared to cope with
3630them (e.g. by ignoring them). Remember that warnings are just that:
3631warnings, not errors, or proof of bugs.
3632
3633
3634=head1 VALGRIND
3635
3636Valgrind has a special section here because it is a popular tool that is
3637highly useful, but valgrind reports are very hard to interpret.
3638
3639If you think you found a bug (memory leak, uninitialised data access etc.)
3640in libev, then check twice: If valgrind reports something like:
3641
3642 ==2274== definitely lost: 0 bytes in 0 blocks.
3643 ==2274== possibly lost: 0 bytes in 0 blocks.
3644 ==2274== still reachable: 256 bytes in 1 blocks.
3645
3646Then there is no memory leak. Similarly, under some circumstances,
3647valgrind might report kernel bugs as if it were a bug in libev, or it
3648might be confused (it is a very good tool, but only a tool).
3649
3650If you are unsure about something, feel free to contact the mailing list
3651with the full valgrind report and an explanation on why you think this is
3652a bug in libev. However, don't be annoyed when you get a brisk "this is
3653no bug" answer and take the chance of learning how to interpret valgrind
3654properly.
3655
3656If you need, for some reason, empty reports from valgrind for your project
3657I suggest using suppression lists.
3658
3659
3660=head1 AUTHOR 3672=head1 AUTHOR
3661 3673
3662Marc Lehmann <libev@schmorp.de>. 3674Marc Lehmann <libev@schmorp.de>.
3663 3675

Diff Legend

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