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

Comparing libev/ev.3 (file contents):
Revision 1.31 by root, Wed Nov 28 11:31:34 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
… …
305might be supported on the current system, you would need to look at 305might be supported on the current system, you would need to look at
306\&\f(CW\*(C`ev_embeddable_backends () & ev_supported_backends ()\*(C'\fR, likewise for 306\&\f(CW\*(C`ev_embeddable_backends () & ev_supported_backends ()\*(C'\fR, likewise for
307recommended ones. 307recommended ones.
308.Sp 308.Sp
309See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 309See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
310.IP "ev_set_allocator (void *(*cb)(void *ptr, size_t size))" 4 310.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4
311.IX Item "ev_set_allocator (void *(*cb)(void *ptr, size_t size))" 311.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))"
312Sets the allocation function to use (the prototype and semantics are 312Sets the allocation function to use (the prototype is similar \- the
313identical to the realloc C function). It is used to allocate and free 313semantics is identical \- to the realloc C function). It is used to
314memory (no surprises here). If it returns zero when memory needs to be 314allocate and free memory (no surprises here). If it returns zero when
315allocated, the library might abort or take some potentially destructive 315memory needs to be allocated, the library might abort or take some
316action. The default is your system realloc function. 316potentially destructive action. The default is your system realloc
317function.
317.Sp 318.Sp
318You could override this function in high-availability programs to, say, 319You could override this function in high-availability programs to, say,
319free some memory if it cannot allocate memory, to use a special allocator, 320free some memory if it cannot allocate memory, to use a special allocator,
320or even to sleep a while and retry until some memory is available. 321or even to sleep a while and retry until some memory is available.
321.Sp 322.Sp
… …
410or setgid) then libev will \fInot\fR look at the environment variable 411or setgid) then libev will \fInot\fR look at the environment variable
411\&\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
412override 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
413useful 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
414around 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.
415.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 436.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
416.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
417.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 438.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
418This 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
419libev 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,
… …
1070.IP "ev_timer_again (loop)" 4 1091.IP "ev_timer_again (loop)" 4
1071.IX Item "ev_timer_again (loop)" 1092.IX Item "ev_timer_again (loop)"
1072This 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
1073repeating. The exact semantics are: 1094repeating. The exact semantics are:
1074.Sp 1095.Sp
1096If the timer is pending, its pending status is cleared.
1097.Sp
1075If the timer is started but nonrepeating, stop it. 1098If the timer is started but nonrepeating, stop it (as if it timed out).
1076.Sp 1099.Sp
1077If the timer is repeating, either start it if necessary (with the repeat 1100If the timer is repeating, either start it if necessary (with the
1078value), 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.
1079.Sp 1102.Sp
1080This sounds a bit complicated, but here is a useful and typical 1103This sounds a bit complicated, but here is a useful and typical
1081example: 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
1082idle 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
1083say, 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
1084this 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
1085\&\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
1086you 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
1087socket, 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
1088need be. 1111automatically restart it if need be.
1089.Sp 1112.Sp
1090You 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
1091and 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:
1092.Sp 1115.Sp
1093.Vb 8 1116.Vb 8
1094\& ev_timer_init (timer, callback, 0., 5.); 1117\& ev_timer_init (timer, callback, 0., 5.);
1095\& ev_timer_again (loop, timer); 1118\& ev_timer_again (loop, timer);
1096\& ... 1119\& ...
… …
1099\& ... 1122\& ...
1100\& timer->again = 10.; 1123\& timer->again = 10.;
1101\& ev_timer_again (loop, timer); 1124\& ev_timer_again (loop, timer);
1102.Ve 1125.Ve
1103.Sp 1126.Sp
1104This is more efficient then stopping/starting the timer eahc time you want 1127This is more slightly efficient then stopping/starting the timer each time
1105to modify its timeout value. 1128you want to modify its timeout value.
1106.IP "ev_tstamp repeat [read\-write]" 4 1129.IP "ev_tstamp repeat [read\-write]" 4
1107.IX Item "ev_tstamp repeat [read-write]" 1130.IX Item "ev_tstamp repeat [read-write]"
1108The 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
1109or \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),
1110which is also when any modifications are taken into account. 1133which is also when any modifications are taken into account.
… …
1383not 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
1384not 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
1385otherwise 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
1386the stat buffer having unspecified contents. 1409the stat buffer having unspecified contents.
1387.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
1388Since there is no standard to do this, the portable implementation simply 1414Since there is no standard to do this, the portable implementation simply
1389calls \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
1390can specify a recommended polling interval for this case. If you specify 1416can specify a recommended polling interval for this case. If you specify
1391a polling interval of \f(CW0\fR (highly recommended!) then a \fIsuitable, 1417a polling interval of \f(CW0\fR (highly recommended!) then a \fIsuitable,
1392unspecified 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
… …
1971.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 1997.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
1972.IX Item "EV_DEFAULT, EV_DEFAULT_" 1998.IX Item "EV_DEFAULT, EV_DEFAULT_"
1973Similar 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
1974loop, if multiple loops are supported (\*(L"ev loop default\*(R"). 2000loop, if multiple loops are supported (\*(L"ev loop default\*(R").
1975.PP 2001.PP
1976Example: Declare and initialise a check watcher, working regardless of 2002Example: Declare and initialise a check watcher, utilising the above
1977wether multiple loops are supported or not. 2003macros so it will work regardless of wether multiple loops are supported
2004or not.
1978.PP 2005.PP
1979.Vb 5 2006.Vb 5
1980\& static void 2007\& static void
1981\& check_cb (EV_P_ ev_timer *w, int revents) 2008\& check_cb (EV_P_ ev_timer *w, int revents)
1982\& { 2009\& {
… …
2045.Vb 1 2072.Vb 1
2046\& ev_win32.c required on win32 platforms only 2073\& ev_win32.c required on win32 platforms only
2047.Ve 2074.Ve
2048.PP 2075.PP
2049.Vb 5 2076.Vb 5
2050\& 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)
2051\& 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)
2052\& 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)
2053\& 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)
2054\& 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)
2055.Ve 2082.Ve
… …
2282interface) 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
2283will 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
2284file. 2311file.
2285.Sp 2312.Sp
2286The 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
2287that everybody includes and which overrides some autoconf choices: 2314that everybody includes and which overrides some configure choices:
2288.Sp 2315.Sp
2289.Vb 4 2316.Vb 9
2317\& #define EV_MINIMAL 1
2290\& #define EV_USE_POLL 0 2318\& #define EV_USE_POLL 0
2291\& #define EV_MULTIPLICITY 0 2319\& #define EV_MULTIPLICITY 0
2292\& #define EV_PERIODICS 0 2320\& #define EV_PERIODIC_ENABLE 0
2321\& #define EV_STAT_ENABLE 0
2322\& #define EV_FORK_ENABLE 0
2293\& #define EV_CONFIG_H <config.h> 2323\& #define EV_CONFIG_H <config.h>
2324\& #define EV_MINPRI 0
2325\& #define EV_MAXPRI 0
2294.Ve 2326.Ve
2295.Sp 2327.Sp
2296.Vb 1 2328.Vb 1
2297\& #include "ev++.h" 2329\& #include "ev++.h"
2298.Ve 2330.Ve

Diff Legend

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