… | |
… | |
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" |
134 | libev \- a high performance full\-featured event loop written in C |
134 | libev \- 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 |
… | |
… | |
305 | might be supported on the current system, you would need to look at |
305 | might 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 |
307 | recommended ones. |
307 | recommended ones. |
308 | .Sp |
308 | .Sp |
309 | See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
309 | See 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))" |
312 | Sets the allocation function to use (the prototype and semantics are |
312 | Sets the allocation function to use (the prototype is similar \- the |
313 | identical to the realloc C function). It is used to allocate and free |
313 | semantics is identical \- to the realloc C function). It is used to |
314 | memory (no surprises here). If it returns zero when memory needs to be |
314 | allocate and free memory (no surprises here). If it returns zero when |
315 | allocated, the library might abort or take some potentially destructive |
315 | memory needs to be allocated, the library might abort or take some |
316 | action. The default is your system realloc function. |
316 | potentially destructive action. The default is your system realloc |
|
|
317 | function. |
317 | .Sp |
318 | .Sp |
318 | You could override this function in high-availability programs to, say, |
319 | You could override this function in high-availability programs to, say, |
319 | free some memory if it cannot allocate memory, to use a special allocator, |
320 | free some memory if it cannot allocate memory, to use a special allocator, |
320 | or even to sleep a while and retry until some memory is available. |
321 | or even to sleep a while and retry until some memory is available. |
321 | .Sp |
322 | .Sp |
… | |
… | |
1070 | .IP "ev_timer_again (loop)" 4 |
1071 | .IP "ev_timer_again (loop)" 4 |
1071 | .IX Item "ev_timer_again (loop)" |
1072 | .IX Item "ev_timer_again (loop)" |
1072 | This will act as if the timer timed out and restart it again if it is |
1073 | This will act as if the timer timed out and restart it again if it is |
1073 | repeating. The exact semantics are: |
1074 | repeating. The exact semantics are: |
1074 | .Sp |
1075 | .Sp |
|
|
1076 | If the timer is pending, its pending status is cleared. |
|
|
1077 | .Sp |
1075 | If the timer is started but nonrepeating, stop it. |
1078 | If the timer is started but nonrepeating, stop it (as if it timed out). |
1076 | .Sp |
1079 | .Sp |
1077 | If the timer is repeating, either start it if necessary (with the repeat |
1080 | If the timer is repeating, either start it if necessary (with the |
1078 | value), or reset the running timer to the repeat value. |
1081 | \&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value. |
1079 | .Sp |
1082 | .Sp |
1080 | This sounds a bit complicated, but here is a useful and typical |
1083 | This sounds a bit complicated, but here is a useful and typical |
1081 | example: Imagine you have a tcp connection and you want a so-called |
1084 | example: Imagine you have a tcp connection and you want a so-called idle |
1082 | idle timeout, that is, you want to be called when there have been, |
1085 | timeout, that is, you want to be called when there have been, say, 60 |
1083 | say, 60 seconds of inactivity on the socket. The easiest way to do |
1086 | seconds of inactivity on the socket. The easiest way to do this is to |
1084 | 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 |
1087 | 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 |
1085 | \&\f(CW\*(C`ev_timer_again\*(C'\fR each time you successfully read or write some data. If |
1088 | \&\f(CW\*(C`ev_timer_again\*(C'\fR each time you successfully read or write some data. If |
1086 | you go into an idle state where you do not expect data to travel on the |
1089 | you go into an idle state where you do not expect data to travel on the |
1087 | socket, you can stop the timer, and again will automatically restart it if |
1090 | socket, you can \f(CW\*(C`ev_timer_stop\*(C'\fR the timer, and \f(CW\*(C`ev_timer_again\*(C'\fR will |
1088 | need be. |
1091 | automatically restart it if need be. |
1089 | .Sp |
1092 | .Sp |
1090 | You can also ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR altogether |
1093 | That means you can ignore the \f(CW\*(C`after\*(C'\fR value and \f(CW\*(C`ev_timer_start\*(C'\fR |
1091 | and only ever use the \f(CW\*(C`repeat\*(C'\fR value: |
1094 | altogether and only ever use the \f(CW\*(C`repeat\*(C'\fR value and \f(CW\*(C`ev_timer_again\*(C'\fR: |
1092 | .Sp |
1095 | .Sp |
1093 | .Vb 8 |
1096 | .Vb 8 |
1094 | \& ev_timer_init (timer, callback, 0., 5.); |
1097 | \& ev_timer_init (timer, callback, 0., 5.); |
1095 | \& ev_timer_again (loop, timer); |
1098 | \& ev_timer_again (loop, timer); |
1096 | \& ... |
1099 | \& ... |
… | |
… | |
1099 | \& ... |
1102 | \& ... |
1100 | \& timer->again = 10.; |
1103 | \& timer->again = 10.; |
1101 | \& ev_timer_again (loop, timer); |
1104 | \& ev_timer_again (loop, timer); |
1102 | .Ve |
1105 | .Ve |
1103 | .Sp |
1106 | .Sp |
1104 | This is more efficient then stopping/starting the timer eahc time you want |
1107 | This is more slightly efficient then stopping/starting the timer each time |
1105 | to modify its timeout value. |
1108 | you want to modify its timeout value. |
1106 | .IP "ev_tstamp repeat [read\-write]" 4 |
1109 | .IP "ev_tstamp repeat [read\-write]" 4 |
1107 | .IX Item "ev_tstamp repeat [read-write]" |
1110 | .IX Item "ev_tstamp repeat [read-write]" |
1108 | The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out |
1111 | The current \f(CW\*(C`repeat\*(C'\fR value. Will be used each time the watcher times out |
1109 | or \f(CW\*(C`ev_timer_again\*(C'\fR is called and determines the next timeout (if any), |
1112 | or \f(CW\*(C`ev_timer_again\*(C'\fR is called and determines the next timeout (if any), |
1110 | which is also when any modifications are taken into account. |
1113 | which is also when any modifications are taken into account. |
… | |
… | |
1382 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
1385 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
1383 | not exist\*(R" is a status change like any other. The condition \*(L"path does |
1386 | not exist\*(R" is a status change like any other. The condition \*(L"path does |
1384 | not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is |
1387 | not exist\*(R" is signified by the \f(CW\*(C`st_nlink\*(C'\fR field being zero (which is |
1385 | otherwise always forced to be at least one) and all the other fields of |
1388 | otherwise always forced to be at least one) and all the other fields of |
1386 | the stat buffer having unspecified contents. |
1389 | the stat buffer having unspecified contents. |
|
|
1390 | .PP |
|
|
1391 | The path \fIshould\fR be absolute and \fImust not\fR end in a slash. If it is |
|
|
1392 | relative and your working directory changes, the behaviour is undefined. |
1387 | .PP |
1393 | .PP |
1388 | Since there is no standard to do this, the portable implementation simply |
1394 | Since there is no standard to do this, the portable implementation simply |
1389 | calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if it changed somehow. You |
1395 | calls \f(CW\*(C`stat (2)\*(C'\fR regularly on the path to see if it changed somehow. You |
1390 | can specify a recommended polling interval for this case. If you specify |
1396 | can specify a recommended polling interval for this case. If you specify |
1391 | a polling interval of \f(CW0\fR (highly recommended!) then a \fIsuitable, |
1397 | a polling interval of \f(CW0\fR (highly recommended!) then a \fIsuitable, |