X-Git-Url: https://git.llucax.com/software/libev.git/blobdiff_plain/d42cbf5de98e3dfe102ad9e2acbb57c401bafadc..5ad960a6f99234c2085d0247aaf0c9343cae5be1:/ev.pod

diff --git a/ev.pod b/ev.pod
index 3104747..199eac0 100644
--- a/ev.pod
+++ b/ev.pod
@@ -325,8 +325,12 @@ Example: try to create a event loop that uses epoll and nothing else.
 =item ev_default_destroy ()
 
 Destroys the default loop again (frees all memory and kernel state
-etc.). This stops all registered event watchers (by not touching them in
-any way whatsoever, although you cannot rely on this :).
+etc.). None of the active event watchers will be stopped in the normal
+sense, so e.g. C<ev_is_active> might still return true. It is your
+responsibility to either stop all watchers cleanly yoursef I<before>
+calling this function, or cope with the fact afterwards (which is usually
+the easiest thing, youc na just ignore the watchers and/or C<free ()> them
+for example).
 
 =item ev_loop_destroy (loop)
 
@@ -507,12 +511,7 @@ corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
 
 As long as your watcher is active (has been started but not stopped) you
 must not touch the values stored in it. Most specifically you must never
-reinitialise it or call its set macro.
-
-You can check whether an event is active by calling the C<ev_is_active
-(watcher *)> macro. To see whether an event is outstanding (but the
-callback for it has not been called yet) you can use the C<ev_is_pending
-(watcher *)> macro.
+reinitialise it or call its C<set> macro.
 
 Each and every callback receives the event loop pointer as first, the
 registered watcher structure as second, and a bitset of received events as
@@ -579,6 +578,85 @@ programs, though, so beware.
 
 =back
 
+=head2 SUMMARY OF GENERIC WATCHER FUNCTIONS
+
+In the following description, C<TYPE> stands for the watcher type,
+e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
+
+=over 4
+
+=item C<ev_init> (ev_TYPE *watcher, callback)
+
+This macro initialises the generic portion of a watcher. The contents
+of the watcher object can be arbitrary (so C<malloc> will do). Only
+the generic parts of the watcher are initialised, you I<need> to call
+the type-specific C<ev_TYPE_set> macro afterwards to initialise the
+type-specific parts. For each type there is also a C<ev_TYPE_init> macro
+which rolls both calls into one.
+
+You can reinitialise a watcher at any time as long as it has been stopped
+(or never started) and there are no pending events outstanding.
+
+The callbakc is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher,
+int revents)>.
+
+=item C<ev_TYPE_set> (ev_TYPE *, [args])
+
+This macro initialises the type-specific parts of a watcher. You need to
+call C<ev_init> at least once before you call this macro, but you can
+call C<ev_TYPE_set> any number of times. You must not, however, call this
+macro on a watcher that is active (it can be pending, however, which is a
+difference to the C<ev_init> macro).
+
+Although some watcher types do not have type-specific arguments
+(e.g. C<ev_prepare>) you still need to call its C<set> macro.
+
+=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
+
+This convinience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
+calls into a single call. This is the most convinient method to initialise
+a watcher. The same limitations apply, of course.
+
+=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
+
+Starts (activates) the given watcher. Only active watchers will receive
+events. If the watcher is already active nothing will happen.
+
+=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
+
+Stops the given watcher again (if active) and clears the pending
+status. It is possible that stopped watchers are pending (for example,
+non-repeating timers are being stopped when they become pending), but
+C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If
+you want to free or reuse the memory used by the watcher it is therefore a
+good idea to always call its C<ev_TYPE_stop> function.
+
+=item bool ev_is_active (ev_TYPE *watcher)
+
+Returns a true value iff the watcher is active (i.e. it has been started
+and not yet been stopped). As long as a watcher is active you must not modify
+it.
+
+=item bool ev_is_pending (ev_TYPE *watcher)
+
+Returns a true value iff the watcher is pending, (i.e. it has outstanding
+events but its callback has not yet been invoked). As long as a watcher
+is pending (but not active) you must not call an init function on it (but
+C<ev_TYPE_set> is safe) and you must make sure the watcher is available to
+libev (e.g. you cnanot C<free ()> it).
+
+=item callback = ev_cb (ev_TYPE *watcher)
+
+Returns the callback currently set on the watcher.
+
+=item ev_cb_set (ev_TYPE *watcher, callback)
+
+Change the callback. You can change the callback at virtually any time
+(modulo threads).
+
+=back
+
+
 =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
 
 Each watcher has, by default, a member C<void *data> that you can change
