.\" ========================================================================
.\"
.IX Title ""<STANDARD INPUT>" 1"
-.TH "<STANDARD INPUT>" 1 "2007-11-27" "perl v5.8.8" "User Contributed Perl Documentation"
+.TH "<STANDARD INPUT>" 1 "2007-11-29" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
libev \- a high performance full\-featured event loop written in C
.SH "SYNOPSIS"
watcher.
.SH "FEATURES"
.IX Header "FEATURES"
-Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the linux-specific \f(CW\*(C`epoll\*(C'\fR, the
-bsd-specific \f(CW\*(C`kqueue\*(C'\fR and the solaris-specific event port mechanisms
-for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR),
-absolute timers with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous
-signals (\f(CW\*(C`ev_signal\*(C'\fR), process status change events (\f(CW\*(C`ev_child\*(C'\fR), and
-event watchers dealing with the event loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR,
+Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the
+BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms
+for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface
+(for \f(CW\*(C`ev_stat\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers
+with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals
+(\f(CW\*(C`ev_signal\*(C'\fR), process status change events (\f(CW\*(C`ev_child\*(C'\fR), and event
+watchers dealing with the event loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR,
\&\f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and \f(CW\*(C`ev_check\*(C'\fR watchers) as well as
file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even limited support for fork events
(\f(CW\*(C`ev_fork\*(C'\fR).
recommended ones.
.Sp
See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
-.IP "ev_set_allocator (void *(*cb)(void *ptr, size_t size))" 4
-.IX Item "ev_set_allocator (void *(*cb)(void *ptr, size_t size))"
-Sets the allocation function to use (the prototype and semantics are
-identical to the realloc C function). It is used to allocate and free
-memory (no surprises here). If it returns zero when memory needs to be
-allocated, the library might abort or take some potentially destructive
-action. The default is your system realloc function.
+.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 \- the
+semantics is identical \- to the realloc C function). It is used to
+allocate and free memory (no surprises here). If it returns zero when
+memory needs to be allocated, the library might abort or take some
+potentially destructive action. The default is your system realloc
+function.
.Sp
You could override this function in high-availability programs to, say,
free some memory if it cannot allocate memory, to use a special allocator,
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 """EVFLAG_FORKCHECK""" 4
+.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4
+.IX Item "EVFLAG_FORKCHECK"
+Instead of calling \f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR manually after
+a fork, you can also make libev check for a fork in each iteration by
+enabling this flag.
+.Sp
+This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop,
+and thus this might slow down your event loop if you do a lot of loop
+iterations and little real work, but is usually not noticable (on my
+Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence
+without a syscall and thus \fIvery\fR fast, but my Linux system also has
+\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster).
+.Sp
+The big advantage of this flag is that you can forget about fork (and
+forget about forgetting to tell libev about forking) when you use this
+flag.
+.Sp
+This flag setting cannot be overriden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR
+environment variable.
.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
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.
+If the timer is pending, its pending status is cleared.
+.Sp
+If the timer is started but nonrepeating, stop it (as if it timed out).
.Sp
-If the timer is repeating, either start it if necessary (with the repeat
-value), or reset the running timer to the repeat value.
+If the timer is repeating, either start it if necessary (with the
+\&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR 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 \f(CW\*(C`after\*(C'\fR=\f(CW\*(C`repeat\*(C'\fR=\f(CW60\fR and calling
+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 a \f(CW\*(C`repeat\*(C'\fR value of \f(CW60\fR and then call
\&\f(CW\*(C`ev_timer_again\*(C'\fR 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.
+socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will
+automatically restart it if need be.
.Sp
-You can also ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR altogether
-and only ever use the \f(CW\*(C`repeat\*(C'\fR value:
+That means you can ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR
+altogether and only ever use the \f(CW\*(C`repeat\*(C'\fR value and \f(CW\*(C`ev_timer_again\*(C'\fR:
.Sp
.Vb 8
\& ev_timer_init (timer, callback, 0., 5.);
\& ev_timer_again (loop, timer);
.Ve
.Sp
-This is more efficient then stopping/starting the timer eahc time you want
-to modify its timeout value.
+This is more slightly efficient then stopping/starting the timer each time
+you want to modify its timeout value.
.IP "ev_tstamp repeat [read\-write]" 4
.IX Item "ev_tstamp repeat [read-write]"
The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out
otherwise always forced to be at least one) and all the other fields of
the stat buffer having unspecified contents.
.PP
+The path \fIshould\fR be absolute and \fImust not\fR end in a slash. If it is
+relative and your working directory changes, the behaviour is undefined.
+.PP
Since there is no standard to do this, the portable implementation simply
-calls \f(CW\*(C`stat (2)\*(C'\fR regulalry on the path to see if it changed somehow. You
+calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if it changed somehow. You
can specify a recommended polling interval for this case. If you specify
a polling interval of \f(CW0\fR (highly recommended!) then a \fIsuitable,
unspecified default\fR value will be used (which you can expect to be around
as even with OS-supported change notifications, this can be
resource\-intensive.
.PP
-At the time of this writing, no specific \s-1OS\s0 backends are implemented, but
-if demand increases, at least a kqueue and inotify backend will be added.
+At the time of this writing, only the Linux inotify interface is
+implemented (implementing kqueue support is left as an exercise for the
+reader). Inotify will be used to give hints only and should not change the
+semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs
+to fall back to regular polling again even with inotify, but changes are
+usually detected immediately, and if the file exists there will be no
+polling.
.IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4
.IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)"
.PD 0
Similar to the other two macros, this gives you the value of the default
loop, if multiple loops are supported (\*(L"ev loop default\*(R").
.PP
-Example: Declare and initialise a check watcher, working regardless of
-wether multiple loops are supported or not.
+Example: Declare and initialise a check watcher, utilising the above
+macros so it will work regardless of wether multiple loops are supported
+or not.
.PP
.Vb 5
\& static void
.Ve
.PP
.Vb 5
-\& ev_select.c only when select backend is enabled (which is by default)
+\& ev_select.c only when select backend is enabled (which is enabled by default)
\& ev_poll.c only when poll backend is enabled (disabled by default)
\& ev_epoll.c only when the epoll backend is enabled (disabled by default)
\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
.IP "\s-1EV_USE_DEVPOLL\s0" 4
.IX Item "EV_USE_DEVPOLL"
reserved for future expansion, works like the \s-1USE\s0 symbols above.
+.IP "\s-1EV_USE_INOTIFY\s0" 4
+.IX Item "EV_USE_INOTIFY"
+If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify
+interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will
+be detected at runtime.
.IP "\s-1EV_H\s0" 4
.IX Item "EV_H"
The name of the \fIev.h\fR header file used to include it. The default if
\&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by
pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more
than enough. If you need to manage thousands of children you might want to
-increase this value.
+increase this value (\fImust\fR be a power of two).
+.IP "\s-1EV_INOTIFY_HASHSIZE\s0" 4
+.IX Item "EV_INOTIFY_HASHSIZE"
+\&\f(CW\*(C`ev_staz\*(C'\fR watchers use a small hash table to distribute workload by
+inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR),
+usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR
+watchers you might want to increase this value (\fImust\fR be a power of
+two).
.IP "\s-1EV_COMMON\s0" 4
.IX Item "EV_COMMON"
By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
file.
.Sp
The usage in rxvt-unicode is simpler. It has a \fIev_cpp.h\fR header file
-that everybody includes and which overrides some autoconf choices:
+that everybody includes and which overrides some configure choices:
.Sp
-.Vb 4
+.Vb 9
+\& #define EV_MINIMAL 1
\& #define EV_USE_POLL 0
\& #define EV_MULTIPLICITY 0
-\& #define EV_PERIODICS 0
+\& #define EV_PERIODIC_ENABLE 0
+\& #define EV_STAT_ENABLE 0
+\& #define EV_FORK_ENABLE 0
\& #define EV_CONFIG_H <config.h>
+\& #define EV_MINPRI 0
+\& #define EV_MAXPRI 0
.Ve
.Sp
.Vb 1
.IX Item "Starting io/check/prepare/idle/signal/child watchers: O(1)"
.IP "Stopping check/prepare/idle watchers: O(1)" 4
.IX Item "Stopping check/prepare/idle watchers: O(1)"
-.IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))" 4
-.IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))"
+.IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4
+.IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))"
.IP "Finding the next timer per loop iteration: O(1)" 4
.IX Item "Finding the next timer per loop iteration: O(1)"
.IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4
projects / software / libev.git / blobdiff