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

Comparing libev/ev.pod (file contents):
Revision 1.388 by root, Tue Dec 20 04:08:35 2011 UTC vs.
Revision 1.401 by root, Wed Apr 18 06:06:04 2012 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))
+=item ev_set_allocator (void *(*cb)(void *ptr, long size) throw ())
 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))
+=item ev_set_syserr_cb (void (*cb)(const char *msg) throw ())
 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
 It scales in the same way as the epoll backend, but the interface to the
 kernel is more efficient (which says nothing about its actual speed, of
 course). While stopping, setting and starting an I/O watcher does never
 cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
-two event changes per incident. Support for C<fork ()> is very bad (but
+two event changes per incident. Support for C<fork ()> is very bad (you
-sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
+might have to leak fd's on fork, but it's more sane than epoll) and it
-cases
+drops fds silently in similarly hard-to-detect cases
 This backend usually performs well under most conditions.
 While nominally embeddable in other event loops, this doesn't work
 everywhere, so you might need to test for this. And since it is broken
 without a previous call to C<ev_suspend>.
 Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
 event loop time (see C<ev_now_update>).
-=item ev_run (loop, int flags)
+=item bool ev_run (loop, int flags)
 Finally, this is it, the event handler. This function usually is called
 after you have initialised all your watchers and you want to start
 handling events. It will ask the operating system for any new events, call
-the watcher callbacks, an then repeat the whole process indefinitely: This
+the watcher callbacks, and then repeat the whole process indefinitely: This
 is why event loops are called I<loops>.
 If the flags argument is specified as C<0>, it will keep handling events
 until either no event watchers are active anymore or C<ev_break> was
 called.
+The return value is false if there are no more active watchers (which
+usually means "all jobs done" or "deadlock"), and true in all other cases
+(which usually means " you should call C<ev_run> again").
 Please note that an explicit C<ev_break> is usually better than
 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
+This function is I<mostly> exception-safe - you can break out of a
-a C<ev_run> call by calling C<longjmp> in a callback, throwing a C++
+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
 invoke the actual watchers inside another context (another thread etc.).
 If you want to reset the callback, use C<ev_invoke_pending> as new
 callback.
-=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
+=item ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ())
 Sometimes you want to share the same loop between multiple threads. This
 can be done relatively simply by putting mutex_lock/unlock calls around
 each call to a libev function.
          // timeout occurred, take action
        }
      else
        {
          // callback was invoked, but there was some recent
-         // activity.  simply restart the timer to time out
+         // activity. simply restart the timer to time out
          // after "after" seconds, which is the earliest time
          // the timeout can occur.
          ev_timer_set (w, after, 0.);
          ev_timer_start (EV_A_ w);
        }
 keep up with the timer (because it takes longer than those 10 seconds to
 do stuff) the timer will not fire more than once per event loop iteration.
 =item ev_timer_again (loop, ev_timer *)
-This will act as if the timer timed out and restarts it again if it is
+This will act as if the timer timed out, and restarts it again if it is
-repeating. The exact semantics are:
+repeating. It basically works like calling C<ev_timer_stop>, updating the
+timeout to the C<repeat> value and calling C<ev_timer_start>.
+The exact semantics are as in the following rules, all of which will be
+applied to the watcher:
+=over 4
-If the timer is pending, its pending status is cleared.
+=item If the timer is pending, the pending status is always cleared.
-If the timer is started but non-repeating, stop it (as if it timed out).
+=item If the timer is started but non-repeating, stop it (as if it timed
+out, without invoking it).
-If the timer is repeating, either start it if necessary (with the
+=item If the timer is repeating, make the C<repeat> value the new timeout
-C<repeat> value), or reset the running timer to the C<repeat> value.
+and start the timer, if necessary.
+=back
 This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
 usage example.
 =item ev_tstamp ev_timer_remaining (loop, ev_timer *)
    int exit_main_loop = 0;
    while (!exit_main_loop)
      ev_run (EV_DEFAULT_ EVRUN_ONCE);
-   // in a model watcher
+   // in a modal watcher
    int exit_nested_loop = 0;
    while (!exit_nested_loop)
      ev_run (EV_A_ EVRUN_ONCE);
      switch_to (libev_coro);
    }
 That basically suspends the coroutine inside C<wait_for_event> and
 continues the libev coroutine, which, when appropriate, switches back to
