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

Comparing libev/ev.3 (file contents):
Revision 1.44 by root, Sat Dec 8 15:30:26 2007 UTC vs.
Revision 1.59 by root, Tue Dec 25 07:16:53 2007 UTC

… …
126. ds Ae AE 126. ds Ae AE
127.\} 127.\}
128.rm #[ #] #H #V #F C 128.rm #[ #] #H #V #F C
129.\" ======================================================================== 129.\" ========================================================================
130.\" 130.\"
131.IX Title ""<STANDARD INPUT>" 1" 131.IX Title "EV 1"
132.TH "<STANDARD INPUT>" 1 "2007-12-08" "perl v5.8.8" "User Contributed Perl Documentation" 132.TH EV 1 "2007-12-25" "perl v5.8.8" "User Contributed Perl Documentation"
133.SH "NAME" 133.SH "NAME"
134libev \- a high performance full\-featured event loop written in C 134libev \- a high performance full\-featured event loop written in C
135.SH "SYNOPSIS" 135.SH "SYNOPSIS"
136.IX Header "SYNOPSIS" 136.IX Header "SYNOPSIS"
137.Vb 1 137.Vb 1
138\& #include <ev.h> 138\& #include <ev.h>
139.Ve 139.Ve
140.SH "EXAMPLE PROGRAM" 140.Sh "\s-1EXAMPLE\s0 \s-1PROGRAM\s0"
141.IX Header "EXAMPLE PROGRAM" 141.IX Subsection "EXAMPLE PROGRAM"
142.Vb 1 142.Vb 1
143\& #include <ev.h> 143\& #include <ev.h>
144.Ve 144.Ve
145.PP 145.PP
146.Vb 2 146.Vb 2
… …
201The newest version of this document is also available as a html-formatted 201The newest version of this document is also available as a html-formatted
202web page you might find easier to navigate when reading it for the first 202web page you might find easier to navigate when reading it for the first
203time: <http://cvs.schmorp.de/libev/ev.html>. 203time: <http://cvs.schmorp.de/libev/ev.html>.
204.PP 204.PP
205Libev is an event loop: you register interest in certain events (such as a 205Libev is an event loop: you register interest in certain events (such as a
206file descriptor being readable or a timeout occuring), and it will manage 206file descriptor being readable or a timeout occurring), and it will manage
207these event sources and provide your program with events. 207these event sources and provide your program with events.
208.PP 208.PP
209To do this, it must take more or less complete control over your process 209To do this, it must take more or less complete control over your process
210(or thread) by executing the \fIevent loop\fR handler, and will then 210(or thread) by executing the \fIevent loop\fR handler, and will then
211communicate events via a callback mechanism. 211communicate events via a callback mechanism.
212.PP 212.PP
213You register interest in certain events by registering so-called \fIevent 213You register interest in certain events by registering so-called \fIevent
214watchers\fR, which are relatively small C structures you initialise with the 214watchers\fR, which are relatively small C structures you initialise with the
215details of the event, and then hand it over to libev by \fIstarting\fR the 215details of the event, and then hand it over to libev by \fIstarting\fR the
216watcher. 216watcher.
217.SH "FEATURES" 217.Sh "\s-1FEATURES\s0"
218.IX Header "FEATURES" 218.IX Subsection "FEATURES"
219Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the 219Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the
220BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms 220BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms
221for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface 221for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface
222(for \f(CW\*(C`ev_stat\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers 222(for \f(CW\*(C`ev_stat\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers
223with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals 223with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals
… …
228(\f(CW\*(C`ev_fork\*(C'\fR). 228(\f(CW\*(C`ev_fork\*(C'\fR).
229.PP 229.PP
230It also is quite fast (see this 230It also is quite fast (see this
231benchmark comparing it to libevent 231benchmark comparing it to libevent
232for example). 232for example).
233.SH "CONVENTIONS" 233.Sh "\s-1CONVENTIONS\s0"
234.IX Header "CONVENTIONS" 234.IX Subsection "CONVENTIONS"
235Libev is very configurable. In this manual the default configuration will 235Libev is very configurable. In this manual the default configuration will
236be described, which supports multiple event loops. For more info about 236be described, which supports multiple event loops. For more info about
237various configuration options please have a look at \fB\s-1EMBED\s0\fR section in 237various configuration options please have a look at \fB\s-1EMBED\s0\fR section in
238this manual. If libev was configured without support for multiple event 238this manual. If libev was configured without support for multiple event
239loops, then all functions taking an initial argument of name \f(CW\*(C`loop\*(C'\fR 239loops, then all functions taking an initial argument of name \f(CW\*(C`loop\*(C'\fR
240(which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have this argument. 240(which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have this argument.
241.SH "TIME REPRESENTATION" 241.Sh "\s-1TIME\s0 \s-1REPRESENTATION\s0"
242.IX Header "TIME REPRESENTATION" 242.IX Subsection "TIME REPRESENTATION"
243Libev represents time as a single floating point number, representing the 243Libev represents time as a single floating point number, representing the
244(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near 244(fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere near
245the beginning of 1970, details are complicated, don't ask). This type is 245the beginning of 1970, details are complicated, don't ask). This type is
246called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use too. It usually aliases 246called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use too. It usually aliases
247to the \f(CW\*(C`double\*(C'\fR type in C, and when you need to do any calculations on 247to the \f(CW\*(C`double\*(C'\fR type in C, and when you need to do any calculations on
248it, you should treat it as such. 248it, you should treat it as some floatingpoint value. Unlike the name
249component \f(CW\*(C`stamp\*(C'\fR might indicate, it is also used for time differences
250throughout libev.
249.SH "GLOBAL FUNCTIONS" 251.SH "GLOBAL FUNCTIONS"
250.IX Header "GLOBAL FUNCTIONS" 252.IX Header "GLOBAL FUNCTIONS"
251These functions can be called anytime, even before initialising the 253These functions can be called anytime, even before initialising the
252library in any way. 254library in any way.
253.IP "ev_tstamp ev_time ()" 4 255.IP "ev_tstamp ev_time ()" 4
254.IX Item "ev_tstamp ev_time ()" 256.IX Item "ev_tstamp ev_time ()"
255Returns the current time as libev would use it. Please note that the 257Returns the current time as libev would use it. Please note that the
256\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp 258\&\f(CW\*(C`ev_now\*(C'\fR function is usually faster and also often returns the timestamp
257you actually want to know. 259you actually want to know.
260.IP "ev_sleep (ev_tstamp interval)" 4
261.IX Item "ev_sleep (ev_tstamp interval)"
262Sleep for the given interval: The current thread will be blocked until
263either it is interrupted or the given time interval has passed. Basically
264this is a subsecond-resolution \f(CW\*(C`sleep ()\*(C'\fR.
258.IP "int ev_version_major ()" 4 265.IP "int ev_version_major ()" 4
259.IX Item "int ev_version_major ()" 266.IX Item "int ev_version_major ()"
260.PD 0 267.PD 0
261.IP "int ev_version_minor ()" 4 268.IP "int ev_version_minor ()" 4
262.IX Item "int ev_version_minor ()" 269.IX Item "int ev_version_minor ()"
263.PD 270.PD
264You can find out the major and minor version numbers of the library 271You can find out the major and minor \s-1ABI\s0 version numbers of the library
265you linked against by calling the functions \f(CW\*(C`ev_version_major\*(C'\fR and 272you linked against by calling the functions \f(CW\*(C`ev_version_major\*(C'\fR and
266\&\f(CW\*(C`ev_version_minor\*(C'\fR. If you want, you can compare against the global 273\&\f(CW\*(C`ev_version_minor\*(C'\fR. If you want, you can compare against the global
267symbols \f(CW\*(C`EV_VERSION_MAJOR\*(C'\fR and \f(CW\*(C`EV_VERSION_MINOR\*(C'\fR, which specify the 274symbols \f(CW\*(C`EV_VERSION_MAJOR\*(C'\fR and \f(CW\*(C`EV_VERSION_MINOR\*(C'\fR, which specify the
268version of the library your program was compiled against. 275version of the library your program was compiled against.
269.Sp 276.Sp
277These version numbers refer to the \s-1ABI\s0 version of the library, not the
278release version.
279.Sp
270Usually, it's a good idea to terminate if the major versions mismatch, 280Usually, it's a good idea to terminate if the major versions mismatch,
271as this indicates an incompatible change. Minor versions are usually 281as this indicates an incompatible change. Minor versions are usually
272compatible to older versions, so a larger minor version alone is usually 282compatible to older versions, so a larger minor version alone is usually
273not a problem. 283not a problem.
274.Sp 284.Sp
275Example: Make sure we haven't accidentally been linked against the wrong 285Example: Make sure we haven't accidentally been linked against the wrong
276version. 286version.
… …
441.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 451.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
442.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 452.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
443This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 453This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
444libev tries to roll its own fd_set with no limits on the number of fds, 454libev tries to roll its own fd_set with no limits on the number of fds,
445but if that fails, expect a fairly low limit on the number of fds when 455but if that fails, expect a fairly low limit on the number of fds when
446using this backend. It doesn't scale too well (O(highest_fd)), but its usually 456using this backend. It doesn't scale too well (O(highest_fd)), but its
447the fastest backend for a low number of fds. 457usually the fastest backend for a low number of (low\-numbered :) fds.
458.Sp
459To get good performance out of this backend you need a high amount of
460parallelity (most of the file descriptors should be busy). If you are
461writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many
462connections as possible during one iteration. You might also want to have
463a look at \f(CW\*(C`ev_set_io_collect_interval ()\*(C'\fR to increase the amount of
464readyness notifications you get per iteration.
448.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 465.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
449.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 466.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
450.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" 467.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
451And this is your standard \fIpoll\fR\|(2) backend. It's more complicated than 468And this is your standard \fIpoll\fR\|(2) backend. It's more complicated
452select, but handles sparse fds better and has no artificial limit on the 469than select, but handles sparse fds better and has no artificial
453number of fds you can use (except it will slow down considerably with a 470limit on the number of fds you can use (except it will slow down
454lot of inactive fds). It scales similarly to select, i.e. O(total_fds). 471considerably with a lot of inactive fds). It scales similarly to select,
472i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
473performance tips.
455.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 474.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
456.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 475.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
457.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 476.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
458For few fds, this backend is a bit little slower than poll and select, 477For few fds, this backend is a bit little slower than poll and select,
459but it scales phenomenally better. While poll and select usually scale like 478but it scales phenomenally better. While poll and select usually scale
460O(total_fds) where n is the total number of fds (or the highest fd), epoll scales 479like O(total_fds) where n is the total number of fds (or the highest fd),
461either O(1) or O(active_fds). 480epoll scales either O(1) or O(active_fds). The epoll design has a number
481of shortcomings, such as silently dropping events in some hard-to-detect
482cases and rewiring a syscall per fd change, no fork support and bad
483support for dup.
462.Sp 484.Sp
463While stopping and starting an I/O watcher in the same iteration will 485While stopping, setting and starting an I/O watcher in the same iteration
464result in some caching, there is still a syscall per such incident 486will result in some caching, there is still a syscall per such incident
465(because the fd could point to a different file description now), so its 487(because the fd could point to a different file description now), so its
466best to avoid that. Also, \fIdup()\fRed file descriptors might not work very 488best to avoid that. Also, \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors might not work
467well if you register events for both fds. 489very well if you register events for both fds.
468.Sp 490.Sp
469Please note that epoll sometimes generates spurious notifications, so you 491Please note that epoll sometimes generates spurious notifications, so you
470need to use non-blocking I/O or other means to avoid blocking when no data 492need to use non-blocking I/O or other means to avoid blocking when no data
471(or space) is available. 493(or space) is available.
494.Sp
495Best performance from this backend is achieved by not unregistering all
496watchers for a file descriptor until it has been closed, if possible, i.e.
497keep at least one watcher active per fd at all times.
498.Sp
499While nominally embeddeble in other event loops, this feature is broken in
500all kernel versions tested so far.
472.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 501.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
473.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 502.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
474.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 503.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
475Kqueue deserves special mention, as at the time of this writing, it 504Kqueue deserves special mention, as at the time of this writing, it
476was broken on all BSDs except NetBSD (usually it doesn't work with 505was broken on all BSDs except NetBSD (usually it doesn't work reliably
477anything but sockets and pipes, except on Darwin, where of course its 506with anything but sockets and pipes, except on Darwin, where of course
478completely useless). For this reason its not being \*(L"autodetected\*(R" 507it's completely useless). For this reason it's not being \*(L"autodetected\*(R"
479unless you explicitly specify it explicitly in the flags (i.e. using 508unless you explicitly specify it explicitly in the flags (i.e. using
480\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR). 509\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough)
510system like NetBSD.
511.Sp
512You still can embed kqueue into a normal poll or select backend and use it
513only for sockets (after having made sure that sockets work with kqueue on
514the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
481.Sp 515.Sp
482It scales in the same way as the epoll backend, but the interface to the 516It scales in the same way as the epoll backend, but the interface to the
483kernel is more efficient (which says nothing about its actual speed, of 517kernel is more efficient (which says nothing about its actual speed, of
484course). While starting and stopping an I/O watcher does not cause an 518course). While stopping, setting and starting an I/O watcher does never
485extra syscall as with epoll, it still adds up to four event changes per 519cause an extra syscall as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
486incident, so its best to avoid that. 520two event changes per incident, support for \f(CW\*(C`fork ()\*(C'\fR is very bad and it
521drops fds silently in similarly hard-to-detect cases.
522.Sp
523This backend usually performs well under most conditions.
524.Sp
525While nominally embeddable in other event loops, this doesn't work
526everywhere, so you might need to test for this. And since it is broken
527almost everywhere, you should only use it when you have a lot of sockets
528(for which it usually works), by embedding it into another event loop
529(e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR) and using it only for
530sockets.
487.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 531.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
488.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 532.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4
489.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" 533.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)"
490This is not implemented yet (and might never be). 534This is not implemented yet (and might never be, unless you send me an
535implementation). According to reports, \f(CW\*(C`/dev/poll\*(C'\fR only supports sockets
536and is not embeddable, which would limit the usefulness of this backend
537immensely.
491.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 538.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
492.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 539.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
493.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" 540.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
494This uses the Solaris 10 port mechanism. As with everything on Solaris, 541This uses the Solaris 10 event port mechanism. As with everything on Solaris,
495it's really slow, but it still scales very well (O(active_fds)). 542it's really slow, but it still scales very well (O(active_fds)).
496.Sp 543.Sp
497Please note that solaris ports can result in a lot of spurious 544Please note that solaris event ports can deliver a lot of spurious
498notifications, so you need to use non-blocking I/O or other means to avoid 545notifications, so you need to use non-blocking I/O or other means to avoid
499blocking when no data (or space) is available. 546blocking when no data (or space) is available.
547.Sp
548While this backend scales well, it requires one system call per active
549file descriptor per loop iteration. For small and medium numbers of file
550descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend
551might perform better.
500.ie n .IP """EVBACKEND_ALL""" 4 552.ie n .IP """EVBACKEND_ALL""" 4
501.el .IP "\f(CWEVBACKEND_ALL\fR" 4 553.el .IP "\f(CWEVBACKEND_ALL\fR" 4
502.IX Item "EVBACKEND_ALL" 554.IX Item "EVBACKEND_ALL"
503Try all backends (even potentially broken ones that wouldn't be tried 555Try all backends (even potentially broken ones that wouldn't be tried
504with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as 556with \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). Since this is a mask, you can do stuff such as
505\&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR. 557\&\f(CW\*(C`EVBACKEND_ALL & ~EVBACKEND_KQUEUE\*(C'\fR.
558.Sp
559It is definitely not recommended to use this flag.
506.RE 560.RE
507.RS 4 561.RS 4
508.Sp 562.Sp
509If one or more of these are ored into the flags value, then only these 563If one or more of these are ored into the flags value, then only these
510backends will be tried (in the reverse order as given here). If none are 564backends will be tried (in the reverse order as given here). If none are
… …
552Destroys the default loop again (frees all memory and kernel state 606Destroys the default loop again (frees all memory and kernel state
553etc.). None of the active event watchers will be stopped in the normal 607etc.). None of the active event watchers will be stopped in the normal
554sense, so e.g. \f(CW\*(C`ev_is_active\*(C'\fR might still return true. It is your 608sense, so e.g. \f(CW\*(C`ev_is_active\*(C'\fR might still return true. It is your
555responsibility to either stop all watchers cleanly yoursef \fIbefore\fR 609responsibility to either stop all watchers cleanly yoursef \fIbefore\fR
556calling this function, or cope with the fact afterwards (which is usually 610calling this function, or cope with the fact afterwards (which is usually
557the easiest thing, youc na just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them 611the easiest thing, you can just ignore the watchers and/or \f(CW\*(C`free ()\*(C'\fR them
558for example). 612for example).
613.Sp
614Note that certain global state, such as signal state, will not be freed by
615this function, and related watchers (such as signal and child watchers)
616would need to be stopped manually.
617.Sp
618In general it is not advisable to call this function except in the
619rare occasion where you really need to free e.g. the signal handling
620pipe fds. If you need dynamically allocated loops it is better to use
621\&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR).
559.IP "ev_loop_destroy (loop)" 4 622.IP "ev_loop_destroy (loop)" 4
560.IX Item "ev_loop_destroy (loop)" 623.IX Item "ev_loop_destroy (loop)"
561Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an 624Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an
562earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. 625earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR.
563.IP "ev_default_fork ()" 4 626.IP "ev_default_fork ()" 4
… …
604.IX Item "ev_tstamp ev_now (loop)" 667.IX Item "ev_tstamp ev_now (loop)"
605Returns the current \*(L"event loop time\*(R", which is the time the event loop 668Returns the current \*(L"event loop time\*(R", which is the time the event loop
606received events and started processing them. This timestamp does not 669received events and started processing them. This timestamp does not
607change as long as callbacks are being processed, and this is also the base 670change as long as callbacks are being processed, and this is also the base
608time used for relative timers. You can treat it as the timestamp of the 671time used for relative timers. You can treat it as the timestamp of the
609event occuring (or more correctly, libev finding out about it). 672event occurring (or more correctly, libev finding out about it).
610.IP "ev_loop (loop, int flags)" 4 673.IP "ev_loop (loop, int flags)" 4
611.IX Item "ev_loop (loop, int flags)" 674.IX Item "ev_loop (loop, int flags)"
612Finally, this is it, the event handler. This function usually is called 675Finally, this is it, the event handler. This function usually is called
613after you initialised all your watchers and you want to start handling 676after you initialised all your watchers and you want to start handling
614events. 677events.
… …
634libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is 697libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is
635usually a better approach for this kind of thing. 698usually a better approach for this kind of thing.
636.Sp 699.Sp
637Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does: 700Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does:
638.Sp 701.Sp
639.Vb 18 702.Vb 19
703\& - Before the first iteration, call any pending watchers.
640\& * If there are no active watchers (reference count is zero), return. 704\& * If there are no active watchers (reference count is zero), return.
641\& - Queue prepare watchers and then call all outstanding watchers. 705\& - Queue all prepare watchers and then call all outstanding watchers.
642\& - If we have been forked, recreate the kernel state. 706\& - If we have been forked, recreate the kernel state.
643\& - Update the kernel state with all outstanding changes. 707\& - Update the kernel state with all outstanding changes.
644\& - Update the "event loop time". 708\& - Update the "event loop time".
645\& - Calculate for how long to block. 709\& - Calculate for how long to block.
646\& - Block the process, waiting for any events. 710\& - Block the process, waiting for any events.
… …
703.Sp 767.Sp
704.Vb 2 768.Vb 2
705\& ev_ref (loop); 769\& ev_ref (loop);
706\& ev_signal_stop (loop, &exitsig); 770\& ev_signal_stop (loop, &exitsig);
707.Ve 771.Ve
772.IP "ev_set_io_collect_interval (loop, ev_tstamp interval)" 4
773.IX Item "ev_set_io_collect_interval (loop, ev_tstamp interval)"
774.PD 0
775.IP "ev_set_timeout_collect_interval (loop, ev_tstamp interval)" 4
776.IX Item "ev_set_timeout_collect_interval (loop, ev_tstamp interval)"
777.PD
778These advanced functions influence the time that libev will spend waiting
779for events. Both are by default \f(CW0\fR, meaning that libev will try to
780invoke timer/periodic callbacks and I/O callbacks with minimum latency.
781.Sp
782Setting these to a higher value (the \f(CW\*(C`interval\*(C'\fR \fImust\fR be >= \f(CW0\fR)
783allows libev to delay invocation of I/O and timer/periodic callbacks to
784increase efficiency of loop iterations.
785.Sp
786The background is that sometimes your program runs just fast enough to
787handle one (or very few) event(s) per loop iteration. While this makes
788the program responsive, it also wastes a lot of \s-1CPU\s0 time to poll for new
789events, especially with backends like \f(CW\*(C`select ()\*(C'\fR which have a high
790overhead for the actual polling but can deliver many events at once.
791.Sp
792By setting a higher \fIio collect interval\fR you allow libev to spend more
793time collecting I/O events, so you can handle more events per iteration,
794at the cost of increasing latency. Timeouts (both \f(CW\*(C`ev_periodic\*(C'\fR and
795\&\f(CW\*(C`ev_timer\*(C'\fR) will be not affected. Setting this to a non-null value will
796introduce an additional \f(CW\*(C`ev_sleep ()\*(C'\fR call into most loop iterations.
797.Sp
798Likewise, by setting a higher \fItimeout collect interval\fR you allow libev
799to spend more time collecting timeouts, at the expense of increased
800latency (the watcher callback will be called later). \f(CW\*(C`ev_io\*(C'\fR watchers
801will not be affected. Setting this to a non-null value will not introduce
802any overhead in libev.
803.Sp
804Many (busy) programs can usually benefit by setting the io collect
805interval to a value near \f(CW0.1\fR or so, which is often enough for
806interactive servers (of course not for games), likewise for timeouts. It
807usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR,
808as this approsaches the timing granularity of most systems.
708.SH "ANATOMY OF A WATCHER" 809.SH "ANATOMY OF A WATCHER"
709.IX Header "ANATOMY OF A WATCHER" 810.IX Header "ANATOMY OF A WATCHER"
710A watcher is a structure that you create and register to record your 811A watcher is a structure that you create and register to record your
711interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to 812interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to
712become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: 813become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that:
… …
1037In general you can register as many read and/or write event watchers per 1138In general you can register as many read and/or write event watchers per
1038fd as you want (as long as you don't confuse yourself). Setting all file 1139fd as you want (as long as you don't confuse yourself). Setting all file
1039descriptors to non-blocking mode is also usually a good idea (but not 1140descriptors to non-blocking mode is also usually a good idea (but not
1040required if you know what you are doing). 1141required if you know what you are doing).
1041.PP 1142.PP
1042You have to be careful with dup'ed file descriptors, though. Some backends
1043(the linux epoll backend is a notable example) cannot handle dup'ed file
1044descriptors correctly if you register interest in two or more fds pointing
1045to the same underlying file/socket/etc. description (that is, they share
1046the same underlying \*(L"file open\*(R").
1047.PP
1048If you must do this, then force the use of a known-to-be-good backend 1143If you must do this, then force the use of a known-to-be-good backend
1049(at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and 1144(at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and
1050\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR). 1145\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR).
1051.PP 1146.PP
1052Another thing you have to watch out for is that it is quite easy to 1147Another thing you have to watch out for is that it is quite easy to
… …
1061If you cannot run the fd in non-blocking mode (for example you should not 1156If you cannot run the fd in non-blocking mode (for example you should not
1062play around with an Xlib connection), then you have to seperately re-test 1157play around with an Xlib connection), then you have to seperately re-test
1063whether a file descriptor is really ready with a known-to-be good interface 1158whether a file descriptor is really ready with a known-to-be good interface
1064such as poll (fortunately in our Xlib example, Xlib already does this on 1159such as poll (fortunately in our Xlib example, Xlib already does this on
1065its own, so its quite safe to use). 1160its own, so its quite safe to use).
1161.PP
1162\fIThe special problem of disappearing file descriptors\fR
1163.IX Subsection "The special problem of disappearing file descriptors"
1164.PP
1165Some backends (e.g. kqueue, epoll) need to be told about closing a file
1166descriptor (either by calling \f(CW\*(C`close\*(C'\fR explicitly or by any other means,
1167such as \f(CW\*(C`dup\*(C'\fR). The reason is that you register interest in some file
1168descriptor, but when it goes away, the operating system will silently drop
1169this interest. If another file descriptor with the same number then is
1170registered with libev, there is no efficient way to see that this is, in
1171fact, a different file descriptor.
1172.PP
1173To avoid having to explicitly tell libev about such cases, libev follows
1174the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1175will assume that this is potentially a new file descriptor, otherwise
1176it is assumed that the file descriptor stays the same. That means that
1177you \fIhave\fR to call \f(CW\*(C`ev_io_set\*(C'\fR (or \f(CW\*(C`ev_io_init\*(C'\fR) when you change the
1178descriptor even if the file descriptor number itself did not change.
1179.PP
1180This is how one would do it normally anyway, the important point is that
1181the libev application should not optimise around libev but should leave
1182optimisations to libev.
1183.PP
1184\fIThe special problem of dup'ed file descriptors\fR
1185.IX Subsection "The special problem of dup'ed file descriptors"
1186.PP
1187Some backends (e.g. epoll), cannot register events for file descriptors,
1188but only events for the underlying file descriptions. That means when you
1189have \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors or weirder constellations, and register
1190events for them, only one file descriptor might actually receive events.
1191.PP
1192There is no workaround possible except not registering events
1193for potentially \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors, or to resort to
1194\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1195.PP
1196\fIThe special problem of fork\fR
1197.IX Subsection "The special problem of fork"
1198.PP
1199Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit
1200useless behaviour. Libev fully supports fork, but needs to be told about
1201it in the child.
1202.PP
1203To support fork in your programs, you either have to call
1204\&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child,
1205enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or
1206\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1207.PP
1208\fIWatcher-Specific Functions\fR
1209.IX Subsection "Watcher-Specific Functions"
1066.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 1210.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4
1067.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" 1211.IX Item "ev_io_init (ev_io *, callback, int fd, int events)"
1068.PD 0 1212.PD 0
1069.IP "ev_io_set (ev_io *, int fd, int events)" 4 1213.IP "ev_io_set (ev_io *, int fd, int events)" 4
1070.IX Item "ev_io_set (ev_io *, int fd, int events)" 1214.IX Item "ev_io_set (ev_io *, int fd, int events)"
… …
1123.Ve 1267.Ve
1124.PP 1268.PP
1125The callback is guarenteed to be invoked only when its timeout has passed, 1269The callback is guarenteed to be invoked only when its timeout has passed,
1126but if multiple timers become ready during the same loop iteration then 1270but if multiple timers become ready during the same loop iteration then
1127order of execution is undefined. 1271order of execution is undefined.
1272.PP
1273\fIWatcher-Specific Functions and Data Members\fR
1274.IX Subsection "Watcher-Specific Functions and Data Members"
1128.IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4 1275.IP "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 4
1129.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 1276.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
1130.PD 0 1277.PD 0
1131.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 1278.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
1132.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 1279.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
… …
1234but on wallclock time (absolute time). You can tell a periodic watcher 1381but on wallclock time (absolute time). You can tell a periodic watcher
1235to trigger \*(L"at\*(R" some specific point in time. For example, if you tell a 1382to trigger \*(L"at\*(R" some specific point in time. For example, if you tell a
1236periodic watcher to trigger in 10 seconds (by specifiying e.g. \f(CW\*(C`ev_now () 1383periodic watcher to trigger in 10 seconds (by specifiying e.g. \f(CW\*(C`ev_now ()
1237+ 10.\*(C'\fR) and then reset your system clock to the last year, then it will 1384+ 10.\*(C'\fR) and then reset your system clock to the last year, then it will
1238take a year to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would trigger 1385take a year to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would trigger
1239roughly 10 seconds later and of course not if you reset your system time 1386roughly 10 seconds later).
1240again).
1241.PP 1387.PP
1242They can also be used to implement vastly more complex timers, such as 1388They can also be used to implement vastly more complex timers, such as
1243triggering an event on eahc midnight, local time. 1389triggering an event on each midnight, local time or other, complicated,
1390rules.
1244.PP 1391.PP
1245As with timers, the callback is guarenteed to be invoked only when the 1392As with timers, the callback is guarenteed to be invoked only when the
1246time (\f(CW\*(C`at\*(C'\fR) has been passed, but if multiple periodic timers become ready 1393time (\f(CW\*(C`at\*(C'\fR) has been passed, but if multiple periodic timers become ready
1247during the same loop iteration then order of execution is undefined. 1394during the same loop iteration then order of execution is undefined.
1395.PP
1396\fIWatcher-Specific Functions and Data Members\fR
1397.IX Subsection "Watcher-Specific Functions and Data Members"
1248.IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4 1398.IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4
1249.IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 1399.IX Item "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)"
1250.PD 0 1400.PD 0
1251.IP "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 4 1401.IP "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 4
1252.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)" 1402.IX Item "ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)"
1253.PD 1403.PD
1254Lots of arguments, lets sort it out... There are basically three modes of 1404Lots of arguments, lets sort it out... There are basically three modes of
1255operation, and we will explain them from simplest to complex: 1405operation, and we will explain them from simplest to complex:
1256.RS 4 1406.RS 4
1257.IP "* absolute timer (interval = reschedule_cb = 0)" 4 1407.IP "* absolute timer (at = time, interval = reschedule_cb = 0)" 4
1258.IX Item "absolute timer (interval = reschedule_cb = 0)" 1408.IX Item "absolute timer (at = time, interval = reschedule_cb = 0)"
1259In this configuration the watcher triggers an event at the wallclock time 1409In this configuration the watcher triggers an event at the wallclock time
1260\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs, 1410\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs,
1261that is, if it is to be run at January 1st 2011 then it will run when the 1411that is, if it is to be run at January 1st 2011 then it will run when the
1262system time reaches or surpasses this time. 1412system time reaches or surpasses this time.
1263.IP "* non-repeating interval timer (interval > 0, reschedule_cb = 0)" 4 1413.IP "* non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)" 4
1264.IX Item "non-repeating interval timer (interval > 0, reschedule_cb = 0)" 1414.IX Item "non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)"
1265In this mode the watcher will always be scheduled to time out at the next 1415In this mode the watcher will always be scheduled to time out at the next
1266\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N) and then repeat, regardless 1416\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative)
1267of any time jumps. 1417and then repeat, regardless of any time jumps.
1268.Sp 1418.Sp
1269This can be used to create timers that do not drift with respect to system 1419This can be used to create timers that do not drift with respect to system
1270time: 1420time:
1271.Sp 1421.Sp
1272.Vb 1 1422.Vb 1
… …
1279by 3600. 1429by 3600.
1280.Sp 1430.Sp
1281Another way to think about it (for the mathematically inclined) is that 1431Another way to think about it (for the mathematically inclined) is that
1282\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible 1432\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible
1283time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps. 1433time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps.
1434.Sp
1435For numerical stability it is preferable that the \f(CW\*(C`at\*(C'\fR value is near
1436\&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for
1437this value.
1284.IP "* manual reschedule mode (reschedule_cb = callback)" 4 1438.IP "* manual reschedule mode (at and interval ignored, reschedule_cb = callback)" 4
1285.IX Item "manual reschedule mode (reschedule_cb = callback)" 1439.IX Item "manual reschedule mode (at and interval ignored, reschedule_cb = callback)"
1286In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being 1440In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being
1287ignored. Instead, each time the periodic watcher gets scheduled, the 1441ignored. Instead, each time the periodic watcher gets scheduled, the
1288reschedule callback will be called with the watcher as first, and the 1442reschedule callback will be called with the watcher as first, and the
1289current time as second argument. 1443current time as second argument.
1290.Sp 1444.Sp
1291\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, 1445\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher,
1292ever, or make any event loop modifications\fR. If you need to stop it, 1446ever, or make any event loop modifications\fR. If you need to stop it,
1293return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop it afterwards (e.g. by 1447return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop it afterwards (e.g. by
1294starting a prepare watcher). 1448starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is legal).
1295.Sp 1449.Sp
1296Its prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 1450Its prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
1297ev_tstamp now)\*(C'\fR, e.g.: 1451ev_tstamp now)\*(C'\fR, e.g.:
1298.Sp 1452.Sp
1299.Vb 4 1453.Vb 4
… …
1323.IX Item "ev_periodic_again (loop, ev_periodic *)" 1477.IX Item "ev_periodic_again (loop, ev_periodic *)"
1324Simply stops and restarts the periodic watcher again. This is only useful 1478Simply stops and restarts the periodic watcher again. This is only useful
1325when you changed some parameters or the reschedule callback would return 1479when you changed some parameters or the reschedule callback would return
1326a different time than the last time it was called (e.g. in a crond like 1480a different time than the last time it was called (e.g. in a crond like
1327program when the crontabs have changed). 1481program when the crontabs have changed).
1482.IP "ev_tstamp offset [read\-write]" 4
1483.IX Item "ev_tstamp offset [read-write]"
1484When repeating, this contains the offset value, otherwise this is the
1485absolute point in time (the \f(CW\*(C`at\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR).
1486.Sp
1487Can be modified any time, but changes only take effect when the periodic
1488timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called.
1328.IP "ev_tstamp interval [read\-write]" 4 1489.IP "ev_tstamp interval [read\-write]" 4
1329.IX Item "ev_tstamp interval [read-write]" 1490.IX Item "ev_tstamp interval [read-write]"
1330The current interval value. Can be modified any time, but changes only 1491The current interval value. Can be modified any time, but changes only
1331take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being 1492take effect when the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being
1332called. 1493called.
1333.IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4 1494.IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4
1334.IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]" 1495.IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]"
1335The current reschedule callback, or \f(CW0\fR, if this functionality is 1496The current reschedule callback, or \f(CW0\fR, if this functionality is
1336switched off. Can be changed any time, but changes only take effect when 1497switched off. Can be changed any time, but changes only take effect when
1337the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. 1498the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called.
1499.IP "ev_tstamp at [read\-only]" 4
1500.IX Item "ev_tstamp at [read-only]"
1501When active, contains the absolute time that the watcher is supposed to
1502trigger next.
1338.PP 1503.PP
1339Example: Call a callback every hour, or, more precisely, whenever the 1504Example: Call a callback every hour, or, more precisely, whenever the
1340system clock is divisible by 3600. The callback invocation times have 1505system clock is divisible by 3600. The callback invocation times have
1341potentially a lot of jittering, but good long-term stability. 1506potentially a lot of jittering, but good long-term stability.
1342.PP 1507.PP
… …
1392first watcher gets started will libev actually register a signal watcher 1557first watcher gets started will libev actually register a signal watcher
1393with the kernel (thus it coexists with your own signal handlers as long 1558with the kernel (thus it coexists with your own signal handlers as long
1394as you don't register any with libev). Similarly, when the last signal 1559as you don't register any with libev). Similarly, when the last signal
1395watcher for a signal is stopped libev will reset the signal handler to 1560watcher for a signal is stopped libev will reset the signal handler to
1396\&\s-1SIG_DFL\s0 (regardless of what it was set to before). 1561\&\s-1SIG_DFL\s0 (regardless of what it was set to before).
1562.PP
1563\fIWatcher-Specific Functions and Data Members\fR
1564.IX Subsection "Watcher-Specific Functions and Data Members"
1397.IP "ev_signal_init (ev_signal *, callback, int signum)" 4 1565.IP "ev_signal_init (ev_signal *, callback, int signum)" 4
1398.IX Item "ev_signal_init (ev_signal *, callback, int signum)" 1566.IX Item "ev_signal_init (ev_signal *, callback, int signum)"
1399.PD 0 1567.PD 0
1400.IP "ev_signal_set (ev_signal *, int signum)" 4 1568.IP "ev_signal_set (ev_signal *, int signum)" 4
1401.IX Item "ev_signal_set (ev_signal *, int signum)" 1569.IX Item "ev_signal_set (ev_signal *, int signum)"
… …
1408.ie n .Sh """ev_child"" \- watch out for process status changes" 1576.ie n .Sh """ev_child"" \- watch out for process status changes"
1409.el .Sh "\f(CWev_child\fP \- watch out for process status changes" 1577.el .Sh "\f(CWev_child\fP \- watch out for process status changes"
1410.IX Subsection "ev_child - watch out for process status changes" 1578.IX Subsection "ev_child - watch out for process status changes"
1411Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to 1579Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to
1412some child status changes (most typically when a child of yours dies). 1580some child status changes (most typically when a child of yours dies).
1581.PP
1582\fIWatcher-Specific Functions and Data Members\fR
1583.IX Subsection "Watcher-Specific Functions and Data Members"
1413.IP "ev_child_init (ev_child *, callback, int pid)" 4 1584.IP "ev_child_init (ev_child *, callback, int pid)" 4
1414.IX Item "ev_child_init (ev_child *, callback, int pid)" 1585.IX Item "ev_child_init (ev_child *, callback, int pid)"
1415.PD 0 1586.PD 0
1416.IP "ev_child_set (ev_child *, int pid)" 4 1587.IP "ev_child_set (ev_child *, int pid)" 4
1417.IX Item "ev_child_set (ev_child *, int pid)" 1588.IX Item "ev_child_set (ev_child *, int pid)"
… …
1482reader). Inotify will be used to give hints only and should not change the 1653reader). Inotify will be used to give hints only and should not change the
1483semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs 1654semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs
1484to fall back to regular polling again even with inotify, but changes are 1655to fall back to regular polling again even with inotify, but changes are
1485usually detected immediately, and if the file exists there will be no 1656usually detected immediately, and if the file exists there will be no
1486polling. 1657polling.
1658.PP
1659\fIInotify\fR
1660.IX Subsection "Inotify"
1661.PP
1662When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only
1663available on Linux) and present at runtime, it will be used to speed up
1664change detection where possible. The inotify descriptor will be created lazily
1665when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started.
1666.PP
1667Inotify presense does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers
1668except that changes might be detected earlier, and in some cases, to avoid
1669making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presense of inotify support
1670there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling.
1671.PP
1672(There is no support for kqueue, as apparently it cannot be used to
1673implement this functionality, due to the requirement of having a file
1674descriptor open on the object at all times).
1675.PP
1676\fIThe special problem of stat time resolution\fR
1677.IX Subsection "The special problem of stat time resolution"
1678.PP
1679The \f(CW\*(C`stat ()\*(C'\fR syscall only supports full-second resolution portably, and
1680even on systems where the resolution is higher, many filesystems still
1681only support whole seconds.
1682.PP
1683That means that, if the time is the only thing that changes, you might
1684miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and calls
1685your callback, which does something. When there is another update within
1686the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect it.
1687.PP
1688The solution to this is to delay acting on a change for a second (or till
1689the next second boundary), using a roughly one-second delay \f(CW\*(C`ev_timer\*(C'\fR
1690(\f(CW\*(C`ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)\*(C'\fR). The \f(CW.01\fR
1691is added to work around small timing inconsistencies of some operating
1692systems.
1693.PP
1694\fIWatcher-Specific Functions and Data Members\fR
1695.IX Subsection "Watcher-Specific Functions and Data Members"
1487.IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4 1696.IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4
1488.IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 1697.IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)"
1489.PD 0 1698.PD 0
1490.IP "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)" 4 1699.IP "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)" 4
1491.IX Item "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)" 1700.IX Item "ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)"
… …
1520The specified interval. 1729The specified interval.
1521.IP "const char *path [read\-only]" 4 1730.IP "const char *path [read\-only]" 4
1522.IX Item "const char *path [read-only]" 1731.IX Item "const char *path [read-only]"
1523The filesystem path that is being watched. 1732The filesystem path that is being watched.
1524.PP 1733.PP
1734\fIExamples\fR
1735.IX Subsection "Examples"
1736.PP
1525Example: Watch \f(CW\*(C`/etc/passwd\*(C'\fR for attribute changes. 1737Example: Watch \f(CW\*(C`/etc/passwd\*(C'\fR for attribute changes.
1526.PP 1738.PP
1527.Vb 15 1739.Vb 15
1528\& static void 1740\& static void
1529\& passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 1741\& passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
… …
1546\& ... 1758\& ...
1547\& ev_stat passwd; 1759\& ev_stat passwd;
1548.Ve 1760.Ve
1549.PP 1761.PP
1550.Vb 2 1762.Vb 2
1551\& ev_stat_init (&passwd, passwd_cb, "/etc/passwd"); 1763\& ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1552\& ev_stat_start (loop, &passwd); 1764\& ev_stat_start (loop, &passwd);
1765.Ve
1766.PP
1767Example: Like above, but additionally use a one-second delay so we do not
1768miss updates (however, frequent updates will delay processing, too, so
1769one might do the work both on \f(CW\*(C`ev_stat\*(C'\fR callback invocation \fIand\fR on
1770\&\f(CW\*(C`ev_timer\*(C'\fR callback invocation).
1771.PP
1772.Vb 2
1773\& static ev_stat passwd;
1774\& static ev_timer timer;
1775.Ve
1776.PP
1777.Vb 4
1778\& static void
1779\& timer_cb (EV_P_ ev_timer *w, int revents)
1780\& {
1781\& ev_timer_stop (EV_A_ w);
1782.Ve
1783.PP
1784.Vb 2
1785\& /* now it's one second after the most recent passwd change */
1786\& }
1787.Ve
1788.PP
1789.Vb 6
1790\& static void
1791\& stat_cb (EV_P_ ev_stat *w, int revents)
1792\& {
1793\& /* reset the one-second timer */
1794\& ev_timer_again (EV_A_ &timer);
1795\& }
1796.Ve
1797.PP
1798.Vb 4
1799\& ...
1800\& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1801\& ev_stat_start (loop, &passwd);
1802\& ev_timer_init (&timer, timer_cb, 0., 1.01);
1553.Ve 1803.Ve
1554.ie n .Sh """ev_idle"" \- when you've got nothing better to do..." 1804.ie n .Sh """ev_idle"" \- when you've got nothing better to do..."
1555.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..." 1805.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..."
1556.IX Subsection "ev_idle - when you've got nothing better to do..." 1806.IX Subsection "ev_idle - when you've got nothing better to do..."
1557Idle watchers trigger events when no other events of the same or higher 1807Idle watchers trigger events when no other events of the same or higher
… …
1570.PP 1820.PP
1571Apart from keeping your process non-blocking (which is a useful 1821Apart from keeping your process non-blocking (which is a useful
1572effect on its own sometimes), idle watchers are a good place to do 1822effect on its own sometimes), idle watchers are a good place to do
1573\&\*(L"pseudo\-background processing\*(R", or delay processing stuff to after the 1823\&\*(L"pseudo\-background processing\*(R", or delay processing stuff to after the
1574event loop has handled all outstanding events. 1824event loop has handled all outstanding events.
1825.PP
1826\fIWatcher-Specific Functions and Data Members\fR
1827.IX Subsection "Watcher-Specific Functions and Data Members"
1575.IP "ev_idle_init (ev_signal *, callback)" 4 1828.IP "ev_idle_init (ev_signal *, callback)" 4
1576.IX Item "ev_idle_init (ev_signal *, callback)" 1829.IX Item "ev_idle_init (ev_signal *, callback)"
1577Initialises and configures the idle watcher \- it has no parameters of any 1830Initialises and configures the idle watcher \- it has no parameters of any
1578kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless, 1831kind. There is a \f(CW\*(C`ev_idle_set\*(C'\fR macro, but using it is utterly pointless,
1579believe me. 1832believe me.
… …
1634are ready to run (it's actually more complicated: it only runs coroutines 1887are ready to run (it's actually more complicated: it only runs coroutines
1635with priority higher than or equal to the event loop and one coroutine 1888with priority higher than or equal to the event loop and one coroutine
1636of lower priority, but only once, using idle watchers to keep the event 1889of lower priority, but only once, using idle watchers to keep the event
1637loop from blocking if lower-priority coroutines are active, thus mapping 1890loop from blocking if lower-priority coroutines are active, thus mapping
1638low-priority coroutines to idle/background tasks). 1891low-priority coroutines to idle/background tasks).
1892.PP
1893It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR)
1894priority, to ensure that they are being run before any other watchers
1895after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers,
1896too) should not activate (\*(L"feed\*(R") events into libev. While libev fully
1897supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers
1898did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other
1899(non\-libev) event loops those other event loops might be in an unusable
1900state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to
1901coexist peacefully with others).
1902.PP
1903\fIWatcher-Specific Functions and Data Members\fR
1904.IX Subsection "Watcher-Specific Functions and Data Members"
1639.IP "ev_prepare_init (ev_prepare *, callback)" 4 1905.IP "ev_prepare_init (ev_prepare *, callback)" 4
1640.IX Item "ev_prepare_init (ev_prepare *, callback)" 1906.IX Item "ev_prepare_init (ev_prepare *, callback)"
1641.PD 0 1907.PD 0
1642.IP "ev_check_init (ev_check *, callback)" 4 1908.IP "ev_check_init (ev_check *, callback)" 4
1643.IX Item "ev_check_init (ev_check *, callback)" 1909.IX Item "ev_check_init (ev_check *, callback)"
… …
1890\& ev_embed_start (loop_hi, &embed); 2156\& ev_embed_start (loop_hi, &embed);
1891\& } 2157\& }
1892\& else 2158\& else
1893\& loop_lo = loop_hi; 2159\& loop_lo = loop_hi;
1894.Ve 2160.Ve
2161.PP
2162\fIWatcher-Specific Functions and Data Members\fR
2163.IX Subsection "Watcher-Specific Functions and Data Members"
1895.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 2164.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
1896.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 2165.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"
1897.PD 0 2166.PD 0
1898.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 2167.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
1899.IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 2168.IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)"
… …
1906.IP "ev_embed_sweep (loop, ev_embed *)" 4 2175.IP "ev_embed_sweep (loop, ev_embed *)" 4
1907.IX Item "ev_embed_sweep (loop, ev_embed *)" 2176.IX Item "ev_embed_sweep (loop, ev_embed *)"
1908Make a single, non-blocking sweep over the embedded loop. This works 2177Make a single, non-blocking sweep over the embedded loop. This works
1909similarly to \f(CW\*(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\*(C'\fR, but in the most 2178similarly to \f(CW\*(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\*(C'\fR, but in the most
1910apropriate way for embedded loops. 2179apropriate way for embedded loops.
1911.IP "struct ev_loop *loop [read\-only]" 4 2180.IP "struct ev_loop *other [read\-only]" 4
1912.IX Item "struct ev_loop *loop [read-only]" 2181.IX Item "struct ev_loop *other [read-only]"
1913The embedded event loop. 2182The embedded event loop.
1914.ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork" 2183.ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork"
1915.el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" 2184.el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork"
1916.IX Subsection "ev_fork - the audacity to resume the event loop after a fork" 2185.IX Subsection "ev_fork - the audacity to resume the event loop after a fork"
1917Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because 2186Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
… …
1919\&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the 2188\&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the
1920event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, 2189event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called,
1921and only in the child after the fork. If whoever good citizen calling 2190and only in the child after the fork. If whoever good citizen calling
1922\&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork 2191\&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork
1923handlers will be invoked, too, of course. 2192handlers will be invoked, too, of course.
2193.PP
2194\fIWatcher-Specific Functions and Data Members\fR
2195.IX Subsection "Watcher-Specific Functions and Data Members"
1924.IP "ev_fork_init (ev_signal *, callback)" 4 2196.IP "ev_fork_init (ev_signal *, callback)" 4
1925.IX Item "ev_fork_init (ev_signal *, callback)" 2197.IX Item "ev_fork_init (ev_signal *, callback)"
1926Initialises and configures the fork watcher \- it has no parameters of any 2198Initialises and configures the fork watcher \- it has no parameters of any
1927kind. There is a \f(CW\*(C`ev_fork_set\*(C'\fR macro, but using it is utterly pointless, 2199kind. There is a \f(CW\*(C`ev_fork_set\*(C'\fR macro, but using it is utterly pointless,
1928believe me. 2200believe me.
… …
2122Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 2394Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
2123constructor already stores the event loop. 2395constructor already stores the event loop.
2124.IP "w\->stop ()" 4 2396.IP "w\->stop ()" 4
2125.IX Item "w->stop ()" 2397.IX Item "w->stop ()"
2126Stops the watcher if it is active. Again, no \f(CW\*(C`loop\*(C'\fR argument. 2398Stops the watcher if it is active. Again, no \f(CW\*(C`loop\*(C'\fR argument.
2127.ie n .IP "w\->again () ""ev::timer""\fR, \f(CW""ev::periodic"" only" 4 2399.ie n .IP "w\->again () (""ev::timer""\fR, \f(CW""ev::periodic"" only)" 4
2128.el .IP "w\->again () \f(CWev::timer\fR, \f(CWev::periodic\fR only" 4 2400.el .IP "w\->again () (\f(CWev::timer\fR, \f(CWev::periodic\fR only)" 4
2129.IX Item "w->again () ev::timer, ev::periodic only" 2401.IX Item "w->again () (ev::timer, ev::periodic only)"
2130For \f(CW\*(C`ev::timer\*(C'\fR and \f(CW\*(C`ev::periodic\*(C'\fR, this invokes the corresponding 2402For \f(CW\*(C`ev::timer\*(C'\fR and \f(CW\*(C`ev::periodic\*(C'\fR, this invokes the corresponding
2131\&\f(CW\*(C`ev_TYPE_again\*(C'\fR function. 2403\&\f(CW\*(C`ev_TYPE_again\*(C'\fR function.
2132.ie n .IP "w\->sweep () ""ev::embed"" only" 4 2404.ie n .IP "w\->sweep () (""ev::embed"" only)" 4
2133.el .IP "w\->sweep () \f(CWev::embed\fR only" 4 2405.el .IP "w\->sweep () (\f(CWev::embed\fR only)" 4
2134.IX Item "w->sweep () ev::embed only" 2406.IX Item "w->sweep () (ev::embed only)"
2135Invokes \f(CW\*(C`ev_embed_sweep\*(C'\fR. 2407Invokes \f(CW\*(C`ev_embed_sweep\*(C'\fR.
2136.ie n .IP "w\->update () ""ev::stat"" only" 4 2408.ie n .IP "w\->update () (""ev::stat"" only)" 4
2137.el .IP "w\->update () \f(CWev::stat\fR only" 4 2409.el .IP "w\->update () (\f(CWev::stat\fR only)" 4
2138.IX Item "w->update () ev::stat only" 2410.IX Item "w->update () (ev::stat only)"
2139Invokes \f(CW\*(C`ev_stat_stat\*(C'\fR. 2411Invokes \f(CW\*(C`ev_stat_stat\*(C'\fR.
2140.RE 2412.RE
2141.RS 4 2413.RS 4
2142.RE 2414.RE
2143.PP 2415.PP
… …
2167\& io.start (fd, ev::READ); 2439\& io.start (fd, ev::READ);
2168\& } 2440\& }
2169.Ve 2441.Ve
2170.SH "MACRO MAGIC" 2442.SH "MACRO MAGIC"
2171.IX Header "MACRO MAGIC" 2443.IX Header "MACRO MAGIC"
2172Libev can be compiled with a variety of options, the most fundemantal is 2444Libev can be compiled with a variety of options, the most fundamantal
2173\&\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) functions and 2445of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
2174callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 2446functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
2175.PP 2447.PP
2176To make it easier to write programs that cope with either variant, the 2448To make it easier to write programs that cope with either variant, the
2177following macros are defined: 2449following macros are defined:
2178.ie n .IP """EV_A""\fR, \f(CW""EV_A_""" 4 2450.ie n .IP """EV_A""\fR, \f(CW""EV_A_""" 4
2179.el .IP "\f(CWEV_A\fR, \f(CWEV_A_\fR" 4 2451.el .IP "\f(CWEV_A\fR, \f(CWEV_A_\fR" 4
… …
2238Libev can (and often is) directly embedded into host 2510Libev can (and often is) directly embedded into host
2239applications. Examples of applications that embed it include the Deliantra 2511applications. Examples of applications that embed it include the Deliantra
2240Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe) 2512Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe)
2241and rxvt\-unicode. 2513and rxvt\-unicode.
2242.PP 2514.PP
2243The goal is to enable you to just copy the neecssary files into your 2515The goal is to enable you to just copy the necessary files into your
2244source directory without having to change even a single line in them, so 2516source directory without having to change even a single line in them, so
2245you can easily upgrade by simply copying (or having a checked-out copy of 2517you can easily upgrade by simply copying (or having a checked-out copy of
2246libev somewhere in your source tree). 2518libev somewhere in your source tree).
2247.Sh "\s-1FILESETS\s0" 2519.Sh "\s-1FILESETS\s0"
2248.IX Subsection "FILESETS" 2520.IX Subsection "FILESETS"
… …
2353.IX Item "EV_USE_MONOTONIC" 2625.IX Item "EV_USE_MONOTONIC"
2354If defined to be \f(CW1\fR, libev will try to detect the availability of the 2626If defined to be \f(CW1\fR, libev will try to detect the availability of the
2355monotonic clock option at both compiletime and runtime. Otherwise no use 2627monotonic clock option at both compiletime and runtime. Otherwise no use
2356of the monotonic clock option will be attempted. If you enable this, you 2628of the monotonic clock option will be attempted. If you enable this, you
2357usually have to link against librt or something similar. Enabling it when 2629usually have to link against librt or something similar. Enabling it when
2358the functionality isn't available is safe, though, althoguh you have 2630the functionality isn't available is safe, though, although you have
2359to make sure you link against any libraries where the \f(CW\*(C`clock_gettime\*(C'\fR 2631to make sure you link against any libraries where the \f(CW\*(C`clock_gettime\*(C'\fR
2360function is hiding in (often \fI\-lrt\fR). 2632function is hiding in (often \fI\-lrt\fR).
2361.IP "\s-1EV_USE_REALTIME\s0" 4 2633.IP "\s-1EV_USE_REALTIME\s0" 4
2362.IX Item "EV_USE_REALTIME" 2634.IX Item "EV_USE_REALTIME"
2363If defined to be \f(CW1\fR, libev will try to detect the availability of the 2635If defined to be \f(CW1\fR, libev will try to detect the availability of the
2364realtime clock option at compiletime (and assume its availability at 2636realtime clock option at compiletime (and assume its availability at
2365runtime if successful). Otherwise no use of the realtime clock option will 2637runtime if successful). Otherwise no use of the realtime clock option will
2366be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get 2638be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get
2367(CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See tzhe note about libraries 2639(CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the
2368in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. 2640note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though.
2641.IP "\s-1EV_USE_NANOSLEEP\s0" 4
2642.IX Item "EV_USE_NANOSLEEP"
2643If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
2644and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
2369.IP "\s-1EV_USE_SELECT\s0" 4 2645.IP "\s-1EV_USE_SELECT\s0" 4
2370.IX Item "EV_USE_SELECT" 2646.IX Item "EV_USE_SELECT"
2371If undefined or defined to be \f(CW1\fR, libev will compile in support for the 2647If undefined or defined to be \f(CW1\fR, libev will compile in support for the
2372\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no 2648\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no
2373other method takes over, select will be it. Otherwise the select backend 2649other method takes over, select will be it. Otherwise the select backend
… …
2427interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will 2703interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will
2428be detected at runtime. 2704be detected at runtime.
2429.IP "\s-1EV_H\s0" 4 2705.IP "\s-1EV_H\s0" 4
2430.IX Item "EV_H" 2706.IX Item "EV_H"
2431The name of the \fIev.h\fR header file used to include it. The default if 2707The name of the \fIev.h\fR header file used to include it. The default if
2432undefined is \f(CW\*(C`<ev.h>\*(C'\fR in \fIevent.h\fR and \f(CW"ev.h"\fR in \fIev.c\fR. This 2708undefined is \f(CW"ev.h"\fR in \fIevent.h\fR and \fIev.c\fR. This can be used to
2433can be used to virtually rename the \fIev.h\fR header file in case of conflicts. 2709virtually rename the \fIev.h\fR header file in case of conflicts.
2434.IP "\s-1EV_CONFIG_H\s0" 4 2710.IP "\s-1EV_CONFIG_H\s0" 4
2435.IX Item "EV_CONFIG_H" 2711.IX Item "EV_CONFIG_H"
2436If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 2712If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
2437\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 2713\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
2438\&\f(CW\*(C`EV_H\*(C'\fR, above. 2714\&\f(CW\*(C`EV_H\*(C'\fR, above.
2439.IP "\s-1EV_EVENT_H\s0" 4 2715.IP "\s-1EV_EVENT_H\s0" 4
2440.IX Item "EV_EVENT_H" 2716.IX Item "EV_EVENT_H"
2441Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 2717Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
2442of how the \fIevent.h\fR header can be found. 2718of how the \fIevent.h\fR header can be found, the dfeault is \f(CW"event.h"\fR.
2443.IP "\s-1EV_PROTOTYPES\s0" 4 2719.IP "\s-1EV_PROTOTYPES\s0" 4
2444.IX Item "EV_PROTOTYPES" 2720.IX Item "EV_PROTOTYPES"
2445If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 2721If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
2446prototypes, but still define all the structs and other symbols. This is 2722prototypes, but still define all the structs and other symbols. This is
2447occasionally useful if you want to provide your own wrapper functions 2723occasionally useful if you want to provide your own wrapper functions
… …
2504pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more 2780pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more
2505than enough. If you need to manage thousands of children you might want to 2781than enough. If you need to manage thousands of children you might want to
2506increase this value (\fImust\fR be a power of two). 2782increase this value (\fImust\fR be a power of two).
2507.IP "\s-1EV_INOTIFY_HASHSIZE\s0" 4 2783.IP "\s-1EV_INOTIFY_HASHSIZE\s0" 4
2508.IX Item "EV_INOTIFY_HASHSIZE" 2784.IX Item "EV_INOTIFY_HASHSIZE"
2509\&\f(CW\*(C`ev_staz\*(C'\fR watchers use a small hash table to distribute workload by 2785\&\f(CW\*(C`ev_stat\*(C'\fR watchers use a small hash table to distribute workload by
2510inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), 2786inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR),
2511usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR 2787usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR
2512watchers you might want to increase this value (\fImust\fR be a power of 2788watchers you might want to increase this value (\fImust\fR be a power of
2513two). 2789two).
2514.IP "\s-1EV_COMMON\s0" 4 2790.IP "\s-1EV_COMMON\s0" 4
… …
2533.IP "ev_set_cb (ev, cb)" 4 2809.IP "ev_set_cb (ev, cb)" 4
2534.IX Item "ev_set_cb (ev, cb)" 2810.IX Item "ev_set_cb (ev, cb)"
2535.PD 2811.PD
2536Can be used to change the callback member declaration in each watcher, 2812Can be used to change the callback member declaration in each watcher,
2537and the way callbacks are invoked and set. Must expand to a struct member 2813and the way callbacks are invoked and set. Must expand to a struct member
2538definition and a statement, respectively. See the \fIev.v\fR header file for 2814definition and a statement, respectively. See the \fIev.h\fR header file for
2539their default definitions. One possible use for overriding these is to 2815their default definitions. One possible use for overriding these is to
2540avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 2816avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
2541method calls instead of plain function calls in \*(C+. 2817method calls instead of plain function calls in \*(C+.
2818.Sh "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0"
2819.IX Subsection "EXPORTED API SYMBOLS"
2820If you need to re-export the \s-1API\s0 (e.g. via a dll) and you need a list of
2821exported symbols, you can use the provided \fISymbol.*\fR files which list
2822all public symbols, one per line:
2823.Sp
2824.Vb 2
2825\& Symbols.ev for libev proper
2826\& Symbols.event for the libevent emulation
2827.Ve
2828.Sp
2829This can also be used to rename all public symbols to avoid clashes with
2830multiple versions of libev linked together (which is obviously bad in
2831itself, but sometimes it is inconvinient to avoid this).
2832.Sp
2833A sed command like this will create wrapper \f(CW\*(C`#define\*(C'\fR's that you need to
2834include before including \fIev.h\fR:
2835.Sp
2836.Vb 1
2837\& <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
2838.Ve
2839.Sp
2840This would create a file \fIwrap.h\fR which essentially looks like this:
2841.Sp
2842.Vb 4
2843\& #define ev_backend myprefix_ev_backend
2844\& #define ev_check_start myprefix_ev_check_start
2845\& #define ev_check_stop myprefix_ev_check_stop
2846\& ...
2847.Ve
2542.Sh "\s-1EXAMPLES\s0" 2848.Sh "\s-1EXAMPLES\s0"
2543.IX Subsection "EXAMPLES" 2849.IX Subsection "EXAMPLES"
2544For a real-world example of a program the includes libev 2850For a real-world example of a program the includes libev
2545verbatim, you can have a look at the \s-1EV\s0 perl module 2851verbatim, you can have a look at the \s-1EV\s0 perl module
2546(<http://software.schmorp.de/pkg/EV.html>). It has the libev files in 2852(<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
… …
2588.RS 4 2894.RS 4
2589.IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4 2895.IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4
2590.IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 2896.IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)"
2591This means that, when you have a watcher that triggers in one hour and 2897This means that, when you have a watcher that triggers in one hour and
2592there are 100 watchers that would trigger before that then inserting will 2898there are 100 watchers that would trigger before that then inserting will
2593have to skip those 100 watchers. 2899have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers.
2594.IP "Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)" 4 2900.IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4
2595.IX Item "Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)" 2901.IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)"
2596That means that for changing a timer costs less than removing/adding them 2902That means that changing a timer costs less than removing/adding them
2597as only the relative motion in the event queue has to be paid for. 2903as only the relative motion in the event queue has to be paid for.
2598.IP "Starting io/check/prepare/idle/signal/child watchers: O(1)" 4 2904.IP "Starting io/check/prepare/idle/signal/child watchers: O(1)" 4
2599.IX Item "Starting io/check/prepare/idle/signal/child watchers: O(1)" 2905.IX Item "Starting io/check/prepare/idle/signal/child watchers: O(1)"
2600These just add the watcher into an array or at the head of a list. 2906These just add the watcher into an array or at the head of a list.
2907.IP "Stopping check/prepare/idle watchers: O(1)" 4
2601=item Stopping check/prepare/idle watchers: O(1) 2908.IX Item "Stopping check/prepare/idle watchers: O(1)"
2909.PD 0
2602.IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4 2910.IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4
2603.IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))" 2911.IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))"
2912.PD
2604These watchers are stored in lists then need to be walked to find the 2913These watchers are stored in lists then need to be walked to find the
2605correct watcher to remove. The lists are usually short (you don't usually 2914correct watcher to remove. The lists are usually short (you don't usually
2606have many watchers waiting for the same fd or signal). 2915have many watchers waiting for the same fd or signal).
2607.IP "Finding the next timer per loop iteration: O(1)" 4 2916.IP "Finding the next timer in each loop iteration: O(1)" 4
2608.IX Item "Finding the next timer per loop iteration: O(1)" 2917.IX Item "Finding the next timer in each loop iteration: O(1)"
2609.PD 0 2918By virtue of using a binary heap, the next timer is always found at the
2919beginning of the storage array.
2610.IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 2920.IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4
2611.IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 2921.IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)"
2612.PD
2613A change means an I/O watcher gets started or stopped, which requires 2922A change means an I/O watcher gets started or stopped, which requires
2614libev to recalculate its status (and possibly tell the kernel). 2923libev to recalculate its status (and possibly tell the kernel, depending
2615.IP "Activating one watcher: O(1)" 4 2924on backend and wether \f(CW\*(C`ev_io_set\*(C'\fR was used).
2616.IX Item "Activating one watcher: O(1)" 2925.IP "Activating one watcher (putting it into the pending state): O(1)" 4
2926.IX Item "Activating one watcher (putting it into the pending state): O(1)"
2617.PD 0 2927.PD 0
2618.IP "Priority handling: O(number_of_priorities)" 4 2928.IP "Priority handling: O(number_of_priorities)" 4
2619.IX Item "Priority handling: O(number_of_priorities)" 2929.IX Item "Priority handling: O(number_of_priorities)"
2620.PD 2930.PD
2621Priorities are implemented by allocating some space for each 2931Priorities are implemented by allocating some space for each
2622priority. When doing priority-based operations, libev usually has to 2932priority. When doing priority-based operations, libev usually has to
2623linearly search all the priorities. 2933linearly search all the priorities, but starting/stopping and activating
2934watchers becomes O(1) w.r.t. prioritiy handling.
2624.RE 2935.RE
2625.RS 4 2936.RS 4
2626.SH "AUTHOR" 2937.SH "AUTHOR"
2627.IX Header "AUTHOR" 2938.IX Header "AUTHOR"
2628Marc Lehmann <libev@schmorp.de>. 2939Marc Lehmann <libev@schmorp.de>.

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines