--- libev/ev.pod 2007/12/12 04:53:58 1.81 +++ 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 @@ -935,6 +946,8 @@ optimisations to libev. +=head3 Watcher-Specific Functions + =over 4 =item ev_io_init (ev_io *, callback, int fd, int events) @@ -997,6 +1010,8 @@ but if multiple timers become ready during the same loop iteration then order of execution is undefined. +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) @@ -1111,6 +1126,8 @@ time (C) has been passed, but if multiple periodic timers become ready during the same loop iteration then order of execution is undefined. +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) @@ -1216,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 @@ -1266,6 +1288,8 @@ watcher for a signal is stopped libev will reset the signal handler to SIG_DFL (regardless of what it was set to before). +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_signal_init (ev_signal *, callback, int signum) @@ -1287,6 +1311,8 @@ Child watchers trigger when your process receives a SIGCHLD in response to some child status changes (most typically when a child of yours dies). +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_child_init (ev_child *, callback, int pid) @@ -1364,6 +1390,8 @@ usually detected immediately, and if the file exists there will be no polling. +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) @@ -1455,6 +1483,8 @@ "pseudo-background processing", or delay processing stuff to after the event loop has handled all outstanding events. +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_idle_init (ev_signal *, callback) @@ -1531,6 +1561,8 @@ C watcher ran (always remind yourself to coexist peacefully with others). +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_prepare_init (ev_prepare *, callback) @@ -1741,6 +1773,8 @@ else loop_lo = loop_hi; +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) @@ -1759,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. @@ -1776,6 +1810,8 @@ C cheats and calls it in the wrong process, the fork handlers will be invoked, too, of course. +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_fork_init (ev_signal *, callback) @@ -2001,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. @@ -2040,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: @@ -2106,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). @@ -2216,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 @@ -2411,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