[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.338 by root, Sun Oct 31 21:16:26 2010 UTC vs.
Revision 1.344 by root, Wed Nov 10 13:41:48 2010 UTC

 the current system, you would need to look at C<ev_embeddable_backends ()
 & ev_supported_backends ()>, likewise for recommended ones.
 See the description of C<ev_embed> watchers for more info.
-=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
+=item ev_set_allocator (void *(*cb)(void *ptr, long size))
 Sets the allocation function to use (the prototype is similar - the
 semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
 used to allocate and free memory (no surprises here). If it returns zero
 when memory needs to be allocated (C<size != 0>), the library might abort
    }
    ...
    ev_set_allocator (persistent_realloc);
-=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
+=item ev_set_syserr_cb (void (*cb)(const char *msg))
 Set the callback function to call on a retryable system call error (such
 as failed select, poll, epoll_wait). The message is a printable string
 indicating the system call or subsystem causing the problem. If this
 callback is set, then libev will expect it to remedy the situation, no
 =item struct ev_loop *ev_loop_new (unsigned int flags)
 This will create and initialise a new event loop object. If the loop
 could not be initialised, returns false.
-Note that this function I<is> thread-safe, and one common way to use
+This function is thread-safe, and one common way to use libev with
-libev with threads is indeed to create one loop per thread, and using the
+threads is indeed to create one loop per thread, and using the default
-default loop in the "main" or "initial" thread.
+loop in the "main" or "initial" thread.
 The flags argument can be used to specify special behaviour or specific
 backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
 The following flags are supported:
 environment variable.
 =item C<EVFLAG_NOINOTIFY>
 When this flag is specified, then libev will not attempt to use the
-I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
+I<inotify> API for its C<ev_stat> watchers. Apart from debugging and
 testing, this flag can be useful to conserve inotify file descriptors, as
 otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
 =item C<EVFLAG_SIGNALFD>
 When this flag is specified, then libev will attempt to use the
-I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
+I<signalfd> API for its C<ev_signal> (and C<ev_child>) watchers. This API
 delivers signals synchronously, which makes it both faster and might make
 it possible to get the queued signal data. It can also simplify signal
 handling with threads, as long as you properly block signals in your
 threads that are not interested in handling them.
 This function is normally used on loop objects allocated by
 C<ev_loop_new>, but it can also be used on the default loop returned by
 C<ev_default_loop>, in which case it is not thread-safe.
 Note that it is not advisable to call this function on the default loop
-except in the rare occasion where you really need to free it's resources.
+except in the rare occasion where you really need to free its resources.
 If you need dynamically allocated loops it is better to use C<ev_loop_new>
 and C<ev_loop_destroy>.
 =item ev_loop_fork (loop)
 prepare and check phases.
 =item unsigned int ev_depth (loop)
 Returns the number of times C<ev_run> was entered minus the number of
-times C<ev_run> was exited, in other words, the recursion depth.
+times C<ev_run> was exited normally, in other words, the recursion depth.
 Outside C<ev_run>, this number is zero. In a callback, this number is
 C<1>, unless C<ev_run> was invoked recursively (or from another thread),
 in which case it is higher.
-Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread
+Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread,
-etc.), doesn't count as "exit" - consider this as a hint to avoid such
+throwing an exception etc.), doesn't count as "exit" - consider this
-ungentleman-like behaviour unless it's really convenient.
+as a hint to avoid such ungentleman-like behaviour unless it's really
+convenient, in which case it is fully supported.
 =item unsigned int ev_backend (loop)
 Returns one of the C<EVBACKEND_*> flags indicating the event backend in
 use.
 relying on all watchers to be stopped when deciding when a program has
 finished (especially in interactive programs), but having a program
 that automatically loops as long as it has to and no longer by virtue
 of relying on its watchers stopping correctly, that is truly a thing of
 beauty.
+This function is also I<mostly> exception-safe - you can break out of
+a C<ev_run> call by calling C<longjmp> in a callback, throwing a C++
+exception and so on. This does not decrement the C<ev_depth> value, nor
+will it clear any outstanding C<EVBREAK_ONE> breaks.
 A flags value of C<EVRUN_NOWAIT> will look for new events, will handle
 those events and any already outstanding ones, but will not wait and
 block your process in case there are no events and will return after one
 iteration of the loop. This is sometimes useful to poll and handle new
 Can be used to make a call to C<ev_run> return early (but only after it
 has processed all outstanding events). The C<how> argument must be either
 C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or
 C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return.
-This "break state" will be cleared when entering C<ev_run> again.
+This "break state" will be cleared on the next call to C<ev_run>.
-It is safe to call C<ev_break> from outside any C<ev_run> calls, too.
+It is safe to call C<ev_break> from outside any C<ev_run> calls, too, in
+which case it will have no effect.
 =item ev_ref (loop)
 =item ev_unref (loop)
 See also the locking example in the C<THREADS> section later in this
 document.
 =item ev_set_userdata (loop, void *data)
-=item ev_userdata (loop)
+=item void *ev_userdata (loop)
 Set and retrieve a single C<void *> associated with a loop. When
 C<ev_set_userdata> has never been called, then C<ev_userdata> returns
-C<0.>
+C<0>.
 These two functions can be used to associate arbitrary data with a loop,
 and are intended solely for the C<invoke_pending_cb>, C<release> and
 C<acquire> callbacks described above, but of course can be (ab-)used for
 any other purpose as well.
 =head2 C<ev_signal> - signal me when a signal gets signalled!
 Signal watchers will trigger an event when the process receives a specific
 signal one or more times. Even though signals are very asynchronous, libev
-will try it's best to deliver signals synchronously, i.e. as part of the
+will try its best to deliver signals synchronously, i.e. as part of the
 normal event processing, like any other event.
 If you want signals to be delivered truly asynchronously, just use
 C<sigaction> as you would do without libev and forget about sharing
 the signal. You can even use C<ev_async> from a signal handler to
 =item * Priorities are not currently supported. Initialising priorities
 will fail and all watchers will have the same priority, even though there
 is an ev_pri field.
 =item * In libevent, the last base created gets the signals, in libev, the
-first base created (== the default loop) gets the signals.
+base that registered the signal gets the signals.
 =item * Other members are not supported.
 =item * The libev emulation is I<not> ABI compatible to libevent, you need
 to use the libev header file and library.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.338 by root, Sun Oct 31 21:16:26 2010 UTC vs. Revision 1.344 by root, Wed Nov 10 13:41:48 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.338 by root, Sun Oct 31 21:16:26 2010 UTC vs.
Revision 1.344 by root, Wed Nov 10 13:41:48 2010 UTC