+.\" 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>.
projects / software / libev.git / commitdiff