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

Comparing libev/ev.pod (file contents):
Revision 1.198 by root, Thu Oct 23 06:30:48 2008 UTC vs.
Revision 1.228 by root, Sat Mar 28 08:22:30 2009 UTC

9=head2 EXAMPLE PROGRAM 9=head2 EXAMPLE PROGRAM
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 #include <stdio.h> // for puts
15
14 // every watcher type has its own typedef'd struct 16 // every watcher type has its own typedef'd struct
15 // with the name ev_<type> 17 // with the name ev_TYPE
16 ev_io stdin_watcher; 18 ev_io stdin_watcher;
17 ev_timer timeout_watcher; 19 ev_timer timeout_watcher;
18 20
19 // all watcher callbacks have a similar signature 21 // all watcher callbacks have a similar signature
20 // this callback is called when data is readable on stdin 22 // this callback is called when data is readable on stdin
41 43
42 int 44 int
43 main (void) 45 main (void)
44 { 46 {
45 // use the default event loop unless you have special needs 47 // use the default event loop unless you have special needs
46 ev_loop *loop = ev_default_loop (0); 48 struct ev_loop *loop = ev_default_loop (0);
47 49
48 // initialise an io watcher, then start it 50 // initialise an io watcher, then start it
49 // this one will watch for stdin to become readable 51 // this one will watch for stdin to become readable
50 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); 52 ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
51 ev_io_start (loop, &stdin_watcher); 53 ev_io_start (loop, &stdin_watcher);
276 278
277=back 279=back
278 280
279=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 281=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
280 282
281An event loop is described by a C<ev_loop *>. The library knows two 283An 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 284is I<not> optional in this case, as there is also an C<ev_loop>
283events, and dynamically created loops which do not. 285I<function>).
286
287The library knows two types of such loops, the I<default> loop, which
288supports signals and child events, and dynamically created loops which do
289not.
284 290
285=over 4 291=over 4
286 292
287=item struct ev_loop *ev_default_loop (unsigned int flags) 293=item struct ev_loop *ev_default_loop (unsigned int flags)
288 294
294If you don't know what event loop to use, use the one returned from this 300If you don't know what event loop to use, use the one returned from this
295function. 301function.
296 302
297Note that this function is I<not> thread-safe, so if you want to use it 303Note that this function is I<not> thread-safe, so if you want to use it
298from multiple threads, you have to lock (note also that this is unlikely, 304from multiple threads, you have to lock (note also that this is unlikely,
299as loops cannot bes hared easily between threads anyway). 305as loops cannot be shared easily between threads anyway).
300 306
301The default loop is the only loop that can handle C<ev_signal> and 307The default loop is the only loop that can handle C<ev_signal> and
302C<ev_child> watchers, and to do this, it always registers a handler 308C<ev_child> watchers, and to do this, it always registers a handler
303for C<SIGCHLD>. If this is a problem for your application you can either 309for C<SIGCHLD>. If this is a problem for your application you can either
304create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 310create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
380=item C<EVBACKEND_EPOLL> (value 4, Linux) 386=item C<EVBACKEND_EPOLL> (value 4, Linux)
381 387
382For few fds, this backend is a bit little slower than poll and select, 388For few fds, this backend is a bit little slower than poll and select,
383but it scales phenomenally better. While poll and select usually scale 389but it scales phenomenally better. While poll and select usually scale
384like O(total_fds) where n is the total number of fds (or the highest fd), 390like O(total_fds) where n is the total number of fds (or the highest fd),
385epoll scales either O(1) or O(active_fds). The epoll design has a number 391epoll scales either O(1) or O(active_fds).
386of shortcomings, such as silently dropping events in some hard-to-detect 392
387cases and requiring a system call per fd change, no fork support and bad 393The epoll mechanism deserves honorable mention as the most misdesigned
388support for dup. 394of the more advanced event mechanisms: mere annoyances include silently
395dropping file descriptors, requiring a system call per change per file
396descriptor (and unnecessary guessing of parameters), problems with dup and
397so on. The biggest issue is fork races, however - if a program forks then
398I<both> parent and child process have to recreate the epoll set, which can
399take considerable time (one syscall per file descriptor) and is of course
400hard to detect.
401
402Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
403of course I<doesn't>, and epoll just loves to report events for totally
404I<different> file descriptors (even already closed ones, so one cannot
405even remove them from the set) than registered in the set (especially
406on SMP systems). Libev tries to counter these spurious notifications by
407employing an additional generation counter and comparing that against the
408events to filter out spurious ones, recreating the set when required.
389 409
390While stopping, setting and starting an I/O watcher in the same iteration 410While stopping, setting and starting an I/O watcher in the same iteration
391will result in some caching, there is still a system call per such incident 411will result in some caching, there is still a system call per such
392(because the fd could point to a different file description now), so its 412incident (because the same I<file descriptor> could point to a different
393best to avoid that. Also, C<dup ()>'ed file descriptors might not work 413I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
394very well if you register events for both fds. 414file descriptors might not work very well if you register events for both
395 415file descriptors.
396Please note that epoll sometimes generates spurious notifications, so you
397need to use non-blocking I/O or other means to avoid blocking when no data
398(or space) is available.
399 416
400Best performance from this backend is achieved by not unregistering all 417Best performance from this backend is achieved by not unregistering all
401watchers for a file descriptor until it has been closed, if possible, 418watchers for a file descriptor until it has been closed, if possible,
402i.e. keep at least one watcher active per fd at all times. Stopping and 419i.e. keep at least one watcher active per fd at all times. Stopping and
403starting a watcher (without re-setting it) also usually doesn't cause 420starting a watcher (without re-setting it) also usually doesn't cause
404extra overhead. 421extra overhead. A fork can both result in spurious notifications as well
422as in libev having to destroy and recreate the epoll object, which can
423take considerable time and thus should be avoided.
424
425All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
426faster than epoll for maybe up to a hundred file descriptors, depending on
427the usage. So sad.
405 428
406While nominally embeddable in other event loops, this feature is broken in 429While nominally embeddable in other event loops, this feature is broken in
407all kernel versions tested so far. 430all kernel versions tested so far.
408 431
409This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 432This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
410C<EVBACKEND_POLL>. 433C<EVBACKEND_POLL>.
411 434
412=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 435=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
413 436
414Kqueue deserves special mention, as at the time of this writing, it was 437Kqueue deserves special mention, as at the time of this writing, it
415broken on all BSDs except NetBSD (usually it doesn't work reliably with 438was broken on all BSDs except NetBSD (usually it doesn't work reliably
416anything but sockets and pipes, except on Darwin, where of course it's 439with anything but sockets and pipes, except on Darwin, where of course
417completely useless). For this reason it's not being "auto-detected" unless 440it's completely useless). Unlike epoll, however, whose brokenness
418you explicitly specify it in the flags (i.e. using C<EVBACKEND_KQUEUE>) or 441is by design, these kqueue bugs can (and eventually will) be fixed
419libev was compiled on a known-to-be-good (-enough) system like NetBSD. 442without API changes to existing programs. For this reason it's not being
443"auto-detected" unless you explicitly specify it in the flags (i.e. using
444C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
445system like NetBSD.
420 446
421You still can embed kqueue into a normal poll or select backend and use it 447You still can embed kqueue into a normal poll or select backend and use it
422only for sockets (after having made sure that sockets work with kqueue on 448only for sockets (after having made sure that sockets work with kqueue on
423the target platform). See C<ev_embed> watchers for more info. 449the target platform). See C<ev_embed> watchers for more info.
424 450
425It scales in the same way as the epoll backend, but the interface to the 451It scales in the same way as the epoll backend, but the interface to the
426kernel is more efficient (which says nothing about its actual speed, of 452kernel is more efficient (which says nothing about its actual speed, of
427course). While stopping, setting and starting an I/O watcher does never 453course). While stopping, setting and starting an I/O watcher does never
428cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 454cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
429two event changes per incident. Support for C<fork ()> is very bad and it 455two event changes per incident. Support for C<fork ()> is very bad (but
430drops fds silently in similarly hard-to-detect cases. 456sane, unlike epoll) and it drops fds silently in similarly hard-to-detect
457cases
431 458
432This backend usually performs well under most conditions. 459This backend usually performs well under most conditions.
433 460
434While nominally embeddable in other event loops, this doesn't work 461While nominally embeddable in other event loops, this doesn't work
435everywhere, so you might need to test for this. And since it is broken 462everywhere, so you might need to test for this. And since it is broken
436almost everywhere, you should only use it when you have a lot of sockets 463almost everywhere, you should only use it when you have a lot of sockets
437(for which it usually works), by embedding it into another event loop 464(for which it usually works), by embedding it into another event loop
438(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and, did I mention it, 465(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> (but C<poll> is of course
439using it only for sockets. 466also broken on OS X)) and, did I mention it, using it only for sockets.
440 467
441This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with 468This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
442C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with 469C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
443C<NOTE_EOF>. 470C<NOTE_EOF>.
444 471
464might perform better. 491might perform better.
465 492
466On the positive side, with the exception of the spurious readiness 493On the positive side, with the exception of the spurious readiness
467notifications, this backend actually performed fully to specification 494notifications, this backend actually performed fully to specification
468in all tests and is fully embeddable, which is a rare feat among the 495in all tests and is fully embeddable, which is a rare feat among the
469OS-specific backends. 496OS-specific backends (I vastly prefer correctness over speed hacks).
470 497
471This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 498This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
472C<EVBACKEND_POLL>. 499C<EVBACKEND_POLL>.
473 500
474=item C<EVBACKEND_ALL> 501=item C<EVBACKEND_ALL>
527responsibility to either stop all watchers cleanly yourself I<before> 554responsibility to either stop all watchers cleanly yourself I<before>
528calling this function, or cope with the fact afterwards (which is usually 555calling this function, or cope with the fact afterwards (which is usually
529the easiest thing, you can just ignore the watchers and/or C<free ()> them 556the easiest thing, you can just ignore the watchers and/or C<free ()> them
530for example). 557for example).
531 558
532Note that certain global state, such as signal state, will not be freed by 559Note that certain global state, such as signal state (and installed signal
533this function, and related watchers (such as signal and child watchers) 560handlers), will not be freed by this function, and related watchers (such
534would need to be stopped manually. 561as signal and child watchers) would need to be stopped manually.
535 562
536In general it is not advisable to call this function except in the 563In general it is not advisable to call this function except in the
537rare occasion where you really need to free e.g. the signal handling 564rare occasion where you really need to free e.g. the signal handling
538pipe fds. If you need dynamically allocated loops it is better to use 565pipe fds. If you need dynamically allocated loops it is better to use
539C<ev_loop_new> and C<ev_loop_destroy>). 566C<ev_loop_new> and C<ev_loop_destroy>).
631the loop. 658the loop.
632 659
633A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 660A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
634necessary) and will handle those and any already outstanding ones. It 661necessary) and will handle those and any already outstanding ones. It
635will block your process until at least one new event arrives (which could 662will block your process until at least one new event arrives (which could
636be an event internal to libev itself, so there is no guarentee that a 663be an event internal to libev itself, so there is no guarantee that a
637user-registered callback will be called), and will return after one 664user-registered callback will be called), and will return after one
638iteration of the loop. 665iteration of the loop.
639 666
640This is useful if you are waiting for some external event in conjunction 667This is useful if you are waiting for some external event in conjunction
641with something not expressible using other libev watchers (i.e. "roll your 668with something not expressible using other libev watchers (i.e. "roll your
768they fire on, say, one-second boundaries only. 795they fire on, say, one-second boundaries only.
769 796
770=item ev_loop_verify (loop) 797=item ev_loop_verify (loop)
771 798
772This function only does something when C<EV_VERIFY> support has been 799This 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 800compiled in, which is the default for non-minimal builds. It tries to go
774through all internal structures and checks them for validity. If anything 801through all internal structures and checks them for validity. If anything
775is found to be inconsistent, it will print an error message to standard 802is found to be inconsistent, it will print an error message to standard
776error and call C<abort ()>. 803error and call C<abort ()>.
777 804
778This can be used to catch bugs inside libev itself: under normal 805This can be used to catch bugs inside libev itself: under normal
781 808
782=back 809=back
783 810
784 811
785=head1 ANATOMY OF A WATCHER 812=head1 ANATOMY OF A WATCHER
813
814In the following description, uppercase C<TYPE> in names stands for the
815watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
816watchers and C<ev_io_start> for I/O watchers.
786 817
787A watcher is a structure that you create and register to record your 818A 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 819interest 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: 820become readable, you would create an C<ev_io> watcher for that:
790 821
793 ev_io_stop (w); 824 ev_io_stop (w);
794 ev_unloop (loop, EVUNLOOP_ALL); 825 ev_unloop (loop, EVUNLOOP_ALL);
795 } 826 }
796 827
797 struct ev_loop *loop = ev_default_loop (0); 828 struct ev_loop *loop = ev_default_loop (0);
829
798 ev_io stdin_watcher; 830 ev_io stdin_watcher;
831
799 ev_init (&stdin_watcher, my_cb); 832 ev_init (&stdin_watcher, my_cb);
800 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); 833 ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
801 ev_io_start (loop, &stdin_watcher); 834 ev_io_start (loop, &stdin_watcher);
835
802 ev_loop (loop, 0); 836 ev_loop (loop, 0);
803 837
804As you can see, you are responsible for allocating the memory for your 838As 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, 839watcher structures (and it is I<usually> a bad idea to do this on the
806although this can sometimes be quite valid). 840stack).
841
842Each watcher has an associated watcher structure (called C<struct ev_TYPE>
843or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
807 844
808Each watcher structure must be initialised by a call to C<ev_init 845Each watcher structure must be initialised by a call to C<ev_init
809(watcher *, callback)>, which expects a callback to be provided. This 846(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 847callback 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 848watchers, each time the event loop detects that the file descriptor given
812is readable and/or writable). 849is readable and/or writable).
813 850
814Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 851Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
815with arguments specific to this watcher type. There is also a macro 852macro to configure it, with arguments specific to the watcher type. There
816to combine initialisation and setting in one call: C<< ev_<type>_init 853is also a macro to combine initialisation and setting in one call: C<<
817(watcher *, callback, ...) >>. 854ev_TYPE_init (watcher *, callback, ...) >>.
818 855
819To make the watcher actually watch out for events, you have to start it 856To 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 857with 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 858*) >>), and you can stop watching for events at any time by calling the
822corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>. 859corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
823 860
824As long as your watcher is active (has been started but not stopped) you 861As 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 862must not touch the values stored in it. Most specifically you must never
826reinitialise it or call its C<set> macro. 863reinitialise it or call its C<ev_TYPE_set> macro.
827 864
828Each and every callback receives the event loop pointer as first, the 865Each and every callback receives the event loop pointer as first, the
829registered watcher structure as second, and a bitset of received events as 866registered watcher structure as second, and a bitset of received events as
830third argument. 867third argument.
831 868
912 949
913=back 950=back
914 951
915=head2 GENERIC WATCHER FUNCTIONS 952=head2 GENERIC WATCHER FUNCTIONS
916 953
917In the following description, C<TYPE> stands for the watcher type,
918e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
919
920=over 4 954=over 4
921 955
922=item C<ev_init> (ev_TYPE *watcher, callback) 956=item C<ev_init> (ev_TYPE *watcher, callback)
923 957
924This macro initialises the generic portion of a watcher. The contents 958This macro initialises the generic portion of a watcher. The contents
1032The default priority used by watchers when no priority has been set is 1066The default priority used by watchers when no priority has been set is
1033always C<0>, which is supposed to not be too high and not be too low :). 1067always C<0>, which is supposed to not be too high and not be too low :).
1034 1068
1035Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1069Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1036fine, as long as you do not mind that the priority value you query might 1070fine, as long as you do not mind that the priority value you query might
1037or might not have been adjusted to be within valid range. 1071or might not have been clamped to the valid range.
1038 1072
1039=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1073=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1040 1074
1041Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1075Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1042C<loop> nor C<revents> need to be valid as long as the watcher callback 1076C<loop> nor C<revents> need to be valid as long as the watcher callback
1288passed, but if multiple timers become ready during the same loop iteration 1322passed, but if multiple timers become ready during the same loop iteration
1289then order of execution is undefined. 1323then order of execution is undefined.
1290 1324
1291=head3 Be smart about timeouts 1325=head3 Be smart about timeouts
1292 1326
1293Many real-world problems invole some kind of time-out, usually for error 1327Many real-world problems involve some kind of timeout, usually for error
1294recovery. A typical example is an HTTP request - if the other side hangs, 1328recovery. A typical example is an HTTP request - if the other side hangs,
1295you want to raise some error after a while. 1329you want to raise some error after a while.
1296 1330
1297Here are some ways on how to handle this problem, from simple and 1331What follows are some ways to handle this problem, from obvious and
1298inefficient to very efficient. 1332inefficient to smart and efficient.
1299 1333
1300In the following examples a 60 second activity timeout is assumed - a 1334In the following, a 60 second activity timeout is assumed - a timeout that
1301timeout that gets reset to 60 seconds each time some data ("a lifesign") 1335gets reset to 60 seconds each time there is activity (e.g. each time some
1302was received. 1336data or other life sign was received).
1303 1337
1304=over 4 1338=over 4
1305 1339
1306=item 1. Use a timer and stop, reinitialise, start it on activity. 1340=item 1. Use a timer and stop, reinitialise and start it on activity.
1307 1341
1308This is the most obvious, but not the most simple way: In the beginning, 1342This is the most obvious, but not the most simple way: In the beginning,
1309start the watcher: 1343start the watcher:
1310 1344
1311 ev_timer_init (timer, callback, 60., 0.); 1345 ev_timer_init (timer, callback, 60., 0.);
1312 ev_timer_start (loop, timer); 1346 ev_timer_start (loop, timer);
1313 1347
1314Then, each time there is some activity, C<ev_timer_stop> the timer, 1348Then, each time there is some activity, C<ev_timer_stop> it, initialise it
1315initialise it again, and start it: 1349and start it again:
1316 1350
1317 ev_timer_stop (loop, timer); 1351 ev_timer_stop (loop, timer);
1318 ev_timer_set (timer, 60., 0.); 1352 ev_timer_set (timer, 60., 0.);
1319 ev_timer_start (loop, timer); 1353 ev_timer_start (loop, timer);
1320 1354
1321This is relatively simple to implement, but means that each time there 1355This is relatively simple to implement, but means that each time there is
1322is some activity, libev will first have to remove the timer from it's 1356some activity, libev will first have to remove the timer from its internal
1323internal data strcuture and then add it again. 1357data structure and then add it again. Libev tries to be fast, but it's
1358still not a constant-time operation.
1324 1359
1325=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity. 1360=item 2. Use a timer and re-start it with C<ev_timer_again> inactivity.
1326 1361
1327This is the easiest way, and involves using C<ev_timer_again> instead of 1362This is the easiest way, and involves using C<ev_timer_again> instead of
1328C<ev_timer_start>. 1363C<ev_timer_start>.
1329 1364
1330For this, configure an C<ev_timer> with a C<repeat> value of C<60> and 1365To implement this, configure an C<ev_timer> with a C<repeat> value
1331then call C<ev_timer_again> at start and each time you successfully read 1366of C<60> and then call C<ev_timer_again> at start and each time you
1332or write some data. If you go into an idle state where you do not expect 1367successfully read or write some data. If you go into an idle state where
1333data to travel on the socket, you can C<ev_timer_stop> the timer, and 1368you do not expect data to travel on the socket, you can C<ev_timer_stop>
1334C<ev_timer_again> will automatically restart it if need be. 1369the timer, and C<ev_timer_again> will automatically restart it if need be.
1335 1370
1336That means you can ignore the C<after> value and C<ev_timer_start> 1371That means you can ignore both the C<ev_timer_start> function and the
1337altogether and only ever use the C<repeat> value and C<ev_timer_again>. 1372C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1373member and C<ev_timer_again>.
1338 1374
1339At start: 1375At start:
1340 1376
1341 ev_timer_init (timer, callback, 0., 60.); 1377 ev_timer_init (timer, callback);
1378 timer->repeat = 60.;
1342 ev_timer_again (loop, timer); 1379 ev_timer_again (loop, timer);
1343 1380
1344Each time you receive some data: 1381Each time there is some activity:
1345 1382
1346 ev_timer_again (loop, timer); 1383 ev_timer_again (loop, timer);
1347 1384
1348It is even possible to change the time-out on the fly: 1385It is even possible to change the time-out on the fly, regardless of
1386whether the watcher is active or not:
1349 1387
1350 timer->repeat = 30.; 1388 timer->repeat = 30.;
1351 ev_timer_again (loop, timer); 1389 ev_timer_again (loop, timer);
1352 1390
1353This is slightly more efficient then stopping/starting the timer each time 1391This is slightly more efficient then stopping/starting the timer each time
1354you want to modify its timeout value, as libev does not have to completely 1392you want to modify its timeout value, as libev does not have to completely
1355remove and re-insert the timer from/into it's internal data structure. 1393remove and re-insert the timer from/into its internal data structure.
1394
1395It is, however, even simpler than the "obvious" way to do it.
1356 1396
1357=item 3. Let the timer time out, but then re-arm it as required. 1397=item 3. Let the timer time out, but then re-arm it as required.
1358 1398
1359This method is more tricky, but usually most efficient: Most timeouts are 1399This method is more tricky, but usually most efficient: Most timeouts are
1360relatively long compared to the loop iteration time - in our example, 1400relatively long compared to the intervals between other activity - in
1361within 60 seconds, there are usually many I/O events with associated 1401our example, within 60 seconds, there are usually many I/O events with
1362activity resets. 1402associated activity resets.
1363 1403
1364In this case, it would be more efficient to leave the C<ev_timer> alone, 1404In this case, it would be more efficient to leave the C<ev_timer> alone,
1365but remember the time of last activity, and check for a real timeout only 1405but remember the time of last activity, and check for a real timeout only
1366within the callback: 1406within the callback:
1367 1407
1368 ev_tstamp last_activity; // time of last activity 1408 ev_tstamp last_activity; // time of last activity
1369 1409
1370 static void 1410 static void
1371 callback (EV_P_ ev_timer *w, int revents) 1411 callback (EV_P_ ev_timer *w, int revents)
1372 { 1412 {
1373 ev_tstamp now = ev_now (EV_A); 1413 ev_tstamp now = ev_now (EV_A);
1374 ev_tstamp timeout = last_activity + 60.; 1414 ev_tstamp timeout = last_activity + 60.;
1375 1415
1376 // if last_activity is older than now - timeout, we did time out 1416 // if last_activity + 60. is older than now, we did time out
1377 if (timeout < now) 1417 if (timeout < now)
1378 { 1418 {
1379 // timeout occured, take action 1419 // timeout occured, take action
1380 } 1420 }
1381 else 1421 else
1382 { 1422 {
1383 // callback was invoked, but there was some activity, re-arm 1423 // callback was invoked, but there was some activity, re-arm
1384 // to fire in last_activity + 60. 1424 // the watcher to fire in last_activity + 60, which is
1425 // guaranteed to be in the future, so "again" is positive:
1385 w->again = timeout - now; 1426 w->repeat = timeout - now;
1386 ev_timer_again (EV_A_ w); 1427 ev_timer_again (EV_A_ w);
1387 } 1428 }
1388 } 1429 }
1389 1430
1390To summarise the callback: first calculate the real time-out (defined as 1431To summarise the callback: first calculate the real timeout (defined
1391"60 seconds after the last activity"), then check if that time has been 1432as "60 seconds after the last activity"), then check if that time has
1392reached, which means there was a real timeout. Otherwise the callback was 1433been reached, which means something I<did>, in fact, time out. Otherwise
1393invoked too early (timeout is in the future), so re-schedule the timer to 1434the callback was invoked too early (C<timeout> is in the future), so
1394fire at that future time. 1435re-schedule the timer to fire at that future time, to see if maybe we have
1436a timeout then.
1395 1437
1396Note how C<ev_timer_again> is used, taking advantage of the 1438Note how C<ev_timer_again> is used, taking advantage of the
1397C<ev_timer_again> optimisation when the timer is already running. 1439C<ev_timer_again> optimisation when the timer is already running.
1398 1440
1399This scheme causes more callback invocations (about one every 60 seconds), 1441This scheme causes more callback invocations (about one every 60 seconds
1400but virtually no calls to libev to change the timeout. 1442minus half the average time between activity), but virtually no calls to
1443libev to change the timeout.
1401 1444
1402To start the timer, simply intiialise the watcher and C<last_activity>, 1445To start the timer, simply initialise the watcher and set C<last_activity>
1403then call the callback: 1446to the current time (meaning we just have some activity :), then call the
1447callback, which will "do the right thing" and start the timer:
1404 1448
1405 ev_timer_init (timer, callback); 1449 ev_timer_init (timer, callback);
1406 last_activity = ev_now (loop); 1450 last_activity = ev_now (loop);
1407 callback (loop, timer, EV_TIMEOUT); 1451 callback (loop, timer, EV_TIMEOUT);
1408 1452
1409And when there is some activity, simply remember the time in 1453And when there is some activity, simply store the current time in
1410C<last_activity>: 1454C<last_activity>, no libev calls at all:
1411 1455
1412 last_actiivty = ev_now (loop); 1456 last_actiivty = ev_now (loop);
1413 1457
1414This technique is slightly more complex, but in most cases where the 1458This technique is slightly more complex, but in most cases where the
1415time-out is unlikely to be triggered, much more efficient. 1459time-out is unlikely to be triggered, much more efficient.
1416 1460
1461Changing the timeout is trivial as well (if it isn't hard-coded in the
1462callback :) - just change the timeout and invoke the callback, which will
1463fix things for you.
1464
1465=item 4. Wee, just use a double-linked list for your timeouts.
1466
1467If there is not one request, but many thousands (millions...), all
1468employing some kind of timeout with the same timeout value, then one can
1469do even better:
1470
1471When starting the timeout, calculate the timeout value and put the timeout
1472at the I<end> of the list.
1473
1474Then use an C<ev_timer> to fire when the timeout at the I<beginning> of
1475the list is expected to fire (for example, using the technique #3).
1476
1477When there is some activity, remove the timer from the list, recalculate
1478the timeout, append it to the end of the list again, and make sure to
1479update the C<ev_timer> if it was taken from the beginning of the list.
1480
1481This way, one can manage an unlimited number of timeouts in O(1) time for
1482starting, stopping and updating the timers, at the expense of a major
1483complication, and having to use a constant timeout. The constant timeout
1484ensures that the list stays sorted.
1485
1417=back 1486=back
1487
1488So which method the best?
1489
1490Method #2 is a simple no-brain-required solution that is adequate in most
1491situations. Method #3 requires a bit more thinking, but handles many cases
1492better, and isn't very complicated either. In most case, choosing either
1493one is fine, with #3 being better in typical situations.
1494
1495Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1496rather complicated, but extremely efficient, something that really pays
1497off after the first million or so of active timers, i.e. it's usually
1498overkill :)
1418 1499
1419=head3 The special problem of time updates 1500=head3 The special problem of time updates
1420 1501
1421Establishing the current time is a costly operation (it usually takes at 1502Establishing the current time is a costly operation (it usually takes at
1422least two system calls): EV therefore updates its idea of the current 1503least two system calls): EV therefore updates its idea of the current
1515=head2 C<ev_periodic> - to cron or not to cron? 1596=head2 C<ev_periodic> - to cron or not to cron?
1516 1597
1517Periodic watchers are also timers of a kind, but they are very versatile 1598Periodic watchers are also timers of a kind, but they are very versatile
1518(and unfortunately a bit complex). 1599(and unfortunately a bit complex).
1519 1600
1520Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1601Unlike C<ev_timer>, periodic watchers are not based on real time (or
1521but on wall clock time (absolute time). You can tell a periodic watcher 1602relative time, the physical time that passes) but on wall clock time
1522to trigger after some specific point in time. For example, if you tell a 1603(absolute time, the thing you can read on your calender or clock). The
1523periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now () 1604difference is that wall clock time can run faster or slower than real
1524+ 10.>, that is, an absolute time not a delay) and then reset your system 1605time, and time jumps are not uncommon (e.g. when you adjust your
1525clock to January of the previous year, then it will take more than year 1606wrist-watch).
1526to trigger the event (unlike an C<ev_timer>, which would still trigger
1527roughly 10 seconds later as it uses a relative timeout).
1528 1607
1608You can tell a periodic watcher to trigger after some specific point
1609in time: for example, if you tell a periodic watcher to trigger "in 10
1610seconds" (by specifying e.g. C<ev_now () + 10.>, that is, an absolute time
1611not a delay) and then reset your system clock to January of the previous
1612year, then it will take a year or more to trigger the event (unlike an
1613C<ev_timer>, which would still trigger roughly 10 seconds after starting
1614it, as it uses a relative timeout).
1615
1529C<ev_periodic>s can also be used to implement vastly more complex timers, 1616C<ev_periodic> watchers can also be used to implement vastly more complex
1530such as triggering an event on each "midnight, local time", or other 1617timers, such as triggering an event on each "midnight, local time", or
1531complicated rules. 1618other complicated rules. This cannot be done with C<ev_timer> watchers, as
1619those cannot react to time jumps.
1532 1620
1533As with timers, the callback is guaranteed to be invoked only when the 1621As with timers, the callback is guaranteed to be invoked only when the
1534time (C<at>) has passed, but if multiple periodic timers become ready 1622point in time where it is supposed to trigger has passed, but if multiple
1535during the same loop iteration, then order of execution is undefined. 1623periodic timers become ready during the same loop iteration, then order of
1624execution is undefined.
1536 1625
1537=head3 Watcher-Specific Functions and Data Members 1626=head3 Watcher-Specific Functions and Data Members
1538 1627
1539=over 4 1628=over 4
1540 1629
1541=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1630=item ev_periodic_init (ev_periodic *, callback, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1542 1631
1543=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1632=item ev_periodic_set (ev_periodic *, ev_tstamp offset, ev_tstamp interval, reschedule_cb)
1544 1633
1545Lots of arguments, lets sort it out... There are basically three modes of 1634Lots of arguments, let's sort it out... There are basically three modes of
1546operation, and we will explain them from simplest to most complex: 1635operation, and we will explain them from simplest to most complex:
1547 1636
1548=over 4 1637=over 4
1549 1638
1550=item * absolute timer (at = time, interval = reschedule_cb = 0) 1639=item * absolute timer (offset = absolute time, interval = 0, reschedule_cb = 0)
1551 1640
1552In this configuration the watcher triggers an event after the wall clock 1641In this configuration the watcher triggers an event after the wall clock
1553time C<at> has passed. It will not repeat and will not adjust when a time 1642time C<offset> has passed. It will not repeat and will not adjust when a
1554jump occurs, that is, if it is to be run at January 1st 2011 then it will 1643time jump occurs, that is, if it is to be run at January 1st 2011 then it
1555only run when the system clock reaches or surpasses this time. 1644will be stopped and invoked when the system clock reaches or surpasses
1645this point in time.
1556 1646
1557=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1647=item * repeating interval timer (offset = offset within interval, interval > 0, reschedule_cb = 0)
1558 1648
1559In this mode the watcher will always be scheduled to time out at the next 1649In this mode the watcher will always be scheduled to time out at the next
1560C<at + N * interval> time (for some integer N, which can also be negative) 1650C<offset + N * interval> time (for some integer N, which can also be
1561and then repeat, regardless of any time jumps. 1651negative) and then repeat, regardless of any time jumps. The C<offset>
1652argument is merely an offset into the C<interval> periods.
1562 1653
1563This can be used to create timers that do not drift with respect to the 1654This can be used to create timers that do not drift with respect to the
1564system clock, for example, here is a C<ev_periodic> that triggers each 1655system clock, for example, here is an C<ev_periodic> that triggers each
1565hour, on the hour: 1656hour, on the hour (with respect to UTC):
1566 1657
1567 ev_periodic_set (&periodic, 0., 3600., 0); 1658 ev_periodic_set (&periodic, 0., 3600., 0);
1568 1659
1569This doesn't mean there will always be 3600 seconds in between triggers, 1660This doesn't mean there will always be 3600 seconds in between triggers,
1570but only that the callback will be called when the system time shows a 1661but only that the callback will be called when the system time shows a
1571full hour (UTC), or more correctly, when the system time is evenly divisible 1662full hour (UTC), or more correctly, when the system time is evenly divisible
1572by 3600. 1663by 3600.
1573 1664
1574Another way to think about it (for the mathematically inclined) is that 1665Another way to think about it (for the mathematically inclined) is that
1575C<ev_periodic> will try to run the callback in this mode at the next possible 1666C<ev_periodic> will try to run the callback in this mode at the next possible
1576time where C<time = at (mod interval)>, regardless of any time jumps. 1667time where C<time = offset (mod interval)>, regardless of any time jumps.
1577 1668
1578For numerical stability it is preferable that the C<at> value is near 1669For numerical stability it is preferable that the C<offset> value is near
1579C<ev_now ()> (the current time), but there is no range requirement for 1670C<ev_now ()> (the current time), but there is no range requirement for
1580this value, and in fact is often specified as zero. 1671this value, and in fact is often specified as zero.
1581 1672
1582Note also that there is an upper limit to how often a timer can fire (CPU 1673Note also that there is an upper limit to how often a timer can fire (CPU
1583speed for example), so if C<interval> is very small then timing stability 1674speed for example), so if C<interval> is very small then timing stability
1584will of course deteriorate. Libev itself tries to be exact to be about one 1675will of course deteriorate. Libev itself tries to be exact to be about one
1585millisecond (if the OS supports it and the machine is fast enough). 1676millisecond (if the OS supports it and the machine is fast enough).
1586 1677
1587=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1678=item * manual reschedule mode (offset ignored, interval ignored, reschedule_cb = callback)
1588 1679
1589In this mode the values for C<interval> and C<at> are both being 1680In this mode the values for C<interval> and C<offset> are both being
1590ignored. Instead, each time the periodic watcher gets scheduled, the 1681ignored. Instead, each time the periodic watcher gets scheduled, the
1591reschedule callback will be called with the watcher as first, and the 1682reschedule callback will be called with the watcher as first, and the
1592current time as second argument. 1683current time as second argument.
1593 1684
1594NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1685NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever,
1595ever, or make ANY event loop modifications whatsoever>. 1686or make ANY other event loop modifications whatsoever, unless explicitly
1687allowed by documentation here>.
1596 1688
1597If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop 1689If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1598it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the 1690it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1599only event loop modification you are allowed to do). 1691only event loop modification you are allowed to do).
1600 1692
1630a different time than the last time it was called (e.g. in a crond like 1722a different time than the last time it was called (e.g. in a crond like
1631program when the crontabs have changed). 1723program when the crontabs have changed).
1632 1724
1633=item ev_tstamp ev_periodic_at (ev_periodic *) 1725=item ev_tstamp ev_periodic_at (ev_periodic *)
1634 1726
1635When active, returns the absolute time that the watcher is supposed to 1727When active, returns the absolute time that the watcher is supposed
1636trigger next. 1728to trigger next. This is not the same as the C<offset> argument to
1729C<ev_periodic_set>, but indeed works even in interval and manual
1730rescheduling modes.
1637 1731
1638=item ev_tstamp offset [read-write] 1732=item ev_tstamp offset [read-write]
1639 1733
1640When repeating, this contains the offset value, otherwise this is the 1734When repeating, this contains the offset value, otherwise this is the
1641absolute point in time (the C<at> value passed to C<ev_periodic_set>). 1735absolute point in time (the C<offset> value passed to C<ev_periodic_set>,
1736although libev might modify this value for better numerical stability).
1642 1737
1643Can be modified any time, but changes only take effect when the periodic 1738Can be modified any time, but changes only take effect when the periodic
1644timer fires or C<ev_periodic_again> is being called. 1739timer fires or C<ev_periodic_again> is being called.
1645 1740
1646=item ev_tstamp interval [read-write] 1741=item ev_tstamp interval [read-write]
1852 1947
1853 1948
1854=head2 C<ev_stat> - did the file attributes just change? 1949=head2 C<ev_stat> - did the file attributes just change?
1855 1950
1856This watches a file system path for attribute changes. That is, it calls 1951This watches a file system path for attribute changes. That is, it calls
1857C<stat> regularly (or when the OS says it changed) and sees if it changed 1952C<stat> on that path in regular intervals (or when the OS says it changed)
1858compared to the last time, invoking the callback if it did. 1953and sees if it changed compared to the last time, invoking the callback if
1954it did.
1859 1955
1860The path does not need to exist: changing from "path exists" to "path does 1956The path does not need to exist: changing from "path exists" to "path does
1861not exist" is a status change like any other. The condition "path does 1957not exist" is a status change like any other. The condition "path does not
1862not exist" is signified by the C<st_nlink> field being zero (which is 1958exist" (or more correctly "path cannot be stat'ed") is signified by the
1863otherwise always forced to be at least one) and all the other fields of 1959C<st_nlink> field being zero (which is otherwise always forced to be at
1864the stat buffer having unspecified contents. 1960least one) and all the other fields of the stat buffer having unspecified
1961contents.
1865 1962
1866The path I<should> be absolute and I<must not> end in a slash. If it is 1963The path I<must not> end in a slash or contain special components such as
1964C<.> or C<..>. The path I<should> be absolute: If it is relative and
1867relative and your working directory changes, the behaviour is undefined. 1965your working directory changes, then the behaviour is undefined.
1868 1966
1869Since there is no standard kernel interface to do this, the portable 1967Since there is no portable change notification interface available, the
1870implementation simply calls C<stat (2)> regularly on the path to see if 1968portable implementation simply calls C<stat(2)> regularly on the path
1871it changed somehow. You can specify a recommended polling interval for 1969to see if it changed somehow. You can specify a recommended polling
1872this case. If you specify a polling interval of C<0> (highly recommended!) 1970interval for this case. If you specify a polling interval of C<0> (highly
1873then a I<suitable, unspecified default> value will be used (which 1971recommended!) then a I<suitable, unspecified default> value will be used
1874you can expect to be around five seconds, although this might change 1972(which you can expect to be around five seconds, although this might
1875dynamically). Libev will also impose a minimum interval which is currently 1973change dynamically). Libev will also impose a minimum interval which is
1876around C<0.1>, but thats usually overkill. 1974currently around C<0.1>, but that's usually overkill.
1877 1975
1878This watcher type is not meant for massive numbers of stat watchers, 1976This watcher type is not meant for massive numbers of stat watchers,
1879as even with OS-supported change notifications, this can be 1977as even with OS-supported change notifications, this can be
1880resource-intensive. 1978resource-intensive.
1881 1979
1882At the time of this writing, the only OS-specific interface implemented 1980At the time of this writing, the only OS-specific interface implemented
1883is the Linux inotify interface (implementing kqueue support is left as 1981is the Linux inotify interface (implementing kqueue support is left as an
1884an exercise for the reader. Note, however, that the author sees no way 1982exercise for the reader. Note, however, that the author sees no way of
1885of implementing C<ev_stat> semantics with kqueue). 1983implementing C<ev_stat> semantics with kqueue, except as a hint).
1886 1984
1887=head3 ABI Issues (Largefile Support) 1985=head3 ABI Issues (Largefile Support)
1888 1986
1889Libev by default (unless the user overrides this) uses the default 1987Libev by default (unless the user overrides this) uses the default
1890compilation environment, which means that on systems with large file 1988compilation environment, which means that on systems with large file
1891support disabled by default, you get the 32 bit version of the stat 1989support disabled by default, you get the 32 bit version of the stat
1892structure. When using the library from programs that change the ABI to 1990structure. When using the library from programs that change the ABI to
1893use 64 bit file offsets the programs will fail. In that case you have to 1991use 64 bit file offsets the programs will fail. In that case you have to
1894compile libev with the same flags to get binary compatibility. This is 1992compile libev with the same flags to get binary compatibility. This is
1895obviously the case with any flags that change the ABI, but the problem is 1993obviously the case with any flags that change the ABI, but the problem is
1896most noticeably disabled with ev_stat and large file support. 1994most noticeably displayed with ev_stat and large file support.
1897 1995
1898The solution for this is to lobby your distribution maker to make large 1996The solution for this is to lobby your distribution maker to make large
1899file interfaces available by default (as e.g. FreeBSD does) and not 1997file interfaces available by default (as e.g. FreeBSD does) and not
1900optional. Libev cannot simply switch on large file support because it has 1998optional. Libev cannot simply switch on large file support because it has
1901to exchange stat structures with application programs compiled using the 1999to exchange stat structures with application programs compiled using the
1902default compilation environment. 2000default compilation environment.
1903 2001
1904=head3 Inotify and Kqueue 2002=head3 Inotify and Kqueue
1905 2003
1906When C<inotify (7)> support has been compiled into libev (generally 2004When C<inotify (7)> support has been compiled into libev and present at
1907only available with Linux 2.6.25 or above due to bugs in earlier 2005runtime, it will be used to speed up change detection where possible. The
1908implementations) and present at runtime, it will be used to speed up 2006inotify descriptor will be created lazily when the first C<ev_stat>
1909change detection where possible. The inotify descriptor will be created 2007watcher is being started.
1910lazily when the first C<ev_stat> watcher is being started.
1911 2008
1912Inotify presence does not change the semantics of C<ev_stat> watchers 2009Inotify presence does not change the semantics of C<ev_stat> watchers
1913except that changes might be detected earlier, and in some cases, to avoid 2010except that changes might be detected earlier, and in some cases, to avoid
1914making regular C<stat> calls. Even in the presence of inotify support 2011making regular C<stat> calls. Even in the presence of inotify support
1915there are many cases where libev has to resort to regular C<stat> polling, 2012there are many cases where libev has to resort to regular C<stat> polling,
1916but as long as the path exists, libev usually gets away without polling. 2013but as long as kernel 2.6.25 or newer is used (2.6.24 and older have too
2014many bugs), the path exists (i.e. stat succeeds), and the path resides on
2015a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and
2016xfs are fully working) libev usually gets away without polling.
1917 2017
1918There is no support for kqueue, as apparently it cannot be used to 2018There is no support for kqueue, as apparently it cannot be used to
1919implement this functionality, due to the requirement of having a file 2019implement this functionality, due to the requirement of having a file
1920descriptor open on the object at all times, and detecting renames, unlinks 2020descriptor open on the object at all times, and detecting renames, unlinks
1921etc. is difficult. 2021etc. is difficult.
1922 2022
2023=head3 C<stat ()> is a synchronous operation
2024
2025Libev doesn't normally do any kind of I/O itself, and so is not blocking
2026the process. The exception are C<ev_stat> watchers - those call C<stat
2027()>, which is a synchronous operation.
2028
2029For local paths, this usually doesn't matter: unless the system is very
2030busy or the intervals between stat's are large, a stat call will be fast,
2031as the path data is usually in memory already (except when starting the
2032watcher).
2033
2034For networked file systems, calling C<stat ()> can block an indefinite
2035time due to network issues, and even under good conditions, a stat call
2036often takes multiple milliseconds.
2037
2038Therefore, it is best to avoid using C<ev_stat> watchers on networked
2039paths, although this is fully supported by libev.
2040
1923=head3 The special problem of stat time resolution 2041=head3 The special problem of stat time resolution
1924 2042
1925The C<stat ()> system call only supports full-second resolution portably, and 2043The C<stat ()> system call only supports full-second resolution portably,
1926even on systems where the resolution is higher, most file systems still 2044and even on systems where the resolution is higher, most file systems
1927only support whole seconds. 2045still only support whole seconds.
1928 2046
1929That means that, if the time is the only thing that changes, you can 2047That means that, if the time is the only thing that changes, you can
1930easily miss updates: on the first update, C<ev_stat> detects a change and 2048easily miss updates: on the first update, C<ev_stat> detects a change and
1931calls your callback, which does something. When there is another update 2049calls your callback, which does something. When there is another update
1932within the same second, C<ev_stat> will be unable to detect unless the 2050within the same second, C<ev_stat> will be unable to detect unless the
2075 2193
2076=head3 Watcher-Specific Functions and Data Members 2194=head3 Watcher-Specific Functions and Data Members
2077 2195
2078=over 4 2196=over 4
2079 2197
2080=item ev_idle_init (ev_signal *, callback) 2198=item ev_idle_init (ev_idle *, callback)
2081 2199
2082Initialises and configures the idle watcher - it has no parameters of any 2200Initialises and configures the idle watcher - it has no parameters of any
2083kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 2201kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
2084believe me. 2202believe me.
2085 2203
2324some fds have to be watched and handled very quickly (with low latency), 2442some fds have to be watched and handled very quickly (with low latency),
2325and even priorities and idle watchers might have too much overhead. In 2443and even priorities and idle watchers might have too much overhead. In
2326this case you would put all the high priority stuff in one loop and all 2444this case you would put all the high priority stuff in one loop and all
2327the rest in a second one, and embed the second one in the first. 2445the rest in a second one, and embed the second one in the first.
2328 2446
2329As long as the watcher is active, the callback will be invoked every time 2447As long as the watcher is active, the callback will be invoked every
2330there might be events pending in the embedded loop. The callback must then 2448time there might be events pending in the embedded loop. The callback
2331call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke 2449must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
2332their callbacks (you could also start an idle watcher to give the embedded 2450sweep and invoke their callbacks (the callback doesn't need to invoke the
2333loop strictly lower priority for example). You can also set the callback 2451C<ev_embed_sweep> function directly, it could also start an idle watcher
2334to C<0>, in which case the embed watcher will automatically execute the 2452to give the embedded loop strictly lower priority for example).
2335embedded loop sweep.
2336 2453
2337As long as the watcher is started it will automatically handle events. The 2454You can also set the callback to C<0>, in which case the embed watcher
2338callback will be invoked whenever some events have been handled. You can 2455will automatically execute the embedded loop sweep whenever necessary.
2339set the callback to C<0> to avoid having to specify one if you are not
2340interested in that.
2341 2456
2342Also, there have not currently been made special provisions for forking: 2457Fork detection will be handled transparently while the C<ev_embed> watcher
2343when you fork, you not only have to call C<ev_loop_fork> on both loops, 2458is active, i.e., the embedded loop will automatically be forked when the
2344but you will also have to stop and restart any C<ev_embed> watchers 2459embedding loop forks. In other cases, the user is responsible for calling
2345yourself - but you can use a fork watcher to handle this automatically, 2460C<ev_loop_fork> on the embedded loop.
2346and future versions of libev might do just that.
2347 2461
2348Unfortunately, not all backends are embeddable: only the ones returned by 2462Unfortunately, not all backends are embeddable: only the ones returned by
2349C<ev_embeddable_backends> are, which, unfortunately, does not include any 2463C<ev_embeddable_backends> are, which, unfortunately, does not include any
2350portable one. 2464portable one.
2351 2465
2571=over 4 2685=over 4
2572 2686
2573=item ev_async_init (ev_async *, callback) 2687=item ev_async_init (ev_async *, callback)
2574 2688
2575Initialises and configures the async watcher - it has no parameters of any 2689Initialises and configures the async watcher - it has no parameters of any
2576kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless, 2690kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
2577trust me. 2691trust me.
2578 2692
2579=item ev_async_send (loop, ev_async *) 2693=item ev_async_send (loop, ev_async *)
2580 2694
2581Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2695Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2582an C<EV_ASYNC> event on the watcher into the event loop. Unlike 2696an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2583C<ev_feed_event>, this call is safe to do from other threads, signal or 2697C<ev_feed_event>, this call is safe to do from other threads, signal or
2584similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding 2698similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2585section below on what exactly this means). 2699section below on what exactly this means).
2586 2700
2701Note that, as with other watchers in libev, multiple events might get
2702compressed into a single callback invocation (another way to look at this
2703is that C<ev_async> watchers are level-triggered, set on C<ev_async_send>,
2704reset when the event loop detects that).
2705
2587This call incurs the overhead of a system call only once per loop iteration, 2706This call incurs the overhead of a system call only once per event loop
2588so while the overhead might be noticeable, it doesn't apply to repeated 2707iteration, so while the overhead might be noticeable, it doesn't apply to
2589calls to C<ev_async_send>. 2708repeated calls to C<ev_async_send> for the same event loop.
2590 2709
2591=item bool = ev_async_pending (ev_async *) 2710=item bool = ev_async_pending (ev_async *)
2592 2711
2593Returns a non-zero value when C<ev_async_send> has been called on the 2712Returns a non-zero value when C<ev_async_send> has been called on the
2594watcher but the event has not yet been processed (or even noted) by the 2713watcher but the event has not yet been processed (or even noted) by the
2597C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 2716C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2598the loop iterates next and checks for the watcher to have become active, 2717the loop iterates next and checks for the watcher to have become active,
2599it will reset the flag again. C<ev_async_pending> can be used to very 2718it will reset the flag again. C<ev_async_pending> can be used to very
2600quickly check whether invoking the loop might be a good idea. 2719quickly check whether invoking the loop might be a good idea.
2601 2720
2602Not that this does I<not> check whether the watcher itself is pending, only 2721Not that this does I<not> check whether the watcher itself is pending,
2603whether it has been requested to make this watcher pending. 2722only whether it has been requested to make this watcher pending: there
2723is a time window between the event loop checking and resetting the async
2724notification, and the callback being invoked.
2604 2725
2605=back 2726=back
2606 2727
2607 2728
2608=head1 OTHER FUNCTIONS 2729=head1 OTHER FUNCTIONS
2787 2908
2788 myclass obj; 2909 myclass obj;
2789 ev::io iow; 2910 ev::io iow;
2790 iow.set <myclass, &myclass::io_cb> (&obj); 2911 iow.set <myclass, &myclass::io_cb> (&obj);
2791 2912
2913=item w->set (object *)
2914
2915This is an B<experimental> feature that might go away in a future version.
2916
2917This is a variation of a method callback - leaving out the method to call
2918will default the method to C<operator ()>, which makes it possible to use
2919functor objects without having to manually specify the C<operator ()> all
2920the time. Incidentally, you can then also leave out the template argument
2921list.
2922
2923The C<operator ()> method prototype must be C<void operator ()(watcher &w,
2924int revents)>.
2925
2926See the method-C<set> above for more details.
2927
2928Example: use a functor object as callback.
2929
2930 struct myfunctor
2931 {
2932 void operator() (ev::io &w, int revents)
2933 {
2934 ...
2935 }
2936 }
2937
2938 myfunctor f;
2939
2940 ev::io w;
2941 w.set (&f);
2942
2792=item w->set<function> (void *data = 0) 2943=item w->set<function> (void *data = 0)
2793 2944
2794Also sets a callback, but uses a static method or plain function as 2945Also sets a callback, but uses a static method or plain function as
2795callback. The optional C<data> argument will be stored in the watcher's 2946callback. The optional C<data> argument will be stored in the watcher's
2796C<data> member and is free for you to use. 2947C<data> member and is free for you to use.
2882L<http://software.schmorp.de/pkg/EV>. 3033L<http://software.schmorp.de/pkg/EV>.
2883 3034
2884=item Python 3035=item Python
2885 3036
2886Python bindings can be found at L<http://code.google.com/p/pyev/>. It 3037Python bindings can be found at L<http://code.google.com/p/pyev/>. It
2887seems to be quite complete and well-documented. Note, however, that the 3038seems to be quite complete and well-documented.
2888patch they require for libev is outright dangerous as it breaks the ABI
2889for everybody else, and therefore, should never be applied in an installed
2890libev (if python requires an incompatible ABI then it needs to embed
2891libev).
2892 3039
2893=item Ruby 3040=item Ruby
2894 3041
2895Tony Arcieri has written a ruby extension that offers access to a subset 3042Tony Arcieri has written a ruby extension that offers access to a subset
2896of the libev API and adds file handle abstractions, asynchronous DNS and 3043of the libev API and adds file handle abstractions, asynchronous DNS and
2897more on top of it. It can be found via gem servers. Its homepage is at 3044more on top of it. It can be found via gem servers. Its homepage is at
2898L<http://rev.rubyforge.org/>. 3045L<http://rev.rubyforge.org/>.
2899 3046
3047Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3048makes rev work even on mingw.
3049
3050=item Haskell
3051
3052A haskell binding to libev is available at
3053L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3054
2900=item D 3055=item D
2901 3056
2902Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to 3057Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
2903be found at L<http://proj.llucax.com.ar/wiki/evd>. 3058be found at L<http://proj.llucax.com.ar/wiki/evd>.
3059
3060=item Ocaml
3061
3062Erkki Seppala has written Ocaml bindings for libev, to be found at
3063L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
2904 3064
2905=back 3065=back
2906 3066
2907 3067
2908=head1 MACRO MAGIC 3068=head1 MACRO MAGIC
3009 3169
3010 #define EV_STANDALONE 1 3170 #define EV_STANDALONE 1
3011 #include "ev.h" 3171 #include "ev.h"
3012 3172
3013Both header files and implementation files can be compiled with a C++ 3173Both header files and implementation files can be compiled with a C++
3014compiler (at least, thats a stated goal, and breakage will be treated 3174compiler (at least, that's a stated goal, and breakage will be treated
3015as a bug). 3175as a bug).
3016 3176
3017You need the following files in your source tree, or in a directory 3177You need the following files in your source tree, or in a directory
3018in your include path (e.g. in libev/ when using -Ilibev): 3178in your include path (e.g. in libev/ when using -Ilibev):
3019 3179
3075keeps libev from including F<config.h>, and it also defines dummy 3235keeps libev from including F<config.h>, and it also defines dummy
3076implementations for some libevent functions (such as logging, which is not 3236implementations for some libevent functions (such as logging, which is not
3077supported). It will also not define any of the structs usually found in 3237supported). It will also not define any of the structs usually found in
3078F<event.h> that are not directly supported by the libev core alone. 3238F<event.h> that are not directly supported by the libev core alone.
3079 3239
3240In stanbdalone mode, libev will still try to automatically deduce the
3241configuration, but has to be more conservative.
3242
3080=item EV_USE_MONOTONIC 3243=item EV_USE_MONOTONIC
3081 3244
3082If defined to be C<1>, libev will try to detect the availability of the 3245If defined to be C<1>, libev will try to detect the availability of the
3083monotonic clock option at both compile time and runtime. Otherwise no use 3246monotonic clock option at both compile time and runtime. Otherwise no
3084of the monotonic clock option will be attempted. If you enable this, you 3247use of the monotonic clock option will be attempted. If you enable this,
3085usually have to link against librt or something similar. Enabling it when 3248you usually have to link against librt or something similar. Enabling it
3086the functionality isn't available is safe, though, although you have 3249when the functionality isn't available is safe, though, although you have
3087to make sure you link against any libraries where the C<clock_gettime> 3250to make sure you link against any libraries where the C<clock_gettime>
3088function is hiding in (often F<-lrt>). 3251function is hiding in (often F<-lrt>). See also C<EV_USE_CLOCK_SYSCALL>.
3089 3252
3090=item EV_USE_REALTIME 3253=item EV_USE_REALTIME
3091 3254
3092If defined to be C<1>, libev will try to detect the availability of the 3255If defined to be C<1>, libev will try to detect the availability of the
3093real-time clock option at compile time (and assume its availability at 3256real-time clock option at compile time (and assume its availability
3094runtime if successful). Otherwise no use of the real-time clock option will 3257at runtime if successful). Otherwise no use of the real-time clock
3095be attempted. This effectively replaces C<gettimeofday> by C<clock_get 3258option will be attempted. This effectively replaces C<gettimeofday>
3096(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 3259by C<clock_get (CLOCK_REALTIME, ...)> and will not normally affect
3097note about libraries in the description of C<EV_USE_MONOTONIC>, though. 3260correctness. See the note about libraries in the description of
3261C<EV_USE_MONOTONIC>, though. Defaults to the opposite value of
3262C<EV_USE_CLOCK_SYSCALL>.
3263
3264=item EV_USE_CLOCK_SYSCALL
3265
3266If defined to be C<1>, libev will try to use a direct syscall instead
3267of calling the system-provided C<clock_gettime> function. This option
3268exists because on GNU/Linux, C<clock_gettime> is in C<librt>, but C<librt>
3269unconditionally pulls in C<libpthread>, slowing down single-threaded
3270programs needlessly. Using a direct syscall is slightly slower (in
3271theory), because no optimised vdso implementation can be used, but avoids
3272the pthread dependency. Defaults to C<1> on GNU/Linux with glibc 2.x or
3273higher, as it simplifies linking (no need for C<-lrt>).
3098 3274
3099=item EV_USE_NANOSLEEP 3275=item EV_USE_NANOSLEEP
3100 3276
3101If defined to be C<1>, libev will assume that C<nanosleep ()> is available 3277If defined to be C<1>, libev will assume that C<nanosleep ()> is available
3102and will use it for delays. Otherwise it will use C<select ()>. 3278and will use it for delays. Otherwise it will use C<select ()>.
3118 3294
3119=item EV_SELECT_USE_FD_SET 3295=item EV_SELECT_USE_FD_SET
3120 3296
3121If defined to C<1>, then the select backend will use the system C<fd_set> 3297If defined to C<1>, then the select backend will use the system C<fd_set>
3122structure. This is useful if libev doesn't compile due to a missing 3298structure. This is useful if libev doesn't compile due to a missing
3123C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout on 3299C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout
3124exotic systems. This usually limits the range of file descriptors to some 3300on exotic systems. This usually limits the range of file descriptors to
3125low limit such as 1024 or might have other limitations (winsocket only 3301some low limit such as 1024 or might have other limitations (winsocket
3126allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 3302only allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation,
3127influence the size of the C<fd_set> used. 3303configures the maximum size of the C<fd_set>.
3128 3304
3129=item EV_SELECT_IS_WINSOCKET 3305=item EV_SELECT_IS_WINSOCKET
3130 3306
3131When defined to C<1>, the select backend will assume that 3307When defined to C<1>, the select backend will assume that
3132select/socket/connect etc. don't understand file descriptors but 3308select/socket/connect etc. don't understand file descriptors but
3491loop, as long as you don't confuse yourself). The only exception is that 3667loop, as long as you don't confuse yourself). The only exception is that
3492you must not do this from C<ev_periodic> reschedule callbacks. 3668you must not do this from C<ev_periodic> reschedule callbacks.
3493 3669
3494Care has been taken to ensure that libev does not keep local state inside 3670Care has been taken to ensure that libev does not keep local state inside
3495C<ev_loop>, and other calls do not usually allow for coroutine switches as 3671C<ev_loop>, and other calls do not usually allow for coroutine switches as
3496they do not clal any callbacks. 3672they do not call any callbacks.
3497 3673
3498=head2 COMPILER WARNINGS 3674=head2 COMPILER WARNINGS
3499 3675
3500Depending on your compiler and compiler settings, you might get no or a 3676Depending on your compiler and compiler settings, you might get no or a
3501lot of warnings when compiling libev code. Some people are apparently 3677lot of warnings when compiling libev code. Some people are apparently
3535 ==2274== definitely lost: 0 bytes in 0 blocks. 3711 ==2274== definitely lost: 0 bytes in 0 blocks.
3536 ==2274== possibly lost: 0 bytes in 0 blocks. 3712 ==2274== possibly lost: 0 bytes in 0 blocks.
3537 ==2274== still reachable: 256 bytes in 1 blocks. 3713 ==2274== still reachable: 256 bytes in 1 blocks.
3538 3714
3539Then there is no memory leak, just as memory accounted to global variables 3715Then there is no memory leak, just as memory accounted to global variables
3540is not a memleak - the memory is still being refernced, and didn't leak. 3716is not a memleak - the memory is still being referenced, and didn't leak.
3541 3717
3542Similarly, under some circumstances, valgrind might report kernel bugs 3718Similarly, under some circumstances, valgrind might report kernel bugs
3543as if it were a bug in libev (e.g. in realloc or in the poll backend, 3719as if it were a bug in libev (e.g. in realloc or in the poll backend,
3544although an acceptable workaround has been found here), or it might be 3720although an acceptable workaround has been found here), or it might be
3545confused. 3721confused.
3783=back 3959=back
3784 3960
3785 3961
3786=head1 AUTHOR 3962=head1 AUTHOR
3787 3963
3788Marc Lehmann <libev@schmorp.de>. 3964Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3789 3965

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines