--- libev/ev.pod 2007/12/12 17:55:31 1.83 +++ libev/ev.pod 2007/12/20 07:12:57 1.91 @@ -100,7 +100,9 @@ the beginning of 1970, details are complicated, don't ask). This type is called C, which is what you should use too. It usually aliases to the C type in C, and when you need to do any calculations on -it, you should treat it as such. +it, you should treat it as some floatingpoint value. Unlike the name +component C might indicate, it is also used for time differences +throughout libev. =head1 GLOBAL FUNCTIONS @@ -331,8 +333,8 @@ Kqueue deserves special mention, as at the time of this writing, it was broken on all BSDs except NetBSD (usually it doesn't work with -anything but sockets and pipes, except on Darwin, where of course its -completely useless). For this reason its not being "autodetected" +anything but sockets and pipes, except on Darwin, where of course it's +completely useless). For this reason it's not being "autodetected" unless you explicitly specify it explicitly in the flags (i.e. using C). @@ -404,9 +406,18 @@ 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 +the easiest thing, you can just ignore the watchers and/or C them for example). +Note that certain global state, such as signal state, will not be freed by +this function, and related watchers (such as signal and child watchers) +would need to be stopped manually. + +In general it is not advisable to call this function except in the +rare occasion where you really need to free e.g. the signal handling +pipe fds. If you need dynamically allocated loops it is better to use +C and C). + =item ev_loop_destroy (loop) Like C, but destroys an event loop created by an @@ -1222,6 +1233,11 @@ switched off. Can be changed any time, but changes only take effect when the periodic timer fires or C is being called. +=item ev_tstamp at [read-only] + +When active, contains the absolute time that the watcher is supposed to +trigger next. + =back Example: Call a callback every hour, or, more precisely, whenever the @@ -1777,7 +1793,7 @@ similarly to C, but in the most apropriate way for embedded loops. -=item struct ev_loop *loop [read-only] +=item struct ev_loop *other [read-only] The embedded event loop. @@ -2021,16 +2037,16 @@ Stops the watcher if it is active. Again, no C argument. -=item w->again () C, C only +=item w->again () (C, C only) For C and C, this invokes the corresponding C function. -=item w->sweep () C only +=item w->sweep () (C only) Invokes C. -=item w->update () C only +=item w->update () (C only) Invokes C. @@ -2060,9 +2076,9 @@ =head1 MACRO MAGIC -Libev can be compiled with a variety of options, the most fundemantal is -C. This option determines whether (most) functions and -callbacks have an initial C argument. +Libev can be compiled with a variety of options, the most fundamantal +of which is C. This option determines whether (most) +functions and callbacks have an initial C argument. To make it easier to write programs that cope with either variant, the following macros are defined: @@ -2126,7 +2142,7 @@ 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 +The goal is to enable you to just copy the necessary 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). @@ -2236,8 +2252,8 @@ 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. +(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the +note about libraries in the description of C, though. =item EV_USE_SELECT @@ -2431,6 +2447,31 @@ avoid the C as first argument in all cases, or to use method calls instead of plain function calls in C++. +=head2 EXPORTED API SYMBOLS + +If you need to re-export the API (e.g. via a dll) and you need a list of +exported symbols, you can use the provided F files which list +all public symbols, one per line: + + Symbols.ev for libev proper + Symbols.event for the libevent emulation + +This can also be used to rename all public symbols to avoid clashes with +multiple versions of libev linked together (which is obviously bad in +itself, but sometimes it is inconvinient to avoid this). + +A sed comamnd like this will create wrapper C<#define>'s that you need to +include before including F: + + wrap.h + +This would create a file F which essentially looks like this: + + #define ev_backend myprefix_ev_backend + #define ev_check_start myprefix_ev_check_start + #define ev_check_stop myprefix_ev_check_stop + ... + =head2 EXAMPLES For a real-world example of a program the includes libev