*** empty log message ***

1 files changed, 77 insertions, 65 deletions

diff --git a/ev.pod b/ev.pod
index 01070c8..9823fe9 100644
--- a/ev.pod
+++ b/ev.pod
@@ -3308,10 +3308,11 @@ And a F<ev_cpp.C> implementation file that contains libev proper and is compiled
    #include "ev_cpp.h"
    #include "ev.c"
 
+=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
 
-=head1 THREADS AND COROUTINES
+=head2 THREADS AND COROUTINES
 
-=head2 THREADS
+=head3 THREADS
 
 All libev functions are reentrant and thread-safe unless explicitly
 documented otherwise, but it uses no locking itself. This means that you
@@ -3368,7 +3369,7 @@ watcher callback into the event loop interested in the signal.
 
 =back
 
-=head2 COROUTINES
+=head3 COROUTINES
 
 Libev is much more accommodating to coroutines ("cooperative threads"):
 libev fully supports nesting calls to it's functions from different
@@ -3380,6 +3381,68 @@ you must not do this from C<ev_periodic> reschedule callbacks.
 Care has been taken to ensure that libev does not keep local state inside
 C<ev_loop>, and other calls do not usually allow coroutine switches.
 
+=head2 COMPILER WARNINGS
+
+Depending on your compiler and compiler settings, you might get no or a
+lot of warnings when compiling libev code. Some people are apparently
+scared by this.
+
+However, these are unavoidable for many reasons. For one, each compiler
+has different warnings, and each user has different tastes regarding
+warning options. "Warn-free" code therefore cannot be a goal except when
+targeting a specific compiler and compiler-version.
+
+Another reason is that some compiler warnings require elaborate
+workarounds, or other changes to the code that make it less clear and less
+maintainable.
+
+And of course, some compiler warnings are just plain stupid, or simply
+wrong (because they don't actually warn about the condition their message
+seems to warn about). For example, certain older gcc versions had some
+warnings that resulted an extreme number of false positives. These have
+been fixed, but some people still insist on making code warn-free with
+such buggy versions.
+
+While libev is written to generate as few warnings as possible,
+"warn-free" code is not a goal, and it is recommended not to build libev
+with any compiler warnings enabled unless you are prepared to cope with
+them (e.g. by ignoring them). Remember that warnings are just that:
+warnings, not errors, or proof of bugs.
+
+
+=head1 VALGRIND
+
+Valgrind has a special section here because it is a popular tool that is
+highly useful. Unfortunately, valgrind reports are very hard to interpret.
+
+If you think you found a bug (memory leak, uninitialised data access etc.)
+in libev, then check twice: If valgrind reports something like:
+
+   ==2274==    definitely lost: 0 bytes in 0 blocks.
+   ==2274==      possibly lost: 0 bytes in 0 blocks.
+   ==2274==    still reachable: 256 bytes in 1 blocks.
+
+Then there is no memory leak, just as memory accounted to global variables
+is not a memleak - the memory is still being refernced, and didn't leak.
+
+Similarly, under some circumstances, valgrind might report kernel bugs
+as if it were a bug in libev (e.g. in realloc or in the poll backend,
+although an acceptable workaround has been found here), or it might be
+confused.
+
+Keep in mind that valgrind is a very good tool, but only a tool. Don't
+make it into some kind of religion.
+
+If you are unsure about something, feel free to contact the mailing list
+with the full valgrind report and an explanation on why you think this
+is a bug in libev (best check the archives, too :). However, don't be
+annoyed when you get a brisk "this is no bug" answer and take the chance
+of learning how to interpret valgrind properly.
+
+If you need, for some reason, empty reports from valgrind for your project
+I suggest using suppression lists.
+
+
 
 =head1 COMPLEXITIES
 
@@ -3451,7 +3514,9 @@ involves iterating over all running async watchers or all signal numbers.
 =back
 
 
-=head1 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
+=head1 PORTABILITY
+
+=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
 
 Win32 doesn't support any of the standards (e.g. POSIX) that libev
 requires, and its I/O model is fundamentally incompatible with the POSIX
@@ -3548,11 +3613,10 @@ calling select (O(n²)) will likely make this unworkable.
 
 =back
 
+=head2 PORTABILITY REQUIREMENTS
 
-=head1 PORTABILITY REQUIREMENTS
-
-In addition to a working ISO-C implementation, libev relies on a few
-additional extensions:
+In addition to a working ISO-C implementation and of course the
+backend-specific APIs, libev relies on a few additional extensions:
 
 =over 4
 
@@ -3587,11 +3651,11 @@ well.
 
 =item C<long> must be large enough for common memory allocation sizes
 
-To improve portability and simplify using libev, libev uses C<long>
-internally instead of C<size_t> when allocating its data structures. On
-non-POSIX systems (Microsoft...) this might be unexpectedly low, but
-is still at least 31 bits everywhere, which is enough for hundreds of
-millions of watchers.
+To improve portability and simplify its API, libev uses C<long> internally
+instead of C<size_t> when allocating its data structures. On non-POSIX
+systems (Microsoft...) this might be unexpectedly low, but is still at
+least 31 bits everywhere, which is enough for hundreds of millions of
+watchers.
 
 =item C<double> must hold a time value in seconds with enough accuracy
 
@@ -3605,58 +3669,6 @@ implementations implementing IEEE 754 (basically all existing ones).
 If you know of other additional requirements drop me a note.
 
 
-=head1 COMPILER WARNINGS
-
-Depending on your compiler and compiler settings, you might get no or a
-lot of warnings when compiling libev code. Some people are apparently
-scared by this.
-
-However, these are unavoidable for many reasons. For one, each compiler
-has different warnings, and each user has different tastes regarding
-warning options. "Warn-free" code therefore cannot be a goal except when
-targeting a specific compiler and compiler-version.
-
-Another reason is that some compiler warnings require elaborate
-workarounds, or other changes to the code that make it less clear and less
-maintainable.
-
-And of course, some compiler warnings are just plain stupid, or simply
-wrong (because they don't actually warn about the condition their message
-seems to warn about).
-
-While libev is written to generate as few warnings as possible,
-"warn-free" code is not a goal, and it is recommended not to build libev
-with any compiler warnings enabled unless you are prepared to cope with
-them (e.g. by ignoring them). Remember that warnings are just that:
-warnings, not errors, or proof of bugs.
-
-
-=head1 VALGRIND
-
-Valgrind has a special section here because it is a popular tool that is
-highly useful, but valgrind reports are very hard to interpret.
-
-If you think you found a bug (memory leak, uninitialised data access etc.)
-in libev, then check twice: If valgrind reports something like:
-
-   ==2274==    definitely lost: 0 bytes in 0 blocks.
-   ==2274==      possibly lost: 0 bytes in 0 blocks.
-   ==2274==    still reachable: 256 bytes in 1 blocks.
-
-Then there is no memory leak. Similarly, under some circumstances,
-valgrind might report kernel bugs as if it were a bug in libev, or it
-might be confused (it is a very good tool, but only a tool).
-
-If you are unsure about something, feel free to contact the mailing list
-with the full valgrind report and an explanation on why you think this is
-a bug in libev. However, don't be annoyed when you get a brisk "this is
-no bug" answer and take the chance of learning how to interpret valgrind
-properly.
-
-If you need, for some reason, empty reports from valgrind for your project
-I suggest using suppression lists.
-
-
 =head1 AUTHOR
 
 Marc Lehmann <libev@schmorp.de>.