X-Git-Url: https://git.llucax.com/software/libev.git/blobdiff_plain/4422091b9b8967efdcfea8f650321595a8d95a98..bd14babf134e551f28f49193bf20705933c772c8:/ev.3

diff --git a/ev.3 b/ev.3
index 4cddbe3..6c36997 100644
--- a/ev.3
+++ b/ev.3
@@ -134,9 +134,65 @@
 libev \- a high performance full\-featured event loop written in C
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
-.Vb 1
+.Vb 2
+\&  /* this is the only header you need */
 \&  #include <ev.h>
 .Ve
+.PP
+.Vb 3
+\&  /* what follows is a fully working example program */
+\&  ev_io stdin_watcher;
+\&  ev_timer timeout_watcher;
+.Ve
+.PP
+.Vb 8
+\&  /* called when data readable on stdin */
+\&  static void
+\&  stdin_cb (EV_P_ struct ev_io *w, int revents)
+\&  {
+\&    /* puts ("stdin ready"); */
+\&    ev_io_stop (EV_A_ w); /* just a syntax example */
+\&    ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
+\&  }
+.Ve
+.PP
+.Vb 6
+\&  static void
+\&  timeout_cb (EV_P_ struct ev_timer *w, int revents)
+\&  {
+\&    /* puts ("timeout"); */
+\&    ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
+\&  }
+.Ve
+.PP
+.Vb 4
+\&  int
+\&  main (void)
+\&  {
+\&    struct ev_loop *loop = ev_default_loop (0);
+.Ve
+.PP
+.Vb 3
+\&    /* initialise an io watcher, then start it */
+\&    ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
+\&    ev_io_start (loop, &stdin_watcher);
+.Ve
+.PP
+.Vb 3
+\&    /* simple non-repeating 5.5 second timeout */
+\&    ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
+\&    ev_timer_start (loop, &timeout_watcher);
+.Ve
+.PP
+.Vb 2
+\&    /* loop till timeout or data ready */
+\&    ev_loop (loop, 0);
+.Ve
+.PP
+.Vb 2
+\&    return 0;
+\&  }
+.Ve
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 Libev is an event loop: you register interest in certain events (such as a
@@ -242,13 +298,13 @@ might be supported on the current system, you would need to look at
 recommended ones.
 .Sp
 See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
-.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4
-.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))"
-Sets the allocation function to use (the prototype is similar to the
-realloc C function, the semantics are identical). It is used to allocate
-and free memory (no surprises here). If it returns zero when memory
-needs to be allocated, the library might abort or take some potentially
-destructive action. The default is your system realloc function.
+.IP "ev_set_allocator (void *(*cb)(void *ptr, size_t size))" 4
+.IX Item "ev_set_allocator (void *(*cb)(void *ptr, size_t size))"
+Sets the allocation function to use (the prototype and semantics are
+identical to the realloc C function). It is used to allocate and free
+memory (no surprises here). If it returns zero when memory needs to be
+allocated, the library might abort or take some potentially destructive
+action. The default is your system realloc function.
 .Sp
 You could override this function in high-availability programs to, say,
 free some memory if it cannot allocate memory, to use a special allocator,
@@ -259,7 +315,7 @@ retries: better than mine).
 .Sp
 .Vb 6
 \&   static void *
-\&   persistent_realloc (void *ptr, long size)
+\&   persistent_realloc (void *ptr, size_t size)
 \&   {
 \&     for (;;)
 \&       {
@@ -709,6 +765,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).
+.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"
@@ -1615,6 +1680,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.
+.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.
@@ -1763,6 +1843,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.
+.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
@@ -1790,6 +1874,71 @@ the constructor.
 \&    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
@@ -2018,11 +2167,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.
+.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_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