--- libev/ev.pod 2010/03/16 17:11:49 1.289 +++ libev/ev.pod 2010/03/24 18:27:13 1.293 @@ -126,13 +126,14 @@ =head2 TIME REPRESENTATION Libev represents time as a single floating point number, representing -the (fractional) number of seconds since the (POSIX) epoch (somewhere -near the beginning of 1970, details are complicated, don't ask). This -type is called C, which is what you should use too. It usually -aliases to the C type in C. When you need to do any calculations -on it, you should treat it as some floating point value. Unlike the name -component C might indicate, it is also used for time differences -throughout libev. +the (fractional) number of seconds since the (POSIX) epoch (in practise +somewhere near the beginning of 1970, details are complicated, don't +ask). This type is called C, which is what you should use +too. It usually aliases to the C type in C. When you need to do +any calculations on it, you should treat it as some floating point value. + +Unlike the name component C might indicate, it is also used for +time differences (e.g. delays) throughout libev. =head1 ERROR HANDLING @@ -347,9 +348,8 @@ =item C -Instead of calling C or C manually after -a fork, you can also make libev check for a fork in each iteration by -enabling this flag. +Instead of calling C manually after a fork, you can also +make libev check for a fork in each iteration by enabling this flag. This works by calling C on every iteration of the loop, and thus this might slow down your event loop if you do a lot of loop @@ -569,11 +569,9 @@ =item struct ev_loop *ev_loop_new (unsigned int flags) Similar to C, but always creates a new event loop that is -always distinct from the default loop. Unlike the default loop, it cannot -handle signal and child watchers, and attempts to do so will be greeted by -undefined behaviour (or a failed assertion if assertions are enabled). +always distinct from the default loop. -Note that this function I thread-safe, and the recommended way to use +Note that this function I thread-safe, and one common way to use libev with threads is indeed to create one loop per thread, and using the default loop in the "main" or "initial" thread. @@ -585,13 +583,12 @@ =item ev_default_destroy () -Destroys the default loop again (frees all memory and kernel state -etc.). None of the active event watchers will be stopped in the normal -sense, so e.g. C might still return true. It is your -responsibility to either stop all watchers cleanly yourself I -calling this function, or cope with the fact afterwards (which is usually -the easiest thing, you can just ignore the watchers and/or C them -for example). +Destroys the default loop (frees all memory and kernel state etc.). None +of the active event watchers will be stopped in the normal sense, so +e.g. C might still return true. It is your responsibility to +either stop all watchers cleanly yourself I calling this function, +or cope with the fact afterwards (which is usually the easiest thing, you +can just ignore the watchers and/or C them for example). Note that certain global state, such as signal state (and installed signal handlers), will not be freed by this function, and related watchers (such @@ -616,9 +613,15 @@ sense). You I call it in the child before using any of the libev functions, and it will only take effect at the next C iteration. +Again, you I to call it on I loop that you want to re-use after +a fork, I. This is +because some kernel interfaces *cough* I *cough* do funny things +during fork. + On the other hand, you only need to call this function in the child -process if and only if you want to use the event library in the child. If -you just fork+exec, you don't have to call it at all. +process if and only if you want to use the event loop in the child. If you +just fork+exec or create a new loop in the child, you don't have to call +it at all. The function itself is quite fast and it's usually not a problem to call it just in case after a fork. To make this easy, the function will fit in @@ -630,25 +633,26 @@ Like C, but acts on an event loop created by C. Yes, you have to call this on every allocated event loop -after fork that you want to re-use in the child, and how you do this is -entirely your own problem. +after fork that you want to re-use in the child, and how you keep track of +them is entirely your own problem. =item int ev_is_default_loop (loop) Returns true when the given loop is, in fact, the default loop, and false otherwise. -=item unsigned int ev_loop_count (loop) +=item unsigned int ev_iteration (loop) -Returns the count of loop iterations for the loop, which is identical to +Returns the current iteration count for the loop, which is identical to the number of times libev did poll for new events. It starts at C<0> and happily wraps around with enough iterations. This value can sometimes be useful as a generation counter of sorts (it "ticks" the number of loop iterations), as it roughly corresponds with -C and C calls. +C and C calls - and is incremented between the +prepare and check phases. -=item unsigned int ev_loop_depth (loop) +=item unsigned int ev_depth (loop) Returns the number of times C was entered minus the number of times C was exited, in other words, the recursion depth. @@ -658,7 +662,8 @@ in which case it is higher. Leaving C abnormally (setjmp/longjmp, cancelling the thread -etc.), doesn't count as exit. +etc.), doesn't count as "exit" - consider this as a hint to avoid such +ungentleman behaviour unless it's really convenient. =item unsigned int ev_backend (loop) @@ -1543,7 +1548,7 @@ =head3 The special problem of accept()ing when you can't Many implementations of the POSIX C function (for example, -found in port-2004 Linux) have the peculiar behaviour of not removing a +found in post-2004 Linux) have the peculiar behaviour of not removing a connection from the pending queue in all error cases. For example, larger servers often run out of file descriptors (because @@ -3662,7 +3667,7 @@ Symbols marked with "(h)" do not change the ABI, and can have different values when compiling libev vs. including F, so it is permissible -to redefine them before including F without breakign compatibility +to redefine them before including F without breaking compatibility to a compiled library. All other symbols change the ABI, which means all users of libev and the libev code itself must be compiled with compatible settings. @@ -4623,13 +4628,28 @@ =back -=head1 PORTING FROM 3.X TO 4.X +=head1 PORTING FROM LIBEV 3.X TO 4.X The major version 4 introduced some minor incompatible changes to the API. +At the moment, the C header file tries to implement superficial +compatibility, so most programs should still compile. Those might be +removed in later versions of libev, so better update early than late. + =over 4 -=item C replaced by C in C +=item C renamed to C + +=item C renamed to C + +=item C renamed to C + +Most functions working on C objects don't have an +C prefix, so it was removed. Note that C is +still called C because it would otherwise clash with the +C typedef. + +=item C renamed to C in C This is a simple rename - all other watcher types use their name as revents flag, and now C does, too.