--- libev/ev.pod 2007/11/23 16:17:12 1.34 +++ libev/ev.pod 2007/11/24 10:15:16 1.40 @@ -108,6 +108,16 @@ (assuming you know what you are doing). This is the set of backends that libev will probe for if you specify no backends explicitly. +=item unsigned int ev_embeddable_backends () + +Returns the set of backends that are embeddable in other event loops. This +is the theoretical, all-platform, value. To find which backends +might be supported on the current system, you would need to look at +C, likewise for +recommended ones. + +See the description of C watchers for more info. + =item ev_set_allocator (void *(*cb)(void *ptr, long size)) Sets the allocation function to use (the prototype is similar to the @@ -315,8 +325,12 @@ =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 might still return true. It is your +responsibility to either stop all watchers cleanly yoursef I +calling this function, or cope with the fact afterwards (which is usually +the easiest thing, youc na just ignore the watchers and/or C them +for example). =item ev_loop_destroy (loop) @@ -497,12 +511,7 @@ 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 macro. To see whether an event is outstanding (but the -callback for it has not been called yet) you can use the C macro. +reinitialise it or call its C 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 @@ -569,6 +578,85 @@ =back +=head2 SUMMARY OF GENERIC WATCHER FUNCTIONS + +In the following description, C stands for the watcher type, +e.g. C for C watchers and C for C watchers. + +=over 4 + +=item C (ev_TYPE *watcher, callback) + +This macro initialises the generic portion of a watcher. The contents +of the watcher object can be arbitrary (so C will do). Only +the generic parts of the watcher are initialised, you I to call +the type-specific C macro afterwards to initialise the +type-specific parts. For each type there is also a C 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. + +=item C (ev_TYPE *, [args]) + +This macro initialises the type-specific parts of a watcher. You need to +call C at least once before you call this macro, but you can +call C 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 macro). + +Although some watcher types do not have type-specific arguments +(e.g. C) you still need to call its C macro. + +=item C (ev_TYPE *watcher, callback, [args]) + +This convinience macro rolls both C and C macro +calls into a single call. This is the most convinient method to initialise +a watcher. The same limitations apply, of course. + +=item C (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 (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 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 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 is safe) and you must make sure the watcher is available to +libev (e.g. you cnanot C 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 that you can change @@ -770,7 +858,7 @@ Unlike C'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) and then reset your system clock to the last year, then it will take a year to trigger the event (unlike an C, which would trigger roughly 10 seconds later and of course not if you reset your system time @@ -925,6 +1013,7 @@ =back + =head2 C - wait for pid status changes Child watchers trigger when your process receives a SIGCHLD in response to @@ -1008,9 +1097,10 @@ prepare watchers get invoked before the process blocks and check watchers afterwards. -Their main purpose is to integrate other event mechanisms into libev. This -could be used, for example, to track variable changes, implement your own -watchers, integrate net-snmp or a coroutine library and lots more. +Their main purpose is to integrate other event mechanisms into libev and +their use is somewhat advanced. This could be used, for example, to track +variable changes, implement your own watchers, integrate net-snmp or a +coroutine library and lots more. This is done by examining in each prepare call which file descriptors need to be watched by the other library, registering C watchers for @@ -1045,6 +1135,97 @@ Example: *TODO*. +=head2 C - when one backend isn't enough + +This is a rather advanced watcher type that lets you embed one event loop +into another (currently only C 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. + +As an example for a bug workaround, the kqueue backend might only support +sockets on some platform, so it is unusable as generic backend, but you +still want to make use of it because you have many sockets and it scales +so nicely. In this case, you would create a kqueue-based loop and embed it +into your default loop (which might use e.g. poll). Overall operation will +be a bit slower because first libev has to poll and then call kevent, but +at least you can use both at what they are best. + +As for prioritising I/O: rarely you have the case where some fds have +to be watched and handled very quickly (with low latency), and even +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 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 +interested in that. + +Also, there have not currently been made special provisions for forking: +when you fork, you not only have to call C on both loops, +but you will also have to stop and restart any C watchers +yourself. + +Unfortunately, not all backends are embeddable, only the ones returned by +C are, which, unfortunately, does not include any +portable one. + +So when you want to use this feature you will always have to be prepared +that you cannot get an embeddable loop. The recommended way to get around +this is to have a separate variables for your embeddable loop, try to +create it, and if that fails, use the normal loop for everything: + + struct ev_loop *loop_hi = ev_default_init (0); + struct ev_loop *loop_lo = 0; + struct 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 () + ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) + : 0; + + // if we got one, then embed it, otherwise default to loop_hi + if (loop_lo) + { + ev_embed_init (&embed, 0, loop_lo); + ev_embed_start (loop_hi, &embed); + } + else + loop_lo = loop_hi; + +=over 4 + +=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_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. If the callback is C<0>, then C 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, but in the most +apropriate way for embedded loops. + +=back + + =head1 OTHER FUNCTIONS There are some other functions of possible interest. Described. Here. Now. @@ -1083,20 +1264,21 @@ 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 must be the default +loop!). =back @@ -1130,7 +1312,380 @@ =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 + +(it is not installed by default). This automatically includes F +and puts all of its definitions (many of them macros) into the global +namespace. All C++ specific things are put into the C namespace. + +It should support all the same embedding options as F, most notably +C. + +Here is a list of things available in the C namespace: + +=over 4 + +=item C, C etc. + +These are just enum values with the same values as the C etc. +macros from F. + +=item C, C + +Aliases to the same types/functions as with the C prefix. + +=item C, C, C, C, C etc. + +For each C watcher in F there is a corresponding class of +the same name in the C namespace, with the exception of C +which is called C to avoid clashes with the C 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 for you, which means you have to call the C 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 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, 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 argument as the +constructor already takes the loop. + +=item w->stop () + +Stops the watcher if it is active. Again, no C argument. + +=item w->again () C, C only + +For C and C, this invokes the corresponding +C function. + +=item w->sweep () C only + +Invokes C. + +=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 functions), with manual +configuration (no autoconf): + + #define EV_STANDALONE 1 + #include "ev.c" + +This will automatically include F, 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 in all files wishing to use this API (best +done by writing a wrapper around F 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 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, and: + + #include "event.h" + +in the files that want to use the libevent API. This also includes F. + +You need the following additional files for this: + + event.h + event.c + +=head3 AUTOCONF SUPPORT + +Instead of using C and providing your config in +whatever way you want, you can also C in your +F and leave C off. F will then include +F 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, 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 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 +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 by C and will not normally affect correctness. See tzhe note about libraries +in the description of C, though. + +=item EV_USE_SELECT + +If undefined or defined to be C<1>, libev will compile in support for the +C