… | |
… | |
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-12-08" "perl v5.8.8" "User Contributed Perl Documentation" |
132 | .TH "<STANDARD INPUT>" 1 "2007-12-09" "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 |
… | |
… | |
634 | libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is |
634 | libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is |
635 | usually a better approach for this kind of thing. |
635 | usually a better approach for this kind of thing. |
636 | .Sp |
636 | .Sp |
637 | Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does: |
637 | Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does: |
638 | .Sp |
638 | .Sp |
639 | .Vb 18 |
639 | .Vb 19 |
|
|
640 | \& - Before the first iteration, call any pending watchers. |
640 | \& * If there are no active watchers (reference count is zero), return. |
641 | \& * If there are no active watchers (reference count is zero), return. |
641 | \& - Queue prepare watchers and then call all outstanding watchers. |
642 | \& - Queue all prepare watchers and then call all outstanding watchers. |
642 | \& - If we have been forked, recreate the kernel state. |
643 | \& - If we have been forked, recreate the kernel state. |
643 | \& - Update the kernel state with all outstanding changes. |
644 | \& - Update the kernel state with all outstanding changes. |
644 | \& - Update the "event loop time". |
645 | \& - Update the "event loop time". |
645 | \& - Calculate for how long to block. |
646 | \& - Calculate for how long to block. |
646 | \& - Block the process, waiting for any events. |
647 | \& - Block the process, waiting for any events. |
… | |
… | |
1234 | but on wallclock time (absolute time). You can tell a periodic watcher |
1235 | but on wallclock time (absolute time). You can tell a periodic watcher |
1235 | to trigger \*(L"at\*(R" some specific point in time. For example, if you tell a |
1236 | to trigger \*(L"at\*(R" some specific point in time. For example, if you tell a |
1236 | periodic watcher to trigger in 10 seconds (by specifiying e.g. \f(CW\*(C`ev_now () |
1237 | periodic watcher to trigger in 10 seconds (by specifiying e.g. \f(CW\*(C`ev_now () |
1237 | + 10.\*(C'\fR) and then reset your system clock to the last year, then it will |
1238 | + 10.\*(C'\fR) and then reset your system clock to the last year, then it will |
1238 | take a year to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would trigger |
1239 | take a year to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would trigger |
1239 | roughly 10 seconds later and of course not if you reset your system time |
1240 | roughly 10 seconds later). |
1240 | again). |
|
|
1241 | .PP |
1241 | .PP |
1242 | They can also be used to implement vastly more complex timers, such as |
1242 | They can also be used to implement vastly more complex timers, such as |
1243 | triggering an event on eahc midnight, local time. |
1243 | triggering an event on each midnight, local time or other, complicated, |
|
|
1244 | rules. |
1244 | .PP |
1245 | .PP |
1245 | As with timers, the callback is guarenteed to be invoked only when the |
1246 | As with timers, the callback is guarenteed to be invoked only when the |
1246 | time (\f(CW\*(C`at\*(C'\fR) has been passed, but if multiple periodic timers become ready |
1247 | time (\f(CW\*(C`at\*(C'\fR) has been passed, but if multiple periodic timers become ready |
1247 | during the same loop iteration then order of execution is undefined. |
1248 | during the same loop iteration then order of execution is undefined. |
1248 | .IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4 |
1249 | .IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4 |
… | |
… | |
1252 | .IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" |
1253 | .IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" |
1253 | .PD |
1254 | .PD |
1254 | Lots of arguments, lets sort it out... There are basically three modes of |
1255 | Lots of arguments, lets sort it out... There are basically three modes of |
1255 | operation, and we will explain them from simplest to complex: |
1256 | operation, and we will explain them from simplest to complex: |
1256 | .RS 4 |
1257 | .RS 4 |
1257 | .IP "* absolute timer (interval = reschedule_cb = 0)" 4 |
1258 | .IP "* absolute timer (at = time, interval = reschedule_cb = 0)" 4 |
1258 | .IX Item "absolute timer (interval = reschedule_cb = 0)" |
1259 | .IX Item "absolute timer (at = time, interval = reschedule_cb = 0)" |
1259 | In this configuration the watcher triggers an event at the wallclock time |
1260 | In this configuration the watcher triggers an event at the wallclock time |
1260 | \&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs, |
1261 | \&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs, |
1261 | that is, if it is to be run at January 1st 2011 then it will run when the |
1262 | that is, if it is to be run at January 1st 2011 then it will run when the |
1262 | system time reaches or surpasses this time. |
1263 | system time reaches or surpasses this time. |
1263 | .IP "* non-repeating interval timer (interval > 0, reschedule_cb = 0)" 4 |
1264 | .IP "* non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)" 4 |
1264 | .IX Item "non-repeating interval timer (interval > 0, reschedule_cb = 0)" |
1265 | .IX Item "non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)" |
1265 | In this mode the watcher will always be scheduled to time out at the next |
1266 | In this mode the watcher will always be scheduled to time out at the next |
1266 | \&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N) and then repeat, regardless |
1267 | \&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative) |
1267 | of any time jumps. |
1268 | and then repeat, regardless of any time jumps. |
1268 | .Sp |
1269 | .Sp |
1269 | This can be used to create timers that do not drift with respect to system |
1270 | This can be used to create timers that do not drift with respect to system |
1270 | time: |
1271 | time: |
1271 | .Sp |
1272 | .Sp |
1272 | .Vb 1 |
1273 | .Vb 1 |
… | |
… | |
1279 | by 3600. |
1280 | by 3600. |
1280 | .Sp |
1281 | .Sp |
1281 | Another way to think about it (for the mathematically inclined) is that |
1282 | Another way to think about it (for the mathematically inclined) is that |
1282 | \&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible |
1283 | \&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible |
1283 | time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps. |
1284 | time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps. |
|
|
1285 | .Sp |
|
|
1286 | For numerical stability it is preferable that the \f(CW\*(C`at\*(C'\fR value is near |
|
|
1287 | \&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for |
|
|
1288 | this value. |
1284 | .IP "* manual reschedule mode (reschedule_cb = callback)" 4 |
1289 | .IP "* manual reschedule mode (at and interval ignored, reschedule_cb = callback)" 4 |
1285 | .IX Item "manual reschedule mode (reschedule_cb = callback)" |
1290 | .IX Item "manual reschedule mode (at and interval ignored, reschedule_cb = callback)" |
1286 | In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being |
1291 | In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being |
1287 | ignored. Instead, each time the periodic watcher gets scheduled, the |
1292 | ignored. Instead, each time the periodic watcher gets scheduled, the |
1288 | reschedule callback will be called with the watcher as first, and the |
1293 | reschedule callback will be called with the watcher as first, and the |
1289 | current time as second argument. |
1294 | current time as second argument. |
1290 | .Sp |
1295 | .Sp |
1291 | \&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, |
1296 | \&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, |
1292 | ever, or make any event loop modifications\fR. If you need to stop it, |
1297 | ever, or make any event loop modifications\fR. If you need to stop it, |
1293 | return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop it afterwards (e.g. by |
1298 | return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop it afterwards (e.g. by |
1294 | starting a prepare watcher). |
1299 | starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is legal). |
1295 | .Sp |
1300 | .Sp |
1296 | Its prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic *w, |
1301 | Its prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic *w, |
1297 | ev_tstamp now)\*(C'\fR, e.g.: |
1302 | ev_tstamp now)\*(C'\fR, e.g.: |
1298 | .Sp |
1303 | .Sp |
1299 | .Vb 4 |
1304 | .Vb 4 |
… | |
… | |
1323 | .IX Item "ev_periodic_again (loop, ev_periodic *)" |
1328 | .IX Item "ev_periodic_again (loop, ev_periodic *)" |
1324 | Simply stops and restarts the periodic watcher again. This is only useful |
1329 | Simply stops and restarts the periodic watcher again. This is only useful |
1325 | when you changed some parameters or the reschedule callback would return |
1330 | when you changed some parameters or the reschedule callback would return |
1326 | a different time than the last time it was called (e.g. in a crond like |
1331 | a different time than the last time it was called (e.g. in a crond like |
1327 | program when the crontabs have changed). |
1332 | program when the crontabs have changed). |
|
|
1333 | .IP "ev_tstamp offset [read\-write]" 4 |
|
|
1334 | .IX Item "ev_tstamp offset [read-write]" |
|
|
1335 | When repeating, this contains the offset value, otherwise this is the |
|
|
1336 | absolute point in time (the \f(CW\*(C`at\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR). |
|
|
1337 | .Sp |
|
|
1338 | Can be modified any time, but changes only take effect when the periodic |
|
|
1339 | timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. |
1328 | .IP "ev_tstamp interval [read\-write]" 4 |
1340 | .IP "ev_tstamp interval [read\-write]" 4 |
1329 | .IX Item "ev_tstamp interval [read-write]" |
1341 | .IX Item "ev_tstamp interval [read-write]" |
1330 | The current interval value. Can be modified any time, but changes only |
1342 | The current interval value. Can be modified any time, but changes only |
1331 | take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being |
1343 | take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being |
1332 | called. |
1344 | called. |
… | |
… | |
1634 | are ready to run (it's actually more complicated: it only runs coroutines |
1646 | are ready to run (it's actually more complicated: it only runs coroutines |
1635 | with priority higher than or equal to the event loop and one coroutine |
1647 | with priority higher than or equal to the event loop and one coroutine |
1636 | of lower priority, but only once, using idle watchers to keep the event |
1648 | of lower priority, but only once, using idle watchers to keep the event |
1637 | loop from blocking if lower-priority coroutines are active, thus mapping |
1649 | loop from blocking if lower-priority coroutines are active, thus mapping |
1638 | low-priority coroutines to idle/background tasks). |
1650 | low-priority coroutines to idle/background tasks). |
|
|
1651 | .PP |
|
|
1652 | It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) |
|
|
1653 | priority, to ensure that they are being run before any other watchers |
|
|
1654 | after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, |
|
|
1655 | too) should not activate (\*(L"feed\*(R") events into libev. While libev fully |
|
|
1656 | supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers did |
|
|
1657 | their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other event |
|
|
1658 | loops those other event loops might be in an unusable state until their |
|
|
1659 | \&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with |
|
|
1660 | others). |
1639 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
1661 | .IP "ev_prepare_init (ev_prepare *, callback)" 4 |
1640 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
1662 | .IX Item "ev_prepare_init (ev_prepare *, callback)" |
1641 | .PD 0 |
1663 | .PD 0 |
1642 | .IP "ev_check_init (ev_check *, callback)" 4 |
1664 | .IP "ev_check_init (ev_check *, callback)" 4 |
1643 | .IX Item "ev_check_init (ev_check *, callback)" |
1665 | .IX Item "ev_check_init (ev_check *, callback)" |