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

Comparing libev/ev.pod (file contents):
Revision 1.62 by root, Thu Nov 29 17:28:13 2007 UTC vs.
Revision 1.110 by root, Tue Dec 25 07:05:45 2007 UTC

4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 #include <ev.h> 7 #include <ev.h>
8 8
9=head1 EXAMPLE PROGRAM 9=head2 EXAMPLE PROGRAM
10 10
11 #include <ev.h> 11 #include <ev.h>
12 12
13 ev_io stdin_watcher; 13 ev_io stdin_watcher;
14 ev_timer timeout_watcher; 14 ev_timer timeout_watcher;
48 return 0; 48 return 0;
49 } 49 }
50 50
51=head1 DESCRIPTION 51=head1 DESCRIPTION
52 52
53The newest version of this document is also available as a html-formatted
54web page you might find easier to navigate when reading it for the first
55time: L<http://cvs.schmorp.de/libev/ev.html>.
56
53Libev is an event loop: you register interest in certain events (such as a 57Libev is an event loop: you register interest in certain events (such as a
54file descriptor being readable or a timeout occuring), and it will manage 58file descriptor being readable or a timeout occurring), and it will manage
55these event sources and provide your program with events. 59these event sources and provide your program with events.
56 60
57To do this, it must take more or less complete control over your process 61To do this, it must take more or less complete control over your process
58(or thread) by executing the I<event loop> handler, and will then 62(or thread) by executing the I<event loop> handler, and will then
59communicate events via a callback mechanism. 63communicate events via a callback mechanism.
61You register interest in certain events by registering so-called I<event 65You register interest in certain events by registering so-called I<event
62watchers>, which are relatively small C structures you initialise with the 66watchers>, which are relatively small C structures you initialise with the
63details of the event, and then hand it over to libev by I<starting> the 67details of the event, and then hand it over to libev by I<starting> the
64watcher. 68watcher.
65 69
66=head1 FEATURES 70=head2 FEATURES
67 71
68Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 72Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
69BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 73BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
70for file descriptor events (C<ev_io>), the Linux C<inotify> interface 74for file descriptor events (C<ev_io>), the Linux C<inotify> interface
71(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 75(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
78 82
79It also is quite fast (see this 83It also is quite fast (see this
80L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 84L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
81for example). 85for example).
82 86
83=head1 CONVENTIONS 87=head2 CONVENTIONS
84 88
85Libev is very configurable. In this manual the default configuration will 89Libev is very configurable. In this manual the default configuration will
86be described, which supports multiple event loops. For more info about 90be described, which supports multiple event loops. For more info about
87various configuration options please have a look at B<EMBED> section in 91various configuration options please have a look at B<EMBED> section in
88this manual. If libev was configured without support for multiple event 92this manual. If libev was configured without support for multiple event
89loops, then all functions taking an initial argument of name C<loop> 93loops, then all functions taking an initial argument of name C<loop>
90(which is always of type C<struct ev_loop *>) will not have this argument. 94(which is always of type C<struct ev_loop *>) will not have this argument.
91 95
92=head1 TIME REPRESENTATION 96=head2 TIME REPRESENTATION
93 97
94Libev represents time as a single floating point number, representing the 98Libev represents time as a single floating point number, representing the
95(fractional) number of seconds since the (POSIX) epoch (somewhere near 99(fractional) number of seconds since the (POSIX) epoch (somewhere near
96the beginning of 1970, details are complicated, don't ask). This type is 100the beginning of 1970, details are complicated, don't ask). This type is
97called C<ev_tstamp>, which is what you should use too. It usually aliases 101called C<ev_tstamp>, which is what you should use too. It usually aliases
98to the C<double> type in C, and when you need to do any calculations on 102to the C<double> type in C, and when you need to do any calculations on
99it, you should treat it as such. 103it, you should treat it as some floatingpoint value. Unlike the name
104component C<stamp> might indicate, it is also used for time differences
105throughout libev.
100 106
101=head1 GLOBAL FUNCTIONS 107=head1 GLOBAL FUNCTIONS
102 108
103These functions can be called anytime, even before initialising the 109These functions can be called anytime, even before initialising the
104library in any way. 110library in any way.
109 115
110Returns the current time as libev would use it. Please note that the 116Returns the current time as libev would use it. Please note that the
111C<ev_now> function is usually faster and also often returns the timestamp 117C<ev_now> function is usually faster and also often returns the timestamp
112you actually want to know. 118you actually want to know.
113 119
120=item ev_sleep (ev_tstamp interval)
121
122Sleep for the given interval: The current thread will be blocked until
123either it is interrupted or the given time interval has passed. Basically
124this is a subsecond-resolution C<sleep ()>.
125
114=item int ev_version_major () 126=item int ev_version_major ()
115 127
116=item int ev_version_minor () 128=item int ev_version_minor ()
117 129
118You can find out the major and minor version numbers of the library 130You can find out the major and minor ABI version numbers of the library
119you linked against by calling the functions C<ev_version_major> and 131you linked against by calling the functions C<ev_version_major> and
120C<ev_version_minor>. If you want, you can compare against the global 132C<ev_version_minor>. If you want, you can compare against the global
121symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the 133symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
122version of the library your program was compiled against. 134version of the library your program was compiled against.
123 135
136These version numbers refer to the ABI version of the library, not the
137release version.
138
124Usually, it's a good idea to terminate if the major versions mismatch, 139Usually, it's a good idea to terminate if the major versions mismatch,
125as this indicates an incompatible change. Minor versions are usually 140as this indicates an incompatible change. Minor versions are usually
126compatible to older versions, so a larger minor version alone is usually 141compatible to older versions, so a larger minor version alone is usually
127not a problem. 142not a problem.
128 143
129Example: Make sure we haven't accidentally been linked against the wrong 144Example: Make sure we haven't accidentally been linked against the wrong
130version. 145version.
274a fork, you can also make libev check for a fork in each iteration by 289a fork, you can also make libev check for a fork in each iteration by
275enabling this flag. 290enabling this flag.
276 291
277This works by calling C<getpid ()> on every iteration of the loop, 292This works by calling C<getpid ()> on every iteration of the loop,
278and thus this might slow down your event loop if you do a lot of loop 293and thus this might slow down your event loop if you do a lot of loop
279iterations and little real work, but is usually not noticable (on my 294iterations and little real work, but is usually not noticeable (on my
280Linux system for example, C<getpid> is actually a simple 5-insn sequence 295Linux system for example, C<getpid> is actually a simple 5-insn sequence
281without a syscall and thus I<very> fast, but my Linux system also has 296without a syscall and thus I<very> fast, but my Linux system also has
282C<pthread_atfork> which is even faster). 297C<pthread_atfork> which is even faster).
283 298
284The big advantage of this flag is that you can forget about fork (and 299The big advantage of this flag is that you can forget about fork (and
291=item C<EVBACKEND_SELECT> (value 1, portable select backend) 306=item C<EVBACKEND_SELECT> (value 1, portable select backend)
292 307
293This is your standard select(2) backend. Not I<completely> standard, as 308This is your standard select(2) backend. Not I<completely> standard, as
294libev tries to roll its own fd_set with no limits on the number of fds, 309libev tries to roll its own fd_set with no limits on the number of fds,
295but if that fails, expect a fairly low limit on the number of fds when 310but if that fails, expect a fairly low limit on the number of fds when
296using this backend. It doesn't scale too well (O(highest_fd)), but its usually 311using this backend. It doesn't scale too well (O(highest_fd)), but its
297the fastest backend for a low number of fds. 312usually the fastest backend for a low number of (low-numbered :) fds.
313
314To get good performance out of this backend you need a high amount of
315parallelity (most of the file descriptors should be busy). If you are
316writing a server, you should C<accept ()> in a loop to accept as many
317connections as possible during one iteration. You might also want to have
318a look at C<ev_set_io_collect_interval ()> to increase the amount of
319readyness notifications you get per iteration.
298 320
299=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) 321=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
300 322
301And this is your standard poll(2) backend. It's more complicated than 323And this is your standard poll(2) backend. It's more complicated
302select, but handles sparse fds better and has no artificial limit on the 324than select, but handles sparse fds better and has no artificial
303number of fds you can use (except it will slow down considerably with a 325limit on the number of fds you can use (except it will slow down
304lot of inactive fds). It scales similarly to select, i.e. O(total_fds). 326considerably with a lot of inactive fds). It scales similarly to select,
327i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
328performance tips.
305 329
306=item C<EVBACKEND_EPOLL> (value 4, Linux) 330=item C<EVBACKEND_EPOLL> (value 4, Linux)
307 331
308For few fds, this backend is a bit little slower than poll and select, 332For few fds, this backend is a bit little slower than poll and select,
309but it scales phenomenally better. While poll and select usually scale like 333but it scales phenomenally better. While poll and select usually scale
310O(total_fds) where n is the total number of fds (or the highest fd), epoll scales 334like O(total_fds) where n is the total number of fds (or the highest fd),
311either O(1) or O(active_fds). 335epoll scales either O(1) or O(active_fds). The epoll design has a number
336of shortcomings, such as silently dropping events in some hard-to-detect
337cases and rewiring a syscall per fd change, no fork support and bad
338support for dup.
312 339
313While stopping and starting an I/O watcher in the same iteration will 340While stopping, setting and starting an I/O watcher in the same iteration
314result in some caching, there is still a syscall per such incident 341will result in some caching, there is still a syscall per such incident
315(because the fd could point to a different file description now), so its 342(because the fd could point to a different file description now), so its
316best to avoid that. Also, dup()ed file descriptors might not work very 343best to avoid that. Also, C<dup ()>'ed file descriptors might not work
317well if you register events for both fds. 344very well if you register events for both fds.
318 345
319Please note that epoll sometimes generates spurious notifications, so you 346Please note that epoll sometimes generates spurious notifications, so you
320need to use non-blocking I/O or other means to avoid blocking when no data 347need to use non-blocking I/O or other means to avoid blocking when no data
321(or space) is available. 348(or space) is available.
322 349
350Best performance from this backend is achieved by not unregistering all
351watchers for a file descriptor until it has been closed, if possible, i.e.
352keep at least one watcher active per fd at all times.
353
354While nominally embeddeble in other event loops, this feature is broken in
355all kernel versions tested so far.
356
323=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 357=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
324 358
325Kqueue deserves special mention, as at the time of this writing, it 359Kqueue deserves special mention, as at the time of this writing, it
326was broken on all BSDs except NetBSD (usually it doesn't work with 360was broken on all BSDs except NetBSD (usually it doesn't work reliably
327anything but sockets and pipes, except on Darwin, where of course its 361with anything but sockets and pipes, except on Darwin, where of course
328completely useless). For this reason its not being "autodetected" 362it's completely useless). For this reason it's not being "autodetected"
329unless you explicitly specify it explicitly in the flags (i.e. using 363unless you explicitly specify it explicitly in the flags (i.e. using
330C<EVBACKEND_KQUEUE>). 364C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
365system like NetBSD.
366
367You still can embed kqueue into a normal poll or select backend and use it
368only for sockets (after having made sure that sockets work with kqueue on
369the target platform). See C<ev_embed> watchers for more info.
331 370
332It scales in the same way as the epoll backend, but the interface to the 371It scales in the same way as the epoll backend, but the interface to the
333kernel is more efficient (which says nothing about its actual speed, of 372kernel is more efficient (which says nothing about its actual speed, of
334course). While starting and stopping an I/O watcher does not cause an 373course). While stopping, setting and starting an I/O watcher does never
335extra syscall as with epoll, it still adds up to four event changes per 374cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to
336incident, so its best to avoid that. 375two event changes per incident, support for C<fork ()> is very bad and it
376drops fds silently in similarly hard-to-detect cases.
377
378This backend usually performs well under most conditions.
379
380While nominally embeddable in other event loops, this doesn't work
381everywhere, so you might need to test for this. And since it is broken
382almost everywhere, you should only use it when you have a lot of sockets
383(for which it usually works), by embedding it into another event loop
384(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
385sockets.
337 386
338=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 387=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
339 388
340This is not implemented yet (and might never be). 389This is not implemented yet (and might never be, unless you send me an
390implementation). According to reports, C</dev/poll> only supports sockets
391and is not embeddable, which would limit the usefulness of this backend
392immensely.
341 393
342=item C<EVBACKEND_PORT> (value 32, Solaris 10) 394=item C<EVBACKEND_PORT> (value 32, Solaris 10)
343 395
344This uses the Solaris 10 port mechanism. As with everything on Solaris, 396This uses the Solaris 10 event port mechanism. As with everything on Solaris,
345it's really slow, but it still scales very well (O(active_fds)). 397it's really slow, but it still scales very well (O(active_fds)).
346 398
347Please note that solaris ports can result in a lot of spurious 399Please note that solaris event ports can deliver a lot of spurious
348notifications, so you need to use non-blocking I/O or other means to avoid 400notifications, so you need to use non-blocking I/O or other means to avoid
349blocking when no data (or space) is available. 401blocking when no data (or space) is available.
402
403While this backend scales well, it requires one system call per active
404file descriptor per loop iteration. For small and medium numbers of file
405descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
406might perform better.
350 407
351=item C<EVBACKEND_ALL> 408=item C<EVBACKEND_ALL>
352 409
353Try all backends (even potentially broken ones that wouldn't be tried 410Try all backends (even potentially broken ones that wouldn't be tried
354with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 411with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
355C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 412C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
413
414It is definitely not recommended to use this flag.
356 415
357=back 416=back
358 417
359If one or more of these are ored into the flags value, then only these 418If one or more of these are ored into the flags value, then only these
360backends will be tried (in the reverse order as given here). If none are 419backends will be tried (in the reverse order as given here). If none are
395Destroys the default loop again (frees all memory and kernel state 454Destroys the default loop again (frees all memory and kernel state
396etc.). None of the active event watchers will be stopped in the normal 455etc.). None of the active event watchers will be stopped in the normal
397sense, so e.g. C<ev_is_active> might still return true. It is your 456sense, so e.g. C<ev_is_active> might still return true. It is your
398responsibility to either stop all watchers cleanly yoursef I<before> 457responsibility to either stop all watchers cleanly yoursef I<before>
399calling this function, or cope with the fact afterwards (which is usually 458calling this function, or cope with the fact afterwards (which is usually
400the easiest thing, youc na just ignore the watchers and/or C<free ()> them 459the easiest thing, you can just ignore the watchers and/or C<free ()> them
401for example). 460for example).
461
462Note that certain global state, such as signal state, will not be freed by
463this function, and related watchers (such as signal and child watchers)
464would need to be stopped manually.
465
466In general it is not advisable to call this function except in the
467rare occasion where you really need to free e.g. the signal handling
468pipe fds. If you need dynamically allocated loops it is better to use
469C<ev_loop_new> and C<ev_loop_destroy>).
402 470
403=item ev_loop_destroy (loop) 471=item ev_loop_destroy (loop)
404 472
405Like C<ev_default_destroy>, but destroys an event loop created by an 473Like C<ev_default_destroy>, but destroys an event loop created by an
406earlier call to C<ev_loop_new>. 474earlier call to C<ev_loop_new>.
430 498
431Like C<ev_default_fork>, but acts on an event loop created by 499Like C<ev_default_fork>, but acts on an event loop created by
432C<ev_loop_new>. Yes, you have to call this on every allocated event loop 500C<ev_loop_new>. Yes, you have to call this on every allocated event loop
433after fork, and how you do this is entirely your own problem. 501after fork, and how you do this is entirely your own problem.
434 502
503=item unsigned int ev_loop_count (loop)
504
505Returns the count of loop iterations for the loop, which is identical to
506the number of times libev did poll for new events. It starts at C<0> and
507happily wraps around with enough iterations.
508
509This value can sometimes be useful as a generation counter of sorts (it
510"ticks" the number of loop iterations), as it roughly corresponds with
511C<ev_prepare> and C<ev_check> calls.
512
435=item unsigned int ev_backend (loop) 513=item unsigned int ev_backend (loop)
436 514
437Returns one of the C<EVBACKEND_*> flags indicating the event backend in 515Returns one of the C<EVBACKEND_*> flags indicating the event backend in
438use. 516use.
439 517
441 519
442Returns the current "event loop time", which is the time the event loop 520Returns the current "event loop time", which is the time the event loop
443received events and started processing them. This timestamp does not 521received events and started processing them. This timestamp does not
444change as long as callbacks are being processed, and this is also the base 522change as long as callbacks are being processed, and this is also the base
445time used for relative timers. You can treat it as the timestamp of the 523time used for relative timers. You can treat it as the timestamp of the
446event occuring (or more correctly, libev finding out about it). 524event occurring (or more correctly, libev finding out about it).
447 525
448=item ev_loop (loop, int flags) 526=item ev_loop (loop, int flags)
449 527
450Finally, this is it, the event handler. This function usually is called 528Finally, this is it, the event handler. This function usually is called
451after you initialised all your watchers and you want to start handling 529after you initialised all your watchers and you want to start handling
472libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is 550libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
473usually a better approach for this kind of thing. 551usually a better approach for this kind of thing.
474 552
475Here are the gory details of what C<ev_loop> does: 553Here are the gory details of what C<ev_loop> does:
476 554
555 - Before the first iteration, call any pending watchers.
477 * If there are no active watchers (reference count is zero), return. 556 * If there are no active watchers (reference count is zero), return.
478 - Queue prepare watchers and then call all outstanding watchers. 557 - Queue all prepare watchers and then call all outstanding watchers.
479 - If we have been forked, recreate the kernel state. 558 - If we have been forked, recreate the kernel state.
480 - Update the kernel state with all outstanding changes. 559 - Update the kernel state with all outstanding changes.
481 - Update the "event loop time". 560 - Update the "event loop time".
482 - Calculate for how long to block. 561 - Calculate for how long to block.
483 - Block the process, waiting for any events. 562 - Block the process, waiting for any events.
534Example: For some weird reason, unregister the above signal handler again. 613Example: For some weird reason, unregister the above signal handler again.
535 614
536 ev_ref (loop); 615 ev_ref (loop);
537 ev_signal_stop (loop, &exitsig); 616 ev_signal_stop (loop, &exitsig);
538 617
618=item ev_set_io_collect_interval (loop, ev_tstamp interval)
619
620=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
621
622These advanced functions influence the time that libev will spend waiting
623for events. Both are by default C<0>, meaning that libev will try to
624invoke timer/periodic callbacks and I/O callbacks with minimum latency.
625
626Setting these to a higher value (the C<interval> I<must> be >= C<0>)
627allows libev to delay invocation of I/O and timer/periodic callbacks to
628increase efficiency of loop iterations.
629
630The background is that sometimes your program runs just fast enough to
631handle one (or very few) event(s) per loop iteration. While this makes
632the program responsive, it also wastes a lot of CPU time to poll for new
633events, especially with backends like C<select ()> which have a high
634overhead for the actual polling but can deliver many events at once.
635
636By setting a higher I<io collect interval> you allow libev to spend more
637time collecting I/O events, so you can handle more events per iteration,
638at the cost of increasing latency. Timeouts (both C<ev_periodic> and
639C<ev_timer>) will be not affected. Setting this to a non-null value will
640introduce an additional C<ev_sleep ()> call into most loop iterations.
641
642Likewise, by setting a higher I<timeout collect interval> you allow libev
643to spend more time collecting timeouts, at the expense of increased
644latency (the watcher callback will be called later). C<ev_io> watchers
645will not be affected. Setting this to a non-null value will not introduce
646any overhead in libev.
647
648Many (busy) programs can usually benefit by setting the io collect
649interval to a value near C<0.1> or so, which is often enough for
650interactive servers (of course not for games), likewise for timeouts. It
651usually doesn't make much sense to set it to a lower value than C<0.01>,
652as this approsaches the timing granularity of most systems.
653
539=back 654=back
540 655
541 656
542=head1 ANATOMY OF A WATCHER 657=head1 ANATOMY OF A WATCHER
543 658
722=item bool ev_is_pending (ev_TYPE *watcher) 837=item bool ev_is_pending (ev_TYPE *watcher)
723 838
724Returns a true value iff the watcher is pending, (i.e. it has outstanding 839Returns a true value iff the watcher is pending, (i.e. it has outstanding
725events but its callback has not yet been invoked). As long as a watcher 840events but its callback has not yet been invoked). As long as a watcher
726is pending (but not active) you must not call an init function on it (but 841is pending (but not active) you must not call an init function on it (but
727C<ev_TYPE_set> is safe) and you must make sure the watcher is available to 842C<ev_TYPE_set> is safe), you must not change its priority, and you must
728libev (e.g. you cnanot C<free ()> it). 843make sure the watcher is available to libev (e.g. you cannot C<free ()>
844it).
729 845
730=item callback ev_cb (ev_TYPE *watcher) 846=item callback ev_cb (ev_TYPE *watcher)
731 847
732Returns the callback currently set on the watcher. 848Returns the callback currently set on the watcher.
733 849
734=item ev_cb_set (ev_TYPE *watcher, callback) 850=item ev_cb_set (ev_TYPE *watcher, callback)
735 851
736Change the callback. You can change the callback at virtually any time 852Change the callback. You can change the callback at virtually any time
737(modulo threads). 853(modulo threads).
854
855=item ev_set_priority (ev_TYPE *watcher, priority)
856
857=item int ev_priority (ev_TYPE *watcher)
858
859Set and query the priority of the watcher. The priority is a small
860integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
861(default: C<-2>). Pending watchers with higher priority will be invoked
862before watchers with lower priority, but priority will not keep watchers
863from being executed (except for C<ev_idle> watchers).
864
865This means that priorities are I<only> used for ordering callback
866invocation after new events have been received. This is useful, for
867example, to reduce latency after idling, or more often, to bind two
868watchers on the same event and make sure one is called first.
869
870If you need to suppress invocation when higher priority events are pending
871you need to look at C<ev_idle> watchers, which provide this functionality.
872
873You I<must not> change the priority of a watcher as long as it is active or
874pending.
875
876The default priority used by watchers when no priority has been set is
877always C<0>, which is supposed to not be too high and not be too low :).
878
879Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
880fine, as long as you do not mind that the priority value you query might
881or might not have been adjusted to be within valid range.
882
883=item ev_invoke (loop, ev_TYPE *watcher, int revents)
884
885Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
886C<loop> nor C<revents> need to be valid as long as the watcher callback
887can deal with that fact.
888
889=item int ev_clear_pending (loop, ev_TYPE *watcher)
890
891If the watcher is pending, this function returns clears its pending status
892and returns its C<revents> bitset (as if its callback was invoked). If the
893watcher isn't pending it does nothing and returns C<0>.
738 894
739=back 895=back
740 896
741 897
742=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 898=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
827In general you can register as many read and/or write event watchers per 983In general you can register as many read and/or write event watchers per
828fd as you want (as long as you don't confuse yourself). Setting all file 984fd as you want (as long as you don't confuse yourself). Setting all file
829descriptors to non-blocking mode is also usually a good idea (but not 985descriptors to non-blocking mode is also usually a good idea (but not
830required if you know what you are doing). 986required if you know what you are doing).
831 987
832You have to be careful with dup'ed file descriptors, though. Some backends
833(the linux epoll backend is a notable example) cannot handle dup'ed file
834descriptors correctly if you register interest in two or more fds pointing
835to the same underlying file/socket/etc. description (that is, they share
836the same underlying "file open").
837
838If you must do this, then force the use of a known-to-be-good backend 988If you must do this, then force the use of a known-to-be-good backend
839(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 989(at the time of this writing, this includes only C<EVBACKEND_SELECT> and
840C<EVBACKEND_POLL>). 990C<EVBACKEND_POLL>).
841 991
842Another thing you have to watch out for is that it is quite easy to 992Another thing you have to watch out for is that it is quite easy to
848it is best to always use non-blocking I/O: An extra C<read>(2) returning 998it is best to always use non-blocking I/O: An extra C<read>(2) returning
849C<EAGAIN> is far preferable to a program hanging until some data arrives. 999C<EAGAIN> is far preferable to a program hanging until some data arrives.
850 1000
851If you cannot run the fd in non-blocking mode (for example you should not 1001If you cannot run the fd in non-blocking mode (for example you should not
852play around with an Xlib connection), then you have to seperately re-test 1002play around with an Xlib connection), then you have to seperately re-test
853wether a file descriptor is really ready with a known-to-be good interface 1003whether a file descriptor is really ready with a known-to-be good interface
854such as poll (fortunately in our Xlib example, Xlib already does this on 1004such as poll (fortunately in our Xlib example, Xlib already does this on
855its own, so its quite safe to use). 1005its own, so its quite safe to use).
1006
1007=head3 The special problem of disappearing file descriptors
1008
1009Some backends (e.g. kqueue, epoll) need to be told about closing a file
1010descriptor (either by calling C<close> explicitly or by any other means,
1011such as C<dup>). The reason is that you register interest in some file
1012descriptor, but when it goes away, the operating system will silently drop
1013this interest. If another file descriptor with the same number then is
1014registered with libev, there is no efficient way to see that this is, in
1015fact, a different file descriptor.
1016
1017To avoid having to explicitly tell libev about such cases, libev follows
1018the following policy: Each time C<ev_io_set> is being called, libev
1019will assume that this is potentially a new file descriptor, otherwise
1020it is assumed that the file descriptor stays the same. That means that
1021you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the
1022descriptor even if the file descriptor number itself did not change.
1023
1024This is how one would do it normally anyway, the important point is that
1025the libev application should not optimise around libev but should leave
1026optimisations to libev.
1027
1028=head3 The special problem of dup'ed file descriptors
1029
1030Some backends (e.g. epoll), cannot register events for file descriptors,
1031but only events for the underlying file descriptions. That means when you
1032have C<dup ()>'ed file descriptors or weirder constellations, and register
1033events for them, only one file descriptor might actually receive events.
1034
1035There is no workaround possible except not registering events
1036for potentially C<dup ()>'ed file descriptors, or to resort to
1037C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1038
1039=head3 The special problem of fork
1040
1041Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
1042useless behaviour. Libev fully supports fork, but needs to be told about
1043it in the child.
1044
1045To support fork in your programs, you either have to call
1046C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
1047enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1048C<EVBACKEND_POLL>.
1049
1050
1051=head3 Watcher-Specific Functions
856 1052
857=over 4 1053=over 4
858 1054
859=item ev_io_init (ev_io *, callback, int fd, int events) 1055=item ev_io_init (ev_io *, callback, int fd, int events)
860 1056
913 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1109 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
914 1110
915The callback is guarenteed to be invoked only when its timeout has passed, 1111The callback is guarenteed to be invoked only when its timeout has passed,
916but if multiple timers become ready during the same loop iteration then 1112but if multiple timers become ready during the same loop iteration then
917order of execution is undefined. 1113order of execution is undefined.
1114
1115=head3 Watcher-Specific Functions and Data Members
918 1116
919=over 4 1117=over 4
920 1118
921=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1119=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
922 1120
1018but on wallclock time (absolute time). You can tell a periodic watcher 1216but on wallclock time (absolute time). You can tell a periodic watcher
1019to trigger "at" some specific point in time. For example, if you tell a 1217to trigger "at" some specific point in time. For example, if you tell a
1020periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now () 1218periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
1021+ 10.>) and then reset your system clock to the last year, then it will 1219+ 10.>) and then reset your system clock to the last year, then it will
1022take a year to trigger the event (unlike an C<ev_timer>, which would trigger 1220take a year to trigger the event (unlike an C<ev_timer>, which would trigger
1023roughly 10 seconds later and of course not if you reset your system time 1221roughly 10 seconds later).
1024again).
1025 1222
1026They can also be used to implement vastly more complex timers, such as 1223They can also be used to implement vastly more complex timers, such as
1027triggering an event on eahc midnight, local time. 1224triggering an event on each midnight, local time or other, complicated,
1225rules.
1028 1226
1029As with timers, the callback is guarenteed to be invoked only when the 1227As with timers, the callback is guarenteed to be invoked only when the
1030time (C<at>) has been passed, but if multiple periodic timers become ready 1228time (C<at>) has been passed, but if multiple periodic timers become ready
1031during the same loop iteration then order of execution is undefined. 1229during the same loop iteration then order of execution is undefined.
1032 1230
1231=head3 Watcher-Specific Functions and Data Members
1232
1033=over 4 1233=over 4
1034 1234
1035=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1235=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1036 1236
1037=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1237=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
1039Lots of arguments, lets sort it out... There are basically three modes of 1239Lots of arguments, lets sort it out... There are basically three modes of
1040operation, and we will explain them from simplest to complex: 1240operation, and we will explain them from simplest to complex:
1041 1241
1042=over 4 1242=over 4
1043 1243
1044=item * absolute timer (interval = reschedule_cb = 0) 1244=item * absolute timer (at = time, interval = reschedule_cb = 0)
1045 1245
1046In this configuration the watcher triggers an event at the wallclock time 1246In this configuration the watcher triggers an event at the wallclock time
1047C<at> and doesn't repeat. It will not adjust when a time jump occurs, 1247C<at> and doesn't repeat. It will not adjust when a time jump occurs,
1048that is, if it is to be run at January 1st 2011 then it will run when the 1248that is, if it is to be run at January 1st 2011 then it will run when the
1049system time reaches or surpasses this time. 1249system time reaches or surpasses this time.
1050 1250
1051=item * non-repeating interval timer (interval > 0, reschedule_cb = 0) 1251=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1052 1252
1053In this mode the watcher will always be scheduled to time out at the next 1253In this mode the watcher will always be scheduled to time out at the next
1054C<at + N * interval> time (for some integer N) and then repeat, regardless 1254C<at + N * interval> time (for some integer N, which can also be negative)
1055of any time jumps. 1255and then repeat, regardless of any time jumps.
1056 1256
1057This can be used to create timers that do not drift with respect to system 1257This can be used to create timers that do not drift with respect to system
1058time: 1258time:
1059 1259
1060 ev_periodic_set (&periodic, 0., 3600., 0); 1260 ev_periodic_set (&periodic, 0., 3600., 0);
1066 1266
1067Another way to think about it (for the mathematically inclined) is that 1267Another way to think about it (for the mathematically inclined) is that
1068C<ev_periodic> will try to run the callback in this mode at the next possible 1268C<ev_periodic> will try to run the callback in this mode at the next possible
1069time where C<time = at (mod interval)>, regardless of any time jumps. 1269time where C<time = at (mod interval)>, regardless of any time jumps.
1070 1270
1271For numerical stability it is preferable that the C<at> value is near
1272C<ev_now ()> (the current time), but there is no range requirement for
1273this value.
1274
1071=item * manual reschedule mode (reschedule_cb = callback) 1275=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1072 1276
1073In this mode the values for C<interval> and C<at> are both being 1277In this mode the values for C<interval> and C<at> are both being
1074ignored. Instead, each time the periodic watcher gets scheduled, the 1278ignored. Instead, each time the periodic watcher gets scheduled, the
1075reschedule callback will be called with the watcher as first, and the 1279reschedule callback will be called with the watcher as first, and the
1076current time as second argument. 1280current time as second argument.
1077 1281
1078NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1282NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1079ever, or make any event loop modifications>. If you need to stop it, 1283ever, or make any event loop modifications>. If you need to stop it,
1080return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by 1284return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1081starting a prepare watcher). 1285starting an C<ev_prepare> watcher, which is legal).
1082 1286
1083Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 1287Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
1084ev_tstamp now)>, e.g.: 1288ev_tstamp now)>, e.g.:
1085 1289
1086 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1290 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
1109Simply stops and restarts the periodic watcher again. This is only useful 1313Simply stops and restarts the periodic watcher again. This is only useful
1110when you changed some parameters or the reschedule callback would return 1314when you changed some parameters or the reschedule callback would return
1111a different time than the last time it was called (e.g. in a crond like 1315a different time than the last time it was called (e.g. in a crond like
1112program when the crontabs have changed). 1316program when the crontabs have changed).
1113 1317
1318=item ev_tstamp offset [read-write]
1319
1320When repeating, this contains the offset value, otherwise this is the
1321absolute point in time (the C<at> value passed to C<ev_periodic_set>).
1322
1323Can be modified any time, but changes only take effect when the periodic
1324timer fires or C<ev_periodic_again> is being called.
1325
1114=item ev_tstamp interval [read-write] 1326=item ev_tstamp interval [read-write]
1115 1327
1116The current interval value. Can be modified any time, but changes only 1328The current interval value. Can be modified any time, but changes only
1117take effect when the periodic timer fires or C<ev_periodic_again> is being 1329take effect when the periodic timer fires or C<ev_periodic_again> is being
1118called. 1330called.
1120=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] 1332=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]
1121 1333
1122The current reschedule callback, or C<0>, if this functionality is 1334The current reschedule callback, or C<0>, if this functionality is
1123switched off. Can be changed any time, but changes only take effect when 1335switched off. Can be changed any time, but changes only take effect when
1124the periodic timer fires or C<ev_periodic_again> is being called. 1336the periodic timer fires or C<ev_periodic_again> is being called.
1337
1338=item ev_tstamp at [read-only]
1339
1340When active, contains the absolute time that the watcher is supposed to
1341trigger next.
1125 1342
1126=back 1343=back
1127 1344
1128Example: Call a callback every hour, or, more precisely, whenever the 1345Example: Call a callback every hour, or, more precisely, whenever the
1129system clock is divisible by 3600. The callback invocation times have 1346system clock is divisible by 3600. The callback invocation times have
1171with the kernel (thus it coexists with your own signal handlers as long 1388with the kernel (thus it coexists with your own signal handlers as long
1172as you don't register any with libev). Similarly, when the last signal 1389as you don't register any with libev). Similarly, when the last signal
1173watcher for a signal is stopped libev will reset the signal handler to 1390watcher for a signal is stopped libev will reset the signal handler to
1174SIG_DFL (regardless of what it was set to before). 1391SIG_DFL (regardless of what it was set to before).
1175 1392
1393=head3 Watcher-Specific Functions and Data Members
1394
1176=over 4 1395=over 4
1177 1396
1178=item ev_signal_init (ev_signal *, callback, int signum) 1397=item ev_signal_init (ev_signal *, callback, int signum)
1179 1398
1180=item ev_signal_set (ev_signal *, int signum) 1399=item ev_signal_set (ev_signal *, int signum)
1191 1410
1192=head2 C<ev_child> - watch out for process status changes 1411=head2 C<ev_child> - watch out for process status changes
1193 1412
1194Child watchers trigger when your process receives a SIGCHLD in response to 1413Child watchers trigger when your process receives a SIGCHLD in response to
1195some child status changes (most typically when a child of yours dies). 1414some child status changes (most typically when a child of yours dies).
1415
1416=head3 Watcher-Specific Functions and Data Members
1196 1417
1197=over 4 1418=over 4
1198 1419
1199=item ev_child_init (ev_child *, callback, int pid) 1420=item ev_child_init (ev_child *, callback, int pid)
1200 1421
1269semantics of C<ev_stat> watchers, which means that libev sometimes needs 1490semantics of C<ev_stat> watchers, which means that libev sometimes needs
1270to fall back to regular polling again even with inotify, but changes are 1491to fall back to regular polling again even with inotify, but changes are
1271usually detected immediately, and if the file exists there will be no 1492usually detected immediately, and if the file exists there will be no
1272polling. 1493polling.
1273 1494
1495=head3 Inotify
1496
1497When C<inotify (7)> support has been compiled into libev (generally only
1498available on Linux) and present at runtime, it will be used to speed up
1499change detection where possible. The inotify descriptor will be created lazily
1500when the first C<ev_stat> watcher is being started.
1501
1502Inotify presense does not change the semantics of C<ev_stat> watchers
1503except that changes might be detected earlier, and in some cases, to avoid
1504making regular C<stat> calls. Even in the presense of inotify support
1505there are many cases where libev has to resort to regular C<stat> polling.
1506
1507(There is no support for kqueue, as apparently it cannot be used to
1508implement this functionality, due to the requirement of having a file
1509descriptor open on the object at all times).
1510
1511=head3 The special problem of stat time resolution
1512
1513The C<stat ()> syscall only supports full-second resolution portably, and
1514even on systems where the resolution is higher, many filesystems still
1515only support whole seconds.
1516
1517That means that, if the time is the only thing that changes, you might
1518miss updates: on the first update, C<ev_stat> detects a change and calls
1519your callback, which does something. When there is another update within
1520the same second, C<ev_stat> will be unable to detect it.
1521
1522The solution to this is to delay acting on a change for a second (or till
1523the next second boundary), using a roughly one-second delay C<ev_timer>
1524(C<ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)>). The C<.01>
1525is added to work around small timing inconsistencies of some operating
1526systems.
1527
1528=head3 Watcher-Specific Functions and Data Members
1529
1274=over 4 1530=over 4
1275 1531
1276=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) 1532=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1277 1533
1278=item ev_stat_set (ev_stat *, const char *path, ev_tstamp interval) 1534=item ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)
1313=item const char *path [read-only] 1569=item const char *path [read-only]
1314 1570
1315The filesystem path that is being watched. 1571The filesystem path that is being watched.
1316 1572
1317=back 1573=back
1574
1575=head3 Examples
1318 1576
1319Example: Watch C</etc/passwd> for attribute changes. 1577Example: Watch C</etc/passwd> for attribute changes.
1320 1578
1321 static void 1579 static void
1322 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 1580 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1335 } 1593 }
1336 1594
1337 ... 1595 ...
1338 ev_stat passwd; 1596 ev_stat passwd;
1339 1597
1340 ev_stat_init (&passwd, passwd_cb, "/etc/passwd"); 1598 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1341 ev_stat_start (loop, &passwd); 1599 ev_stat_start (loop, &passwd);
1342 1600
1601Example: Like above, but additionally use a one-second delay so we do not
1602miss updates (however, frequent updates will delay processing, too, so
1603one might do the work both on C<ev_stat> callback invocation I<and> on
1604C<ev_timer> callback invocation).
1605
1606 static ev_stat passwd;
1607 static ev_timer timer;
1608
1609 static void
1610 timer_cb (EV_P_ ev_timer *w, int revents)
1611 {
1612 ev_timer_stop (EV_A_ w);
1613
1614 /* now it's one second after the most recent passwd change */
1615 }
1616
1617 static void
1618 stat_cb (EV_P_ ev_stat *w, int revents)
1619 {
1620 /* reset the one-second timer */
1621 ev_timer_again (EV_A_ &timer);
1622 }
1623
1624 ...
1625 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1626 ev_stat_start (loop, &passwd);
1627 ev_timer_init (&timer, timer_cb, 0., 1.01);
1628
1343 1629
1344=head2 C<ev_idle> - when you've got nothing better to do... 1630=head2 C<ev_idle> - when you've got nothing better to do...
1345 1631
1346Idle watchers trigger events when there are no other events are pending 1632Idle watchers trigger events when no other events of the same or higher
1347(prepare, check and other idle watchers do not count). That is, as long 1633priority are pending (prepare, check and other idle watchers do not
1348as your process is busy handling sockets or timeouts (or even signals, 1634count).
1349imagine) it will not be triggered. But when your process is idle all idle 1635
1350watchers are being called again and again, once per event loop iteration - 1636That is, as long as your process is busy handling sockets or timeouts
1637(or even signals, imagine) of the same or higher priority it will not be
1638triggered. But when your process is idle (or only lower-priority watchers
1639are pending), the idle watchers are being called once per event loop
1351until stopped, that is, or your process receives more events and becomes 1640iteration - until stopped, that is, or your process receives more events
1352busy. 1641and becomes busy again with higher priority stuff.
1353 1642
1354The most noteworthy effect is that as long as any idle watchers are 1643The most noteworthy effect is that as long as any idle watchers are
1355active, the process will not block when waiting for new events. 1644active, the process will not block when waiting for new events.
1356 1645
1357Apart from keeping your process non-blocking (which is a useful 1646Apart from keeping your process non-blocking (which is a useful
1358effect on its own sometimes), idle watchers are a good place to do 1647effect on its own sometimes), idle watchers are a good place to do
1359"pseudo-background processing", or delay processing stuff to after the 1648"pseudo-background processing", or delay processing stuff to after the
1360event loop has handled all outstanding events. 1649event loop has handled all outstanding events.
1650
1651=head3 Watcher-Specific Functions and Data Members
1361 1652
1362=over 4 1653=over 4
1363 1654
1364=item ev_idle_init (ev_signal *, callback) 1655=item ev_idle_init (ev_signal *, callback)
1365 1656
1423with priority higher than or equal to the event loop and one coroutine 1714with priority higher than or equal to the event loop and one coroutine
1424of lower priority, but only once, using idle watchers to keep the event 1715of lower priority, but only once, using idle watchers to keep the event
1425loop from blocking if lower-priority coroutines are active, thus mapping 1716loop from blocking if lower-priority coroutines are active, thus mapping
1426low-priority coroutines to idle/background tasks). 1717low-priority coroutines to idle/background tasks).
1427 1718
1719It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1720priority, to ensure that they are being run before any other watchers
1721after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
1722too) should not activate ("feed") events into libev. While libev fully
1723supports this, they will be called before other C<ev_check> watchers
1724did their job. As C<ev_check> watchers are often used to embed other
1725(non-libev) event loops those other event loops might be in an unusable
1726state until their C<ev_check> watcher ran (always remind yourself to
1727coexist peacefully with others).
1728
1729=head3 Watcher-Specific Functions and Data Members
1730
1428=over 4 1731=over 4
1429 1732
1430=item ev_prepare_init (ev_prepare *, callback) 1733=item ev_prepare_init (ev_prepare *, callback)
1431 1734
1432=item ev_check_init (ev_check *, callback) 1735=item ev_check_init (ev_check *, callback)
1435parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 1738parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1436macros, but using them is utterly, utterly and completely pointless. 1739macros, but using them is utterly, utterly and completely pointless.
1437 1740
1438=back 1741=back
1439 1742
1440Example: To include a library such as adns, you would add IO watchers 1743There are a number of principal ways to embed other event loops or modules
1441and a timeout watcher in a prepare handler, as required by libadns, and 1744into libev. Here are some ideas on how to include libadns into libev
1745(there is a Perl module named C<EV::ADNS> that does this, which you could
1746use for an actually working example. Another Perl module named C<EV::Glib>
1747embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV
1748into the Glib event loop).
1749
1750Method 1: Add IO watchers and a timeout watcher in a prepare handler,
1442in a check watcher, destroy them and call into libadns. What follows is 1751and in a check watcher, destroy them and call into libadns. What follows
1443pseudo-code only of course: 1752is pseudo-code only of course. This requires you to either use a low
1753priority for the check watcher or use C<ev_clear_pending> explicitly, as
1754the callbacks for the IO/timeout watchers might not have been called yet.
1444 1755
1445 static ev_io iow [nfd]; 1756 static ev_io iow [nfd];
1446 static ev_timer tw; 1757 static ev_timer tw;
1447 1758
1448 static void 1759 static void
1449 io_cb (ev_loop *loop, ev_io *w, int revents) 1760 io_cb (ev_loop *loop, ev_io *w, int revents)
1450 { 1761 {
1451 // set the relevant poll flags
1452 // could also call adns_processreadable etc. here
1453 struct pollfd *fd = (struct pollfd *)w->data;
1454 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1455 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1456 } 1762 }
1457 1763
1458 // create io watchers for each fd and a timer before blocking 1764 // create io watchers for each fd and a timer before blocking
1459 static void 1765 static void
1460 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 1766 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1461 { 1767 {
1462 int timeout = 3600000;truct pollfd fds [nfd]; 1768 int timeout = 3600000;
1769 struct pollfd fds [nfd];
1463 // actual code will need to loop here and realloc etc. 1770 // actual code will need to loop here and realloc etc.
1464 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 1771 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1465 1772
1466 /* the callback is illegal, but won't be called as we stop during check */ 1773 /* the callback is illegal, but won't be called as we stop during check */
1467 ev_timer_init (&tw, 0, timeout * 1e-3); 1774 ev_timer_init (&tw, 0, timeout * 1e-3);
1468 ev_timer_start (loop, &tw); 1775 ev_timer_start (loop, &tw);
1469 1776
1470 // create on ev_io per pollfd 1777 // create one ev_io per pollfd
1471 for (int i = 0; i < nfd; ++i) 1778 for (int i = 0; i < nfd; ++i)
1472 { 1779 {
1473 ev_io_init (iow + i, io_cb, fds [i].fd, 1780 ev_io_init (iow + i, io_cb, fds [i].fd,
1474 ((fds [i].events & POLLIN ? EV_READ : 0) 1781 ((fds [i].events & POLLIN ? EV_READ : 0)
1475 | (fds [i].events & POLLOUT ? EV_WRITE : 0))); 1782 | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1476 1783
1477 fds [i].revents = 0; 1784 fds [i].revents = 0;
1478 iow [i].data = fds + i;
1479 ev_io_start (loop, iow + i); 1785 ev_io_start (loop, iow + i);
1480 } 1786 }
1481 } 1787 }
1482 1788
1483 // stop all watchers after blocking 1789 // stop all watchers after blocking
1485 adns_check_cb (ev_loop *loop, ev_check *w, int revents) 1791 adns_check_cb (ev_loop *loop, ev_check *w, int revents)
1486 { 1792 {
1487 ev_timer_stop (loop, &tw); 1793 ev_timer_stop (loop, &tw);
1488 1794
1489 for (int i = 0; i < nfd; ++i) 1795 for (int i = 0; i < nfd; ++i)
1796 {
1797 // set the relevant poll flags
1798 // could also call adns_processreadable etc. here
1799 struct pollfd *fd = fds + i;
1800 int revents = ev_clear_pending (iow + i);
1801 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1802 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1803
1804 // now stop the watcher
1490 ev_io_stop (loop, iow + i); 1805 ev_io_stop (loop, iow + i);
1806 }
1491 1807
1492 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); 1808 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
1809 }
1810
1811Method 2: This would be just like method 1, but you run C<adns_afterpoll>
1812in the prepare watcher and would dispose of the check watcher.
1813
1814Method 3: If the module to be embedded supports explicit event
1815notification (adns does), you can also make use of the actual watcher
1816callbacks, and only destroy/create the watchers in the prepare watcher.
1817
1818 static void
1819 timer_cb (EV_P_ ev_timer *w, int revents)
1820 {
1821 adns_state ads = (adns_state)w->data;
1822 update_now (EV_A);
1823
1824 adns_processtimeouts (ads, &tv_now);
1825 }
1826
1827 static void
1828 io_cb (EV_P_ ev_io *w, int revents)
1829 {
1830 adns_state ads = (adns_state)w->data;
1831 update_now (EV_A);
1832
1833 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now);
1834 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
1835 }
1836
1837 // do not ever call adns_afterpoll
1838
1839Method 4: Do not use a prepare or check watcher because the module you
1840want to embed is too inflexible to support it. Instead, youc na override
1841their poll function. The drawback with this solution is that the main
1842loop is now no longer controllable by EV. The C<Glib::EV> module does
1843this.
1844
1845 static gint
1846 event_poll_func (GPollFD *fds, guint nfds, gint timeout)
1847 {
1848 int got_events = 0;
1849
1850 for (n = 0; n < nfds; ++n)
1851 // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
1852
1853 if (timeout >= 0)
1854 // create/start timer
1855
1856 // poll
1857 ev_loop (EV_A_ 0);
1858
1859 // stop timer again
1860 if (timeout >= 0)
1861 ev_timer_stop (EV_A_ &to);
1862
1863 // stop io watchers again - their callbacks should have set
1864 for (n = 0; n < nfds; ++n)
1865 ev_io_stop (EV_A_ iow [n]);
1866
1867 return got_events;
1493 } 1868 }
1494 1869
1495 1870
1496=head2 C<ev_embed> - when one backend isn't enough... 1871=head2 C<ev_embed> - when one backend isn't enough...
1497 1872
1561 ev_embed_start (loop_hi, &embed); 1936 ev_embed_start (loop_hi, &embed);
1562 } 1937 }
1563 else 1938 else
1564 loop_lo = loop_hi; 1939 loop_lo = loop_hi;
1565 1940
1941=head3 Watcher-Specific Functions and Data Members
1942
1566=over 4 1943=over 4
1567 1944
1568=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 1945=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
1569 1946
1570=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 1947=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
1579 1956
1580Make a single, non-blocking sweep over the embedded loop. This works 1957Make a single, non-blocking sweep over the embedded loop. This works
1581similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 1958similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
1582apropriate way for embedded loops. 1959apropriate way for embedded loops.
1583 1960
1584=item struct ev_loop *loop [read-only] 1961=item struct ev_loop *other [read-only]
1585 1962
1586The embedded event loop. 1963The embedded event loop.
1587 1964
1588=back 1965=back
1589 1966
1596event loop blocks next and before C<ev_check> watchers are being called, 1973event loop blocks next and before C<ev_check> watchers are being called,
1597and only in the child after the fork. If whoever good citizen calling 1974and only in the child after the fork. If whoever good citizen calling
1598C<ev_default_fork> cheats and calls it in the wrong process, the fork 1975C<ev_default_fork> cheats and calls it in the wrong process, the fork
1599handlers will be invoked, too, of course. 1976handlers will be invoked, too, of course.
1600 1977
1978=head3 Watcher-Specific Functions and Data Members
1979
1601=over 4 1980=over 4
1602 1981
1603=item ev_fork_init (ev_signal *, callback) 1982=item ev_fork_init (ev_signal *, callback)
1604 1983
1605Initialises and configures the fork watcher - it has no parameters of any 1984Initialises and configures the fork watcher - it has no parameters of any
1701 2080
1702To use it, 2081To use it,
1703 2082
1704 #include <ev++.h> 2083 #include <ev++.h>
1705 2084
1706(it is not installed by default). This automatically includes F<ev.h> 2085This automatically includes F<ev.h> and puts all of its definitions (many
1707and puts all of its definitions (many of them macros) into the global 2086of them macros) into the global namespace. All C++ specific things are
1708namespace. All C++ specific things are put into the C<ev> namespace. 2087put into the C<ev> namespace. It should support all the same embedding
2088options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
1709 2089
1710It should support all the same embedding options as F<ev.h>, most notably 2090Care has been taken to keep the overhead low. The only data member the C++
1711C<EV_MULTIPLICITY>. 2091classes add (compared to plain C-style watchers) is the event loop pointer
2092that the watcher is associated with (or no additional members at all if
2093you disable C<EV_MULTIPLICITY> when embedding libev).
2094
2095Currently, functions, and static and non-static member functions can be
2096used as callbacks. Other types should be easy to add as long as they only
2097need one additional pointer for context. If you need support for other
2098types of functors please contact the author (preferably after implementing
2099it).
1712 2100
1713Here is a list of things available in the C<ev> namespace: 2101Here is a list of things available in the C<ev> namespace:
1714 2102
1715=over 4 2103=over 4
1716 2104
1732 2120
1733All of those classes have these methods: 2121All of those classes have these methods:
1734 2122
1735=over 4 2123=over 4
1736 2124
1737=item ev::TYPE::TYPE (object *, object::method *) 2125=item ev::TYPE::TYPE ()
1738 2126
1739=item ev::TYPE::TYPE (object *, object::method *, struct ev_loop *) 2127=item ev::TYPE::TYPE (struct ev_loop *)
1740 2128
1741=item ev::TYPE::~TYPE 2129=item ev::TYPE::~TYPE
1742 2130
1743The constructor takes a pointer to an object and a method pointer to 2131The constructor (optionally) takes an event loop to associate the watcher
1744the event handler callback to call in this class. The constructor calls 2132with. If it is omitted, it will use C<EV_DEFAULT>.
1745C<ev_init> for you, which means you have to call the C<set> method 2133
1746before starting it. If you do not specify a loop then the constructor 2134The constructor calls C<ev_init> for you, which means you have to call the
1747automatically associates the default loop with this watcher. 2135C<set> method before starting it.
2136
2137It will not set a callback, however: You have to call the templated C<set>
2138method to set a callback before you can start the watcher.
2139
2140(The reason why you have to use a method is a limitation in C++ which does
2141not allow explicit template arguments for constructors).
1748 2142
1749The destructor automatically stops the watcher if it is active. 2143The destructor automatically stops the watcher if it is active.
2144
2145=item w->set<class, &class::method> (object *)
2146
2147This method sets the callback method to call. The method has to have a
2148signature of C<void (*)(ev_TYPE &, int)>, it receives the watcher as
2149first argument and the C<revents> as second. The object must be given as
2150parameter and is stored in the C<data> member of the watcher.
2151
2152This method synthesizes efficient thunking code to call your method from
2153the C callback that libev requires. If your compiler can inline your
2154callback (i.e. it is visible to it at the place of the C<set> call and
2155your compiler is good :), then the method will be fully inlined into the
2156thunking function, making it as fast as a direct C callback.
2157
2158Example: simple class declaration and watcher initialisation
2159
2160 struct myclass
2161 {
2162 void io_cb (ev::io &w, int revents) { }
2163 }
2164
2165 myclass obj;
2166 ev::io iow;
2167 iow.set <myclass, &myclass::io_cb> (&obj);
2168
2169=item w->set<function> (void *data = 0)
2170
2171Also sets a callback, but uses a static method or plain function as
2172callback. The optional C<data> argument will be stored in the watcher's
2173C<data> member and is free for you to use.
2174
2175The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
2176
2177See the method-C<set> above for more details.
2178
2179Example:
2180
2181 static void io_cb (ev::io &w, int revents) { }
2182 iow.set <io_cb> ();
1750 2183
1751=item w->set (struct ev_loop *) 2184=item w->set (struct ev_loop *)
1752 2185
1753Associates a different C<struct ev_loop> with this watcher. You can only 2186Associates a different C<struct ev_loop> with this watcher. You can only
1754do this when the watcher is inactive (and not pending either). 2187do this when the watcher is inactive (and not pending either).
1755 2188
1756=item w->set ([args]) 2189=item w->set ([args])
1757 2190
1758Basically the same as C<ev_TYPE_set>, with the same args. Must be 2191Basically the same as C<ev_TYPE_set>, with the same args. Must be
1759called at least once. Unlike the C counterpart, an active watcher gets 2192called at least once. Unlike the C counterpart, an active watcher gets
1760automatically stopped and restarted. 2193automatically stopped and restarted when reconfiguring it with this
2194method.
1761 2195
1762=item w->start () 2196=item w->start ()
1763 2197
1764Starts the watcher. Note that there is no C<loop> argument as the 2198Starts the watcher. Note that there is no C<loop> argument, as the
1765constructor already takes the loop. 2199constructor already stores the event loop.
1766 2200
1767=item w->stop () 2201=item w->stop ()
1768 2202
1769Stops the watcher if it is active. Again, no C<loop> argument. 2203Stops the watcher if it is active. Again, no C<loop> argument.
1770 2204
1771=item w->again () C<ev::timer>, C<ev::periodic> only 2205=item w->again () (C<ev::timer>, C<ev::periodic> only)
1772 2206
1773For C<ev::timer> and C<ev::periodic>, this invokes the corresponding 2207For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
1774C<ev_TYPE_again> function. 2208C<ev_TYPE_again> function.
1775 2209
1776=item w->sweep () C<ev::embed> only 2210=item w->sweep () (C<ev::embed> only)
1777 2211
1778Invokes C<ev_embed_sweep>. 2212Invokes C<ev_embed_sweep>.
1779 2213
1780=item w->update () C<ev::stat> only 2214=item w->update () (C<ev::stat> only)
1781 2215
1782Invokes C<ev_stat_stat>. 2216Invokes C<ev_stat_stat>.
1783 2217
1784=back 2218=back
1785 2219
1795 2229
1796 myclass (); 2230 myclass ();
1797 } 2231 }
1798 2232
1799 myclass::myclass (int fd) 2233 myclass::myclass (int fd)
1800 : io (this, &myclass::io_cb),
1801 idle (this, &myclass::idle_cb)
1802 { 2234 {
2235 io .set <myclass, &myclass::io_cb > (this);
2236 idle.set <myclass, &myclass::idle_cb> (this);
2237
1803 io.start (fd, ev::READ); 2238 io.start (fd, ev::READ);
1804 } 2239 }
1805 2240
1806 2241
1807=head1 MACRO MAGIC 2242=head1 MACRO MAGIC
1808 2243
1809Libev can be compiled with a variety of options, the most fundemantal is 2244Libev can be compiled with a variety of options, the most fundamantal
1810C<EV_MULTIPLICITY>. This option determines wether (most) functions and 2245of which is C<EV_MULTIPLICITY>. This option determines whether (most)
1811callbacks have an initial C<struct ev_loop *> argument. 2246functions and callbacks have an initial C<struct ev_loop *> argument.
1812 2247
1813To make it easier to write programs that cope with either variant, the 2248To make it easier to write programs that cope with either variant, the
1814following macros are defined: 2249following macros are defined:
1815 2250
1816=over 4 2251=over 4
1848Similar to the other two macros, this gives you the value of the default 2283Similar to the other two macros, this gives you the value of the default
1849loop, if multiple loops are supported ("ev loop default"). 2284loop, if multiple loops are supported ("ev loop default").
1850 2285
1851=back 2286=back
1852 2287
1853Example: Declare and initialise a check watcher, working regardless of 2288Example: Declare and initialise a check watcher, utilising the above
1854wether multiple loops are supported or not. 2289macros so it will work regardless of whether multiple loops are supported
2290or not.
1855 2291
1856 static void 2292 static void
1857 check_cb (EV_P_ ev_timer *w, int revents) 2293 check_cb (EV_P_ ev_timer *w, int revents)
1858 { 2294 {
1859 ev_check_stop (EV_A_ w); 2295 ev_check_stop (EV_A_ w);
1862 ev_check check; 2298 ev_check check;
1863 ev_check_init (&check, check_cb); 2299 ev_check_init (&check, check_cb);
1864 ev_check_start (EV_DEFAULT_ &check); 2300 ev_check_start (EV_DEFAULT_ &check);
1865 ev_loop (EV_DEFAULT_ 0); 2301 ev_loop (EV_DEFAULT_ 0);
1866 2302
1867
1868=head1 EMBEDDING 2303=head1 EMBEDDING
1869 2304
1870Libev can (and often is) directly embedded into host 2305Libev can (and often is) directly embedded into host
1871applications. Examples of applications that embed it include the Deliantra 2306applications. Examples of applications that embed it include the Deliantra
1872Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) 2307Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
1873and rxvt-unicode. 2308and rxvt-unicode.
1874 2309
1875The goal is to enable you to just copy the neecssary files into your 2310The goal is to enable you to just copy the necessary files into your
1876source directory without having to change even a single line in them, so 2311source directory without having to change even a single line in them, so
1877you can easily upgrade by simply copying (or having a checked-out copy of 2312you can easily upgrade by simply copying (or having a checked-out copy of
1878libev somewhere in your source tree). 2313libev somewhere in your source tree).
1879 2314
1880=head2 FILESETS 2315=head2 FILESETS
1911 ev_vars.h 2346 ev_vars.h
1912 ev_wrap.h 2347 ev_wrap.h
1913 2348
1914 ev_win32.c required on win32 platforms only 2349 ev_win32.c required on win32 platforms only
1915 2350
1916 ev_select.c only when select backend is enabled (which is by default) 2351 ev_select.c only when select backend is enabled (which is enabled by default)
1917 ev_poll.c only when poll backend is enabled (disabled by default) 2352 ev_poll.c only when poll backend is enabled (disabled by default)
1918 ev_epoll.c only when the epoll backend is enabled (disabled by default) 2353 ev_epoll.c only when the epoll backend is enabled (disabled by default)
1919 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 2354 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
1920 ev_port.c only when the solaris port backend is enabled (disabled by default) 2355 ev_port.c only when the solaris port backend is enabled (disabled by default)
1921 2356
1970 2405
1971If defined to be C<1>, libev will try to detect the availability of the 2406If defined to be C<1>, libev will try to detect the availability of the
1972monotonic clock option at both compiletime and runtime. Otherwise no use 2407monotonic clock option at both compiletime and runtime. Otherwise no use
1973of the monotonic clock option will be attempted. If you enable this, you 2408of the monotonic clock option will be attempted. If you enable this, you
1974usually have to link against librt or something similar. Enabling it when 2409usually have to link against librt or something similar. Enabling it when
1975the functionality isn't available is safe, though, althoguh you have 2410the functionality isn't available is safe, though, although you have
1976to make sure you link against any libraries where the C<clock_gettime> 2411to make sure you link against any libraries where the C<clock_gettime>
1977function is hiding in (often F<-lrt>). 2412function is hiding in (often F<-lrt>).
1978 2413
1979=item EV_USE_REALTIME 2414=item EV_USE_REALTIME
1980 2415
1981If defined to be C<1>, libev will try to detect the availability of the 2416If defined to be C<1>, libev will try to detect the availability of the
1982realtime clock option at compiletime (and assume its availability at 2417realtime clock option at compiletime (and assume its availability at
1983runtime if successful). Otherwise no use of the realtime clock option will 2418runtime if successful). Otherwise no use of the realtime clock option will
1984be attempted. This effectively replaces C<gettimeofday> by C<clock_get 2419be attempted. This effectively replaces C<gettimeofday> by C<clock_get
1985(CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries 2420(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
1986in the description of C<EV_USE_MONOTONIC>, though. 2421note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2422
2423=item EV_USE_NANOSLEEP
2424
2425If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2426and will use it for delays. Otherwise it will use C<select ()>.
1987 2427
1988=item EV_USE_SELECT 2428=item EV_USE_SELECT
1989 2429
1990If undefined or defined to be C<1>, libev will compile in support for the 2430If undefined or defined to be C<1>, libev will compile in support for the
1991C<select>(2) backend. No attempt at autodetection will be done: if no 2431C<select>(2) backend. No attempt at autodetection will be done: if no
2055be detected at runtime. 2495be detected at runtime.
2056 2496
2057=item EV_H 2497=item EV_H
2058 2498
2059The name of the F<ev.h> header file used to include it. The default if 2499The name of the F<ev.h> header file used to include it. The default if
2060undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This 2500undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to
2061can be used to virtually rename the F<ev.h> header file in case of conflicts. 2501virtually rename the F<ev.h> header file in case of conflicts.
2062 2502
2063=item EV_CONFIG_H 2503=item EV_CONFIG_H
2064 2504
2065If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 2505If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2066F<ev.c>'s idea of where to find the F<config.h> file, similarly to 2506F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2067C<EV_H>, above. 2507C<EV_H>, above.
2068 2508
2069=item EV_EVENT_H 2509=item EV_EVENT_H
2070 2510
2071Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 2511Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2072of how the F<event.h> header can be found. 2512of how the F<event.h> header can be found, the dfeault is C<"event.h">.
2073 2513
2074=item EV_PROTOTYPES 2514=item EV_PROTOTYPES
2075 2515
2076If defined to be C<0>, then F<ev.h> will not define any function 2516If defined to be C<0>, then F<ev.h> will not define any function
2077prototypes, but still define all the structs and other symbols. This is 2517prototypes, but still define all the structs and other symbols. This is
2084will have the C<struct ev_loop *> as first argument, and you can create 2524will have the C<struct ev_loop *> as first argument, and you can create
2085additional independent event loops. Otherwise there will be no support 2525additional independent event loops. Otherwise there will be no support
2086for multiple event loops and there is no first event loop pointer 2526for multiple event loops and there is no first event loop pointer
2087argument. Instead, all functions act on the single default loop. 2527argument. Instead, all functions act on the single default loop.
2088 2528
2529=item EV_MINPRI
2530
2531=item EV_MAXPRI
2532
2533The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
2534C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
2535provide for more priorities by overriding those symbols (usually defined
2536to be C<-2> and C<2>, respectively).
2537
2538When doing priority-based operations, libev usually has to linearly search
2539all the priorities, so having many of them (hundreds) uses a lot of space
2540and time, so using the defaults of five priorities (-2 .. +2) is usually
2541fine.
2542
2543If your embedding app does not need any priorities, defining these both to
2544C<0> will save some memory and cpu.
2545
2089=item EV_PERIODIC_ENABLE 2546=item EV_PERIODIC_ENABLE
2090 2547
2091If undefined or defined to be C<1>, then periodic timers are supported. If 2548If undefined or defined to be C<1>, then periodic timers are supported. If
2549defined to be C<0>, then they are not. Disabling them saves a few kB of
2550code.
2551
2552=item EV_IDLE_ENABLE
2553
2554If undefined or defined to be C<1>, then idle watchers are supported. If
2092defined to be C<0>, then they are not. Disabling them saves a few kB of 2555defined to be C<0>, then they are not. Disabling them saves a few kB of
2093code. 2556code.
2094 2557
2095=item EV_EMBED_ENABLE 2558=item EV_EMBED_ENABLE
2096 2559
2120than enough. If you need to manage thousands of children you might want to 2583than enough. If you need to manage thousands of children you might want to
2121increase this value (I<must> be a power of two). 2584increase this value (I<must> be a power of two).
2122 2585
2123=item EV_INOTIFY_HASHSIZE 2586=item EV_INOTIFY_HASHSIZE
2124 2587
2125C<ev_staz> watchers use a small hash table to distribute workload by 2588C<ev_stat> watchers use a small hash table to distribute workload by
2126inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 2589inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2127usually more than enough. If you need to manage thousands of C<ev_stat> 2590usually more than enough. If you need to manage thousands of C<ev_stat>
2128watchers you might want to increase this value (I<must> be a power of 2591watchers you might want to increase this value (I<must> be a power of
2129two). 2592two).
2130 2593
2147 2610
2148=item ev_set_cb (ev, cb) 2611=item ev_set_cb (ev, cb)
2149 2612
2150Can be used to change the callback member declaration in each watcher, 2613Can be used to change the callback member declaration in each watcher,
2151and the way callbacks are invoked and set. Must expand to a struct member 2614and the way callbacks are invoked and set. Must expand to a struct member
2152definition and a statement, respectively. See the F<ev.v> header file for 2615definition and a statement, respectively. See the F<ev.h> header file for
2153their default definitions. One possible use for overriding these is to 2616their default definitions. One possible use for overriding these is to
2154avoid the C<struct ev_loop *> as first argument in all cases, or to use 2617avoid the C<struct ev_loop *> as first argument in all cases, or to use
2155method calls instead of plain function calls in C++. 2618method calls instead of plain function calls in C++.
2619
2620=head2 EXPORTED API SYMBOLS
2621
2622If you need to re-export the API (e.g. via a dll) and you need a list of
2623exported symbols, you can use the provided F<Symbol.*> files which list
2624all public symbols, one per line:
2625
2626 Symbols.ev for libev proper
2627 Symbols.event for the libevent emulation
2628
2629This can also be used to rename all public symbols to avoid clashes with
2630multiple versions of libev linked together (which is obviously bad in
2631itself, but sometimes it is inconvinient to avoid this).
2632
2633A sed command like this will create wrapper C<#define>'s that you need to
2634include before including F<ev.h>:
2635
2636 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
2637
2638This would create a file F<wrap.h> which essentially looks like this:
2639
2640 #define ev_backend myprefix_ev_backend
2641 #define ev_check_start myprefix_ev_check_start
2642 #define ev_check_stop myprefix_ev_check_stop
2643 ...
2156 2644
2157=head2 EXAMPLES 2645=head2 EXAMPLES
2158 2646
2159For a real-world example of a program the includes libev 2647For a real-world example of a program the includes libev
2160verbatim, you can have a look at the EV perl module 2648verbatim, you can have a look at the EV perl module
2163interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file 2651interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
2164will be compiled. It is pretty complex because it provides its own header 2652will be compiled. It is pretty complex because it provides its own header
2165file. 2653file.
2166 2654
2167The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 2655The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
2168that everybody includes and which overrides some autoconf choices: 2656that everybody includes and which overrides some configure choices:
2169 2657
2658 #define EV_MINIMAL 1
2170 #define EV_USE_POLL 0 2659 #define EV_USE_POLL 0
2171 #define EV_MULTIPLICITY 0 2660 #define EV_MULTIPLICITY 0
2172 #define EV_PERIODICS 0 2661 #define EV_PERIODIC_ENABLE 0
2662 #define EV_STAT_ENABLE 0
2663 #define EV_FORK_ENABLE 0
2173 #define EV_CONFIG_H <config.h> 2664 #define EV_CONFIG_H <config.h>
2665 #define EV_MINPRI 0
2666 #define EV_MAXPRI 0
2174 2667
2175 #include "ev++.h" 2668 #include "ev++.h"
2176 2669
2177And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 2670And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
2178 2671
2184 2677
2185In this section the complexities of (many of) the algorithms used inside 2678In this section the complexities of (many of) the algorithms used inside
2186libev will be explained. For complexity discussions about backends see the 2679libev will be explained. For complexity discussions about backends see the
2187documentation for C<ev_default_init>. 2680documentation for C<ev_default_init>.
2188 2681
2682All of the following are about amortised time: If an array needs to be
2683extended, libev needs to realloc and move the whole array, but this
2684happens asymptotically never with higher number of elements, so O(1) might
2685mean it might do a lengthy realloc operation in rare cases, but on average
2686it is much faster and asymptotically approaches constant time.
2687
2189=over 4 2688=over 4
2190 2689
2191=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 2690=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2192 2691
2692This means that, when you have a watcher that triggers in one hour and
2693there are 100 watchers that would trigger before that then inserting will
2694have to skip roughly seven (C<ld 100>) of these watchers.
2695
2193=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) 2696=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
2697
2698That means that changing a timer costs less than removing/adding them
2699as only the relative motion in the event queue has to be paid for.
2194 2700
2195=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2701=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2196 2702
2703These just add the watcher into an array or at the head of a list.
2704
2197=item Stopping check/prepare/idle watchers: O(1) 2705=item Stopping check/prepare/idle watchers: O(1)
2198 2706
2199=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 2707=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2200 2708
2709These watchers are stored in lists then need to be walked to find the
2710correct watcher to remove. The lists are usually short (you don't usually
2711have many watchers waiting for the same fd or signal).
2712
2201=item Finding the next timer per loop iteration: O(1) 2713=item Finding the next timer in each loop iteration: O(1)
2714
2715By virtue of using a binary heap, the next timer is always found at the
2716beginning of the storage array.
2202 2717
2203=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2718=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2204 2719
2205=item Activating one watcher: O(1) 2720A change means an I/O watcher gets started or stopped, which requires
2721libev to recalculate its status (and possibly tell the kernel, depending
2722on backend and wether C<ev_io_set> was used).
2723
2724=item Activating one watcher (putting it into the pending state): O(1)
2725
2726=item Priority handling: O(number_of_priorities)
2727
2728Priorities are implemented by allocating some space for each
2729priority. When doing priority-based operations, libev usually has to
2730linearly search all the priorities, but starting/stopping and activating
2731watchers becomes O(1) w.r.t. prioritiy handling.
2206 2732
2207=back 2733=back
2208 2734
2209 2735
2210=head1 AUTHOR 2736=head1 AUTHOR

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines