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

diff --git a/ev.3 b/ev.3
index 01e5c65..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 (;;)
 \&       {
@@ -2120,6 +2176,12 @@ defined to be \f(CW0\fR, then they are not.
 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