X-Git-Url: https://git.llucax.com/software/libev.git/blobdiff_plain/3360a3869a421bc12a57dcd0a9450ef5ee8a11ec..b3c85cba31a5669ce3e1995d8660542354957a53:/ev.3 diff --git a/ev.3 b/ev.3 index d1a417a..a7805ec 100644 --- a/ev.3 +++ b/ev.3 @@ -128,8 +128,8 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title """ 1" -.TH "" 1 "2007-12-12" "perl v5.8.8" "User Contributed Perl Documentation" +.IX Title "EV 1" +.TH EV 1 "2007-12-19" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" libev \- a high performance full\-featured event loop written in C .SH "SYNOPSIS" @@ -245,7 +245,9 @@ Libev represents time as a single floating point number, representing the the beginning of 1970, details are complicated, don't ask). This type is called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use too. It usually aliases to the \f(CW\*(C`double\*(C'\fR 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 \f(CW\*(C`stamp\*(C'\fR might indicate, it is also used for time differences +throughout libev. .SH "GLOBAL FUNCTIONS" .IX Header "GLOBAL FUNCTIONS" These functions can be called anytime, even before initialising the @@ -557,8 +559,17 @@ etc.). None of the active event watchers will be stopped in the normal sense, so e.g. \f(CW\*(C`ev_is_active\*(C'\fR might still return true. It is your responsibility to either stop all watchers cleanly yoursef \fIbefore\fR calling this function, or cope with the fact afterwards (which is usually -the easiest thing, youc na just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them +the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them for example). +.Sp +Not 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. +.Sp +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 +\&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR). .IP "ev_loop_destroy (loop)" 4 .IX Item "ev_loop_destroy (loop)" Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an @@ -1381,6 +1392,10 @@ called. The current reschedule callback, or \f(CW0\fR, if this functionality is switched off. Can be changed any time, but changes only take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. +.IP "ev_tstamp at [read\-only]" 4 +.IX Item "ev_tstamp at [read-only]" +When active, contains the absolute time that the watcher is supposed to +trigger next. .PP Example: Call a callback every hour, or, more precisely, whenever the system clock is divisible by 3600. The callback invocation times have @@ -1995,6 +2010,9 @@ event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being and only in the child after the fork. If whoever good citizen calling \&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork handlers will be invoked, too, of course. +.PP +\fIWatcher-Specific Functions and Data Members\fR +.IX Subsection "Watcher-Specific Functions and Data Members" .IP "ev_fork_init (ev_signal *, callback)" 4 .IX Item "ev_fork_init (ev_signal *, callback)" Initialises and configures the fork watcher \- it has no parameters of any @@ -2198,18 +2216,18 @@ constructor already stores the event loop. .IP "w\->stop ()" 4 .IX Item "w->stop ()" Stops the watcher if it is active. Again, no \f(CW\*(C`loop\*(C'\fR argument. -.ie n .IP "w\->again () ""ev::timer""\fR, \f(CW""ev::periodic"" only" 4 -.el .IP "w\->again () \f(CWev::timer\fR, \f(CWev::periodic\fR only" 4 -.IX Item "w->again () ev::timer, ev::periodic only" +.ie n .IP "w\->again () (""ev::timer""\fR, \f(CW""ev::periodic"" only)" 4 +.el .IP "w\->again () (\f(CWev::timer\fR, \f(CWev::periodic\fR only)" 4 +.IX Item "w->again () (ev::timer, ev::periodic only)" For \f(CW\*(C`ev::timer\*(C'\fR and \f(CW\*(C`ev::periodic\*(C'\fR, this invokes the corresponding \&\f(CW\*(C`ev_TYPE_again\*(C'\fR function. -.ie n .IP "w\->sweep () ""ev::embed"" only" 4 -.el .IP "w\->sweep () \f(CWev::embed\fR only" 4 -.IX Item "w->sweep () ev::embed only" +.ie n .IP "w\->sweep () (""ev::embed"" only)" 4 +.el .IP "w\->sweep () (\f(CWev::embed\fR only)" 4 +.IX Item "w->sweep () (ev::embed only)" Invokes \f(CW\*(C`ev_embed_sweep\*(C'\fR. -.ie n .IP "w\->update () ""ev::stat"" only" 4 -.el .IP "w\->update () \f(CWev::stat\fR only" 4 -.IX Item "w->update () ev::stat only" +.ie n .IP "w\->update () (""ev::stat"" only)" 4 +.el .IP "w\->update () (\f(CWev::stat\fR only)" 4 +.IX Item "w->update () (ev::stat only)" Invokes \f(CW\*(C`ev_stat_stat\*(C'\fR. .RE .RS 4 @@ -2243,9 +2261,9 @@ the constructor. .Ve .SH "MACRO MAGIC" .IX Header "MACRO MAGIC" -Libev can be compiled with a variety of options, the most fundemantal is -\&\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) functions and -callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. +Libev can be compiled with a variety of options, the most fundamantal +of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) +functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. .PP To make it easier to write programs that cope with either variant, the following macros are defined: @@ -2613,6 +2631,36 @@ definition and a statement, respectively. See the \fIev.v\fR header file for their default definitions. One possible use for overriding these is to avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use method calls instead of plain function calls in \*(C+. +.Sh "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0" +.IX Subsection "EXPORTED API SYMBOLS" +If you need to re-export the \s-1API\s0 (e.g. via a dll) and you need a list of +exported symbols, you can use the provided \fISymbol.*\fR files which list +all public symbols, one per line: +.Sp +.Vb 2 +\& Symbols.ev for libev proper +\& Symbols.event for the libevent emulation +.Ve +.Sp +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). +.Sp +A sed comamnd like this will create wrapper \f(CW\*(C`#define\*(C'\fR's that you need to +include before including \fIev.h\fR: +.Sp +.Vb 1 +\& wrap.h +.Ve +.Sp +This would create a file \fIwrap.h\fR which essentially looks like this: +.Sp +.Vb 4 +\& #define ev_backend myprefix_ev_backend +\& #define ev_check_start myprefix_ev_check_start +\& #define ev_check_stop myprefix_ev_check_stop +\& ... +.Ve .Sh "\s-1EXAMPLES\s0" .IX Subsection "EXAMPLES" For a real-world example of a program the includes libev