X-Git-Url: https://git.llucax.com/software/libev.git/blobdiff_plain/9c4448f04bc46d81f795177671dfedd546e08725..bd14babf134e551f28f49193bf20705933c772c8:/ev.pod diff --git a/ev.pod b/ev.pod index 687a53d..43db80f 100644 --- a/ev.pod +++ b/ev.pod @@ -4,8 +4,48 @@ libev - a high performance full-featured event loop written in C =head1 SYNOPSIS + /* this is the only header you need */ #include + /* what follows is a fully working example program */ + ev_io stdin_watcher; + ev_timer timeout_watcher; + + /* 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 */ + } + + static void + timeout_cb (EV_P_ struct ev_timer *w, int revents) + { + /* puts ("timeout"); */ + ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */ + } + + int + main (void) + { + struct ev_loop *loop = ev_default_loop (0); + + /* 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); + + /* simple non-repeating 5.5 second timeout */ + ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); + ev_timer_start (loop, &timeout_watcher); + + /* loop till timeout or data ready */ + ev_loop (loop, 0); + + return 0; + } + =head1 DESCRIPTION Libev is an event loop: you register interest in certain events (such as a @@ -50,7 +90,6 @@ 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. - =head1 GLOBAL FUNCTIONS These functions can be called anytime, even before initialising the @@ -118,13 +157,13 @@ recommended ones. See the description of C watchers for more info. -=item ev_set_allocator (void *(*cb)(void *ptr, long size)) +=item ev_set_allocator (void *(*cb)(void *ptr, size_t 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. +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. You could override this function in high-availability programs to, say, free some memory if it cannot allocate memory, to use a special allocator, @@ -134,7 +173,7 @@ Example: replace the libev allocator with one that waits a bit and then retries: better than mine). static void * - persistent_realloc (void *ptr, long size) + persistent_realloc (void *ptr, size_t size) { for (;;) { @@ -567,6 +606,15 @@ many watchers as they want, and all of them will be taken into account (for example, a C watcher might start an idle watcher to keep C from blocking). +=item C + +The embedded event loop specified in the C watcher needs attention. + +=item C + +The event loop has been resumed in the child process after fork (see +C). + =item C An unspecified error has occured, the watcher has been stopped. This might @@ -1472,6 +1520,27 @@ The embedded event loop. =back +=head2 C - the audacity to resume the event loop after a fork + +Fork watchers are called when a C was detected (usually because +whoever is a good citizen cared to tell libev about it by calling +C or C). The invocation is done before the +event loop blocks next and before C watchers are being called, +and only in the child after the fork. If whoever good citizen calling +C cheats and calls it in the wrong process, the fork +handlers will be invoked, too, of course. + +=over 4 + +=item ev_fork_init (ev_signal *, callback) + +Initialises and configures the fork watcher - it has no parameters of any +kind. There is a C macro, but using it is utterly pointless, +believe me. + +=back + + =head1 OTHER FUNCTIONS There are some other functions of possible interest. Described. Here. Now. @@ -1666,6 +1735,68 @@ the constructor. io.start (fd, ev::READ); } + +=head1 MACRO MAGIC + +Libev can be compiled with a variety of options, the most fundemantal is +C. This option determines wether (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: + +=over 4 + +=item C, C + +This provides the loop I for functions, if one is required ("ev +loop argument"). The C form is used when this is the sole argument, +C is used when other arguments are following. Example: + + ev_unref (EV_A); + ev_timer_add (EV_A_ watcher); + ev_loop (EV_A_ 0); + +It assumes the variable C of type C is in scope, +which is often provided by the following macro. + +=item C, C + +This provides the loop I for functions, if one is required ("ev +loop parameter"). The C form is used when this is the sole parameter, +C is used when other parameters are following. Example: + + // this is how ev_unref is being declared + static void ev_unref (EV_P); + + // this is how you can declare your typical callback + static void cb (EV_P_ ev_timer *w, int revents) + +It declares a parameter C of type C, quite +suitable for use with C. + +=item C, C + +Similar to the other two macros, this gives you the value of the default +loop, if multiple loops are supported ("ev loop default"). + +=back + +Example: Declare and initialise a check watcher, working regardless of +wether multiple loops are supported or not. + + static void + check_cb (EV_P_ ev_timer *w, int revents) + { + ev_check_stop (EV_A_ w); + } + + ev_check check; + ev_check_init (&check, check_cb); + ev_check_start (EV_DEFAULT_ &check); + ev_loop (EV_DEFAULT_ 0); + + =head1 EMBEDDING Libev can (and often is) directly embedded into host @@ -1897,12 +2028,24 @@ defined to be C<0>, then they are not. If undefined or defined to be C<1>, then stat watchers are supported. If defined to be C<0>, then they are not. +=item EV_FORK_ENABLE + +If undefined or defined to be C<1>, then fork watchers are supported. If +defined to be C<0>, then they are not. + =item EV_MINIMAL If you need to shave off some kilobytes of code at the expense of some speed, define this symbol to C<1>. Currently only used for gcc to override some inlining decisions, saves roughly 30% codesize of amd64. +=item EV_PID_HASHSIZE + +C watchers use a small hash table to distribute workload by +pid. The default size is C<16> (or C<1> with C), usually more +than enough. If you need to manage thousands of children you might want to +increase this value. + =item EV_COMMON By default, all watchers have a C member. By redefining