diff options
Diffstat (limited to 'ev.3')
| -rw-r--r-- | ev.3 | 891 |
1 files changed, 891 insertions, 0 deletions
@@ -0,0 +1,891 @@ +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.35 +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' +.\" expand to `' in nroff, nothing in troff, for use with C<>. +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title ""<STANDARD INPUT>" 1" +.TH "<STANDARD INPUT>" 1 "2007-11-13" "perl v5.8.8" "User Contributed Perl Documentation" +.SH "NAME" +libev \- a high performance full\-featured event loop written in C +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <ev.h> +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Libev is an event loop: you register interest in certain events (such as a +file descriptor being readable or a timeout occuring), and it will manage +these event sources and provide your program with events. +.PP +To do this, it must take more or less complete control over your process +(or thread) by executing the \fIevent loop\fR handler, and will then +communicate events via a callback mechanism. +.PP +You register interest in certain events by registering so-called \fIevent +watchers\fR, which are relatively small C structures you initialise with the +details of the event, and then hand it over to libev by \fIstarting\fR the +watcher. +.SH "FEATURES" +.IX Header "FEATURES" +Libev supports select, poll, the linux-specific epoll and the bsd-specific +kqueue mechanisms for file descriptor events, relative timers, absolute +timers with customised rescheduling, signal events, process status change +events (related to \s-1SIGCHLD\s0), and event watchers dealing with the event +loop mechanism itself (idle, prepare and check watchers). It also is quite +fast (see this benchmark comparing +it to libevent for example). +.SH "CONVENTIONS" +.IX Header "CONVENTIONS" +Libev is very configurable. In this manual the default configuration +will be described, which supports multiple event loops. For more info +about various configuration options please have a look at the file +\&\fI\s-1README\s0.embed\fR in the libev distribution. If libev was configured without +support for multiple event loops, then all functions taking an initial +argument of name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) +will not have this argument. +.SH "TIME REPRESENTATION" +.IX Header "TIME REPRESENTATION" +Libev represents time as a single floating point number, representing the +(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near +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 double type in C. +.SH "GLOBAL FUNCTIONS" +.IX Header "GLOBAL FUNCTIONS" +These functions can be called anytime, even before initialising the +library in any way. +.IP "ev_tstamp ev_time ()" 4 +.IX Item "ev_tstamp ev_time ()" +Returns the current time as libev would use it. +.IP "int ev_version_major ()" 4 +.IX Item "int ev_version_major ()" +.PD 0 +.IP "int ev_version_minor ()" 4 +.IX Item "int ev_version_minor ()" +.PD +You can find out the major and minor version numbers of the library +you linked against by calling the functions \f(CW\*(C`ev_version_major\*(C'\fR and +\&\f(CW\*(C`ev_version_minor\*(C'\fR. If you want, you can compare against the global +symbols \f(CW\*(C`EV_VERSION_MAJOR\*(C'\fR and \f(CW\*(C`EV_VERSION_MINOR\*(C'\fR, which specify the +version of the library your program was compiled against. +.Sp +Usually, it's a good idea to terminate if the major versions mismatch, +as this indicates an incompatible change. Minor versions are usually +compatible to older versions, so a larger minor version alone is usually +not a problem. +.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. +.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, +or even to sleep a while and retry until some memory is available. +.IP "ev_set_syserr_cb (void (*cb)(const char *msg));" 4 +.IX Item "ev_set_syserr_cb (void (*cb)(const char *msg));" +Set the callback function to call on a retryable syscall error (such +as failed select, poll, epoll_wait). The message is a printable string +indicating the system call or subsystem causing the problem. If this +callback is set, then libev will expect it to remedy the sitution, no +matter what, when it returns. That is, libev will generally retry the +requested operation, or, if the condition doesn't go away, do bad stuff +(such as abort). +.SH "FUNCTIONS CONTROLLING THE EVENT LOOP" +.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" +An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two +types of such loops, the \fIdefault\fR loop, which supports signals and child +events, and dynamically created loops which do not. +.PP +If you use threads, a common model is to run the default event loop +in your main thread (or in a separate thread) and for each thread you +create, you also create another event loop. Libev itself does no locking +whatsoever, so if you mix calls to the same event loop in different +threads, make sure you lock (this is usually a bad idea, though, even if +done correctly, because it's hideous and inefficient). +.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 +.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" +This will initialise the default event loop if it hasn't been initialised +yet and return it. If the default loop could not be initialised, returns +false. If it already was initialised it simply returns it (and ignores the +flags). +.Sp +If you don't know what event loop to use, use the one returned from this +function. +.Sp +The flags argument can be used to specify special behaviour or specific +backends to use, and is usually specified as 0 (or \s-1EVFLAG_AUTO\s0). +.Sp +It supports the following flags: +.RS 4 +.ie n .IP """EVFLAG_AUTO""" 4 +.el .IP "\f(CWEVFLAG_AUTO\fR" 4 +.IX Item "EVFLAG_AUTO" +The default flags value. Use this if you have no clue (it's the right +thing, believe me). +.ie n .IP """EVFLAG_NOENV""" 4 +.el .IP "\f(CWEVFLAG_NOENV\fR" 4 +.IX Item "EVFLAG_NOENV" +If this flag bit is ored into the flag value (or the program runs setuid +or setgid) then libev will \fInot\fR look at the environment variable +\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will +override the flags completely if it is found in the environment. This is +useful to try out specific backends to test their performance, or to work +around bugs. +.ie n .IP """EVMETHOD_SELECT"" (portable select backend)" 4 +.el .IP "\f(CWEVMETHOD_SELECT\fR (portable select backend)" 4 +.IX Item "EVMETHOD_SELECT (portable select backend)" +.PD 0 +.ie n .IP """EVMETHOD_POLL"" (poll backend, available everywhere except on windows)" 4 +.el .IP "\f(CWEVMETHOD_POLL\fR (poll backend, available everywhere except on windows)" 4 +.IX Item "EVMETHOD_POLL (poll backend, available everywhere except on windows)" +.ie n .IP """EVMETHOD_EPOLL"" (linux only)" 4 +.el .IP "\f(CWEVMETHOD_EPOLL\fR (linux only)" 4 +.IX Item "EVMETHOD_EPOLL (linux only)" +.ie n .IP """EVMETHOD_KQUEUE"" (some bsds only)" 4 +.el .IP "\f(CWEVMETHOD_KQUEUE\fR (some bsds only)" 4 +.IX Item "EVMETHOD_KQUEUE (some bsds only)" +.ie n .IP """EVMETHOD_DEVPOLL"" (solaris 8 only)" 4 +.el .IP "\f(CWEVMETHOD_DEVPOLL\fR (solaris 8 only)" 4 +.IX Item "EVMETHOD_DEVPOLL (solaris 8 only)" +.ie n .IP """EVMETHOD_PORT"" (solaris 10 only)" 4 +.el .IP "\f(CWEVMETHOD_PORT\fR (solaris 10 only)" 4 +.IX Item "EVMETHOD_PORT (solaris 10 only)" +.PD +If one or more of these are ored into the flags value, then only these +backends will be tried (in the reverse order as given here). If one are +specified, any backend will do. +.RE +.RS 4 +.RE +.IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4 +.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" +Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is +always distinct from the default loop. Unlike the default loop, it cannot +handle signal and child watchers, and attempts to do so will be greeted by +undefined behaviour (or a failed assertion if assertions are enabled). +.IP "ev_default_destroy ()" 4 +.IX Item "ev_default_destroy ()" +Destroys the default loop again (frees all memory and kernel state +etc.). This stops all registered event watchers (by not touching them in +any way whatsoever, although you cannot rely on this :). +.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 +earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. +.IP "ev_default_fork ()" 4 +.IX Item "ev_default_fork ()" +This function reinitialises the kernel state for backends that have +one. Despite the name, you can call it anytime, but it makes most sense +after forking, in either the parent or child process (or both, but that +again makes little sense). +.Sp +You \fImust\fR call this function after forking if and only if you want to +use the event library in both processes. If you just fork+exec, you don't +have to call it. +.Sp +The function itself is quite fast and it's usually not a problem to call +it just in case after a fork. To make this easy, the function will fit in +quite nicely into a call to \f(CW\*(C`pthread_atfork\*(C'\fR: +.Sp +.Vb 1 +\& pthread_atfork (0, 0, ev_default_fork); +.Ve +.IP "ev_loop_fork (loop)" 4 +.IX Item "ev_loop_fork (loop)" +Like \f(CW\*(C`ev_default_fork\*(C'\fR, but acts on an event loop created by +\&\f(CW\*(C`ev_loop_new\*(C'\fR. Yes, you have to call this on every allocated event loop +after fork, and how you do this is entirely your own problem. +.IP "unsigned int ev_method (loop)" 4 +.IX Item "unsigned int ev_method (loop)" +Returns one of the \f(CW\*(C`EVMETHOD_*\*(C'\fR flags indicating the event backend in +use. +.IP "ev_tstamp ev_now (loop)" 4 +.IX Item "ev_tstamp ev_now (loop)" +Returns the current \*(L"event loop time\*(R", which is the time the event loop +got events and started processing them. This timestamp does not change +as long as callbacks are being processed, and this is also the base time +used for relative timers. You can treat it as the timestamp of the event +occuring (or more correctly, the mainloop finding out about it). +.IP "ev_loop (loop, int flags)" 4 +.IX Item "ev_loop (loop, int flags)" +Finally, this is it, the event handler. This function usually is called +after you initialised all your watchers and you want to start handling +events. +.Sp +If the flags argument is specified as 0, it will not return until either +no event watchers are active anymore or \f(CW\*(C`ev_unloop\*(C'\fR was called. +.Sp +A flags value of \f(CW\*(C`EVLOOP_NONBLOCK\*(C'\fR will look for new events, will handle +those events and any outstanding ones, but will not block your process in +case there are no events and will return after one iteration of the loop. +.Sp +A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if +neccessary) and will handle those and any outstanding ones. It will block +your process until at least one new event arrives, and will return after +one iteration of the loop. +.Sp +This flags value could be used to implement alternative looping +constructs, but the \f(CW\*(C`prepare\*(C'\fR and \f(CW\*(C`check\*(C'\fR watchers provide a better and +more generic mechanism. +.IP "ev_unloop (loop, how)" 4 +.IX Item "ev_unloop (loop, how)" +Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it +has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either +\&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or +\&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return. +.IP "ev_ref (loop)" 4 +.IX Item "ev_ref (loop)" +.PD 0 +.IP "ev_unref (loop)" 4 +.IX Item "ev_unref (loop)" +.PD +Ref/unref can be used to add or remove a reference count on the event +loop: Every watcher keeps one reference, and as long as the reference +count is nonzero, \f(CW\*(C`ev_loop\*(C'\fR will not return on its own. If you have +a watcher you never unregister that should not keep \f(CW\*(C`ev_loop\*(C'\fR from +returning, \fIev_unref()\fR after starting, and \fIev_ref()\fR before stopping it. For +example, libev itself uses this for its internal signal pipe: It is not +visible to the libev user and should not keep \f(CW\*(C`ev_loop\*(C'\fR from exiting if +no event watchers registered by it are active. It is also an excellent +way to do this for generic recurring timers or from within third-party +libraries. Just remember to \fIunref after start\fR and \fIref before stop\fR. +.SH "ANATOMY OF A WATCHER" +.IX Header "ANATOMY OF A WATCHER" +A watcher is a structure that you create and register to record your +interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to +become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: +.PP +.Vb 5 +\& static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) +\& { +\& ev_io_stop (w); +\& ev_unloop (loop, EVUNLOOP_ALL); +\& } +.Ve +.PP +.Vb 6 +\& struct ev_loop *loop = ev_default_loop (0); +\& struct ev_io stdin_watcher; +\& ev_init (&stdin_watcher, my_cb); +\& ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); +\& ev_io_start (loop, &stdin_watcher); +\& ev_loop (loop, 0); +.Ve +.PP +As you can see, you are responsible for allocating the memory for your +watcher structures (and it is usually a bad idea to do this on the stack, +although this can sometimes be quite valid). +.PP +Each watcher structure must be initialised by a call to \f(CW\*(C`ev_init +(watcher *, callback)\*(C'\fR, which expects a callback to be provided. This +callback gets invoked each time the event occurs (or, in the case of io +watchers, each time the event loop detects that the file descriptor given +is readable and/or writable). +.PP +Each watcher type has its own \f(CW\*(C`ev_<type>_set (watcher *, ...)\*(C'\fR macro +with arguments specific to this watcher type. There is also a macro +to combine initialisation and setting in one call: \f(CW\*(C`ev_<type>_init +(watcher *, callback, ...)\*(C'\fR. +.PP +To make the watcher actually watch out for events, you have to start it +with a watcher-specific start function (\f(CW\*(C`ev_<type>_start (loop, watcher +*)\*(C'\fR), and you can stop watching for events at any time by calling the +corresponding stop function (\f(CW\*(C`ev_<type>_stop (loop, watcher *)\*(C'\fR. +.PP +As long as your watcher is active (has been started but not stopped) you +must not touch the values stored in it. Most specifically you must never +reinitialise it or call its set method. +.PP +You can check whether an event is active by calling the \f(CW\*(C`ev_is_active +(watcher *)\*(C'\fR macro. To see whether an event is outstanding (but the +callback for it has not been called yet) you can use the \f(CW\*(C`ev_is_pending +(watcher *)\*(C'\fR macro. +.PP +Each and every callback receives the event loop pointer as first, the +registered watcher structure as second, and a bitset of received events as +third argument. +.PP +The received events usually include a single bit per event type received +(you can receive multiple events at the same time). The possible bit masks +are: +.ie n .IP """EV_READ""" 4 +.el .IP "\f(CWEV_READ\fR" 4 +.IX Item "EV_READ" +.PD 0 +.ie n .IP """EV_WRITE""" 4 +.el .IP "\f(CWEV_WRITE\fR" 4 +.IX Item "EV_WRITE" +.PD +The file descriptor in the \f(CW\*(C`ev_io\*(C'\fR watcher has become readable and/or +writable. +.ie n .IP """EV_TIMEOUT""" 4 +.el .IP "\f(CWEV_TIMEOUT\fR" 4 +.IX Item "EV_TIMEOUT" +The \f(CW\*(C`ev_timer\*(C'\fR watcher has timed out. +.ie n .IP """EV_PERIODIC""" 4 +.el .IP "\f(CWEV_PERIODIC\fR" 4 +.IX Item "EV_PERIODIC" +The \f(CW\*(C`ev_periodic\*(C'\fR watcher has timed out. +.ie n .IP """EV_SIGNAL""" 4 +.el .IP "\f(CWEV_SIGNAL\fR" 4 +.IX Item "EV_SIGNAL" +The signal specified in the \f(CW\*(C`ev_signal\*(C'\fR watcher has been received by a thread. +.ie n .IP """EV_CHILD""" 4 +.el .IP "\f(CWEV_CHILD\fR" 4 +.IX Item "EV_CHILD" +The pid specified in the \f(CW\*(C`ev_child\*(C'\fR watcher has received a status change. +.ie n .IP """EV_IDLE""" 4 +.el .IP "\f(CWEV_IDLE\fR" 4 +.IX Item "EV_IDLE" +The \f(CW\*(C`ev_idle\*(C'\fR watcher has determined that you have nothing better to do. +.ie n .IP """EV_PREPARE""" 4 +.el .IP "\f(CWEV_PREPARE\fR" 4 +.IX Item "EV_PREPARE" +.PD 0 +.ie n .IP """EV_CHECK""" 4 +.el .IP "\f(CWEV_CHECK\fR" 4 +.IX Item "EV_CHECK" +.PD +All \f(CW\*(C`ev_prepare\*(C'\fR watchers are invoked just \fIbefore\fR \f(CW\*(C`ev_loop\*(C'\fR starts +to gather new events, and all \f(CW\*(C`ev_check\*(C'\fR watchers are invoked just after +\&\f(CW\*(C`ev_loop\*(C'\fR has gathered them, but before it invokes any callbacks for any +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_ERROR""" 4 +.el .IP "\f(CWEV_ERROR\fR" 4 +.IX Item "EV_ERROR" +An unspecified error has occured, the watcher has been stopped. This might +happen because the watcher could not be properly started because libev +ran out of memory, a file descriptor was found to be closed or any other +problem. You best act on it by reporting the problem and somehow coping +with the watcher being stopped. +.Sp +Libev will usually signal a few \*(L"dummy\*(R" events together with an error, +for example it might indicate that a fd is readable or writable, and if +your callbacks is well-written it can just attempt the operation and cope +with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multithreaded +programs, though, so beware. +.Sh "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" +.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" +Each watcher has, by default, a member \f(CW\*(C`void *data\*(C'\fR that you can change +and read at any time, libev will completely ignore it. This can be used +to associate arbitrary data with your watcher. If you need more data and +don't want to allocate memory and store a pointer to it in that data +member, you can also \*(L"subclass\*(R" the watcher type and provide your own +data: +.PP +.Vb 7 +\& struct my_io +\& { +\& struct ev_io io; +\& int otherfd; +\& void *somedata; +\& struct whatever *mostinteresting; +\& } +.Ve +.PP +And since your callback will be called with a pointer to the watcher, you +can cast it back to your own type: +.PP +.Vb 5 +\& static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) +\& { +\& struct my_io *w = (struct my_io *)w_; +\& ... +\& } +.Ve +.PP +More interesting and less C\-conformant ways of catsing your callback type +have been omitted.... +.SH "WATCHER TYPES" +.IX Header "WATCHER TYPES" +This section describes each watcher in detail, but will not repeat +information given in the last section. +.ie n .Sh """ev_io"" \- is this file descriptor readable or writable" +.el .Sh "\f(CWev_io\fP \- is this file descriptor readable or writable" +.IX Subsection "ev_io - is this file descriptor readable or writable" +I/O watchers check whether a file descriptor is readable or writable +in each iteration of the event loop (This behaviour is called +level-triggering because you keep receiving events as long as the +condition persists. Remember you can stop the watcher if you don't want to +act on the event and neither want to receive future events). +.PP +In general you can register as many read and/or write event watchers per +fd as you want (as long as you don't confuse yourself). Setting all file +descriptors to non-blocking mode is also usually a good idea (but not +required if you know what you are doing). +.PP +You have to be careful with dup'ed file descriptors, though. Some backends +(the linux epoll backend is a notable example) cannot handle dup'ed file +descriptors correctly if you register interest in two or more fds pointing +to the same underlying file/socket etc. description (that is, they share +the same underlying \*(L"file open\*(R"). +.PP +If you must do this, then force the use of a known-to-be-good backend +(at the time of this writing, this includes only \s-1EVMETHOD_SELECT\s0 and +\&\s-1EVMETHOD_POLL\s0). +.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 +.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" +.PD 0 +.IP "ev_io_set (ev_io *, int fd, int events)" 4 +.IX Item "ev_io_set (ev_io *, int fd, int events)" +.PD +Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The fd is the file descriptor to rceeive +events for and events is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_READ | +EV_WRITE\*(C'\fR to receive the given events. +.ie n .Sh """ev_timer"" \- relative and optionally recurring timeouts" +.el .Sh "\f(CWev_timer\fP \- relative and optionally recurring timeouts" +.IX Subsection "ev_timer - relative and optionally recurring timeouts" +Timer watchers are simple relative timers that generate an event after a +given time, and optionally repeating in regular intervals after that. +.PP +The timers are based on real time, that is, if you register an event that +times out after an hour and you reset your system clock to last years +time, it will still time out after (roughly) and hour. \*(L"Roughly\*(R" because +detecting time jumps is hard, and soem inaccuracies are unavoidable (the +monotonic clock option helps a lot here). +.PP +The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR +time. This is usually the right thing as this timestamp refers to the time +of the event triggering whatever timeout you are modifying/starting. If +you suspect event processing to be delayed and you *need* to base the timeout +on the current time, use something like this to adjust for this: +.PP +.Vb 1 +\& ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); +.Ve +.IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4 +.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" +.PD 0 +.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 +.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" +.PD +Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR is +\&\f(CW0.\fR, then it will automatically be stopped. If it is positive, then the +timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds +later, again, and again, until stopped manually. +.Sp +The timer itself will do a best-effort at avoiding drift, that is, if you +configure a timer to trigger every 10 seconds, then it will trigger at +exactly 10 second intervals. If, however, your program cannot keep up with +the timer (because it takes longer than those 10 seconds to do stuff) the +timer will not fire more than once per event loop iteration. +.IP "ev_timer_again (loop)" 4 +.IX Item "ev_timer_again (loop)" +This will act as if the timer timed out and restart it again if it is +repeating. The exact semantics are: +.Sp +If the timer is started but nonrepeating, stop it. +.Sp +If the timer is repeating, either start it if necessary (with the repeat +value), or reset the running timer to the repeat value. +.Sp +This sounds a bit complicated, but here is a useful and typical +example: Imagine you have a tcp connection and you want a so-called idle +timeout, that is, you want to be called when there have been, say, 60 +seconds of inactivity on the socket. The easiest way to do this is to +configure an \f(CW\*(C`ev_timer\*(C'\fR with after=repeat=60 and calling ev_timer_again each +time you successfully read or write some data. If you go into an idle +state where you do not expect data to travel on the socket, you can stop +the timer, and again will automatically restart it if need be. +.ie n .Sh """ev_periodic"" \- to cron or not to cron" +.el .Sh "\f(CWev_periodic\fP \- to cron or not to cron" +.IX Subsection "ev_periodic - to cron or not to cron" +Periodic watchers are also timers of a kind, but they are very versatile +(and unfortunately a bit complex). +.PP +Unlike \f(CW\*(C`ev_timer\*(C'\fR's, they are not based on real time (or relative time) +but on wallclock time (absolute time). You can tell a periodic watcher +to trigger \*(L"at\*(R" some specific point in time. For example, if you tell a +periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now () ++ 10.>) and then reset your system clock to the last year, then it will +take a year to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would trigger +roughly 10 seconds later and of course not if you reset your system time +again). +.PP +They can also be used to implement vastly more complex timers, such as +triggering an event on eahc midnight, local time. +.IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4 +.IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" +.PD 0 +.IP "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 4 +.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" +.PD +Lots of arguments, lets sort it out... There are basically three modes of +operation, and we will explain them from simplest to complex: +.RS 4 +.IP "* absolute timer (interval = reschedule_cb = 0)" 4 +.IX Item "absolute timer (interval = reschedule_cb = 0)" +In this configuration the watcher triggers an event at the wallclock time +\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs, +that is, if it is to be run at January 1st 2011 then it will run when the +system time reaches or surpasses this time. +.IP "* non-repeating interval timer (interval > 0, reschedule_cb = 0)" 4 +.IX Item "non-repeating interval timer (interval > 0, reschedule_cb = 0)" +In this mode the watcher will always be scheduled to time out at the next +\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N) and then repeat, regardless +of any time jumps. +.Sp +This can be used to create timers that do not drift with respect to system +time: +.Sp +.Vb 1 +\& ev_periodic_set (&periodic, 0., 3600., 0); +.Ve +.Sp +This doesn't mean there will always be 3600 seconds in between triggers, +but only that the the callback will be called when the system time shows a +full hour (\s-1UTC\s0), or more correctly, when the system time is evenly divisible +by 3600. +.Sp +Another way to think about it (for the mathematically inclined) is that +\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible +time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps. +.IP "* manual reschedule mode (reschedule_cb = callback)" 4 +.IX Item "manual reschedule mode (reschedule_cb = callback)" +In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being +ignored. Instead, each time the periodic watcher gets scheduled, the +reschedule callback will be called with the watcher as first, and the +current time as second argument. +.Sp +\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, +ever, or make any event loop modifications\fR. If you need to stop it, +return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop it afterwards (e.g. by +starting a prepare watcher). +.Sp +Its prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic *w, +ev_tstamp now)\*(C'\fR, e.g.: +.Sp +.Vb 4 +\& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) +\& { +\& return now + 60.; +\& } +.Ve +.Sp +It must return the next time to trigger, based on the passed time value +(that is, the lowest time value larger than to the second argument). It +will usually be called just before the callback will be triggered, but +might be called at other times, too. +.Sp +\&\s-1NOTE:\s0 \fIThis callback must always return a time that is later than the +passed \f(CI\*(C`now\*(C'\fI value\fR. Not even \f(CW\*(C`now\*(C'\fR itself will do, it \fImust\fR be larger. +.Sp +This can be used to create very complex timers, such as a timer that +triggers on each midnight, local time. To do this, you would calculate the +next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How +you do this is, again, up to you (but it is not trivial, which is the main +reason I omitted it as an example). +.RE +.RS 4 +.RE +.IP "ev_periodic_again (loop, ev_periodic *)" 4 +.IX Item "ev_periodic_again (loop, ev_periodic *)" +Simply stops and restarts the periodic watcher again. This is only useful +when you changed some parameters or the reschedule callback would return +a different time than the last time it was called (e.g. in a crond like +program when the crontabs have changed). +.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled" +.el .Sh "\f(CWev_signal\fP \- signal me when a signal gets signalled" +.IX Subsection "ev_signal - signal me when a signal gets signalled" +Signal watchers will trigger an event when the process receives a specific +signal one or more times. Even though signals are very asynchronous, libev +will try it's best to deliver signals synchronously, i.e. as part of the +normal event processing, like any other event. +.PP +You can configure as many watchers as you like per signal. Only when the +first watcher gets started will libev actually register a signal watcher +with the kernel (thus it coexists with your own signal handlers as long +as you don't register any with libev). Similarly, when the last signal +watcher for a signal is stopped libev will reset the signal handler to +\&\s-1SIG_DFL\s0 (regardless of what it was set to before). +.IP "ev_signal_init (ev_signal *, callback, int signum)" 4 +.IX Item "ev_signal_init (ev_signal *, callback, int signum)" +.PD 0 +.IP "ev_signal_set (ev_signal *, int signum)" 4 +.IX Item "ev_signal_set (ev_signal *, int signum)" +.PD +Configures the watcher to trigger on the given signal number (usually one +of the \f(CW\*(C`SIGxxx\*(C'\fR constants). +.ie n .Sh """ev_child"" \- wait for pid status changes" +.el .Sh "\f(CWev_child\fP \- wait for pid status changes" +.IX Subsection "ev_child - wait for pid status changes" +Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to +some child status changes (most typically when a child of yours dies). +.IP "ev_child_init (ev_child *, callback, int pid)" 4 +.IX Item "ev_child_init (ev_child *, callback, int pid)" +.PD 0 +.IP "ev_child_set (ev_child *, int pid)" 4 +.IX Item "ev_child_set (ev_child *, int pid)" +.PD +Configures the watcher to wait for status changes of process \f(CW\*(C`pid\*(C'\fR (or +\&\fIany\fR process if \f(CW\*(C`pid\*(C'\fR is specified as \f(CW0\fR). The callback can look +at the \f(CW\*(C`rstatus\*(C'\fR member of the \f(CW\*(C`ev_child\*(C'\fR watcher structure to see +the status word (use the macros from \f(CW\*(C`sys/wait.h\*(C'\fR and see your systems +\&\f(CW\*(C`waitpid\*(C'\fR documentation). The \f(CW\*(C`rpid\*(C'\fR member contains the pid of the +process causing the status change. +.ie n .Sh """ev_idle"" \- when you've got nothing better to do" +.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do" +.IX Subsection "ev_idle - when you've got nothing better to do" +Idle watchers trigger events when there are no other events are pending +(prepare, check and other idle watchers do not count). That is, as long +as your process is busy handling sockets or timeouts (or even signals, +imagine) it will not be triggered. But when your process is idle all idle +watchers are being called again and again, once per event loop iteration \- +until stopped, that is, or your process receives more events and becomes +busy. +.PP +The most noteworthy effect is that as long as any idle watchers are +active, the process will not block when waiting for new events. +.PP +Apart from keeping your process non-blocking (which is a useful +effect on its own sometimes), idle watchers are a good place to do +\&\*(L"pseudo\-background processing\*(R", or delay processing stuff to after the +event loop has handled all outstanding events. +.IP "ev_idle_init (ev_signal *, callback)" 4 +.IX Item "ev_idle_init (ev_signal *, callback)" +Initialises and configures the idle watcher \- it has no parameters of any +kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless, +believe me. +.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop" +.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop" +.IX Subsection "ev_prepare and ev_check - customise your event loop" +Prepare and check watchers are usually (but not always) used in tandem: +prepare watchers get invoked before the process blocks and check watchers +afterwards. +.PP +Their main purpose is to integrate other event mechanisms into libev. This +could be used, for example, to track variable changes, implement your own +watchers, integrate net-snmp or a coroutine library and lots more. +.PP +This is done by examining in each prepare call which file descriptors need +to be watched by the other library, registering \f(CW\*(C`ev_io\*(C'\fR watchers for +them and starting an \f(CW\*(C`ev_timer\*(C'\fR watcher for any timeouts (many libraries +provide just this functionality). Then, in the check watcher you check for +any events that occured (by checking the pending status of all watchers +and stopping them) and call back into the library. The I/O and timer +callbacks will never actually be called (but must be valid nevertheless, +because you never know, you know?). +.PP +As another example, the Perl Coro module uses these hooks to integrate +coroutines into libev programs, by yielding to other active coroutines +during each prepare and only letting the process block if no coroutines +are ready to run (it's actually more complicated: it only runs coroutines +with priority higher than or equal to the event loop and one coroutine +of lower priority, but only once, using idle watchers to keep the event +loop from blocking if lower-priority coroutines are active, thus mapping +low-priority coroutines to idle/background tasks). +.IP "ev_prepare_init (ev_prepare *, callback)" 4 +.IX Item "ev_prepare_init (ev_prepare *, callback)" +.PD 0 +.IP "ev_check_init (ev_check *, callback)" 4 +.IX Item "ev_check_init (ev_check *, callback)" +.PD +Initialises and configures the prepare or check watcher \- they have no +parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR +macros, but using them is utterly, utterly and completely pointless. +.SH "OTHER FUNCTIONS" +.IX Header "OTHER FUNCTIONS" +There are some other functions of possible interest. Described. Here. Now. +.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 +.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" +This function combines a simple timer and an I/O watcher, calls your +callback on whichever event happens first and automatically stop both +watchers. This is useful if you want to wait for a single event on an fd +or timeout without having to allocate/configure/start/stop/free one or +more watchers yourself. +.Sp +If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and events +is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for the given \f(CW\*(C`fd\*(C'\fR and +\&\f(CW\*(C`events\*(C'\fR set will be craeted and started. +.Sp +If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be +started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and +repeat = 0) will be started. While \f(CW0\fR is a valid timeout, it is of +dubious value. +.Sp +The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets +passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of +\&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMEOUT\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR +value passed to \f(CW\*(C`ev_once\*(C'\fR: +.Sp +.Vb 7 +\& static void stdin_ready (int revents, void *arg) +\& { +\& if (revents & EV_TIMEOUT) +\& /* doh, nothing entered */; +\& else if (revents & EV_READ) +\& /* stdin might have data for us, joy! */; +\& } +.Ve +.Sp +.Vb 1 +\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); +.Ve +.IP "ev_feed_event (loop, watcher, int events)" 4 +.IX Item "ev_feed_event (loop, watcher, int events)" +Feeds the given event set into the event loop, as if the specified event +had happened for the specified watcher (which must be a pointer to an +initialised but not necessarily started event watcher). +.IP "ev_feed_fd_event (loop, int fd, int revents)" 4 +.IX Item "ev_feed_fd_event (loop, int fd, int revents)" +Feed an event on the given fd, as if a file descriptor backend detected +the given events it. +.IP "ev_feed_signal_event (loop, int signum)" 4 +.IX Item "ev_feed_signal_event (loop, int signum)" +Feed an event as if the given signal occured (loop must be the default loop!). +.SH "LIBEVENT EMULATION" +.IX Header "LIBEVENT EMULATION" +Libev offers a compatibility emulation layer for libevent. It cannot +emulate the internals of libevent, so here are some usage hints: +.IP "* Use it by including <event.h>, as usual." 4 +.IX Item "Use it by including <event.h>, as usual." +.PD 0 +.IP "* The following members are fully supported: ev_base, ev_callback, ev_arg, ev_fd, ev_res, ev_events." 4 +.IX Item "The following members are fully supported: ev_base, ev_callback, ev_arg, ev_fd, ev_res, ev_events." +.IP "* Avoid using ev_flags and the EVLIST_*\-macros, while it is maintained by libev, it does not work exactly the same way as in libevent (consider it a private \s-1API\s0)." 4 +.IX Item "Avoid using ev_flags and the EVLIST_*-macros, while it is maintained by libev, it does not work exactly the same way as in libevent (consider it a private API)." +.IP "* Priorities are not currently supported. Initialising priorities will fail and all watchers will have the same priority, even though there is an ev_pri field." 4 +.IX Item "Priorities are not currently supported. Initialising priorities will fail and all watchers will have the same priority, even though there is an ev_pri field." +.IP "* Other members are not supported." 4 +.IX Item "Other members are not supported." +.IP "* The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need to use the libev header file and library." 4 +.IX Item "The libev emulation is not ABI compatible to libevent, you need to use the libev header file and library." +.PD +.SH "\*(C+ SUPPORT" +.IX Header " SUPPORT" +\&\s-1TBD\s0. +.SH "AUTHOR" +.IX Header "AUTHOR" +Marc Lehmann <libev@schmorp.de>. |