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

Comparing libev/ev.3 (file contents):
Revision 1.50 by root, Wed Dec 12 17:55:05 2007 UTC vs.
Revision 1.58 by root, Sat Dec 22 16:53:56 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-12" "perl v5.8.8" "User Contributed Perl Documentation" 132.TH EV 1 "2007-12-22" "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
… …
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.
… …
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 ()"
… …
444.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
445.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 452.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
446This 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
447libev 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,
448but 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
449using 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
450the 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.
451.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
452.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
453.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)"
454And 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
455select, but handles sparse fds better and has no artificial limit on the 469than select, but handles sparse fds better and has no artificial
456number 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
457lot 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.
458.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 474.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
459.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 475.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
460.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 476.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
461For 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,
462but it scales phenomenally better. While poll and select usually scale like 478but it scales phenomenally better. While poll and select usually scale
463O(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),
464either 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.
465.Sp 484.Sp
466While 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
467result in some caching, there is still a syscall per such incident 486will result in some caching, there is still a syscall per such incident
468(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
469best 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
470well if you register events for both fds. 489very well if you register events for both fds.
471.Sp 490.Sp
472Please note that epoll sometimes generates spurious notifications, so you 491Please note that epoll sometimes generates spurious notifications, so you
473need 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
474(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.
475.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
476.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
477.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 503.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
478Kqueue deserves special mention, as at the time of this writing, it 504Kqueue deserves special mention, as at the time of this writing, it
479was 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
480anything but sockets and pipes, except on Darwin, where of course its 506with anything but sockets and pipes, except on Darwin, where of course
481completely useless). For this reason its not being \*(L"autodetected\*(R" 507it's completely useless). For this reason it's not being \*(L"autodetected\*(R"
482unless you explicitly specify it explicitly in the flags (i.e. using 508unless you explicitly specify it explicitly in the flags (i.e. using
483\&\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.
484.Sp 515.Sp
485It 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
486kernel is more efficient (which says nothing about its actual speed, of 517kernel is more efficient (which says nothing about its actual speed, of
487course). While starting and stopping an I/O watcher does not cause an 518course). While stopping, setting and starting an I/O watcher does never
488extra 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
489incident, 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.
490.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 531.ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4
491.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4 532.el .IP "\f(CWEVBACKEND_DEVPOLL\fR (value 16, Solaris 8)" 4
492.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)" 533.IX Item "EVBACKEND_DEVPOLL (value 16, Solaris 8)"
493This 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.
494.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4 538.ie n .IP """EVBACKEND_PORT"" (value 32, Solaris 10)" 4
495.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4 539.el .IP "\f(CWEVBACKEND_PORT\fR (value 32, Solaris 10)" 4
496.IX Item "EVBACKEND_PORT (value 32, Solaris 10)" 540.IX Item "EVBACKEND_PORT (value 32, Solaris 10)"
497This uses the Solaris 10 port mechanism. As with everything on Solaris, 541This uses the Solaris 10 event port mechanism. As with everything on Solaris,
498it'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)).
499.Sp 543.Sp
500Please note that solaris ports can result in a lot of spurious 544Please note that solaris event ports can deliver a lot of spurious
501notifications, 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
502blocking 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.
503.ie n .IP """EVBACKEND_ALL""" 4 552.ie n .IP """EVBACKEND_ALL""" 4
504.el .IP "\f(CWEVBACKEND_ALL\fR" 4 553.el .IP "\f(CWEVBACKEND_ALL\fR" 4
505.IX Item "EVBACKEND_ALL" 554.IX Item "EVBACKEND_ALL"
506Try all backends (even potentially broken ones that wouldn't be tried 555Try all backends (even potentially broken ones that wouldn't be tried
507with \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
508\&\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.
509.RE 560.RE
510.RS 4 561.RS 4
511.Sp 562.Sp
512If 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
513backends 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
… …
555Destroys the default loop again (frees all memory and kernel state 606Destroys the default loop again (frees all memory and kernel state
556etc.). 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
557sense, 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
558responsibility to either stop all watchers cleanly yoursef \fIbefore\fR 609responsibility to either stop all watchers cleanly yoursef \fIbefore\fR
559calling this function, or cope with the fact afterwards (which is usually 610calling this function, or cope with the fact afterwards (which is usually
560the 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
561for 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).
562.IP "ev_loop_destroy (loop)" 4 622.IP "ev_loop_destroy (loop)" 4
563.IX Item "ev_loop_destroy (loop)" 623.IX Item "ev_loop_destroy (loop)"
564Like \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
565earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. 625earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR.
566.IP "ev_default_fork ()" 4 626.IP "ev_default_fork ()" 4
… …
607.IX Item "ev_tstamp ev_now (loop)" 667.IX Item "ev_tstamp ev_now (loop)"
608Returns 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
609received events and started processing them. This timestamp does not 669received events and started processing them. This timestamp does not
610change 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
611time 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
612event occuring (or more correctly, libev finding out about it). 672event occurring (or more correctly, libev finding out about it).
613.IP "ev_loop (loop, int flags)" 4 673.IP "ev_loop (loop, int flags)" 4
614.IX Item "ev_loop (loop, int flags)" 674.IX Item "ev_loop (loop, int flags)"
615Finally, this is it, the event handler. This function usually is called 675Finally, this is it, the event handler. This function usually is called
616after you initialised all your watchers and you want to start handling 676after you initialised all your watchers and you want to start handling
617events. 677events.
… …
707.Sp 767.Sp
708.Vb 2 768.Vb 2
709\& ev_ref (loop); 769\& ev_ref (loop);
710\& ev_signal_stop (loop, &exitsig); 770\& ev_signal_stop (loop, &exitsig);
711.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.
712.SH "ANATOMY OF A WATCHER" 809.SH "ANATOMY OF A WATCHER"
713.IX Header "ANATOMY OF A WATCHER" 810.IX Header "ANATOMY OF A WATCHER"
714A 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
715interest 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
716become 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:
… …
1069its own, so its quite safe to use). 1166its own, so its quite safe to use).
1070.PP 1167.PP
1071\fIThe special problem of disappearing file descriptors\fR 1168\fIThe special problem of disappearing file descriptors\fR
1072.IX Subsection "The special problem of disappearing file descriptors" 1169.IX Subsection "The special problem of disappearing file descriptors"
1073.PP 1170.PP
1074Some backends (e.g kqueue, epoll) need to be told about closing a file 1171Some backends (e.g. kqueue, epoll) need to be told about closing a file
1075descriptor (either by calling \f(CW\*(C`close\*(C'\fR explicitly or by any other means, 1172descriptor (either by calling \f(CW\*(C`close\*(C'\fR explicitly or by any other means,
1076such as \f(CW\*(C`dup\*(C'\fR). The reason is that you register interest in some file 1173such as \f(CW\*(C`dup\*(C'\fR). The reason is that you register interest in some file
1077descriptor, but when it goes away, the operating system will silently drop 1174descriptor, but when it goes away, the operating system will silently drop
1078this interest. If another file descriptor with the same number then is 1175this interest. If another file descriptor with the same number then is
1079registered with libev, there is no efficient way to see that this is, in 1176registered with libev, there is no efficient way to see that this is, in
… …
1087descriptor even if the file descriptor number itself did not change. 1184descriptor even if the file descriptor number itself did not change.
1088.PP 1185.PP
1089This is how one would do it normally anyway, the important point is that 1186This is how one would do it normally anyway, the important point is that
1090the libev application should not optimise around libev but should leave 1187the libev application should not optimise around libev but should leave
1091optimisations to libev. 1188optimisations to libev.
1189.PP
1190\fIThe special problem of dup'ed file descriptors\fR
1191.IX Subsection "The special problem of dup'ed file descriptors"
1192.PP
1193Some backends (e.g. epoll), cannot register events for file descriptors,
1194but only events for the underlying file descriptions. That menas when you
1195have \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors and register events for them, only one
1196file descriptor might actually receive events.
1197.PP
1198There is no workaorund possible except not registering events
1199for potentially \f(CW\*(C`dup ()\*(C'\fR'ed file descriptors or to resort to
1200\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1201.PP
1202\fIThe special problem of fork\fR
1203.IX Subsection "The special problem of fork"
1204.PP
1205Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit
1206useless behaviour. Libev fully supports fork, but needs to be told about
1207it in the child.
1208.PP
1209To support fork in your programs, you either have to call
1210\&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child,
1211enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or
1212\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1092.PP 1213.PP
1093\fIWatcher-Specific Functions\fR 1214\fIWatcher-Specific Functions\fR
1094.IX Subsection "Watcher-Specific Functions" 1215.IX Subsection "Watcher-Specific Functions"
1095.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 1216.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4
1096.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" 1217.IX Item "ev_io_init (ev_io *, callback, int fd, int events)"
… …
1379.IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4 1500.IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4
1380.IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]" 1501.IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]"
1381The current reschedule callback, or \f(CW0\fR, if this functionality is 1502The current reschedule callback, or \f(CW0\fR, if this functionality is
1382switched off. Can be changed any time, but changes only take effect when 1503switched off. Can be changed any time, but changes only take effect when
1383the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. 1504the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called.
1505.IP "ev_tstamp at [read\-only]" 4
1506.IX Item "ev_tstamp at [read-only]"
1507When active, contains the absolute time that the watcher is supposed to
1508trigger next.
1384.PP 1509.PP
1385Example: Call a callback every hour, or, more precisely, whenever the 1510Example: Call a callback every hour, or, more precisely, whenever the
1386system clock is divisible by 3600. The callback invocation times have 1511system clock is divisible by 3600. The callback invocation times have
1387potentially a lot of jittering, but good long-term stability. 1512potentially a lot of jittering, but good long-term stability.
1388.PP 1513.PP
… …
1697.PP 1822.PP
1698It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) 1823It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR)
1699priority, to ensure that they are being run before any other watchers 1824priority, to ensure that they are being run before any other watchers
1700after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, 1825after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers,
1701too) should not activate (\*(L"feed\*(R") events into libev. While libev fully 1826too) should not activate (\*(L"feed\*(R") events into libev. While libev fully
1702supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers did 1827supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers
1703their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other event 1828did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other
1704loops those other event loops might be in an unusable state until their 1829(non\-libev) event loops those other event loops might be in an unusable
1705\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with 1830state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to
1706others). 1831coexist peacefully with others).
1707.PP 1832.PP
1708\fIWatcher-Specific Functions and Data Members\fR 1833\fIWatcher-Specific Functions and Data Members\fR
1709.IX Subsection "Watcher-Specific Functions and Data Members" 1834.IX Subsection "Watcher-Specific Functions and Data Members"
1710.IP "ev_prepare_init (ev_prepare *, callback)" 4 1835.IP "ev_prepare_init (ev_prepare *, callback)" 4
1711.IX Item "ev_prepare_init (ev_prepare *, callback)" 1836.IX Item "ev_prepare_init (ev_prepare *, callback)"
… …
1980.IP "ev_embed_sweep (loop, ev_embed *)" 4 2105.IP "ev_embed_sweep (loop, ev_embed *)" 4
1981.IX Item "ev_embed_sweep (loop, ev_embed *)" 2106.IX Item "ev_embed_sweep (loop, ev_embed *)"
1982Make a single, non-blocking sweep over the embedded loop. This works 2107Make a single, non-blocking sweep over the embedded loop. This works
1983similarly to \f(CW\*(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\*(C'\fR, but in the most 2108similarly to \f(CW\*(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\*(C'\fR, but in the most
1984apropriate way for embedded loops. 2109apropriate way for embedded loops.
1985.IP "struct ev_loop *loop [read\-only]" 4 2110.IP "struct ev_loop *other [read\-only]" 4
1986.IX Item "struct ev_loop *loop [read-only]" 2111.IX Item "struct ev_loop *other [read-only]"
1987The embedded event loop. 2112The embedded event loop.
1988.ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork" 2113.ie n .Sh """ev_fork"" \- the audacity to resume the event loop after a fork"
1989.el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" 2114.el .Sh "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork"
1990.IX Subsection "ev_fork - the audacity to resume the event loop after a fork" 2115.IX Subsection "ev_fork - the audacity to resume the event loop after a fork"
1991Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because 2116Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
… …
1993\&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the 2118\&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the
1994event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, 2119event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called,
1995and only in the child after the fork. If whoever good citizen calling 2120and only in the child after the fork. If whoever good citizen calling
1996\&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork 2121\&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork
1997handlers will be invoked, too, of course. 2122handlers will be invoked, too, of course.
2123.PP
2124\fIWatcher-Specific Functions and Data Members\fR
2125.IX Subsection "Watcher-Specific Functions and Data Members"
1998.IP "ev_fork_init (ev_signal *, callback)" 4 2126.IP "ev_fork_init (ev_signal *, callback)" 4
1999.IX Item "ev_fork_init (ev_signal *, callback)" 2127.IX Item "ev_fork_init (ev_signal *, callback)"
2000Initialises and configures the fork watcher \- it has no parameters of any 2128Initialises and configures the fork watcher \- it has no parameters of any
2001kind. There is a \f(CW\*(C`ev_fork_set\*(C'\fR macro, but using it is utterly pointless, 2129kind. There is a \f(CW\*(C`ev_fork_set\*(C'\fR macro, but using it is utterly pointless,
2002believe me. 2130believe me.
… …
2196Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 2324Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
2197constructor already stores the event loop. 2325constructor already stores the event loop.
2198.IP "w\->stop ()" 4 2326.IP "w\->stop ()" 4
2199.IX Item "w->stop ()" 2327.IX Item "w->stop ()"
2200Stops the watcher if it is active. Again, no \f(CW\*(C`loop\*(C'\fR argument. 2328Stops the watcher if it is active. Again, no \f(CW\*(C`loop\*(C'\fR argument.
2201.ie n .IP "w\->again () ""ev::timer""\fR, \f(CW""ev::periodic"" only" 4 2329.ie n .IP "w\->again () (""ev::timer""\fR, \f(CW""ev::periodic"" only)" 4
2202.el .IP "w\->again () \f(CWev::timer\fR, \f(CWev::periodic\fR only" 4 2330.el .IP "w\->again () (\f(CWev::timer\fR, \f(CWev::periodic\fR only)" 4
2203.IX Item "w->again () ev::timer, ev::periodic only" 2331.IX Item "w->again () (ev::timer, ev::periodic only)"
2204For \f(CW\*(C`ev::timer\*(C'\fR and \f(CW\*(C`ev::periodic\*(C'\fR, this invokes the corresponding 2332For \f(CW\*(C`ev::timer\*(C'\fR and \f(CW\*(C`ev::periodic\*(C'\fR, this invokes the corresponding
2205\&\f(CW\*(C`ev_TYPE_again\*(C'\fR function. 2333\&\f(CW\*(C`ev_TYPE_again\*(C'\fR function.
2206.ie n .IP "w\->sweep () ""ev::embed"" only" 4 2334.ie n .IP "w\->sweep () (""ev::embed"" only)" 4
2207.el .IP "w\->sweep () \f(CWev::embed\fR only" 4 2335.el .IP "w\->sweep () (\f(CWev::embed\fR only)" 4
2208.IX Item "w->sweep () ev::embed only" 2336.IX Item "w->sweep () (ev::embed only)"
2209Invokes \f(CW\*(C`ev_embed_sweep\*(C'\fR. 2337Invokes \f(CW\*(C`ev_embed_sweep\*(C'\fR.
2210.ie n .IP "w\->update () ""ev::stat"" only" 4 2338.ie n .IP "w\->update () (""ev::stat"" only)" 4
2211.el .IP "w\->update () \f(CWev::stat\fR only" 4 2339.el .IP "w\->update () (\f(CWev::stat\fR only)" 4
2212.IX Item "w->update () ev::stat only" 2340.IX Item "w->update () (ev::stat only)"
2213Invokes \f(CW\*(C`ev_stat_stat\*(C'\fR. 2341Invokes \f(CW\*(C`ev_stat_stat\*(C'\fR.
2214.RE 2342.RE
2215.RS 4 2343.RS 4
2216.RE 2344.RE
2217.PP 2345.PP
… …
2241\& io.start (fd, ev::READ); 2369\& io.start (fd, ev::READ);
2242\& } 2370\& }
2243.Ve 2371.Ve
2244.SH "MACRO MAGIC" 2372.SH "MACRO MAGIC"
2245.IX Header "MACRO MAGIC" 2373.IX Header "MACRO MAGIC"
2246Libev can be compiled with a variety of options, the most fundemantal is 2374Libev can be compiled with a variety of options, the most fundamantal
2247\&\f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) functions and 2375of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
2248callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 2376functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
2249.PP 2377.PP
2250To make it easier to write programs that cope with either variant, the 2378To make it easier to write programs that cope with either variant, the
2251following macros are defined: 2379following macros are defined:
2252.ie n .IP """EV_A""\fR, \f(CW""EV_A_""" 4 2380.ie n .IP """EV_A""\fR, \f(CW""EV_A_""" 4
2253.el .IP "\f(CWEV_A\fR, \f(CWEV_A_\fR" 4 2381.el .IP "\f(CWEV_A\fR, \f(CWEV_A_\fR" 4
… …
2312Libev can (and often is) directly embedded into host 2440Libev can (and often is) directly embedded into host
2313applications. Examples of applications that embed it include the Deliantra 2441applications. Examples of applications that embed it include the Deliantra
2314Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe) 2442Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe)
2315and rxvt\-unicode. 2443and rxvt\-unicode.
2316.PP 2444.PP
2317The goal is to enable you to just copy the neecssary files into your 2445The goal is to enable you to just copy the necessary files into your
2318source directory without having to change even a single line in them, so 2446source directory without having to change even a single line in them, so
2319you can easily upgrade by simply copying (or having a checked-out copy of 2447you can easily upgrade by simply copying (or having a checked-out copy of
2320libev somewhere in your source tree). 2448libev somewhere in your source tree).
2321.Sh "\s-1FILESETS\s0" 2449.Sh "\s-1FILESETS\s0"
2322.IX Subsection "FILESETS" 2450.IX Subsection "FILESETS"
… …
2427.IX Item "EV_USE_MONOTONIC" 2555.IX Item "EV_USE_MONOTONIC"
2428If defined to be \f(CW1\fR, libev will try to detect the availability of the 2556If defined to be \f(CW1\fR, libev will try to detect the availability of the
2429monotonic clock option at both compiletime and runtime. Otherwise no use 2557monotonic clock option at both compiletime and runtime. Otherwise no use
2430of the monotonic clock option will be attempted. If you enable this, you 2558of the monotonic clock option will be attempted. If you enable this, you
2431usually have to link against librt or something similar. Enabling it when 2559usually have to link against librt or something similar. Enabling it when
2432the functionality isn't available is safe, though, althoguh you have 2560the functionality isn't available is safe, though, although you have
2433to make sure you link against any libraries where the \f(CW\*(C`clock_gettime\*(C'\fR 2561to make sure you link against any libraries where the \f(CW\*(C`clock_gettime\*(C'\fR
2434function is hiding in (often \fI\-lrt\fR). 2562function is hiding in (often \fI\-lrt\fR).
2435.IP "\s-1EV_USE_REALTIME\s0" 4 2563.IP "\s-1EV_USE_REALTIME\s0" 4
2436.IX Item "EV_USE_REALTIME" 2564.IX Item "EV_USE_REALTIME"
2437If defined to be \f(CW1\fR, libev will try to detect the availability of the 2565If defined to be \f(CW1\fR, libev will try to detect the availability of the
2438realtime clock option at compiletime (and assume its availability at 2566realtime clock option at compiletime (and assume its availability at
2439runtime if successful). Otherwise no use of the realtime clock option will 2567runtime if successful). Otherwise no use of the realtime clock option will
2440be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get 2568be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get
2441(CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See tzhe note about libraries 2569(CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the
2442in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. 2570note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though.
2571.IP "\s-1EV_USE_NANOSLEEP\s0" 4
2572.IX Item "EV_USE_NANOSLEEP"
2573If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
2574and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
2443.IP "\s-1EV_USE_SELECT\s0" 4 2575.IP "\s-1EV_USE_SELECT\s0" 4
2444.IX Item "EV_USE_SELECT" 2576.IX Item "EV_USE_SELECT"
2445If undefined or defined to be \f(CW1\fR, libev will compile in support for the 2577If undefined or defined to be \f(CW1\fR, libev will compile in support for the
2446\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no 2578\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no
2447other method takes over, select will be it. Otherwise the select backend 2579other method takes over, select will be it. Otherwise the select backend
… …
2607.IP "ev_set_cb (ev, cb)" 4 2739.IP "ev_set_cb (ev, cb)" 4
2608.IX Item "ev_set_cb (ev, cb)" 2740.IX Item "ev_set_cb (ev, cb)"
2609.PD 2741.PD
2610Can be used to change the callback member declaration in each watcher, 2742Can be used to change the callback member declaration in each watcher,
2611and the way callbacks are invoked and set. Must expand to a struct member 2743and the way callbacks are invoked and set. Must expand to a struct member
2612definition and a statement, respectively. See the \fIev.v\fR header file for 2744definition and a statement, respectively. See the \fIev.h\fR header file for
2613their default definitions. One possible use for overriding these is to 2745their default definitions. One possible use for overriding these is to
2614avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 2746avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
2615method calls instead of plain function calls in \*(C+. 2747method calls instead of plain function calls in \*(C+.
2748.Sh "\s-1EXPORTED\s0 \s-1API\s0 \s-1SYMBOLS\s0"
2749.IX Subsection "EXPORTED API SYMBOLS"
2750If you need to re-export the \s-1API\s0 (e.g. via a dll) and you need a list of
2751exported symbols, you can use the provided \fISymbol.*\fR files which list
2752all public symbols, one per line:
2753.Sp
2754.Vb 2
2755\& Symbols.ev for libev proper
2756\& Symbols.event for the libevent emulation
2757.Ve
2758.Sp
2759This can also be used to rename all public symbols to avoid clashes with
2760multiple versions of libev linked together (which is obviously bad in
2761itself, but sometimes it is inconvinient to avoid this).
2762.Sp
2763A sed command like this will create wrapper \f(CW\*(C`#define\*(C'\fR's that you need to
2764include before including \fIev.h\fR:
2765.Sp
2766.Vb 1
2767\& <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
2768.Ve
2769.Sp
2770This would create a file \fIwrap.h\fR which essentially looks like this:
2771.Sp
2772.Vb 4
2773\& #define ev_backend myprefix_ev_backend
2774\& #define ev_check_start myprefix_ev_check_start
2775\& #define ev_check_stop myprefix_ev_check_stop
2776\& ...
2777.Ve
2616.Sh "\s-1EXAMPLES\s0" 2778.Sh "\s-1EXAMPLES\s0"
2617.IX Subsection "EXAMPLES" 2779.IX Subsection "EXAMPLES"
2618For a real-world example of a program the includes libev 2780For a real-world example of a program the includes libev
2619verbatim, you can have a look at the \s-1EV\s0 perl module 2781verbatim, you can have a look at the \s-1EV\s0 perl module
2620(<http://software.schmorp.de/pkg/EV.html>). It has the libev files in 2782(<http://software.schmorp.de/pkg/EV.html>). It has the libev files in

Diff Legend

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