*** empty log message ***

[software/libev.git] / ev.3

diff --git a/ev.3 b/ev.3
index 4cddbe395d798227975bbc681dddd50e28d3924c..d718a09ff67dabad5e108b5f0dd3956da3279786 100644 (file)
--- a/ev.3
+++ b/ev.3
@@ -709,6 +709,15 @@ received events. Callbacks of both watcher types can start and stop as
 many watchers as they want, and all of them will be taken into account
 (for example, a \f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep
 \&\f(CW\*(C`ev_loop\*(C'\fR from blocking).
 many watchers as they want, and all of them will be taken into account
 (for example, a \f(CW\*(C`ev_prepare\*(C'\fR watcher might start an idle watcher to keep
 \&\f(CW\*(C`ev_loop\*(C'\fR from blocking).

+.ie n .IP """EV_EMBED""" 4
+.el .IP "\f(CWEV_EMBED\fR" 4
+.IX Item "EV_EMBED"
+The embedded event loop specified in the \f(CW\*(C`ev_embed\*(C'\fR watcher needs attention.
+.ie n .IP """EV_FORK""" 4
+.el .IP "\f(CWEV_FORK\fR" 4
+.IX Item "EV_FORK"
+The event loop has been resumed in the child process after fork (see
+\&\f(CW\*(C`ev_fork\*(C'\fR).

 .ie n .IP """EV_ERROR""" 4
 .el .IP "\f(CWEV_ERROR\fR" 4
 .IX Item "EV_ERROR"
 .ie n .IP """EV_ERROR""" 4
 .el .IP "\f(CWEV_ERROR\fR" 4
 .IX Item "EV_ERROR"


@@ -1615,6 +1624,21 @@ apropriate way for embedded loops.
 .IP "struct ev_loop *loop [read\-only]" 4
 .IX Item "struct ev_loop *loop [read-only]"
 The embedded event loop.
 .IP "struct ev_loop *loop [read\-only]" 4
 .IX Item "struct ev_loop *loop [read-only]"
 The embedded event loop.

+.ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork"
+.el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork"
+.IX Subsection "ev_fork - the audacity to resume the event loop after a fork"
+Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
+whoever is a good citizen cared to tell libev about it by calling
+\&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the
+event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called,
+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.
+.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
+kind. There is a \f(CW\*(C`ev_fork_set\*(C'\fR macro, but using it is utterly pointless,
+believe me.

 .SH "OTHER FUNCTIONS"
 .IX Header "OTHER FUNCTIONS"
 There are some other functions of possible interest. Described. Here. Now.
 .SH "OTHER FUNCTIONS"
 .IX Header "OTHER FUNCTIONS"
 There are some other functions of possible interest. Described. Here. Now.


@@ -1763,6 +1787,10 @@ For \f(CW\*(C`ev::timer\*(C'\fR and \f(CW\*(C`ev::periodic\*(C'\fR, this invokes
 .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.
 .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"
+Invokes \f(CW\*(C`ev_stat_stat\*(C'\fR.

 .RE
 .RS 4
 .RE
 .RE
 .RS 4
 .RE


@@ -1790,6 +1818,71 @@ the constructor.
 \&    io.start (fd, ev::READ);
 \&  }
 .Ve
 \&    io.start (fd, ev::READ);
 \&  }
 .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 wether (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:
+.ie n .IP """EV_A""\fR, \f(CW""EV_A_""" 4
+.el .IP "\f(CWEV_A\fR, \f(CWEV_A_\fR" 4
+.IX Item "EV_A, EV_A_"
+This provides the loop \fIargument\fR for functions, if one is required (\*(L"ev
+loop argument\*(R"). The \f(CW\*(C`EV_A\*(C'\fR form is used when this is the sole argument,
+\&\f(CW\*(C`EV_A_\*(C'\fR is used when other arguments are following. Example:
+.Sp
+.Vb 3
+\&  ev_unref (EV_A);
+\&  ev_timer_add (EV_A_ watcher);
+\&  ev_loop (EV_A_ 0);
+.Ve
+.Sp
+It assumes the variable \f(CW\*(C`loop\*(C'\fR of type \f(CW\*(C`struct ev_loop *\*(C'\fR is in scope,
+which is often provided by the following macro.
+.ie n .IP """EV_P""\fR, \f(CW""EV_P_""" 4
+.el .IP "\f(CWEV_P\fR, \f(CWEV_P_\fR" 4
+.IX Item "EV_P, EV_P_"
+This provides the loop \fIparameter\fR for functions, if one is required (\*(L"ev
+loop parameter\*(R"). The \f(CW\*(C`EV_P\*(C'\fR form is used when this is the sole parameter,
+\&\f(CW\*(C`EV_P_\*(C'\fR is used when other parameters are following. Example:
+.Sp
+.Vb 2
+\&  // this is how ev_unref is being declared
+\&  static void ev_unref (EV_P);
+.Ve
+.Sp
+.Vb 2
+\&  // this is how you can declare your typical callback
+\&  static void cb (EV_P_ ev_timer *w, int revents)
+.Ve
+.Sp
+It declares a parameter \f(CW\*(C`loop\*(C'\fR of type \f(CW\*(C`struct ev_loop *\*(C'\fR, quite
+suitable for use with \f(CW\*(C`EV_A\*(C'\fR.
+.ie n .IP """EV_DEFAULT""\fR, \f(CW""EV_DEFAULT_""" 4
+.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
+.IX Item "EV_DEFAULT, EV_DEFAULT_"
+Similar to the other two macros, this gives you the value of the default
+loop, if multiple loops are supported (\*(L"ev loop default\*(R").
+.PP
+Example: Declare and initialise a check watcher, working regardless of
+wether multiple loops are supported or not.
+.PP
+.Vb 5
+\&  static void
+\&  check_cb (EV_P_ ev_timer *w, int revents)
+\&  {
+\&    ev_check_stop (EV_A_ w);
+\&  }
+.Ve
+.PP
+.Vb 4
+\&  ev_check check;
+\&  ev_check_init (&check, check_cb);
+\&  ev_check_start (EV_DEFAULT_ &check);
+\&  ev_loop (EV_DEFAULT_ 0);
+.Ve

 .SH "EMBEDDING"
 .IX Header "EMBEDDING"
 Libev can (and often is) directly embedded into host
 .SH "EMBEDDING"
 .IX Header "EMBEDDING"
 Libev can (and often is) directly embedded into host


@@ -2018,11 +2111,21 @@ defined to be \f(CW0\fR, then they are not.
 .IX Item "EV_STAT_ENABLE"
 If undefined or defined to be \f(CW1\fR, then stat watchers are supported. If
 defined to be \f(CW0\fR, then they are not.
 .IX Item "EV_STAT_ENABLE"
 If undefined or defined to be \f(CW1\fR, then stat watchers are supported. If
 defined to be \f(CW0\fR, then they are not.

+.IP "\s-1EV_FORK_ENABLE\s0" 4
+.IX Item "EV_FORK_ENABLE"
+If undefined or defined to be \f(CW1\fR, then fork watchers are supported. If
+defined to be \f(CW0\fR, then they are not.

 .IP "\s-1EV_MINIMAL\s0" 4
 .IX Item "EV_MINIMAL"
 If you need to shave off some kilobytes of code at the expense of some
 speed, define this symbol to \f(CW1\fR. Currently only used for gcc to override
 some inlining decisions, saves roughly 30% codesize of amd64.
 .IP "\s-1EV_MINIMAL\s0" 4
 .IX Item "EV_MINIMAL"
 If you need to shave off some kilobytes of code at the expense of some
 speed, define this symbol to \f(CW1\fR. Currently only used for gcc to override
 some inlining decisions, saves roughly 30% codesize of amd64.

+.IP "\s-1EV_PID_HASHSIZE\s0" 4
+.IX Item "EV_PID_HASHSIZE"
+\&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by
+pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more
+than enough. If you need to manage thousands of children you might want to
+increase this value.

 .IP "\s-1EV_COMMON\s0" 4
 .IX Item "EV_COMMON"
 By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
 .IP "\s-1EV_COMMON\s0" 4
 .IX Item "EV_COMMON"
 By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining