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.35 by root, Thu Nov 29 17:28:13 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.
… …
1383The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does 1405The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does
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.
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.
1388.PP 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,

Diff Legend

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