-this or any other coroutine. I am sure if you sue this your own :)
+this or any other coroutine.
 You can do similar tricks if you have, say, threads with an event queue -
 instead of storing a coroutine, you store the queue object and instead of
 switching to a coroutine, you push the watcher onto the queue and notify
 any waiters.
 to use the libev header file and library.
 =back
 =head1 C++ SUPPORT
+=head2 C API
+The normal C API should work fine when used from C++: both ev.h and the
+libev sources can be compiled as C++. Therefore, code that uses the C API
+will work fine.
+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
+reschedule callbacks) must not throw exceptions, and might need a C<throw
+()> specification. If you have code that needs to be compiled as both C
+and C++ you can use the C<EV_THROW> macro for this:
+   static void
+   fatal_error (const char *msg) EV_THROW
+   {
+     perror (msg);
+     abort ();
+   }
+   ...
+   ev_set_syserr_cb (fatal_error);
+The only API functions that can currently throw exceptions are C<ev_run>,
+C<ev_inoke> and C<ev_invoke_pending>.
+Throwing exceptions in watcher callbacks is only supported if libev itself
+is compiled with a C++ compiler or your C and C++ environments allow
+throwing exceptions through C libraries (most do).
+=head2 C++ API
 Libev comes with some simplistic wrapper classes for C++ that mainly allow
 you to use some convenience methods to start/stop watchers and also change
 the callback model to a model using method callbacks on objects.
 with C<operator ()> can be used as callbacks. Other types should be easy
 to add as long as they only need one additional pointer for context. If
 you need support for other types of functors please contact the author
 (preferably after implementing it).
+For all this to work, your C++ compiler either has to use the same calling
+conventions as your C compiler (for static member functions), or you have
+to embed libev and compile libev itself as C++.
 Here is a list of things available in the C<ev> namespace:
 =over 4
 =item C<ev::READ>, C<ev::WRITE> etc.
 =item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc.
 For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of
 the same name in the C<ev> namespace, with the exception of C<ev_signal>
 which is called C<ev::sig> to avoid clashes with the C<signal> macro
-defines by many implementations.
+defined by many implementations.
 All of those classes have these methods:
 =over 4
 If defined to be C<1>, libev will compile in support for the Linux inotify
 interface to speed up C<ev_stat> watchers. Its actual availability will
 be detected at runtime. If undefined, it will be enabled if the headers
 indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
+=item EV_NO_SMP
+If defined to be C<1>, libev will assume that memory is always coherent
+between threads, that is, threads can be used, but threads never run on
+different cpus (or different cpu cores). This reduces dependencies
+and makes libev faster.
+=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<EV_NO_SMP>,
+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
    #define EV_USE_POLL 1
    #define EV_CHILD_ENABLE 1
    #define EV_ASYNC_ENABLE 1
 The actual value is a bitset, it can be a combination of the following
-values:
+values (by default, all of these are enabled):
 =over 4
 =item C<1> - faster/larger code
 code size by roughly 30% on amd64).
 When optimising for size, use of compiler flags such as C<-Os> with
 gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
 assertions.
+The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
+(e.g. gcc with C<-Os>).
 =item C<2> - faster/larger data structures
 Replaces the small 2-heap for timer management by a faster 4-heap, larger
 hash table sizes and so on. This will usually further increase code size
 and can additionally have an effect on the size of data structures at
 runtime.
+The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler
+(e.g. gcc with C<-Os>).
 =item C<4> - full API configuration
 This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
 enables multiplicity (C<EV_MULTIPLICITY>=1).
 when you embed libev, only want to use libev functions in a single file,
 and do not want its identifiers to be visible.
 To use this, define C<EV_API_STATIC> and include F<ev.c> in the file that
 wants to use libev.
+This option only works when libev is compiled with a C compiler, as C++
+doesn't support the required declaration syntax.
 =item EV_AVOID_STDIO
 If this is set to C<1> at compiletime, then libev will avoid using stdio
 functions (printf, scanf, perror etc.). This will increase the code size

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.388 by root, Tue Dec 20 04:08:35 2011 UTC vs. Revision 1.401 by root, Wed Apr 18 06:06:04 2012 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.388 by root, Tue Dec 20 04:08:35 2011 UTC vs.
Revision 1.401 by root, Wed Apr 18 06:06:04 2012 UTC