@@ -780,7 +858,7 @@ Periodic watchers are also timers of a kind, but they are very versatile
 Unlike C<ev_timer>'s, they are not based on real time (or relative time)
 but on wallclock time (absolute time). You can tell a periodic watcher
 to trigger "at" some specific point in time. For example, if you tell a
-periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now ()
+periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
 + 10.>) and then reset your system clock to the last year, then it will
 take a year to trigger the event (unlike an C<ev_timer>, which would trigger
 roughly 10 seconds later and of course not if you reset your system time
@@ -1060,7 +1138,9 @@ Example: *TODO*.
 =head2 C<ev_embed> - when one backend isn't enough
 
 This is a rather advanced watcher type that lets you embed one event loop
-into another.
+into another (currently only C<ev_io> events are supported in the embedded
+loop, other types of watchers might be handled in a delayed or incorrect
+fashion and must not be used).
 
 There are primarily two reasons you would want that: work around bugs and
 prioritise I/O.
@@ -1079,6 +1159,14 @@ priorities and idle watchers might have too much overhead. In this case
 you would put all the high priority stuff in one loop and all the rest in
 a second one, and embed the second one in the first.
 
+As long as the watcher is active, the callback will be invoked every time
+there might be events pending in the embedded loop. The callback must then
+call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke
+their callbacks (you could also start an idle watcher to give the embedded
+loop strictly lower priority for example). You can also set the callback
+to C<0>, in which case the embed watcher will automatically execute the
+embedded loop sweep.
+
 As long as the watcher is started it will automatically handle events. The
 callback will be invoked whenever some events have been handled. You can
 set the callback to C<0> to avoid having to specify one if you are not
@@ -1119,11 +1207,21 @@ create it, and if that fails, use the normal loop for everything:
 
 =over 4
 
-=item ev_embed_init (ev_embed *, callback, struct ev_loop *loop)
+=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
 
-=item ev_embed_set (ev_embed *, callback, struct ev_loop *loop)
+=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
 
-Configures the watcher to embed the given loop, which must be embeddable.
+Configures the watcher to embed the given loop, which must be
+embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
+invoked automatically, otherwise it is the responsibility of the callback
+to invoke it (it will continue to be called until the sweep has been done,
+if you do not want thta, you need to temporarily stop the embed watcher).
+
+=item ev_embed_sweep (loop, ev_embed *)
+
+Make a single, non-blocking sweep over the embedded loop. This works
+similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
+apropriate way for embedded loops.
 
 =back
 
@@ -1166,20 +1264,21 @@ value passed to C<ev_once>:
 
   ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
 
-=item ev_feed_event (loop, watcher, int events)
+=item ev_feed_event (ev_loop *, watcher *, int revents)
 
 Feeds the given event set into the event loop, as if the specified event
 had happened for the specified watcher (which must be a pointer to an
 initialised but not necessarily started event watcher).
 
-=item ev_feed_fd_event (loop, int fd, int revents)
+=item ev_feed_fd_event (ev_loop *, int fd, int revents)
 
 Feed an event on the given fd, as if a file descriptor backend detected
 the given events it.
 
-=item ev_feed_signal_event (loop, int signum)
+=item ev_feed_signal_event (ev_loop *loop, int signum)
 
-Feed an event as if the given signal occured (loop must be the default loop!).
+Feed an event as if the given signal occured (C<loop> must be the default
+loop!).
 
 =back
 
@@ -1213,7 +1312,380 @@ to use the libev header file and library.
 
 =head1 C++ SUPPORT
 
-TBD.
+Libev comes with some simplistic wrapper classes for C++ that mainly allow
+you to use some convinience methods to start/stop watchers and also change
+the callback model to a model using method callbacks on objects.
+
+To use it,
+   
+  #include <ev++.h>
+
+(it is not installed by default). This automatically includes F<ev.h>
+and puts all of its definitions (many of them macros) into the global
+namespace. All C++ specific things are put into the C<ev> namespace.
+
+It should support all the same embedding options as F<ev.h>, most notably
+C<EV_MULTIPLICITY>.
+
+Here is a list of things available in the C<ev> namespace:
+
+=over 4
+
+=item C<ev::READ>, C<ev::WRITE> etc.
+
+These are just enum values with the same values as the C<EV_READ> etc.
+macros from F<ev.h>.
+
+=item C<ev::tstamp>, C<ev::now>
+
+Aliases to the same types/functions as with the C<ev_> prefix.
+
+=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.
+
+All of those classes have these methods:
+
+=over 4
+
+=item ev::TYPE::TYPE (object *, object::method *)
+
+=item ev::TYPE::TYPE (object *, object::method *, struct ev_loop *)
+
+=item ev::TYPE::~TYPE
+
+The constructor takes a pointer to an object and a method pointer to
+the event handler callback to call in this class. The constructor calls
+C<ev_init> for you, which means you have to call the C<set> method
+before starting it. If you do not specify a loop then the constructor
+automatically associates the default loop with this watcher.
+
+The destructor automatically stops the watcher if it is active.
+
+=item w->set (struct ev_loop *)
+
+Associates a different C<struct ev_loop> with this watcher. You can only
+do this when the watcher is inactive (and not pending either).
+
+=item w->set ([args])
+
+Basically the same as C<ev_TYPE_set>, with the same args. Must be
+called at least once.  Unlike the C counterpart, an active watcher gets
+automatically stopped and restarted.
+
+=item w->start ()
+
+Starts the watcher. Note that there is no C<loop> argument as the
+constructor already takes the loop.
+
+=item w->stop ()
+
+Stops the watcher if it is active. Again, no C<loop> argument.
+
+=item w->again ()       C<ev::timer>, C<ev::periodic> only
+
+For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
+C<ev_TYPE_again> function.
+
+=item w->sweep ()       C<ev::embed> only
+
+Invokes C<ev_embed_sweep>.
+
+=back
+
+=back
+
+Example: Define a class with an IO and idle watcher, start one of them in
+the constructor.
+
+  class myclass
+  {
+    ev_io   io;   void io_cb   (ev::io   &w, int revents);
+    ev_idle idle  void idle_cb (ev::idle &w, int revents);
+
+    myclass ();
+  }
+
+  myclass::myclass (int fd)
+  : io   (this, &myclass::io_cb),
+    idle (this, &myclass::idle_cb)
+  {
+    io.start (fd, ev::READ);
+  }
+
+=head1 EMBEDDING
+
+Libev can (and often is) directly embedded into host
+applications. Examples of applications that embed it include the Deliantra
+Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
+and rxvt-unicode.
+
+The goal is to enable you to just copy the neecssary files into your
+source directory without having to change even a single line in them, so
+you can easily upgrade by simply copying (or having a checked-out copy of
+libev somewhere in your source tree).
+
+=head2 FILESETS
+
+Depending on what features you need you need to include one or more sets of files
+in your app.
+
+=head3 CORE EVENT LOOP
+
+To include only the libev core (all the C<ev_*> functions), with manual
+configuration (no autoconf):
+
+  #define EV_STANDALONE 1
+  #include "ev.c"
+
+This will automatically include F<ev.h>, too, and should be done in a
+single C source file only to provide the function implementations. To use
+it, do the same for F<ev.h> in all files wishing to use this API (best
+done by writing a wrapper around F<ev.h> that you can include instead and
+where you can put other configuration options):
+
+  #define EV_STANDALONE 1
+  #include "ev.h"
+
+Both header files and implementation files can be compiled with a C++
+compiler (at least, thats a stated goal, and breakage will be treated
+as a bug).
+
+You need the following files in your source tree, or in a directory
+in your include path (e.g. in libev/ when using -Ilibev):
+
+  ev.h
+  ev.c
+  ev_vars.h
+  ev_wrap.h
+
+  ev_win32.c      required on win32 platforms only
+
+  ev_select.c     only when select backend is enabled (which is is by default)
+  ev_poll.c       only when poll backend is enabled (disabled by default)
+  ev_epoll.c      only when the epoll backend is enabled (disabled by default)
+  ev_kqueue.c     only when the kqueue backend is enabled (disabled by default)
+  ev_port.c       only when the solaris port backend is enabled (disabled by default)
+
+F<ev.c> includes the backend files directly when enabled, so you only need
+to compile a single file.
+
+=head3 LIBEVENT COMPATIBILITY API
+
+To include the libevent compatibility API, also include:
+
+  #include "event.c"
+
+in the file including F<ev.c>, and:
+
+  #include "event.h"
+
+in the files that want to use the libevent API. This also includes F<ev.h>.
+
+You need the following additional files for this:
+
+  event.h
+  event.c
+
+=head3 AUTOCONF SUPPORT
+
+Instead of using C<EV_STANDALONE=1> and providing your config in
+whatever way you want, you can also C<m4_include([libev.m4])> in your
+F<configure.ac> and leave C<EV_STANDALONE> off. F<ev.c> will then include
+F<config.h> and configure itself accordingly.
+
+For this of course you need the m4 file:
+
+  libev.m4
+
+=head2 PREPROCESSOR SYMBOLS/MACROS
+
+Libev can be configured via a variety of preprocessor symbols you have to define
+before including any of its files. The default is not to build for multiplicity
+and only include the select backend.
+
+=over 4
+
+=item EV_STANDALONE
+
+Must always be C<1> if you do not use autoconf configuration, which
+keeps libev from including F<config.h>, and it also defines dummy
+implementations for some libevent functions (such as logging, which is not
+supported). It will also not define any of the structs usually found in
+F<event.h> that are not directly supported by the libev core alone.
+
+=item EV_USE_MONOTONIC
+
+If defined to be C<1>, libev will try to detect the availability of the
+monotonic clock option at both compiletime and runtime. Otherwise no use
+of the monotonic clock option will be attempted. If you enable this, you
+usually have to link against librt or something similar. Enabling it when
+the functionality isn't available is safe, though, althoguh you have
+to make sure you link against any libraries where the C<clock_gettime>
+function is hiding in (often F<-lrt>).
+
+=item EV_USE_REALTIME
+
+If defined to be C<1>, libev will try to detect the availability of the
+realtime clock option at compiletime (and assume its availability at
+runtime if successful). Otherwise no use of the realtime clock option will
+be attempted. This effectively replaces C<gettimeofday> by C<clock_get
+(CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries
+in the description of C<EV_USE_MONOTONIC>, though.
+
+=item EV_USE_SELECT
+
+If undefined or defined to be C<1>, libev will compile in support for the
+C<select>(2) backend. No attempt at autodetection will be done: if no
+other method takes over, select will be it. Otherwise the select backend
+will not be compiled in.
+
+=item EV_SELECT_USE_FD_SET
+
+If defined to C<1>, then the select backend will use the system C<fd_set>
+structure. This is useful if libev doesn't compile due to a missing
+C<NFDBITS> or C<fd_mask> definition or it misguesses the bitset layout on
+exotic systems. This usually limits the range of file descriptors to some
+low limit such as 1024 or might have other limitations (winsocket only
+allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
+influence the size of the C<fd_set> used.
+
+=item EV_SELECT_IS_WINSOCKET
+
+When defined to C<1>, the select backend will assume that
+select/socket/connect etc. don't understand file descriptors but
+wants osf handles on win32 (this is the case when the select to
+be used is the winsock select). This means that it will call
+C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
+it is assumed that all these functions actually work on fds, even
+on win32. Should not be defined on non-win32 platforms.
+
+=item EV_USE_POLL
+
+If defined to be C<1>, libev will compile in support for the C<poll>(2)
+backend. Otherwise it will be enabled on non-win32 platforms. It
+takes precedence over select.
+
+=item EV_USE_EPOLL
+
+If defined to be C<1>, libev will compile in support for the Linux
+C<epoll>(7) backend. Its availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the
+preferred backend for GNU/Linux systems.
+
+=item EV_USE_KQUEUE
+
+If defined to be C<1>, libev will compile in support for the BSD style
+C<kqueue>(2) backend. Its actual availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the preferred
+backend for BSD and BSD-like systems, although on most BSDs kqueue only
+supports some types of fds correctly (the only platform we found that
+supports ptys for example was NetBSD), so kqueue might be compiled in, but
+not be used unless explicitly requested. The best way to use it is to find
+out whether kqueue supports your type of fd properly and use an embedded
+kqueue loop.
+
+=item EV_USE_PORT
+
+If defined to be C<1>, libev will compile in support for the Solaris
+10 port style backend. Its availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the preferred
+backend for Solaris 10 systems.
+
+=item EV_USE_DEVPOLL
+
+reserved for future expansion, works like the USE symbols above.
+
+=item EV_H
+
+The name of the F<ev.h> header file used to include it. The default if
+undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This
+can be used to virtually rename the F<ev.h> header file in case of conflicts.
+
+=item EV_CONFIG_H
+
+If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
+F<ev.c>'s idea of where to find the F<config.h> file, similarly to
+C<EV_H>, above.
+
+=item EV_EVENT_H
+
+Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
+of how the F<event.h> header can be found.
+
+=item EV_PROTOTYPES
+
+If defined to be C<0>, then F<ev.h> will not define any function
+prototypes, but still define all the structs and other symbols. This is
+occasionally useful if you want to provide your own wrapper functions
+around libev functions.
+
+=item EV_MULTIPLICITY
+
+If undefined or defined to C<1>, then all event-loop-specific functions
+will have the C<struct ev_loop *> as first argument, and you can create
+additional independent event loops. Otherwise there will be no support
+for multiple event loops and there is no first event loop pointer
+argument. Instead, all functions act on the single default loop.
+
+=item EV_PERIODICS
+
+If undefined or defined to be C<1>, then periodic timers are supported,
+otherwise not. This saves a few kb of code.
+
+=item EV_COMMON
+
+By default, all watchers have a C<void *data> member. By redefining
+this macro to a something else you can include more and other types of
+members. You have to define it each time you include one of the files,
+though, and it must be identical each time.
+
+For example, the perl EV module uses something like this:
+
+  #define EV_COMMON                       \
+    SV *self; /* contains this struct */  \
+    SV *cb_sv, *fh /* note no trailing ";" */
+
+=item EV_CB_DECLARE(type)
+
+=item EV_CB_INVOKE(watcher,revents)
+
+=item ev_set_cb(ev,cb)
+
+Can be used to change the callback member declaration in each watcher,
+and the way callbacks are invoked and set. Must expand to a struct member
+definition and a statement, respectively. See the F<ev.v> header file for
+their default definitions. One possible use for overriding these is to
+avoid the ev_loop pointer as first argument in all cases, or to use method
+calls instead of plain function calls in C++.
+
+=head2 EXAMPLES
+
+For a real-world example of a program the includes libev
+verbatim, you can have a look at the EV perl module
+(L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
+the F<libev/> subdirectory and includes them in the F<EV/EVAPI.h> (public
+interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
+will be compiled. It is pretty complex because it provides its own header
+file.
+
+The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
+that everybody includes and which overrides some autoconf choices:
+
+  #define EV_USE_POLL 0
+  #define EV_MULTIPLICITY 0
+  #define EV_PERIODICS 0
+  #define EV_CONFIG_H <config.h>
+
+  #include "ev++.h"
+
+And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
+
+  #include "ev_cpp.h"
+  #include "ev.c"
 
 =head1 AUTHOR