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

Comparing libev/ev.pod (file contents):
Revision 1.195 by root, Mon Oct 20 17:50:48 2008 UTC vs.
Revision 1.202 by root, Fri Oct 24 08:30:01 2008 UTC

10 10
11 // a single header file is required 11 // a single header file is required
12 #include <ev.h> 12 #include <ev.h>
13 13
14 // every watcher type has its own typedef'd struct 14 // every watcher type has its own typedef'd struct
15 // with the name ev_<type> 15 // with the name ev_TYPE
16 ev_io stdin_watcher; 16 ev_io stdin_watcher;
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<struct ev_loop *> (the C<struct>
282types of such loops, the I<default> loop, which supports signals and child 282is I<not> optional in this case, as there is also an C<ev_loop>
283events, and dynamically created loops which do not. 283I<function>).
284
285The library knows two types of such loops, the I<default> loop, which
286supports signals and child events, and dynamically created loops which do
287not.
284 288
285=over 4 289=over 4
286 290
287=item struct ev_loop *ev_default_loop (unsigned int flags) 291=item struct ev_loop *ev_default_loop (unsigned int flags)
288 292
710respectively). 714respectively).
711 715
712Example: Create a signal watcher, but keep it from keeping C<ev_loop> 716Example: Create a signal watcher, but keep it from keeping C<ev_loop>
713running when nothing else is active. 717running when nothing else is active.
714 718
715 struct ev_signal exitsig; 719 ev_signal exitsig;
716 ev_signal_init (&exitsig, sig_cb, SIGINT); 720 ev_signal_init (&exitsig, sig_cb, SIGINT);
717 ev_signal_start (loop, &exitsig); 721 ev_signal_start (loop, &exitsig);
718 evf_unref (loop); 722 evf_unref (loop);
719 723
720Example: For some weird reason, unregister the above signal handler again. 724Example: For some weird reason, unregister the above signal handler again.
768they fire on, say, one-second boundaries only. 772they fire on, say, one-second boundaries only.
769 773
770=item ev_loop_verify (loop) 774=item ev_loop_verify (loop)
771 775
772This function only does something when C<EV_VERIFY> support has been 776This function only does something when C<EV_VERIFY> support has been
773compiled in. which is the default for non-minimal builds. It tries to go 777compiled in, which is the default for non-minimal builds. It tries to go
774through all internal structures and checks them for validity. If anything 778through all internal structures and checks them for validity. If anything
775is found to be inconsistent, it will print an error message to standard 779is found to be inconsistent, it will print an error message to standard
776error and call C<abort ()>. 780error and call C<abort ()>.
777 781
778This can be used to catch bugs inside libev itself: under normal 782This can be used to catch bugs inside libev itself: under normal
782=back 786=back
783 787
784 788
785=head1 ANATOMY OF A WATCHER 789=head1 ANATOMY OF A WATCHER
786 790
791In the following description, uppercase C<TYPE> in names stands for the
792watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
793watchers and C<ev_io_start> for I/O watchers.
794
787A watcher is a structure that you create and register to record your 795A 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 796interest 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: 797become readable, you would create an C<ev_io> watcher for that:
790 798
791 static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) 799 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
792 { 800 {
793 ev_io_stop (w); 801 ev_io_stop (w);
794 ev_unloop (loop, EVUNLOOP_ALL); 802 ev_unloop (loop, EVUNLOOP_ALL);
795 } 803 }
796 804
797 struct ev_loop *loop = ev_default_loop (0); 805 struct ev_loop *loop = ev_default_loop (0);
806
798 struct ev_io stdin_watcher; 807 ev_io stdin_watcher;
808
799 ev_init (&stdin_watcher, my_cb); 809 ev_init (&stdin_watcher, my_cb);
800 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 810 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
801 ev_io_start (loop, &stdin_watcher); 811 ev_io_start (loop, &stdin_watcher);
812
802 ev_loop (loop, 0); 813 ev_loop (loop, 0);
803 814
804As you can see, you are responsible for allocating the memory for your 815As you can see, you are responsible for allocating the memory for your
805watcher structures (and it is usually a bad idea to do this on the stack, 816watcher structures (and it is I<usually> a bad idea to do this on the
806although this can sometimes be quite valid). 817stack).
818
819Each watcher has an associated watcher structure (called C<struct ev_TYPE>
820or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
807 821
808Each watcher structure must be initialised by a call to C<ev_init 822Each watcher structure must be initialised by a call to C<ev_init
809(watcher *, callback)>, which expects a callback to be provided. This 823(watcher *, callback)>, which expects a callback to be provided. This
810callback gets invoked each time the event occurs (or, in the case of I/O 824callback gets invoked each time the event occurs (or, in the case of I/O
811watchers, each time the event loop detects that the file descriptor given 825watchers, each time the event loop detects that the file descriptor given
812is readable and/or writable). 826is readable and/or writable).
813 827
814Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 828Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
815with arguments specific to this watcher type. There is also a macro 829macro to configure it, with arguments specific to the watcher type. There
816to combine initialisation and setting in one call: C<< ev_<type>_init 830is also a macro to combine initialisation and setting in one call: C<<
817(watcher *, callback, ...) >>. 831ev_TYPE_init (watcher *, callback, ...) >>.
818 832
819To make the watcher actually watch out for events, you have to start it 833To make the watcher actually watch out for events, you have to start it
820with a watcher-specific start function (C<< ev_<type>_start (loop, watcher 834with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
821*) >>), and you can stop watching for events at any time by calling the 835*) >>), and you can stop watching for events at any time by calling the
822corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>. 836corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
823 837
824As long as your watcher is active (has been started but not stopped) you 838As long as your watcher is active (has been started but not stopped) you
825must not touch the values stored in it. Most specifically you must never 839must not touch the values stored in it. Most specifically you must never
826reinitialise it or call its C<set> macro. 840reinitialise it or call its C<ev_TYPE_set> macro.
827 841
828Each and every callback receives the event loop pointer as first, the 842Each and every callback receives the event loop pointer as first, the
829registered watcher structure as second, and a bitset of received events as 843registered watcher structure as second, and a bitset of received events as
830third argument. 844third argument.
831 845
894=item C<EV_ERROR> 908=item C<EV_ERROR>
895 909
896An unspecified error has occurred, the watcher has been stopped. This might 910An unspecified error has occurred, the watcher has been stopped. This might
897happen because the watcher could not be properly started because libev 911happen 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 912ran out of memory, a file descriptor was found to be closed or any other
913problem. Libev considers these application bugs.
914
899problem. You best act on it by reporting the problem and somehow coping 915You best act on it by reporting the problem and somehow coping with the
900with the watcher being stopped. 916watcher being stopped. Note that well-written programs should not receive
917an error ever, so when your watcher receives it, this usually indicates a
918bug in your program.
901 919
902Libev will usually signal a few "dummy" events together with an error, for 920Libev 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 921example 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 922callbacks 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 923the error from read() or write(). This will not work in multi-threaded
908 926
909=back 927=back
910 928
911=head2 GENERIC WATCHER FUNCTIONS 929=head2 GENERIC WATCHER FUNCTIONS
912 930
913In the following description, C<TYPE> stands for the watcher type,
914e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
915
916=over 4 931=over 4
917 932
918=item C<ev_init> (ev_TYPE *watcher, callback) 933=item C<ev_init> (ev_TYPE *watcher, callback)
919 934
920This macro initialises the generic portion of a watcher. The contents 935This macro initialises the generic portion of a watcher. The contents
925which rolls both calls into one. 940which rolls both calls into one.
926 941
927You can reinitialise a watcher at any time as long as it has been stopped 942You 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. 943(or never started) and there are no pending events outstanding.
929 944
930The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher, 945The callback is always of type C<void (*)(struct ev_loop *loop, ev_TYPE *watcher,
931int revents)>. 946int revents)>.
932 947
933Example: Initialise an C<ev_io> watcher in two steps. 948Example: Initialise an C<ev_io> watcher in two steps.
934 949
935 ev_io w; 950 ev_io w;
1028The default priority used by watchers when no priority has been set is 1043The default priority used by watchers when no priority has been set is
1029always C<0>, which is supposed to not be too high and not be too low :). 1044always C<0>, which is supposed to not be too high and not be too low :).
1030 1045
1031Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1046Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1032fine, as long as you do not mind that the priority value you query might 1047fine, as long as you do not mind that the priority value you query might
1033or might not have been adjusted to be within valid range. 1048or might not have been clamped to the valid range.
1034 1049
1035=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1050=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1036 1051
1037Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1052Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1038C<loop> nor C<revents> need to be valid as long as the watcher callback 1053C<loop> nor C<revents> need to be valid as long as the watcher callback
1060member, you can also "subclass" the watcher type and provide your own 1075member, you can also "subclass" the watcher type and provide your own
1061data: 1076data:
1062 1077
1063 struct my_io 1078 struct my_io
1064 { 1079 {
1065 struct ev_io io; 1080 ev_io io;
1066 int otherfd; 1081 int otherfd;
1067 void *somedata; 1082 void *somedata;
1068 struct whatever *mostinteresting; 1083 struct whatever *mostinteresting;
1069 }; 1084 };
1070 1085
1073 ev_io_init (&w.io, my_cb, fd, EV_READ); 1088 ev_io_init (&w.io, my_cb, fd, EV_READ);
1074 1089
1075And since your callback will be called with a pointer to the watcher, you 1090And since your callback will be called with a pointer to the watcher, you
1076can cast it back to your own type: 1091can cast it back to your own type:
1077 1092
1078 static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) 1093 static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
1079 { 1094 {
1080 struct my_io *w = (struct my_io *)w_; 1095 struct my_io *w = (struct my_io *)w_;
1081 ... 1096 ...
1082 } 1097 }
1083 1098
1101programmers): 1116programmers):
1102 1117
1103 #include <stddef.h> 1118 #include <stddef.h>
1104 1119
1105 static void 1120 static void
1106 t1_cb (EV_P_ struct ev_timer *w, int revents) 1121 t1_cb (EV_P_ ev_timer *w, int revents)
1107 { 1122 {
1108 struct my_biggy big = (struct my_biggy * 1123 struct my_biggy big = (struct my_biggy *
1109 (((char *)w) - offsetof (struct my_biggy, t1)); 1124 (((char *)w) - offsetof (struct my_biggy, t1));
1110 } 1125 }
1111 1126
1112 static void 1127 static void
1113 t2_cb (EV_P_ struct ev_timer *w, int revents) 1128 t2_cb (EV_P_ ev_timer *w, int revents)
1114 { 1129 {
1115 struct my_biggy big = (struct my_biggy * 1130 struct my_biggy big = (struct my_biggy *
1116 (((char *)w) - offsetof (struct my_biggy, t2)); 1131 (((char *)w) - offsetof (struct my_biggy, t2));
1117 } 1132 }
1118 1133
1253Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well 1268Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
1254readable, but only once. Since it is likely line-buffered, you could 1269readable, but only once. Since it is likely line-buffered, you could
1255attempt to read a whole line in the callback. 1270attempt to read a whole line in the callback.
1256 1271
1257 static void 1272 static void
1258 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1273 stdin_readable_cb (struct ev_loop *loop, ev_io *w, int revents)
1259 { 1274 {
1260 ev_io_stop (loop, w); 1275 ev_io_stop (loop, w);
1261 .. read from stdin here (or from w->fd) and handle any I/O errors 1276 .. read from stdin here (or from w->fd) and handle any I/O errors
1262 } 1277 }
1263 1278
1264 ... 1279 ...
1265 struct ev_loop *loop = ev_default_init (0); 1280 struct ev_loop *loop = ev_default_init (0);
1266 struct ev_io stdin_readable; 1281 ev_io stdin_readable;
1267 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 1282 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
1268 ev_io_start (loop, &stdin_readable); 1283 ev_io_start (loop, &stdin_readable);
1269 ev_loop (loop, 0); 1284 ev_loop (loop, 0);
1270 1285
1271 1286
1282 1297
1283The callback is guaranteed to be invoked only I<after> its timeout has 1298The callback is guaranteed to be invoked only I<after> its timeout has
1284passed, but if multiple timers become ready during the same loop iteration 1299passed, but if multiple timers become ready during the same loop iteration
1285then order of execution is undefined. 1300then order of execution is undefined.
1286 1301
1302=head3 Be smart about timeouts
1303
1304Many real-world problems involve some kind of timeout, usually for error
1305recovery. A typical example is an HTTP request - if the other side hangs,
1306you want to raise some error after a while.
1307
1308What follows are some ways to handle this problem, from obvious and
1309inefficient to smart and efficient.
1310
1311In the following, a 60 second activity timeout is assumed - a timeout that
1312gets reset to 60 seconds each time there is activity (e.g. each time some
1313data or other life sign was received).
1314
1315=over 4
1316
1317=item 1. Use a timer and stop, reinitialise and start it on activity.
1318
1319This is the most obvious, but not the most simple way: In the beginning,
1320start the watcher:
1321
1322 ev_timer_init (timer, callback, 60., 0.);
1323 ev_timer_start (loop, timer);
1324
1325Then, each time there is some activity, C<ev_timer_stop> it, initialise it
1326and start it again:
1327
1328 ev_timer_stop (loop, timer);
1329 ev_timer_set (timer, 60., 0.);
1330 ev_timer_start (loop, timer);
1331
1332This is relatively simple to implement, but means that each time there is
1333some activity, libev will first have to remove the timer from its internal
1334data structure and then add it again. Libev tries to be fast, but it's
1335still not a constant-time operation.
1336
1337=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity.
1338
1339This is the easiest way, and involves using C<ev_timer_again> instead of
1340C<ev_timer_start>.
1341
1342To implement this, configure an C<ev_timer> with a C<repeat> value
1343of C<60> and then call C<ev_timer_again> at start and each time you
1344successfully read or write some data. If you go into an idle state where
1345you do not expect data to travel on the socket, you can C<ev_timer_stop>
1346the timer, and C<ev_timer_again> will automatically restart it if need be.
1347
1348That means you can ignore both the C<ev_timer_start> function and the
1349C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1350member and C<ev_timer_again>.
1351
1352At start:
1353
1354 ev_timer_init (timer, callback);
1355 timer->repeat = 60.;
1356 ev_timer_again (loop, timer);
1357
1358Each time there is some activity:
1359
1360 ev_timer_again (loop, timer);
1361
1362It is even possible to change the time-out on the fly, regardless of
1363whether the watcher is active or not:
1364
1365 timer->repeat = 30.;
1366 ev_timer_again (loop, timer);
1367
1368This is slightly more efficient then stopping/starting the timer each time
1369you want to modify its timeout value, as libev does not have to completely
1370remove and re-insert the timer from/into its internal data structure.
1371
1372It is, however, even simpler than the "obvious" way to do it.
1373
1374=item 3. Let the timer time out, but then re-arm it as required.
1375
1376This method is more tricky, but usually most efficient: Most timeouts are
1377relatively long compared to the intervals between other activity - in
1378our example, within 60 seconds, there are usually many I/O events with
1379associated activity resets.
1380
1381In this case, it would be more efficient to leave the C<ev_timer> alone,
1382but remember the time of last activity, and check for a real timeout only
1383within the callback:
1384
1385 ev_tstamp last_activity; // time of last activity
1386
1387 static void
1388 callback (EV_P_ ev_timer *w, int revents)
1389 {
1390 ev_tstamp now = ev_now (EV_A);
1391 ev_tstamp timeout = last_activity + 60.;
1392
1393 // if last_activity + 60. is older than now, we did time out
1394 if (timeout < now)
1395 {
1396 // timeout occured, take action
1397 }
1398 else
1399 {
1400 // callback was invoked, but there was some activity, re-arm
1401 // the watcher to fire in last_activity + 60, which is
1402 // guaranteed to be in the future, so "again" is positive:
1403 w->again = timeout - now;
1404 ev_timer_again (EV_A_ w);
1405 }
1406 }
1407
1408To summarise the callback: first calculate the real timeout (defined
1409as "60 seconds after the last activity"), then check if that time has
1410been reached, which means something I<did>, in fact, time out. Otherwise
1411the callback was invoked too early (C<timeout> is in the future), so
1412re-schedule the timer to fire at that future time, to see if maybe we have
1413a timeout then.
1414
1415Note how C<ev_timer_again> is used, taking advantage of the
1416C<ev_timer_again> optimisation when the timer is already running.
1417
1418This scheme causes more callback invocations (about one every 60 seconds
1419minus half the average time between activity), but virtually no calls to
1420libev to change the timeout.
1421
1422To start the timer, simply initialise the watcher and set C<last_activity>
1423to the current time (meaning we just have some activity :), then call the
1424callback, which will "do the right thing" and start the timer:
1425
1426 ev_timer_init (timer, callback);
1427 last_activity = ev_now (loop);
1428 callback (loop, timer, EV_TIMEOUT);
1429
1430And when there is some activity, simply store the current time in
1431C<last_activity>, no libev calls at all:
1432
1433 last_actiivty = ev_now (loop);
1434
1435This technique is slightly more complex, but in most cases where the
1436time-out is unlikely to be triggered, much more efficient.
1437
1438Changing the timeout is trivial as well (if it isn't hard-coded in the
1439callback :) - just change the timeout and invoke the callback, which will
1440fix things for you.
1441
1442=item 4. Wee, just use a double-linked list for your timeouts.
1443
1444If there is not one request, but many thousands (millions...), all
1445employing some kind of timeout with the same timeout value, then one can
1446do even better:
1447
1448When starting the timeout, calculate the timeout value and put the timeout
1449at the I<end> of the list.
1450
1451Then use an C<ev_timer> to fire when the timeout at the I<beginning> of
1452the list is expected to fire (for example, using the technique #3).
1453
1454When there is some activity, remove the timer from the list, recalculate
1455the timeout, append it to the end of the list again, and make sure to
1456update the C<ev_timer> if it was taken from the beginning of the list.
1457
1458This way, one can manage an unlimited number of timeouts in O(1) time for
1459starting, stopping and updating the timers, at the expense of a major
1460complication, and having to use a constant timeout. The constant timeout
1461ensures that the list stays sorted.
1462
1463=back
1464
1465So which method the best?
1466
1467Method #2 is a simple no-brain-required solution that is adequate in most
1468situations. Method #3 requires a bit more thinking, but handles many cases
1469better, and isn't very complicated either. In most case, choosing either
1470one is fine, with #3 being better in typical situations.
1471
1472Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1473rather complicated, but extremely efficient, something that really pays
1474off after the first million or so of active timers, i.e. it's usually
1475overkill :)
1476
1287=head3 The special problem of time updates 1477=head3 The special problem of time updates
1288 1478
1289Establishing the current time is a costly operation (it usually takes at 1479Establishing the current time is a costly operation (it usually takes at
1290least two system calls): EV therefore updates its idea of the current 1480least two system calls): EV therefore updates its idea of the current
1291time only before and after C<ev_loop> collects new events, which causes a 1481time only before and after C<ev_loop> collects new events, which causes a
1334If the timer is started but non-repeating, stop it (as if it timed out). 1524If the timer is started but non-repeating, stop it (as if it timed out).
1335 1525
1336If the timer is repeating, either start it if necessary (with the 1526If the timer is repeating, either start it if necessary (with the
1337C<repeat> value), or reset the running timer to the C<repeat> value. 1527C<repeat> value), or reset the running timer to the C<repeat> value.
1338 1528
1339This sounds a bit complicated, but here is a useful and typical 1529This sounds a bit complicated, see "Be smart about timeouts", above, for a
1340example: Imagine you have a TCP connection and you want a so-called idle 1530usage example.
1341timeout, that is, you want to be called when there have been, say, 60
1342seconds of inactivity on the socket. The easiest way to do this is to
1343configure an C<ev_timer> with a C<repeat> value of C<60> and then call
1344C<ev_timer_again> each time you successfully read or write some data. If
1345you go into an idle state where you do not expect data to travel on the
1346socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
1347automatically restart it if need be.
1348
1349That means you can ignore the C<after> value and C<ev_timer_start>
1350altogether and only ever use the C<repeat> value and C<ev_timer_again>:
1351
1352 ev_timer_init (timer, callback, 0., 5.);
1353 ev_timer_again (loop, timer);
1354 ...
1355 timer->again = 17.;
1356 ev_timer_again (loop, timer);
1357 ...
1358 timer->again = 10.;
1359 ev_timer_again (loop, timer);
1360
1361This is more slightly efficient then stopping/starting the timer each time
1362you want to modify its timeout value.
1363
1364Note, however, that it is often even more efficient to remember the
1365time of the last activity and let the timer time-out naturally. In the
1366callback, you then check whether the time-out is real, or, if there was
1367some activity, you reschedule the watcher to time-out in "last_activity +
1368timeout - ev_now ()" seconds.
1369 1531
1370=item ev_tstamp repeat [read-write] 1532=item ev_tstamp repeat [read-write]
1371 1533
1372The current C<repeat> value. Will be used each time the watcher times out 1534The current C<repeat> value. Will be used each time the watcher times out
1373or C<ev_timer_again> is called, and determines the next timeout (if any), 1535or C<ev_timer_again> is called, and determines the next timeout (if any),
1378=head3 Examples 1540=head3 Examples
1379 1541
1380Example: Create a timer that fires after 60 seconds. 1542Example: Create a timer that fires after 60 seconds.
1381 1543
1382 static void 1544 static void
1383 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1545 one_minute_cb (struct ev_loop *loop, ev_timer *w, int revents)
1384 { 1546 {
1385 .. one minute over, w is actually stopped right here 1547 .. one minute over, w is actually stopped right here
1386 } 1548 }
1387 1549
1388 struct ev_timer mytimer; 1550 ev_timer mytimer;
1389 ev_timer_init (&mytimer, one_minute_cb, 60., 0.); 1551 ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
1390 ev_timer_start (loop, &mytimer); 1552 ev_timer_start (loop, &mytimer);
1391 1553
1392Example: Create a timeout timer that times out after 10 seconds of 1554Example: Create a timeout timer that times out after 10 seconds of
1393inactivity. 1555inactivity.
1394 1556
1395 static void 1557 static void
1396 timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 1558 timeout_cb (struct ev_loop *loop, ev_timer *w, int revents)
1397 { 1559 {
1398 .. ten seconds without any activity 1560 .. ten seconds without any activity
1399 } 1561 }
1400 1562
1401 struct ev_timer mytimer; 1563 ev_timer mytimer;
1402 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */ 1564 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
1403 ev_timer_again (&mytimer); /* start timer */ 1565 ev_timer_again (&mytimer); /* start timer */
1404 ev_loop (loop, 0); 1566 ev_loop (loop, 0);
1405 1567
1406 // and in some piece of code that gets executed on any "activity": 1568 // and in some piece of code that gets executed on any "activity":
1492 1654
1493If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 1655If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1494it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 1656it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1495only event loop modification you are allowed to do). 1657only event loop modification you are allowed to do).
1496 1658
1497The callback prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic 1659The callback prototype is C<ev_tstamp (*reschedule_cb)(ev_periodic
1498*w, ev_tstamp now)>, e.g.: 1660*w, ev_tstamp now)>, e.g.:
1499 1661
1662 static ev_tstamp
1500 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1663 my_rescheduler (ev_periodic *w, ev_tstamp now)
1501 { 1664 {
1502 return now + 60.; 1665 return now + 60.;
1503 } 1666 }
1504 1667
1505It must return the next time to trigger, based on the passed time value 1668It must return the next time to trigger, based on the passed time value
1542 1705
1543The current interval value. Can be modified any time, but changes only 1706The current interval value. Can be modified any time, but changes only
1544take effect when the periodic timer fires or C<ev_periodic_again> is being 1707take effect when the periodic timer fires or C<ev_periodic_again> is being
1545called. 1708called.
1546 1709
1547=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] 1710=item ev_tstamp (*reschedule_cb)(ev_periodic *w, ev_tstamp now) [read-write]
1548 1711
1549The current reschedule callback, or C<0>, if this functionality is 1712The current reschedule callback, or C<0>, if this functionality is
1550switched off. Can be changed any time, but changes only take effect when 1713switched off. Can be changed any time, but changes only take effect when
1551the periodic timer fires or C<ev_periodic_again> is being called. 1714the periodic timer fires or C<ev_periodic_again> is being called.
1552 1715
1557Example: Call a callback every hour, or, more precisely, whenever the 1720Example: Call a callback every hour, or, more precisely, whenever the
1558system time is divisible by 3600. The callback invocation times have 1721system time is divisible by 3600. The callback invocation times have
1559potentially a lot of jitter, but good long-term stability. 1722potentially a lot of jitter, but good long-term stability.
1560 1723
1561 static void 1724 static void
1562 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1725 clock_cb (struct ev_loop *loop, ev_io *w, int revents)
1563 { 1726 {
1564 ... its now a full hour (UTC, or TAI or whatever your clock follows) 1727 ... its now a full hour (UTC, or TAI or whatever your clock follows)
1565 } 1728 }
1566 1729
1567 struct ev_periodic hourly_tick; 1730 ev_periodic hourly_tick;
1568 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0); 1731 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
1569 ev_periodic_start (loop, &hourly_tick); 1732 ev_periodic_start (loop, &hourly_tick);
1570 1733
1571Example: The same as above, but use a reschedule callback to do it: 1734Example: The same as above, but use a reschedule callback to do it:
1572 1735
1573 #include <math.h> 1736 #include <math.h>
1574 1737
1575 static ev_tstamp 1738 static ev_tstamp
1576 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now) 1739 my_scheduler_cb (ev_periodic *w, ev_tstamp now)
1577 { 1740 {
1578 return now + (3600. - fmod (now, 3600.)); 1741 return now + (3600. - fmod (now, 3600.));
1579 } 1742 }
1580 1743
1581 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb); 1744 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
1582 1745
1583Example: Call a callback every hour, starting now: 1746Example: Call a callback every hour, starting now:
1584 1747
1585 struct ev_periodic hourly_tick; 1748 ev_periodic hourly_tick;
1586 ev_periodic_init (&hourly_tick, clock_cb, 1749 ev_periodic_init (&hourly_tick, clock_cb,
1587 fmod (ev_now (loop), 3600.), 3600., 0); 1750 fmod (ev_now (loop), 3600.), 3600., 0);
1588 ev_periodic_start (loop, &hourly_tick); 1751 ev_periodic_start (loop, &hourly_tick);
1589 1752
1590 1753
1632=head3 Examples 1795=head3 Examples
1633 1796
1634Example: Try to exit cleanly on SIGINT. 1797Example: Try to exit cleanly on SIGINT.
1635 1798
1636 static void 1799 static void
1637 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1800 sigint_cb (struct ev_loop *loop, ev_signal *w, int revents)
1638 { 1801 {
1639 ev_unloop (loop, EVUNLOOP_ALL); 1802 ev_unloop (loop, EVUNLOOP_ALL);
1640 } 1803 }
1641 1804
1642 struct ev_signal signal_watcher; 1805 ev_signal signal_watcher;
1643 ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1806 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1644 ev_signal_start (loop, &signal_watcher); 1807 ev_signal_start (loop, &signal_watcher);
1645 1808
1646 1809
1647=head2 C<ev_child> - watch out for process status changes 1810=head2 C<ev_child> - watch out for process status changes
1722its completion. 1885its completion.
1723 1886
1724 ev_child cw; 1887 ev_child cw;
1725 1888
1726 static void 1889 static void
1727 child_cb (EV_P_ struct ev_child *w, int revents) 1890 child_cb (EV_P_ ev_child *w, int revents)
1728 { 1891 {
1729 ev_child_stop (EV_A_ w); 1892 ev_child_stop (EV_A_ w);
1730 printf ("process %d exited with status %x\n", w->rpid, w->rstatus); 1893 printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
1731 } 1894 }
1732 1895
1796to exchange stat structures with application programs compiled using the 1959to exchange stat structures with application programs compiled using the
1797default compilation environment. 1960default compilation environment.
1798 1961
1799=head3 Inotify and Kqueue 1962=head3 Inotify and Kqueue
1800 1963
1801When C<inotify (7)> support has been compiled into libev (generally only 1964When C<inotify (7)> support has been compiled into libev (generally
1965only available with Linux 2.6.25 or above due to bugs in earlier
1802available with Linux) and present at runtime, it will be used to speed up 1966implementations) and present at runtime, it will be used to speed up
1803change detection where possible. The inotify descriptor will be created lazily 1967change detection where possible. The inotify descriptor will be created
1804when the first C<ev_stat> watcher is being started. 1968lazily when the first C<ev_stat> watcher is being started.
1805 1969
1806Inotify presence does not change the semantics of C<ev_stat> watchers 1970Inotify presence does not change the semantics of C<ev_stat> watchers
1807except that changes might be detected earlier, and in some cases, to avoid 1971except that changes might be detected earlier, and in some cases, to avoid
1808making regular C<stat> calls. Even in the presence of inotify support 1972making regular C<stat> calls. Even in the presence of inotify support
1809there are many cases where libev has to resort to regular C<stat> polling, 1973there are many cases where libev has to resort to regular C<stat> polling,
1983 2147
1984Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the 2148Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
1985callback, free it. Also, use no error checking, as usual. 2149callback, free it. Also, use no error checking, as usual.
1986 2150
1987 static void 2151 static void
1988 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents) 2152 idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
1989 { 2153 {
1990 free (w); 2154 free (w);
1991 // now do something you wanted to do when the program has 2155 // now do something you wanted to do when the program has
1992 // no longer anything immediate to do. 2156 // no longer anything immediate to do.
1993 } 2157 }
1994 2158
1995 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 2159 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
1996 ev_idle_init (idle_watcher, idle_cb); 2160 ev_idle_init (idle_watcher, idle_cb);
1997 ev_idle_start (loop, idle_cb); 2161 ev_idle_start (loop, idle_cb);
1998 2162
1999 2163
2000=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2164=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2081 2245
2082 static ev_io iow [nfd]; 2246 static ev_io iow [nfd];
2083 static ev_timer tw; 2247 static ev_timer tw;
2084 2248
2085 static void 2249 static void
2086 io_cb (ev_loop *loop, ev_io *w, int revents) 2250 io_cb (struct ev_loop *loop, ev_io *w, int revents)
2087 { 2251 {
2088 } 2252 }
2089 2253
2090 // create io watchers for each fd and a timer before blocking 2254 // create io watchers for each fd and a timer before blocking
2091 static void 2255 static void
2092 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 2256 adns_prepare_cb (struct ev_loop *loop, ev_prepare *w, int revents)
2093 { 2257 {
2094 int timeout = 3600000; 2258 int timeout = 3600000;
2095 struct pollfd fds [nfd]; 2259 struct pollfd fds [nfd];
2096 // actual code will need to loop here and realloc etc. 2260 // actual code will need to loop here and realloc etc.
2097 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2261 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2112 } 2276 }
2113 } 2277 }
2114 2278
2115 // stop all watchers after blocking 2279 // stop all watchers after blocking
2116 static void 2280 static void
2117 adns_check_cb (ev_loop *loop, ev_check *w, int revents) 2281 adns_check_cb (struct ev_loop *loop, ev_check *w, int revents)
2118 { 2282 {
2119 ev_timer_stop (loop, &tw); 2283 ev_timer_stop (loop, &tw);
2120 2284
2121 for (int i = 0; i < nfd; ++i) 2285 for (int i = 0; i < nfd; ++i)
2122 { 2286 {
2290C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be 2454C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be
2291used). 2455used).
2292 2456
2293 struct ev_loop *loop_hi = ev_default_init (0); 2457 struct ev_loop *loop_hi = ev_default_init (0);
2294 struct ev_loop *loop_lo = 0; 2458 struct ev_loop *loop_lo = 0;
2295 struct ev_embed embed; 2459 ev_embed embed;
2296 2460
2297 // see if there is a chance of getting one that works 2461 // see if there is a chance of getting one that works
2298 // (remember that a flags value of 0 means autodetection) 2462 // (remember that a flags value of 0 means autodetection)
2299 loop_lo = ev_embeddable_backends () & ev_recommended_backends () 2463 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
2300 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 2464 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
2314kqueue implementation). Store the kqueue/socket-only event loop in 2478kqueue implementation). Store the kqueue/socket-only event loop in
2315C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). 2479C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
2316 2480
2317 struct ev_loop *loop = ev_default_init (0); 2481 struct ev_loop *loop = ev_default_init (0);
2318 struct ev_loop *loop_socket = 0; 2482 struct ev_loop *loop_socket = 0;
2319 struct ev_embed embed; 2483 ev_embed embed;
2320 2484
2321 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 2485 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
2322 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 2486 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
2323 { 2487 {
2324 ev_embed_init (&embed, 0, loop_socket); 2488 ev_embed_init (&embed, 0, loop_socket);
2538 /* doh, nothing entered */; 2702 /* doh, nothing entered */;
2539 } 2703 }
2540 2704
2541 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 2705 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2542 2706
2543=item ev_feed_event (ev_loop *, watcher *, int revents) 2707=item ev_feed_event (struct ev_loop *, watcher *, int revents)
2544 2708
2545Feeds the given event set into the event loop, as if the specified event 2709Feeds the given event set into the event loop, as if the specified event
2546had happened for the specified watcher (which must be a pointer to an 2710had happened for the specified watcher (which must be a pointer to an
2547initialised but not necessarily started event watcher). 2711initialised but not necessarily started event watcher).
2548 2712
2549=item ev_feed_fd_event (ev_loop *, int fd, int revents) 2713=item ev_feed_fd_event (struct ev_loop *, int fd, int revents)
2550 2714
2551Feed an event on the given fd, as if a file descriptor backend detected 2715Feed an event on the given fd, as if a file descriptor backend detected
2552the given events it. 2716the given events it.
2553 2717
2554=item ev_feed_signal_event (ev_loop *loop, int signum) 2718=item ev_feed_signal_event (struct ev_loop *loop, int signum)
2555 2719
2556Feed an event as if the given signal occurred (C<loop> must be the default 2720Feed an event as if the given signal occurred (C<loop> must be the default
2557loop!). 2721loop!).
2558 2722
2559=back 2723=back
2793 2957
2794=item D 2958=item D
2795 2959
2796Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 2960Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2797be found at L<http://proj.llucax.com.ar/wiki/evd>. 2961be found at L<http://proj.llucax.com.ar/wiki/evd>.
2962
2963=item Ocaml
2964
2965Erkki Seppala has written Ocaml bindings for libev, to be found at
2966L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
2798 2967
2799=back 2968=back
2800 2969
2801 2970
2802=head1 MACRO MAGIC 2971=head1 MACRO MAGIC

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines