--- libev/ev.pod 2012/05/06 13:42:10 1.416 +++ libev/ev.pod 2014/04/26 14:28:48 1.432 @@ -1,3 +1,5 @@ +=encoding utf-8 + =head1 NAME libev - a high performance full-featured event loop written in C @@ -398,8 +400,10 @@ or setgid) then libev will I look at the environment variable C. Otherwise (the default), this environment variable will override the flags completely if it is found in the environment. This is -useful to try out specific backends to test their performance, or to work -around bugs. +useful to try out specific backends to test their performance, to work +around bugs, or to make libev threadsafe (accessing environment variables +cannot be done in a threadsafe way, but usually it works if no other +thread modifies them). =item C @@ -571,7 +575,7 @@ cause an extra system call as with C, it still adds up to two event changes per incident. Support for C is very bad (you might have to leak fd's on fork, but it's more sane than epoll) and it -drops fds silently in similarly hard-to-detect cases +drops fds silently in similarly hard-to-detect cases. This backend usually performs well under most conditions. @@ -686,7 +690,7 @@ the child process. You I call it (or use C) in the child before resuming or calling C. -Again, you I to call it on I loop that you want to re-use after +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. @@ -1395,7 +1399,7 @@ =over 4 -=item initialiased +=item initialised Before a watcher can be registered with the event loop it has to be initialised. This can be done with a call to C, or calls to @@ -2391,7 +2395,7 @@ ev_periodic_init (&hourly_tick, clock_cb, fmod (ev_now (loop), 3600.), 3600., 0); ev_periodic_start (loop, &hourly_tick); - + =head2 C - signal me when a signal gets signalled! @@ -2411,9 +2415,9 @@ C in both the default loop and another loop at the same time. At the moment, C is permanently tied to the default loop. -When the first watcher gets started will libev actually register something -with the kernel (thus it coexists with your own signal handlers as long as -you don't register any with libev for the same signal). +Only after the first watcher for a signal is started will libev actually +register something with the kernel. It thus coexists with your own signal +handlers as long as you don't register any with libev for the same signal. If possible and supported, libev will install its handlers with C (or equivalent) behaviour enabled, so system calls should @@ -2608,8 +2612,9 @@ This watches a file system path for attribute changes. That is, it calls C on that path in regular intervals (or when the OS says it changed) -and sees if it changed compared to the last time, invoking the callback if -it did. +and sees if it changed compared to the last time, invoking the callback +if it did. Starting the watcher C's the file, so only changes that +happen after the watcher has been started will be reported. The path does not need to exist: changing from "path exists" to "path does not exist" is a status change like any other. The condition "path does not @@ -2964,7 +2969,6 @@ next event loop iteration. However, that isn't as soon as possible - without external events, your C watcher will not be invoked. - This is where C watchers come in handy - all you need is a single global idle watcher that is active as long as you have one active C watcher. The C watcher makes sure the event loop @@ -3180,7 +3184,7 @@ =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) -=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) +=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop) Configures the watcher to embed the given loop, which must be embeddable. If the callback is C<0>, then C will be @@ -3211,7 +3215,7 @@ struct ev_loop *loop_hi = ev_default_init (0); struct ev_loop *loop_lo = 0; ev_embed embed; - + // see if there is a chance of getting one that works // (remember that a flags value of 0 means autodetection) loop_lo = ev_embeddable_backends () & ev_recommended_backends () @@ -3235,7 +3239,7 @@ struct ev_loop *loop = ev_default_init (0); struct ev_loop *loop_socket = 0; ev_embed embed; - + if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) { @@ -3253,11 +3257,11 @@ Fork watchers are called when a C was detected (usually because whoever is a good citizen cared to tell libev about it by calling -C or C). The invocation is done before the -event loop blocks next and before C watchers are being called, -and only in the child after the fork. If whoever good citizen calling -C cheats and calls it in the wrong process, the fork -handlers will be invoked, too, of course. +C). The invocation is done before the event loop blocks next +and before C watchers are being called, and only in the child +after the fork. If whoever good citizen calling C cheats +and calls it in the wrong process, the fork handlers will be invoked, too, +of course. =head3 The special problem of life after fork - how is it possible? @@ -3661,9 +3665,9 @@ A common way around all these issues is to make sure that C I returns before the callback is invoked. If C immediately knows the result, it can artificially -delay invoking the callback by e.g. using a C or C watcher -for example, or more sneakily, by reusing an existing (stopped) watcher -and pushing it into the pending queue: +delay invoking the callback by using a C or C watcher for +example, or more sneakily, by reusing an existing (stopped) watcher and +pushing it into the pending queue: ev_set_cb (watcher, callback); ev_feed_event (EV_A_ watcher, 0); @@ -3681,7 +3685,7 @@ main C call, but not the nested one (e.g. user clicked "Quit", but a modal "Are you sure?" dialog is still waiting), or just the nested one and not the main one (e.g. user clocked "Ok" in a modal dialog), or some -other combination: In these cases, C will not work alone. +other combination: In these cases, a simple C will not work. The solution is to maintain "break this loop" variable for each C invocation, and use a loop around C until the condition is @@ -3952,7 +3956,7 @@ Proper exception specifications might have to be added to callbacks passed to libev: exceptions may be thrown only from watcher callbacks, all -other callbacks (allocator, syserr, loop acquire/release and periodioc +other callbacks (allocator, syserr, loop acquire/release and periodic reschedule callbacks) must not throw exceptions, and might need a C specification. If you have code that needs to be compiled as both C and C++ you can use the C macro for this: @@ -3982,7 +3986,7 @@ the callback model to a model using method callbacks on objects. To use it, - + #include This automatically includes F and puts all of its definitions (many @@ -4095,7 +4099,7 @@ ... } } - + myfunctor f; ev::io w; @@ -4123,10 +4127,14 @@ =item w->set ([arguments]) -Basically the same as C, with the same arguments. Either this -method or a suitable start method must be called at least once. Unlike the -C counterpart, an active watcher gets automatically stopped and restarted -when reconfiguring it with this method. +Basically the same as C (except for C watchers>), +with the same arguments. Either this method or a suitable start method +must be called at least once. Unlike the C counterpart, an active watcher +gets automatically stopped and restarted when reconfiguring it with this +method. + +For C watchers this method is called C, to avoid +clashing with the C method. =item w->start () @@ -4556,6 +4564,13 @@ file descriptors again. Note that the replacement function has to close the underlying OS handle. +=item EV_USE_WSASOCKET + +If defined to be C<1>, libev will use C to create its internal +communication socket, which works better in some environments. Otherwise, +the normal C function will be used, which works better in other +environments. + =item EV_USE_POLL If defined to be C<1>, libev will compile in support for the C(2) @@ -4609,23 +4624,22 @@ =item EV_NO_THREADS -If defined to be C<1>, libev will assume that it will never be called -from different threads, which is a stronger assumption than C, -above. This reduces dependencies and makes libev faster. +If defined to be C<1>, libev will assume that it will never be called from +different threads (that includes signal handlers), which is a stronger +assumption than C, above. This reduces dependencies and makes +libev faster. =item EV_ATOMIC_T Libev requires an integer type (suitable for storing C<0> or C<1>) whose -access is atomic and serialised with respect to other threads or signal -contexts. No such type is easily found in the C language, so you can -provide your own type that you know is safe for your purposes. It is used -both for signal handler "locking" as well as for signal and thread safety -in C watchers. +access is atomic with respect to other threads or signal contexts. No +such type is easily found in the C language, so you can provide your own +type that you know is safe for your purposes. It is used both for signal +handler "locking" as well as for signal and thread safety in C +watchers. In the absence of this define, libev will use C -(from F), which is usually good enough on most platforms, -although strictly speaking using a type that also implies a memory fence -is required. +(from F), which is usually good enough on most platforms. =item EV_H (h) @@ -5304,8 +5318,8 @@ C could complicate things, however. The most portable way to handle signals is to block signals in all threads -except the initial one, and run the default loop in the initial thread as -well. +except the initial one, and run the signal handling loop in the initial +thread as well. =item C must be large enough for common memory allocation sizes @@ -5419,7 +5433,7 @@ =item C backwards compatibility mechanism The backward compatibility mechanism can be controlled by -C. See L in the L +C. See L in the L section. =item C and C have been removed