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

Comparing libev/ev.pod (file contents):
Revision 1.194 by root, Mon Oct 20 16:08:36 2008 UTC vs.
Revision 1.199 by root, Thu Oct 23 07:18:21 2008 UTC

17 ev_timer timeout_watcher; 17 ev_timer timeout_watcher;
18 18
19 // all watcher callbacks have a similar signature 19 // all watcher callbacks have a similar signature
20 // this callback is called when data is readable on stdin 20 // this callback is called when data is readable on stdin
21 static void 21 static void
22 stdin_cb (EV_P_ struct ev_io *w, int revents) 22 stdin_cb (EV_P_ ev_io *w, int revents)
23 { 23 {
24 puts ("stdin ready"); 24 puts ("stdin ready");
25 // for one-shot events, one must manually stop the watcher 25 // for one-shot events, one must manually stop the watcher
26 // with its corresponding stop function. 26 // with its corresponding stop function.
27 ev_io_stop (EV_A_ w); 27 ev_io_stop (EV_A_ w);
30 ev_unloop (EV_A_ EVUNLOOP_ALL); 30 ev_unloop (EV_A_ EVUNLOOP_ALL);
31 } 31 }
32 32
33 // another callback, this time for a time-out 33 // another callback, this time for a time-out
34 static void 34 static void
35 timeout_cb (EV_P_ struct ev_timer *w, int revents) 35 timeout_cb (EV_P_ ev_timer *w, int revents)
36 { 36 {
37 puts ("timeout"); 37 puts ("timeout");
38 // this causes the innermost ev_loop to stop iterating 38 // this causes the innermost ev_loop to stop iterating
39 ev_unloop (EV_A_ EVUNLOOP_ONE); 39 ev_unloop (EV_A_ EVUNLOOP_ONE);
40 } 40 }
41 41
42 int 42 int
43 main (void) 43 main (void)
44 { 44 {
45 // use the default event loop unless you have special needs 45 // use the default event loop unless you have special needs
46 struct ev_loop *loop = ev_default_loop (0); 46 ev_loop *loop = ev_default_loop (0);
47 47
48 // initialise an io watcher, then start it 48 // initialise an io watcher, then start it
49 // this one will watch for stdin to become readable 49 // this one will watch for stdin to become readable
50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
51 ev_io_start (loop, &stdin_watcher); 51 ev_io_start (loop, &stdin_watcher);
103Libev is very configurable. In this manual the default (and most common) 103Libev is very configurable. In this manual the default (and most common)
104configuration will be described, which supports multiple event loops. For 104configuration will be described, which supports multiple event loops. For
105more info about various configuration options please have a look at 105more info about various configuration options please have a look at
106B<EMBED> section in this manual. If libev was configured without support 106B<EMBED> section in this manual. If libev was configured without support
107for multiple event loops, then all functions taking an initial argument of 107for multiple event loops, then all functions taking an initial argument of
108name C<loop> (which is always of type C<struct ev_loop *>) will not have 108name C<loop> (which is always of type C<ev_loop *>) will not have
109this argument. 109this argument.
110 110
111=head2 TIME REPRESENTATION 111=head2 TIME REPRESENTATION
112 112
113Libev represents time as a single floating point number, representing the 113Libev represents time as a single floating point number, representing the
276 276
277=back 277=back
278 278
279=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 279=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
280 280
281An event loop is described by a C<struct ev_loop *>. The library knows two 281An event loop is described by a C<ev_loop *>. The library knows two
282types of such loops, the I<default> loop, which supports signals and child 282types of such loops, the I<default> loop, which supports signals and child
283events, and dynamically created loops which do not. 283events, and dynamically created loops which do not.
284 284
285=over 4 285=over 4
286 286
710respectively). 710respectively).
711 711
712Example: Create a signal watcher, but keep it from keeping C<ev_loop> 712Example: Create a signal watcher, but keep it from keeping C<ev_loop>
713running when nothing else is active. 713running when nothing else is active.
714 714
715 struct ev_signal exitsig; 715 ev_signal exitsig;
716 ev_signal_init (&exitsig, sig_cb, SIGINT); 716 ev_signal_init (&exitsig, sig_cb, SIGINT);
717 ev_signal_start (loop, &exitsig); 717 ev_signal_start (loop, &exitsig);
718 evf_unref (loop); 718 evf_unref (loop);
719 719
720Example: For some weird reason, unregister the above signal handler again. 720Example: For some weird reason, unregister the above signal handler again.
786 786
787A watcher is a structure that you create and register to record your 787A watcher is a structure that you create and register to record your
788interest in some event. For instance, if you want to wait for STDIN to 788interest in some event. For instance, if you want to wait for STDIN to
789become readable, you would create an C<ev_io> watcher for that: 789become readable, you would create an C<ev_io> watcher for that:
790 790
791 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 791 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
792 { 792 {
793 ev_io_stop (w); 793 ev_io_stop (w);
794 ev_unloop (loop, EVUNLOOP_ALL); 794 ev_unloop (loop, EVUNLOOP_ALL);
795 } 795 }
796 796
797 struct ev_loop *loop = ev_default_loop (0); 797 struct ev_loop *loop = ev_default_loop (0);
798 struct ev_io stdin_watcher; 798 ev_io stdin_watcher;
799 ev_init (&stdin_watcher, my_cb); 799 ev_init (&stdin_watcher, my_cb);
800 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 800 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
801 ev_io_start (loop, &stdin_watcher); 801 ev_io_start (loop, &stdin_watcher);
802 ev_loop (loop, 0); 802 ev_loop (loop, 0);
803 803
894=item C<EV_ERROR> 894=item C<EV_ERROR>
895 895
896An unspecified error has occurred, the watcher has been stopped. This might 896An unspecified error has occurred, the watcher has been stopped. This might
897happen because the watcher could not be properly started because libev 897happen because the watcher could not be properly started because libev
898ran out of memory, a file descriptor was found to be closed or any other 898ran out of memory, a file descriptor was found to be closed or any other
899problem. Libev considers these application bugs.
900
899problem. You best act on it by reporting the problem and somehow coping 901You best act on it by reporting the problem and somehow coping with the
900with the watcher being stopped. 902watcher being stopped. Note that well-written programs should not receive
903an error ever, so when your watcher receives it, this usually indicates a
904bug in your program.
901 905
902Libev will usually signal a few "dummy" events together with an error, for 906Libev will usually signal a few "dummy" events together with an error, for
903example it might indicate that a fd is readable or writable, and if your 907example it might indicate that a fd is readable or writable, and if your
904callbacks is well-written it can just attempt the operation and cope with 908callbacks is well-written it can just attempt the operation and cope with
905the error from read() or write(). This will not work in multi-threaded 909the error from read() or write(). This will not work in multi-threaded
925which rolls both calls into one. 929which rolls both calls into one.
926 930
927You can reinitialise a watcher at any time as long as it has been stopped 931You can reinitialise a watcher at any time as long as it has been stopped
928(or never started) and there are no pending events outstanding. 932(or never started) and there are no pending events outstanding.
929 933
930The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher, 934The callback is always of type C<void (*)(struct ev_loop *loop, ev_TYPE *watcher,
931int revents)>. 935int revents)>.
932 936
933Example: Initialise an C<ev_io> watcher in two steps. 937Example: Initialise an C<ev_io> watcher in two steps.
934 938
935 ev_io w; 939 ev_io w;
969 973
970 ev_io_start (EV_DEFAULT_UC, &w); 974 ev_io_start (EV_DEFAULT_UC, &w);
971 975
972=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 976=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
973 977
974Stops the given watcher again (if active) and clears the pending 978Stops the given watcher if active, and clears the pending status (whether
979the watcher was active or not).
980
975status. It is possible that stopped watchers are pending (for example, 981It is possible that stopped watchers are pending - for example,
976non-repeating timers are being stopped when they become pending), but 982non-repeating timers are being stopped when they become pending - but
977C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If 983calling C<ev_TYPE_stop> ensures that the watcher is neither active nor
978you want to free or reuse the memory used by the watcher it is therefore a 984pending. If you want to free or reuse the memory used by the watcher it is
979good idea to always call its C<ev_TYPE_stop> function. 985therefore a good idea to always call its C<ev_TYPE_stop> function.
980 986
981=item bool ev_is_active (ev_TYPE *watcher) 987=item bool ev_is_active (ev_TYPE *watcher)
982 988
983Returns a true value iff the watcher is active (i.e. it has been started 989Returns a true value iff the watcher is active (i.e. it has been started
984and not yet been stopped). As long as a watcher is active you must not modify 990and not yet been stopped). As long as a watcher is active you must not modify
1058member, you can also "subclass" the watcher type and provide your own 1064member, you can also "subclass" the watcher type and provide your own
1059data: 1065data:
1060 1066
1061 struct my_io 1067 struct my_io
1062 { 1068 {
1063 struct ev_io io; 1069 ev_io io;
1064 int otherfd; 1070 int otherfd;
1065 void *somedata; 1071 void *somedata;
1066 struct whatever *mostinteresting; 1072 struct whatever *mostinteresting;
1067 }; 1073 };
1068 1074
1071 ev_io_init (&w.io, my_cb, fd, EV_READ); 1077 ev_io_init (&w.io, my_cb, fd, EV_READ);
1072 1078
1073And since your callback will be called with a pointer to the watcher, you 1079And since your callback will be called with a pointer to the watcher, you
1074can cast it back to your own type: 1080can cast it back to your own type:
1075 1081
1076 static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) 1082 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
1077 { 1083 {
1078 struct my_io *w = (struct my_io *)w_; 1084 struct my_io *w = (struct my_io *)w_;
1079 ... 1085 ...
1080 } 1086 }
1081 1087
1099programmers): 1105programmers):
1100 1106
1101 #include <stddef.h> 1107 #include <stddef.h>
1102 1108
1103 static void 1109 static void
1104 t1_cb (EV_P_ struct ev_timer *w, int revents) 1110 t1_cb (EV_P_ ev_timer *w, int revents)
1105 { 1111 {
1106 struct my_biggy big = (struct my_biggy * 1112 struct my_biggy big = (struct my_biggy *
1107 (((char *)w) - offsetof (struct my_biggy, t1)); 1113 (((char *)w) - offsetof (struct my_biggy, t1));
1108 } 1114 }
1109 1115
1110 static void 1116 static void
1111 t2_cb (EV_P_ struct ev_timer *w, int revents) 1117 t2_cb (EV_P_ ev_timer *w, int revents)
1112 { 1118 {
1113 struct my_biggy big = (struct my_biggy * 1119 struct my_biggy big = (struct my_biggy *
1114 (((char *)w) - offsetof (struct my_biggy, t2)); 1120 (((char *)w) - offsetof (struct my_biggy, t2));
1115 } 1121 }
1116 1122
1251Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well 1257Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
1252readable, but only once. Since it is likely line-buffered, you could 1258readable, but only once. Since it is likely line-buffered, you could
1253attempt to read a whole line in the callback. 1259attempt to read a whole line in the callback.
1254 1260
1255 static void 1261 static void
1256 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1262 stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents)
1257 { 1263 {
1258 ev_io_stop (loop, w); 1264 ev_io_stop (loop, w);
1259 .. read from stdin here (or from w->fd) and handle any I/O errors 1265 .. read from stdin here (or from w->fd) and handle any I/O errors
1260 } 1266 }
1261 1267
1262 ... 1268 ...
1263 struct ev_loop *loop = ev_default_init (0); 1269 struct ev_loop *loop = ev_default_init (0);
1264 struct ev_io stdin_readable; 1270 ev_io stdin_readable;
1265 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1271 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1266 ev_io_start (loop, &stdin_readable); 1272 ev_io_start (loop, &stdin_readable);
1267 ev_loop (loop, 0); 1273 ev_loop (loop, 0);
1268 1274
1269 1275
1280 1286
1281The callback is guaranteed to be invoked only I<after> its timeout has 1287The callback is guaranteed to be invoked only I<after> its timeout has
1282passed, but if multiple timers become ready during the same loop iteration 1288passed, but if multiple timers become ready during the same loop iteration
1283then order of execution is undefined. 1289then order of execution is undefined.
1284 1290
1291=head3 Be smart about timeouts
1292
1293Many real-world problems involve some kind of timeout, usually for error
1294recovery. A typical example is an HTTP request - if the other side hangs,
1295you want to raise some error after a while.
1296
1297What follows are some ways to handle this problem, from obvious and
1298inefficient to smart and efficient.
1299
1300In the following, a 60 second activity timeout is assumed - a timeout that
1301gets reset to 60 seconds each time there is activity (e.g. each time some
1302data or other life sign was received).
1303
1304=over 4
1305
1306=item 1. Use a timer and stop, reinitialise and start it on activity.
1307
1308This is the most obvious, but not the most simple way: In the beginning,
1309start the watcher:
1310
1311 ev_timer_init (timer, callback, 60., 0.);
1312 ev_timer_start (loop, timer);
1313
1314Then, each time there is some activity, C<ev_timer_stop> it, initialise it
1315and start it again:
1316
1317 ev_timer_stop (loop, timer);
1318 ev_timer_set (timer, 60., 0.);
1319 ev_timer_start (loop, timer);
1320
1321This is relatively simple to implement, but means that each time there is
1322some activity, libev will first have to remove the timer from its internal
1323data structure and then add it again. Libev tries to be fast, but it's
1324still not a constant-time operation.
1325
1326=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity.
1327
1328This is the easiest way, and involves using C<ev_timer_again> instead of
1329C<ev_timer_start>.
1330
1331To implement this, configure an C<ev_timer> with a C<repeat> value
1332of C<60> and then call C<ev_timer_again> at start and each time you
1333successfully read or write some data. If you go into an idle state where
1334you do not expect data to travel on the socket, you can C<ev_timer_stop>
1335the timer, and C<ev_timer_again> will automatically restart it if need be.
1336
1337That means you can ignore both the C<ev_timer_start> function and the
1338C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1339member and C<ev_timer_again>.
1340
1341At start:
1342
1343 ev_timer_init (timer, callback);
1344 timer->repeat = 60.;
1345 ev_timer_again (loop, timer);
1346
1347Each time there is some activity:
1348
1349 ev_timer_again (loop, timer);
1350
1351It is even possible to change the time-out on the fly, regardless of
1352whether the watcher is active or not:
1353
1354 timer->repeat = 30.;
1355 ev_timer_again (loop, timer);
1356
1357This is slightly more efficient then stopping/starting the timer each time
1358you want to modify its timeout value, as libev does not have to completely
1359remove and re-insert the timer from/into its internal data structure.
1360
1361It is, however, even simpler than the "obvious" way to do it.
1362
1363=item 3. Let the timer time out, but then re-arm it as required.
1364
1365This method is more tricky, but usually most efficient: Most timeouts are
1366relatively long compared to the intervals between other activity - in
1367our example, within 60 seconds, there are usually many I/O events with
1368associated activity resets.
1369
1370In this case, it would be more efficient to leave the C<ev_timer> alone,
1371but remember the time of last activity, and check for a real timeout only
1372within the callback:
1373
1374 ev_tstamp last_activity; // time of last activity
1375
1376 static void
1377 callback (EV_P_ ev_timer *w, int revents)
1378 {
1379 ev_tstamp now = ev_now (EV_A);
1380 ev_tstamp timeout = last_activity + 60.;
1381
1382 // if last_activity + 60. is older than now, we did time out
1383 if (timeout < now)
1384 {
1385 // timeout occured, take action
1386 }
1387 else
1388 {
1389 // callback was invoked, but there was some activity, re-arm
1390 // the watcher to fire in last_activity + 60, which is
1391 // guaranteed to be in the future, so "again" is positive:
1392 w->again = timeout - now;
1393 ev_timer_again (EV_A_ w);
1394 }
1395 }
1396
1397To summarise the callback: first calculate the real timeout (defined
1398as "60 seconds after the last activity"), then check if that time has
1399been reached, which means something I<did>, in fact, time out. Otherwise
1400the callback was invoked too early (C<timeout> is in the future), so
1401re-schedule the timer to fire at that future time, to see if maybe we have
1402a timeout then.
1403
1404Note how C<ev_timer_again> is used, taking advantage of the
1405C<ev_timer_again> optimisation when the timer is already running.
1406
1407This scheme causes more callback invocations (about one every 60 seconds
1408minus half the average time between activity), but virtually no calls to
1409libev to change the timeout.
1410
1411To start the timer, simply initialise the watcher and set C<last_activity>
1412to the current time (meaning we just have some activity :), then call the
1413callback, which will "do the right thing" and start the timer:
1414
1415 ev_timer_init (timer, callback);
1416 last_activity = ev_now (loop);
1417 callback (loop, timer, EV_TIMEOUT);
1418
1419And when there is some activity, simply store the current time in
1420C<last_activity>, no libev calls at all:
1421
1422 last_actiivty = ev_now (loop);
1423
1424This technique is slightly more complex, but in most cases where the
1425time-out is unlikely to be triggered, much more efficient.
1426
1427Changing the timeout is trivial as well (if it isn't hard-coded in the
1428callback :) - just change the timeout and invoke the callback, which will
1429fix things for you.
1430
1431=item 4. Whee, use a double-linked list for your timeouts.
1432
1433If there is not one request, but many thousands, all employing some kind
1434of timeout with the same timeout value, then one can do even better:
1435
1436When starting the timeout, calculate the timeout value and put the timeout
1437at the I<end> of the list.
1438
1439Then use an C<ev_timer> to fire when the timeout at the I<beginning> of
1440the list is expected to fire (for example, using the technique #3).
1441
1442When there is some activity, remove the timer from the list, recalculate
1443the timeout, append it to the end of the list again, and make sure to
1444update the C<ev_timer> if it was taken from the beginning of the list.
1445
1446This way, one can manage an unlimited number of timeouts in O(1) time for
1447starting, stopping and updating the timers, at the expense of a major
1448complication, and having to use a constant timeout. The constant timeout
1449ensures that the list stays sorted.
1450
1451=back
1452
1453So what method is the best?
1454
1455The method #2 is a simple no-brain-required solution that is adequate in
1456most situations. Method #3 requires a bit more thinking, but handles many
1457cases better, and isn't very complicated either. In most case, choosing
1458either one is fine.
1459
1460Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1461rather complicated, but extremely efficient, something that really pays
1462off after the first or so million of active timers, i.e. it's usually
1463overkill :)
1464
1285=head3 The special problem of time updates 1465=head3 The special problem of time updates
1286 1466
1287Establishing the current time is a costly operation (it usually takes at 1467Establishing the current time is a costly operation (it usually takes at
1288least two system calls): EV therefore updates its idea of the current 1468least two system calls): EV therefore updates its idea of the current
1289time only before and after C<ev_loop> collects new events, which causes a 1469time only before and after C<ev_loop> collects new events, which causes a
1332If the timer is started but non-repeating, stop it (as if it timed out). 1512If the timer is started but non-repeating, stop it (as if it timed out).
1333 1513
1334If the timer is repeating, either start it if necessary (with the 1514If the timer is repeating, either start it if necessary (with the
1335C<repeat> value), or reset the running timer to the C<repeat> value. 1515C<repeat> value), or reset the running timer to the C<repeat> value.
1336 1516
1337This sounds a bit complicated, but here is a useful and typical 1517This sounds a bit complicated, see "Be smart about timeouts", above, for a
1338example: Imagine you have a TCP connection and you want a so-called idle 1518usage example.
1339timeout, that is, you want to be called when there have been, say, 60
1340seconds of inactivity on the socket. The easiest way to do this is to
1341configure an C<ev_timer> with a C<repeat> value of C<60> and then call
1342C<ev_timer_again> each time you successfully read or write some data. If
1343you go into an idle state where you do not expect data to travel on the
1344socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
1345automatically restart it if need be.
1346
1347That means you can ignore the C<after> value and C<ev_timer_start>
1348altogether and only ever use the C<repeat> value and C<ev_timer_again>:
1349
1350 ev_timer_init (timer, callback, 0., 5.);
1351 ev_timer_again (loop, timer);
1352 ...
1353 timer->again = 17.;
1354 ev_timer_again (loop, timer);
1355 ...
1356 timer->again = 10.;
1357 ev_timer_again (loop, timer);
1358
1359This is more slightly efficient then stopping/starting the timer each time
1360you want to modify its timeout value.
1361
1362Note, however, that it is often even more efficient to remember the
1363time of the last activity and let the timer time-out naturally. In the
1364callback, you then check whether the time-out is real, or, if there was
1365some activity, you reschedule the watcher to time-out in "last_activity +
1366timeout - ev_now ()" seconds.
1367 1519
1368=item ev_tstamp repeat [read-write] 1520=item ev_tstamp repeat [read-write]
1369 1521
1370The current C<repeat> value. Will be used each time the watcher times out 1522The current C<repeat> value. Will be used each time the watcher times out
1371or C<ev_timer_again> is called, and determines the next timeout (if any), 1523or C<ev_timer_again> is called, and determines the next timeout (if any),
1376=head3 Examples 1528=head3 Examples
1377 1529
1378Example: Create a timer that fires after 60 seconds. 1530Example: Create a timer that fires after 60 seconds.
1379 1531
1380 static void 1532 static void
1381 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1533 one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents)
1382 { 1534 {
1383 .. one minute over, w is actually stopped right here 1535 .. one minute over, w is actually stopped right here
1384 } 1536 }
1385 1537
1386 struct ev_timer mytimer; 1538 ev_timer mytimer;
1387 ev_timer_init (&mytimer, one_minute_cb, 60., 0.); 1539 ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1388 ev_timer_start (loop, &mytimer); 1540 ev_timer_start (loop, &mytimer);
1389 1541
1390Example: Create a timeout timer that times out after 10 seconds of 1542Example: Create a timeout timer that times out after 10 seconds of
1391inactivity. 1543inactivity.
1392 1544
1393 static void 1545 static void
1394 timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1546 timeout_cb (struct ev_loop *loop, ev_timer *w, int revents)
1395 { 1547 {
1396 .. ten seconds without any activity 1548 .. ten seconds without any activity
1397 } 1549 }
1398 1550
1399 struct ev_timer mytimer; 1551 ev_timer mytimer;
1400 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 1552 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1401 ev_timer_again (&mytimer); /* start timer */ 1553 ev_timer_again (&mytimer); /* start timer */
1402 ev_loop (loop, 0); 1554 ev_loop (loop, 0);
1403 1555
1404 // and in some piece of code that gets executed on any "activity": 1556 // and in some piece of code that gets executed on any "activity":
1490 1642
1491If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 1643If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1492it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 1644it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1493only event loop modification you are allowed to do). 1645only event loop modification you are allowed to do).
1494 1646
1495The callback prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic 1647The callback prototype is C<ev_tstamp (*reschedule_cb)(ev_periodic
1496*w, ev_tstamp now)>, e.g.: 1648*w, ev_tstamp now)>, e.g.:
1497 1649
1650 static ev_tstamp
1498 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1651 my_rescheduler (ev_periodic *w, ev_tstamp now)
1499 { 1652 {
1500 return now + 60.; 1653 return now + 60.;
1501 } 1654 }
1502 1655
1503It must return the next time to trigger, based on the passed time value 1656It must return the next time to trigger, based on the passed time value
1540 1693
1541The current interval value. Can be modified any time, but changes only 1694The current interval value. Can be modified any time, but changes only
1542take effect when the periodic timer fires or C<ev_periodic_again> is being 1695take effect when the periodic timer fires or C<ev_periodic_again> is being
1543called. 1696called.
1544 1697
1545=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] 1698=item ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]
1546 1699
1547The current reschedule callback, or C<0>, if this functionality is 1700The current reschedule callback, or C<0>, if this functionality is
1548switched off. Can be changed any time, but changes only take effect when 1701switched off. Can be changed any time, but changes only take effect when
1549the periodic timer fires or C<ev_periodic_again> is being called. 1702the periodic timer fires or C<ev_periodic_again> is being called.
1550 1703
1555Example: Call a callback every hour, or, more precisely, whenever the 1708Example: Call a callback every hour, or, more precisely, whenever the
1556system time is divisible by 3600. The callback invocation times have 1709system time is divisible by 3600. The callback invocation times have
1557potentially a lot of jitter, but good long-term stability. 1710potentially a lot of jitter, but good long-term stability.
1558 1711
1559 static void 1712 static void
1560 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1713 clock_cb (struct ev_loop *loop, ev_io *w, int revents)
1561 { 1714 {
1562 ... its now a full hour (UTC, or TAI or whatever your clock follows) 1715 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1563 } 1716 }
1564 1717
1565 struct ev_periodic hourly_tick; 1718 ev_periodic hourly_tick;
1566 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); 1719 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1567 ev_periodic_start (loop, &hourly_tick); 1720 ev_periodic_start (loop, &hourly_tick);
1568 1721
1569Example: The same as above, but use a reschedule callback to do it: 1722Example: The same as above, but use a reschedule callback to do it:
1570 1723
1571 #include <math.h> 1724 #include <math.h>
1572 1725
1573 static ev_tstamp 1726 static ev_tstamp
1574 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 1727 my_scheduler_cb (ev_periodic *w, ev_tstamp now)
1575 { 1728 {
1576 return now + (3600. - fmod (now, 3600.)); 1729 return now + (3600. - fmod (now, 3600.));
1577 } 1730 }
1578 1731
1579 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); 1732 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1580 1733
1581Example: Call a callback every hour, starting now: 1734Example: Call a callback every hour, starting now:
1582 1735
1583 struct ev_periodic hourly_tick; 1736 ev_periodic hourly_tick;
1584 ev_periodic_init (&hourly_tick, clock_cb, 1737 ev_periodic_init (&hourly_tick, clock_cb,
1585 fmod (ev_now (loop), 3600.), 3600., 0); 1738 fmod (ev_now (loop), 3600.), 3600., 0);
1586 ev_periodic_start (loop, &hourly_tick); 1739 ev_periodic_start (loop, &hourly_tick);
1587 1740
1588 1741
1630=head3 Examples 1783=head3 Examples
1631 1784
1632Example: Try to exit cleanly on SIGINT. 1785Example: Try to exit cleanly on SIGINT.
1633 1786
1634 static void 1787 static void
1635 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1788 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
1636 { 1789 {
1637 ev_unloop (loop, EVUNLOOP_ALL); 1790 ev_unloop (loop, EVUNLOOP_ALL);
1638 } 1791 }
1639 1792
1640 struct ev_signal signal_watcher; 1793 ev_signal signal_watcher;
1641 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1794 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1642 ev_signal_start (loop, &signal_watcher); 1795 ev_signal_start (loop, &signal_watcher);
1643 1796
1644 1797
1645=head2 C<ev_child> - watch out for process status changes 1798=head2 C<ev_child> - watch out for process status changes
1720its completion. 1873its completion.
1721 1874
1722 ev_child cw; 1875 ev_child cw;
1723 1876
1724 static void 1877 static void
1725 child_cb (EV_P_ struct ev_child *w, int revents) 1878 child_cb (EV_P_ ev_child *w, int revents)
1726 { 1879 {
1727 ev_child_stop (EV_A_ w); 1880 ev_child_stop (EV_A_ w);
1728 printf ("process %d exited with status %x\n", w->rpid, w->rstatus); 1881 printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
1729 } 1882 }
1730 1883
1794to exchange stat structures with application programs compiled using the 1947to exchange stat structures with application programs compiled using the
1795default compilation environment. 1948default compilation environment.
1796 1949
1797=head3 Inotify and Kqueue 1950=head3 Inotify and Kqueue
1798 1951
1799When C<inotify (7)> support has been compiled into libev (generally only 1952When C<inotify (7)> support has been compiled into libev (generally
1953only available with Linux 2.6.25 or above due to bugs in earlier
1800available with Linux) and present at runtime, it will be used to speed up 1954implementations) and present at runtime, it will be used to speed up
1801change detection where possible. The inotify descriptor will be created lazily 1955change detection where possible. The inotify descriptor will be created
1802when the first C<ev_stat> watcher is being started. 1956lazily when the first C<ev_stat> watcher is being started.
1803 1957
1804Inotify presence does not change the semantics of C<ev_stat> watchers 1958Inotify presence does not change the semantics of C<ev_stat> watchers
1805except that changes might be detected earlier, and in some cases, to avoid 1959except that changes might be detected earlier, and in some cases, to avoid
1806making regular C<stat> calls. Even in the presence of inotify support 1960making regular C<stat> calls. Even in the presence of inotify support
1807there are many cases where libev has to resort to regular C<stat> polling, 1961there are many cases where libev has to resort to regular C<stat> polling,
1981 2135
1982Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the 2136Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
1983callback, free it. Also, use no error checking, as usual. 2137callback, free it. Also, use no error checking, as usual.
1984 2138
1985 static void 2139 static void
1986 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) 2140 idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
1987 { 2141 {
1988 free (w); 2142 free (w);
1989 // now do something you wanted to do when the program has 2143 // now do something you wanted to do when the program has
1990 // no longer anything immediate to do. 2144 // no longer anything immediate to do.
1991 } 2145 }
1992 2146
1993 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 2147 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
1994 ev_idle_init (idle_watcher, idle_cb); 2148 ev_idle_init (idle_watcher, idle_cb);
1995 ev_idle_start (loop, idle_cb); 2149 ev_idle_start (loop, idle_cb);
1996 2150
1997 2151
1998=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2152=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2079 2233
2080 static ev_io iow [nfd]; 2234 static ev_io iow [nfd];
2081 static ev_timer tw; 2235 static ev_timer tw;
2082 2236
2083 static void 2237 static void
2084 io_cb (ev_loop *loop, ev_io *w, int revents) 2238 io_cb (struct ev_loop *loop, ev_io *w, int revents)
2085 { 2239 {
2086 } 2240 }
2087 2241
2088 // create io watchers for each fd and a timer before blocking 2242 // create io watchers for each fd and a timer before blocking
2089 static void 2243 static void
2090 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 2244 adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents)
2091 { 2245 {
2092 int timeout = 3600000; 2246 int timeout = 3600000;
2093 struct pollfd fds [nfd]; 2247 struct pollfd fds [nfd];
2094 // actual code will need to loop here and realloc etc. 2248 // actual code will need to loop here and realloc etc.
2095 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2249 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2110 } 2264 }
2111 } 2265 }
2112 2266
2113 // stop all watchers after blocking 2267 // stop all watchers after blocking
2114 static void 2268 static void
2115 adns_check_cb (ev_loop *loop, ev_check *w, int revents) 2269 adns_check_cb (struct ev_loop *loop, ev_check *w, int revents)
2116 { 2270 {
2117 ev_timer_stop (loop, &tw); 2271 ev_timer_stop (loop, &tw);
2118 2272
2119 for (int i = 0; i < nfd; ++i) 2273 for (int i = 0; i < nfd; ++i)
2120 { 2274 {
2288C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be 2442C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be
2289used). 2443used).
2290 2444
2291 struct ev_loop *loop_hi = ev_default_init (0); 2445 struct ev_loop *loop_hi = ev_default_init (0);
2292 struct ev_loop *loop_lo = 0; 2446 struct ev_loop *loop_lo = 0;
2293 struct ev_embed embed; 2447 ev_embed embed;
2294 2448
2295 // see if there is a chance of getting one that works 2449 // see if there is a chance of getting one that works
2296 // (remember that a flags value of 0 means autodetection) 2450 // (remember that a flags value of 0 means autodetection)
2297 loop_lo = ev_embeddable_backends () & ev_recommended_backends () 2451 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2298 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 2452 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2312kqueue implementation). Store the kqueue/socket-only event loop in 2466kqueue implementation). Store the kqueue/socket-only event loop in
2313C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). 2467C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
2314 2468
2315 struct ev_loop *loop = ev_default_init (0); 2469 struct ev_loop *loop = ev_default_init (0);
2316 struct ev_loop *loop_socket = 0; 2470 struct ev_loop *loop_socket = 0;
2317 struct ev_embed embed; 2471 ev_embed embed;
2318 2472
2319 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 2473 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2320 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 2474 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2321 { 2475 {
2322 ev_embed_init (&embed, 0, loop_socket); 2476 ev_embed_init (&embed, 0, loop_socket);
2536 /* doh, nothing entered */; 2690 /* doh, nothing entered */;
2537 } 2691 }
2538 2692
2539 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 2693 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2540 2694
2541=item ev_feed_event (ev_loop *, watcher *, int revents) 2695=item ev_feed_event (struct ev_loop *, watcher *, int revents)
2542 2696
2543Feeds the given event set into the event loop, as if the specified event 2697Feeds the given event set into the event loop, as if the specified event
2544had happened for the specified watcher (which must be a pointer to an 2698had happened for the specified watcher (which must be a pointer to an
2545initialised but not necessarily started event watcher). 2699initialised but not necessarily started event watcher).
2546 2700
2547=item ev_feed_fd_event (ev_loop *, int fd, int revents) 2701=item ev_feed_fd_event (struct ev_loop *, int fd, int revents)
2548 2702
2549Feed an event on the given fd, as if a file descriptor backend detected 2703Feed an event on the given fd, as if a file descriptor backend detected
2550the given events it. 2704the given events it.
2551 2705
2552=item ev_feed_signal_event (ev_loop *loop, int signum) 2706=item ev_feed_signal_event (struct ev_loop *loop, int signum)
2553 2707
2554Feed an event as if the given signal occurred (C<loop> must be the default 2708Feed an event as if the given signal occurred (C<loop> must be the default
2555loop!). 2709loop!).
2556 2710
2557=back 2711=back

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines