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

Comparing libev/ev.pod (file contents):
Revision 1.158 by root, Wed May 21 12:51:38 2008 UTC vs.
Revision 1.160 by root, Thu May 22 03:06:58 2008 UTC

… …
116called C<ev_tstamp>, which is what you should use too. It usually aliases 116called C<ev_tstamp>, which is what you should use too. It usually aliases
117to the C<double> type in C, and when you need to do any calculations on 117to the C<double> type in C, and when you need to do any calculations on
118it, you should treat it as some floatingpoint value. Unlike the name 118it, you should treat it as some floatingpoint value. Unlike the name
119component C<stamp> might indicate, it is also used for time differences 119component C<stamp> might indicate, it is also used for time differences
120throughout libev. 120throughout libev.
121
122=head1 ERROR HANDLING
123
124Libev knows three classes of errors: operating system errors, usage errors
125and internal errors (bugs).
126
127When libev catches an operating system error it cannot handle (for example
128a syscall indicating a condition libev cannot fix), it calls the callback
129set via C<ev_set_syserr_cb>, which is supposed to fix the problem or
130abort. The default is to print a diagnostic message and to call C<abort
131()>.
132
133When libev detects a usage error such as a negative timer interval, then
134it will print a diagnostic message and abort (via the C<assert> mechanism,
135so C<NDEBUG> will disable this checking): these are programming errors in
136the libev caller and need to be fixed there.
137
138Libev also has a few internal error-checking C<assert>ions, and also has
139extensive consistency checking code. These do not trigger under normal
140circumstances, as they indicate either a bug in libev or worse.
141
121 142
122=head1 GLOBAL FUNCTIONS 143=head1 GLOBAL FUNCTIONS
123 144
124These functions can be called anytime, even before initialising the 145These functions can be called anytime, even before initialising the
125library in any way. 146library in any way.
… …
689interval to a value near C<0.1> or so, which is often enough for 710interval to a value near C<0.1> or so, which is often enough for
690interactive servers (of course not for games), likewise for timeouts. It 711interactive servers (of course not for games), likewise for timeouts. It
691usually doesn't make much sense to set it to a lower value than C<0.01>, 712usually doesn't make much sense to set it to a lower value than C<0.01>,
692as this approsaches the timing granularity of most systems. 713as this approsaches the timing granularity of most systems.
693 714
715=item ev_loop_verify (loop)
716
717This function only does something when C<EV_VERIFY> support has been
718compiled in. It tries to go through all internal structures and checks
719them for validity. If anything is found to be inconsistent, it will print
720an error message to standard error and call C<abort ()>.
721
722This can be used to catch bugs inside libev itself: under normal
723circumstances, this function will never abort as of course libev keeps its
724data structures consistent.
725
694=back 726=back
695 727
696 728
697=head1 ANATOMY OF A WATCHER 729=head1 ANATOMY OF A WATCHER
698 730
… …
3031noticably with with many (hundreds) of watchers. 3063noticably with with many (hundreds) of watchers.
3032 3064
3033The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 3065The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3034(disabled). 3066(disabled).
3035 3067
3068=item EV_VERIFY
3069
3070Controls how much internal verification (see C<ev_loop_verify ()>) will
3071be done: If set to C<0>, no internal verification code will be compiled
3072in. If set to C<1>, then verification code will be compiled in, but not
3073called. If set to C<2>, then the internal verification code will be
3074called once per loop, which can slow down libev. If set to C<3>, then the
3075verification code will be called very frequently, which will slow down
3076libev considerably.
3077
3078The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be
3079C<0.>
3080
3036=item EV_COMMON 3081=item EV_COMMON
3037 3082
3038By default, all watchers have a C<void *data> member. By redefining 3083By default, all watchers have a C<void *data> member. By redefining
3039this macro to a something else you can include more and other types of 3084this macro to a something else you can include more and other types of
3040members. You have to define it each time you include one of the files, 3085members. You have to define it each time you include one of the files,
… …
3269 3314
3270=over 4 3315=over 4
3271 3316
3272=item The winsocket select function 3317=item The winsocket select function
3273 3318
3274The winsocket C<select> function doesn't follow POSIX in that it requires 3319The winsocket C<select> function doesn't follow POSIX in that it
3275socket I<handles> and not socket I<file descriptors>. This makes select 3320requires socket I<handles> and not socket I<file descriptors> (it is
3276very inefficient, and also requires a mapping from file descriptors 3321also extremely buggy). This makes select very inefficient, and also
3277to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>, 3322requires a mapping from file descriptors to socket handles. See the
3278C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor 3323discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and
3279symbols for more info. 3324C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info.
3280 3325
3281The configuration for a "naked" win32 using the microsoft runtime 3326The configuration for a "naked" win32 using the microsoft runtime
3282libraries and raw winsocket select is: 3327libraries and raw winsocket select is:
3283 3328
3284 #define EV_USE_SELECT 1 3329 #define EV_USE_SELECT 1
… …
3362=back 3407=back
3363 3408
3364If you know of other additional requirements drop me a note. 3409If you know of other additional requirements drop me a note.
3365 3410
3366 3411
3412=head1 COMPILER WARNINGS
3413
3414Depending on your compiler and compiler settings, you might get no or a
3415lot of warnings when compiling libev code. Some people are apparently
3416scared by this.
3417
3418However, these are unavoidable for many reasons. For one, each compiler
3419has different warnings, and each user has different tastes regarding
3420warning options. "Warn-free" code therefore cannot be a goal except when
3421targetting a specific compiler and compiler-version.
3422
3423Another reason is that some compiler warnings require elaborate
3424workarounds, or other changes to the code that make it less clear and less
3425maintainable.
3426
3427And of course, some compiler warnings are just plain stupid, or simply
3428wrong (because they don't actually warn about the cindition their message
3429seems to warn about).
3430
3431While libev is written to generate as few warnings as possible,
3432"warn-free" code is not a goal, and it is recommended not to build libev
3433with any compiler warnings enabled unless you are prepared to cope with
3434them (e.g. by ignoring them). Remember that warnings are just that:
3435warnings, not errors, or proof of bugs.
3436
3437
3367=head1 VALGRIND 3438=head1 VALGRIND
3368 3439
3369Valgrind has a special section here because it is a popular tool that is 3440Valgrind has a special section here because it is a popular tool that is
3370highly useful, but valgrind reports are very hard to interpret. 3441highly useful, but valgrind reports are very hard to interpret.
3371 3442

Diff Legend

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