ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.3
(Generate patch)

Comparing libev/ev.3 (file contents):
Revision 1.32 by root, Wed Nov 28 17:32:24 2007 UTC vs.
Revision 1.36 by root, Thu Nov 29 20:05:59 2007 UTC

… …
127.\} 127.\}
128.rm #[ #] #H #V #F C 128.rm #[ #] #H #V #F C
129.\" ======================================================================== 129.\" ========================================================================
130.\" 130.\"
131.IX Title ""<STANDARD INPUT>" 1" 131.IX Title ""<STANDARD INPUT>" 1"
132.TH "<STANDARD INPUT>" 1 "2007-11-28" "perl v5.8.8" "User Contributed Perl Documentation" 132.TH "<STANDARD INPUT>" 1 "2007-11-29" "perl v5.8.8" "User Contributed Perl Documentation"
133.SH "NAME" 133.SH "NAME"
134libev \- a high performance full\-featured event loop written in C 134libev \- a high performance full\-featured event loop written in C
135.SH "SYNOPSIS" 135.SH "SYNOPSIS"
136.IX Header "SYNOPSIS" 136.IX Header "SYNOPSIS"
137.Vb 1 137.Vb 1
… …
411or setgid) then libev will \fInot\fR look at the environment variable 411or setgid) then libev will \fInot\fR look at the environment variable
412\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will 412\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will
413override the flags completely if it is found in the environment. This is 413override the flags completely if it is found in the environment. This is
414useful to try out specific backends to test their performance, or to work 414useful to try out specific backends to test their performance, or to work
415around bugs. 415around bugs.
416.ie n .IP """EVFLAG_FORKCHECK""" 4
417.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4
418.IX Item "EVFLAG_FORKCHECK"
419Instead of calling \f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR manually after
420a fork, you can also make libev check for a fork in each iteration by
421enabling this flag.
422.Sp
423This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop,
424and thus this might slow down your event loop if you do a lot of loop
425iterations and little real work, but is usually not noticable (on my
426Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence
427without a syscall and thus \fIvery\fR fast, but my Linux system also has
428\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster).
429.Sp
430The big advantage of this flag is that you can forget about fork (and
431forget about forgetting to tell libev about forking) when you use this
432flag.
433.Sp
434This flag setting cannot be overriden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR
435environment variable.
416.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 436.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
417.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 437.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
418.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 438.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
419This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 439This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
420libev tries to roll its own fd_set with no limits on the number of fds, 440libev tries to roll its own fd_set with no limits on the number of fds,
… …
1071.IP "ev_timer_again (loop)" 4 1091.IP "ev_timer_again (loop)" 4
1072.IX Item "ev_timer_again (loop)" 1092.IX Item "ev_timer_again (loop)"
1073This will act as if the timer timed out and restart it again if it is 1093This will act as if the timer timed out and restart it again if it is
1074repeating. The exact semantics are: 1094repeating. The exact semantics are:
1075.Sp 1095.Sp
1096If the timer is pending, its pending status is cleared.
1097.Sp
1076If the timer is started but nonrepeating, stop it. 1098If the timer is started but nonrepeating, stop it (as if it timed out).
1077.Sp 1099.Sp
1078If the timer is repeating, either start it if necessary (with the repeat 1100If the timer is repeating, either start it if necessary (with the
1079value), or reset the running timer to the repeat value. 1101\&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value.
1080.Sp 1102.Sp
1081This sounds a bit complicated, but here is a useful and typical 1103This sounds a bit complicated, but here is a useful and typical
1082example: Imagine you have a tcp connection and you want a so-called 1104example: Imagine you have a tcp connection and you want a so-called idle
1083idle timeout, that is, you want to be called when there have been, 1105timeout, that is, you want to be called when there have been, say, 60
1084say, 60 seconds of inactivity on the socket. The easiest way to do 1106seconds of inactivity on the socket. The easiest way to do this is to
1085this 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 1107configure an \f(CW\*(C`ev_timer\*(C'\fR with a \f(CW\*(C`repeat\*(C'\fR value of \f(CW60\fR and then call
1086\&\f(CW\*(C`ev_timer_again\*(C'\fR each time you successfully read or write some data. If 1108\&\f(CW\*(C`ev_timer_again\*(C'\fR each time you successfully read or write some data. If
1087you go into an idle state where you do not expect data to travel on the 1109you go into an idle state where you do not expect data to travel on the
1088socket, you can stop the timer, and again will automatically restart it if 1110socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will
1089need be. 1111automatically restart it if need be.
1090.Sp 1112.Sp
1091You can also ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR altogether 1113That means you can ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR
1092and only ever use the \f(CW\*(C`repeat\*(C'\fR value: 1114altogether and only ever use the \f(CW\*(C`repeat\*(C'\fR value and \f(CW\*(C`ev_timer_again\*(C'\fR:
1093.Sp 1115.Sp
1094.Vb 8 1116.Vb 8
1095\& ev_timer_init (timer, callback, 0., 5.); 1117\& ev_timer_init (timer, callback, 0., 5.);
1096\& ev_timer_again (loop, timer); 1118\& ev_timer_again (loop, timer);
1097\& ... 1119\& ...
… …
1100\& ... 1122\& ...
1101\& timer->again = 10.; 1123\& timer->again = 10.;
1102\& ev_timer_again (loop, timer); 1124\& ev_timer_again (loop, timer);
1103.Ve 1125.Ve
1104.Sp 1126.Sp
1105This is more efficient then stopping/starting the timer eahc time you want 1127This is more slightly efficient then stopping/starting the timer each time
1106to modify its timeout value. 1128you want to modify its timeout value.
1107.IP "ev_tstamp repeat [read\-write]" 4 1129.IP "ev_tstamp repeat [read\-write]" 4
1108.IX Item "ev_tstamp repeat [read-write]" 1130.IX Item "ev_tstamp repeat [read-write]"
1109The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out 1131The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out
1110or \f(CW\*(C`ev_timer_again\*(C'\fR is called and determines the next timeout (if any), 1132or \f(CW\*(C`ev_timer_again\*(C'\fR is called and determines the next timeout (if any),
1111which is also when any modifications are taken into account. 1133which is also when any modifications are taken into account.
… …
1384not exist\*(R" is a status change like any other. The condition \*(L"path does 1406not exist\*(R" is a status change like any other. The condition \*(L"path does
1385not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is 1407not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is
1386otherwise always forced to be at least one) and all the other fields of 1408otherwise always forced to be at least one) and all the other fields of
1387the stat buffer having unspecified contents. 1409the stat buffer having unspecified contents.
1388.PP 1410.PP
1411The path \fIshould\fR be absolute and \fImust not\fR end in a slash. If it is
1412relative and your working directory changes, the behaviour is undefined.
1413.PP
1389Since there is no standard to do this, the portable implementation simply 1414Since there is no standard to do this, the portable implementation simply
1390calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if it changed somehow. You 1415calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if it changed somehow. You
1391can specify a recommended polling interval for this case. If you specify 1416can specify a recommended polling interval for this case. If you specify
1392a polling interval of \f(CW0\fR (highly recommended!) then a \fIsuitable, 1417a polling interval of \f(CW0\fR (highly recommended!) then a \fIsuitable,
1393unspecified default\fR value will be used (which you can expect to be around 1418unspecified default\fR value will be used (which you can expect to be around
… …
1972.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 1997.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
1973.IX Item "EV_DEFAULT, EV_DEFAULT_" 1998.IX Item "EV_DEFAULT, EV_DEFAULT_"
1974Similar to the other two macros, this gives you the value of the default 1999Similar to the other two macros, this gives you the value of the default
1975loop, if multiple loops are supported (\*(L"ev loop default\*(R"). 2000loop, if multiple loops are supported (\*(L"ev loop default\*(R").
1976.PP 2001.PP
1977Example: Declare and initialise a check watcher, working regardless of 2002Example: Declare and initialise a check watcher, utilising the above
1978wether multiple loops are supported or not. 2003macros so it will work regardless of wether multiple loops are supported
2004or not.
1979.PP 2005.PP
1980.Vb 5 2006.Vb 5
1981\& static void 2007\& static void
1982\& check_cb (EV_P_ ev_timer *w, int revents) 2008\& check_cb (EV_P_ ev_timer *w, int revents)
1983\& { 2009\& {
… …
2046.Vb 1 2072.Vb 1
2047\& ev_win32.c required on win32 platforms only 2073\& ev_win32.c required on win32 platforms only
2048.Ve 2074.Ve
2049.PP 2075.PP
2050.Vb 5 2076.Vb 5
2051\& ev_select.c only when select backend is enabled (which is by default) 2077\& ev_select.c only when select backend is enabled (which is enabled by default)
2052\& ev_poll.c only when poll backend is enabled (disabled by default) 2078\& ev_poll.c only when poll backend is enabled (disabled by default)
2053\& ev_epoll.c only when the epoll backend is enabled (disabled by default) 2079\& ev_epoll.c only when the epoll backend is enabled (disabled by default)
2054\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 2080\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
2055\& ev_port.c only when the solaris port backend is enabled (disabled by default) 2081\& ev_port.c only when the solaris port backend is enabled (disabled by default)
2056.Ve 2082.Ve
… …
2283interface) and \fI\s-1EV\s0.xs\fR (implementation) files. Only the \fI\s-1EV\s0.xs\fR file 2309interface) and \fI\s-1EV\s0.xs\fR (implementation) files. Only the \fI\s-1EV\s0.xs\fR file
2284will be compiled. It is pretty complex because it provides its own header 2310will be compiled. It is pretty complex because it provides its own header
2285file. 2311file.
2286.Sp 2312.Sp
2287The usage in rxvt-unicode is simpler. It has a \fIev_cpp.h\fR header file 2313The usage in rxvt-unicode is simpler. It has a \fIev_cpp.h\fR header file
2288that everybody includes and which overrides some autoconf choices: 2314that everybody includes and which overrides some configure choices:
2289.Sp 2315.Sp
2290.Vb 4 2316.Vb 9
2317\& #define EV_MINIMAL 1
2291\& #define EV_USE_POLL 0 2318\& #define EV_USE_POLL 0
2292\& #define EV_MULTIPLICITY 0 2319\& #define EV_MULTIPLICITY 0
2293\& #define EV_PERIODICS 0 2320\& #define EV_PERIODIC_ENABLE 0
2321\& #define EV_STAT_ENABLE 0
2322\& #define EV_FORK_ENABLE 0
2294\& #define EV_CONFIG_H <config.h> 2323\& #define EV_CONFIG_H <config.h>
2324\& #define EV_MINPRI 0
2325\& #define EV_MAXPRI 0
2295.Ve 2326.Ve
2296.Sp 2327.Sp
2297.Vb 1 2328.Vb 1
2298\& #include "ev++.h" 2329\& #include "ev++.h"
2299.Ve 2330.Ve

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines