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

Comparing libev/ev.3 (file contents):
Revision 1.62 by root, Sun Mar 16 16:38:23 2008 UTC vs.
Revision 1.67 by root, Fri May 23 16:43:45 2008 UTC

… …
129. ds Ae AE 129. ds Ae AE
130.\} 130.\}
131.rm #[ #] #H #V #F C 131.rm #[ #] #H #V #F C
132.\" ======================================================================== 132.\" ========================================================================
133.\" 133.\"
134.IX Title "EV 1" 134.IX Title "LIBEV 3"
135.TH EV 1 "2008-03-13" "perl v5.10.0" "User Contributed Perl Documentation" 135.TH LIBEV 3 "2008-05-22" "libev-3.41" "libev - high perfromance full featured event loop"
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes 136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents. 137.\" way too many mistakes in technical documents.
138.if n .ad l 138.if n .ad l
139.nh 139.nh
140.SH "NAME" 140.SH "NAME"
… …
203.Ve 203.Ve
204.SH "DESCRIPTION" 204.SH "DESCRIPTION"
205.IX Header "DESCRIPTION" 205.IX Header "DESCRIPTION"
206The newest version of this document is also available as an html-formatted 206The newest version of this document is also available as an html-formatted
207web page you might find easier to navigate when reading it for the first 207web page you might find easier to navigate when reading it for the first
208time: <http://cvs.schmorp.de/libev/ev.html>. 208time: <http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
209.PP 209.PP
210Libev is an event loop: you register interest in certain events (such as a 210Libev is an event loop: you register interest in certain events (such as a
211file descriptor being readable or a timeout occurring), and it will manage 211file descriptor being readable or a timeout occurring), and it will manage
212these event sources and provide your program with events. 212these event sources and provide your program with events.
213.PP 213.PP
… …
252called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use too. It usually aliases 252called \f(CW\*(C`ev_tstamp\*(C'\fR, which is what you should use too. It usually aliases
253to the \f(CW\*(C`double\*(C'\fR type in C, and when you need to do any calculations on 253to the \f(CW\*(C`double\*(C'\fR type in C, and when you need to do any calculations on
254it, you should treat it as some floatingpoint value. Unlike the name 254it, you should treat it as some floatingpoint value. Unlike the name
255component \f(CW\*(C`stamp\*(C'\fR might indicate, it is also used for time differences 255component \f(CW\*(C`stamp\*(C'\fR might indicate, it is also used for time differences
256throughout libev. 256throughout libev.
257.SH "ERROR HANDLING"
258.IX Header "ERROR HANDLING"
259Libev knows three classes of errors: operating system errors, usage errors
260and internal errors (bugs).
261.PP
262When libev catches an operating system error it cannot handle (for example
263a syscall indicating a condition libev cannot fix), it calls the callback
264set via \f(CW\*(C`ev_set_syserr_cb\*(C'\fR, which is supposed to fix the problem or
265abort. The default is to print a diagnostic message and to call \f(CW\*(C`abort
266()\*(C'\fR.
267.PP
268When libev detects a usage error such as a negative timer interval, then
269it will print a diagnostic message and abort (via the \f(CW\*(C`assert\*(C'\fR mechanism,
270so \f(CW\*(C`NDEBUG\*(C'\fR will disable this checking): these are programming errors in
271the libev caller and need to be fixed there.
272.PP
273Libev also has a few internal error-checking \f(CW\*(C`assert\*(C'\fRions, and also has
274extensive consistency checking code. These do not trigger under normal
275circumstances, as they indicate either a bug in libev or worse.
257.SH "GLOBAL FUNCTIONS" 276.SH "GLOBAL FUNCTIONS"
258.IX Header "GLOBAL FUNCTIONS" 277.IX Header "GLOBAL FUNCTIONS"
259These functions can be called anytime, even before initialising the 278These functions can be called anytime, even before initialising the
260library in any way. 279library in any way.
261.IP "ev_tstamp ev_time ()" 4 280.IP "ev_tstamp ev_time ()" 4
… …
328.Sp 347.Sp
329See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 348See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
330.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 349.IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4
331.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" 350.IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))"
332Sets the allocation function to use (the prototype is similar \- the 351Sets the allocation function to use (the prototype is similar \- the
333semantics is identical \- to the realloc C function). It is used to 352semantics are identical to the \f(CW\*(C`realloc\*(C'\fR C89/SuS/POSIX function). It is
334allocate and free memory (no surprises here). If it returns zero when 353used to allocate and free memory (no surprises here). If it returns zero
335memory needs to be allocated, the library might abort or take some 354when memory needs to be allocated (\f(CW\*(C`size != 0\*(C'\fR), the library might abort
336potentially destructive action. The default is your system realloc 355or take some potentially destructive action.
337function. 356.Sp
357Since some systems (at least OpenBSD and Darwin) fail to implement
358correct \f(CW\*(C`realloc\*(C'\fR semantics, libev will use a wrapper around the system
359\&\f(CW\*(C`realloc\*(C'\fR and \f(CW\*(C`free\*(C'\fR functions by default.
338.Sp 360.Sp
339You could override this function in high-availability programs to, say, 361You could override this function in high-availability programs to, say,
340free some memory if it cannot allocate memory, to use a special allocator, 362free some memory if it cannot allocate memory, to use a special allocator,
341or even to sleep a while and retry until some memory is available. 363or even to sleep a while and retry until some memory is available.
342.Sp 364.Sp
343Example: Replace the libev allocator with one that waits a bit and then 365Example: Replace the libev allocator with one that waits a bit and then
344retries). 366retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR).
345.Sp 367.Sp
346.Vb 6 368.Vb 6
347\& static void * 369\& static void *
348\& persistent_realloc (void *ptr, size_t size) 370\& persistent_realloc (void *ptr, size_t size)
349\& { 371\& {
… …
387.SH "FUNCTIONS CONTROLLING THE EVENT LOOP" 409.SH "FUNCTIONS CONTROLLING THE EVENT LOOP"
388.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP" 410.IX Header "FUNCTIONS CONTROLLING THE EVENT LOOP"
389An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two 411An event loop is described by a \f(CW\*(C`struct ev_loop *\*(C'\fR. The library knows two
390types of such loops, the \fIdefault\fR loop, which supports signals and child 412types of such loops, the \fIdefault\fR loop, which supports signals and child
391events, and dynamically created loops which do not. 413events, and dynamically created loops which do not.
392.PP
393If you use threads, a common model is to run the default event loop
394in your main thread (or in a separate thread) and for each thread you
395create, you also create another event loop. Libev itself does no locking
396whatsoever, so if you mix calls to the same event loop in different
397threads, make sure you lock (this is usually a bad idea, though, even if
398done correctly, because it's hideous and inefficient).
399.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4 414.IP "struct ev_loop *ev_default_loop (unsigned int flags)" 4
400.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)" 415.IX Item "struct ev_loop *ev_default_loop (unsigned int flags)"
401This will initialise the default event loop if it hasn't been initialised 416This will initialise the default event loop if it hasn't been initialised
402yet and return it. If the default loop could not be initialised, returns 417yet and return it. If the default loop could not be initialised, returns
403false. If it already was initialised it simply returns it (and ignores the 418false. If it already was initialised it simply returns it (and ignores the
404flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards). 419flags. If that is troubling you, check \f(CW\*(C`ev_backend ()\*(C'\fR afterwards).
405.Sp 420.Sp
406If you don't know what event loop to use, use the one returned from this 421If you don't know what event loop to use, use the one returned from this
407function. 422function.
423.Sp
424Note that this function is \fInot\fR thread-safe, so if you want to use it
425from multiple threads, you have to lock (note also that this is unlikely,
426as loops cannot bes hared easily between threads anyway).
408.Sp 427.Sp
409The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and 428The default loop is the only loop that can handle \f(CW\*(C`ev_signal\*(C'\fR and
410\&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler 429\&\f(CW\*(C`ev_child\*(C'\fR watchers, and to do this, it always registers a handler
411for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your app you can either 430for \f(CW\*(C`SIGCHLD\*(C'\fR. If this is a problem for your app you can either
412create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you 431create a dynamic loop with \f(CW\*(C`ev_loop_new\*(C'\fR that doesn't do that, or you
… …
464To get good performance out of this backend you need a high amount of 483To get good performance out of this backend you need a high amount of
465parallelity (most of the file descriptors should be busy). If you are 484parallelity (most of the file descriptors should be busy). If you are
466writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many 485writing a server, you should \f(CW\*(C`accept ()\*(C'\fR in a loop to accept as many
467connections as possible during one iteration. You might also want to have 486connections as possible during one iteration. You might also want to have
468a look at \f(CW\*(C`ev_set_io_collect_interval ()\*(C'\fR to increase the amount of 487a look at \f(CW\*(C`ev_set_io_collect_interval ()\*(C'\fR to increase the amount of
469readyness notifications you get per iteration. 488readiness notifications you get per iteration.
470.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 489.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
471.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 490.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
472.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" 491.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
473And this is your standard \fIpoll\fR\|(2) backend. It's more complicated 492And this is your standard \fIpoll\fR\|(2) backend. It's more complicated
474than select, but handles sparse fds better and has no artificial 493than select, but handles sparse fds better and has no artificial
… …
482For few fds, this backend is a bit little slower than poll and select, 501For few fds, this backend is a bit little slower than poll and select,
483but it scales phenomenally better. While poll and select usually scale 502but it scales phenomenally better. While poll and select usually scale
484like O(total_fds) where n is the total number of fds (or the highest fd), 503like O(total_fds) where n is the total number of fds (or the highest fd),
485epoll scales either O(1) or O(active_fds). The epoll design has a number 504epoll scales either O(1) or O(active_fds). The epoll design has a number
486of shortcomings, such as silently dropping events in some hard-to-detect 505of shortcomings, such as silently dropping events in some hard-to-detect
487cases and rewiring a syscall per fd change, no fork support and bad 506cases and requiring a syscall per fd change, no fork support and bad
488support for dup. 507support for dup.
489.Sp 508.Sp
490While stopping, setting and starting an I/O watcher in the same iteration 509While stopping, setting and starting an I/O watcher in the same iteration
491will result in some caching, there is still a syscall per such incident 510will result in some caching, there is still a syscall per such incident
492(because the fd could point to a different file description now), so its 511(because the fd could point to a different file description now), so its
… …
553While this backend scales well, it requires one system call per active 572While this backend scales well, it requires one system call per active
554file descriptor per loop iteration. For small and medium numbers of file 573file descriptor per loop iteration. For small and medium numbers of file
555descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend 574descriptors a \*(L"slow\*(R" \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR backend
556might perform better. 575might perform better.
557.Sp 576.Sp
558On the positive side, ignoring the spurious readyness notifications, this 577On the positive side, ignoring the spurious readiness notifications, this
559backend actually performed to specification in all tests and is fully 578backend actually performed to specification in all tests and is fully
560embeddable, which is a rare feat among the OS-specific backends. 579embeddable, which is a rare feat among the OS-specific backends.
561.ie n .IP """EVBACKEND_ALL""" 4 580.ie n .IP """EVBACKEND_ALL""" 4
562.el .IP "\f(CWEVBACKEND_ALL\fR" 4 581.el .IP "\f(CWEVBACKEND_ALL\fR" 4
563.IX Item "EVBACKEND_ALL" 582.IX Item "EVBACKEND_ALL"
… …
599.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" 618.IX Item "struct ev_loop *ev_loop_new (unsigned int flags)"
600Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is 619Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is
601always distinct from the default loop. Unlike the default loop, it cannot 620always distinct from the default loop. Unlike the default loop, it cannot
602handle signal and child watchers, and attempts to do so will be greeted by 621handle signal and child watchers, and attempts to do so will be greeted by
603undefined behaviour (or a failed assertion if assertions are enabled). 622undefined behaviour (or a failed assertion if assertions are enabled).
623.Sp
624Note that this function \fIis\fR thread-safe, and the recommended way to use
625libev with threads is indeed to create one loop per thread, and using the
626default loop in the \*(L"main\*(R" or \*(L"initial\*(R" thread.
604.Sp 627.Sp
605Example: Try to create a event loop that uses epoll and nothing else. 628Example: Try to create a event loop that uses epoll and nothing else.
606.Sp 629.Sp
607.Vb 3 630.Vb 3
608\& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 631\& struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
… …
822Many (busy) programs can usually benefit by setting the io collect 845Many (busy) programs can usually benefit by setting the io collect
823interval to a value near \f(CW0.1\fR or so, which is often enough for 846interval to a value near \f(CW0.1\fR or so, which is often enough for
824interactive servers (of course not for games), likewise for timeouts. It 847interactive servers (of course not for games), likewise for timeouts. It
825usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR, 848usually doesn't make much sense to set it to a lower value than \f(CW0.01\fR,
826as this approsaches the timing granularity of most systems. 849as this approsaches the timing granularity of most systems.
850.IP "ev_loop_verify (loop)" 4
851.IX Item "ev_loop_verify (loop)"
852This function only does something when \f(CW\*(C`EV_VERIFY\*(C'\fR support has been
853compiled in. It tries to go through all internal structures and checks
854them for validity. If anything is found to be inconsistent, it will print
855an error message to standard error and call \f(CW\*(C`abort ()\*(C'\fR.
856.Sp
857This can be used to catch bugs inside libev itself: under normal
858circumstances, this function will never abort as of course libev keeps its
859data structures consistent.
827.SH "ANATOMY OF A WATCHER" 860.SH "ANATOMY OF A WATCHER"
828.IX Header "ANATOMY OF A WATCHER" 861.IX Header "ANATOMY OF A WATCHER"
829A watcher is a structure that you create and register to record your 862A watcher is a structure that you create and register to record your
830interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to 863interest in some event. For instance, if you want to wait for \s-1STDIN\s0 to
831become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that: 864become readable, you would create an \f(CW\*(C`ev_io\*(C'\fR watcher for that:
… …
1159If you must do this, then force the use of a known-to-be-good backend 1192If you must do this, then force the use of a known-to-be-good backend
1160(at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and 1193(at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and
1161\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR). 1194\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR).
1162.PP 1195.PP
1163Another thing you have to watch out for is that it is quite easy to 1196Another thing you have to watch out for is that it is quite easy to
1164receive \*(L"spurious\*(R" readyness notifications, that is your callback might 1197receive \*(L"spurious\*(R" readiness notifications, that is your callback might
1165be called with \f(CW\*(C`EV_READ\*(C'\fR but a subsequent \f(CW\*(C`read\*(C'\fR(2) will actually block 1198be called with \f(CW\*(C`EV_READ\*(C'\fR but a subsequent \f(CW\*(C`read\*(C'\fR(2) will actually block
1166because there is no data. Not only are some backends known to create a 1199because there is no data. Not only are some backends known to create a
1167lot of those (for example solaris ports), it is very easy to get into 1200lot of those (for example solaris ports), it is very easy to get into
1168this situation even with a relatively standard program structure. Thus 1201this situation even with a relatively standard program structure. Thus
1169it is best to always use non-blocking I/O: An extra \f(CW\*(C`read\*(C'\fR(2) returning 1202it is best to always use non-blocking I/O: An extra \f(CW\*(C`read\*(C'\fR(2) returning
… …
1218.PP 1251.PP
1219To support fork in your programs, you either have to call 1252To support fork in your programs, you either have to call
1220\&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child, 1253\&\f(CW\*(C`ev_default_fork ()\*(C'\fR or \f(CW\*(C`ev_loop_fork ()\*(C'\fR after a fork in the child,
1221enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or 1254enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or
1222\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1255\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1256.PP
1257\fIThe special problem of \s-1SIGPIPE\s0\fR
1258.IX Subsection "The special problem of SIGPIPE"
1259.PP
1260While not really specific to libev, it is easy to forget about \s-1SIGPIPE:\s0
1261when reading from a pipe whose other end has been closed, your program
1262gets send a \s-1SIGPIPE\s0, which, by default, aborts your program. For most
1263programs this is sensible behaviour, for daemons, this is usually
1264undesirable.
1265.PP
1266So when you encounter spurious, unexplained daemon exits, make sure you
1267ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1268somewhere, as that would have given you a big clue).
1223.PP 1269.PP
1224\fIWatcher-Specific Functions\fR 1270\fIWatcher-Specific Functions\fR
1225.IX Subsection "Watcher-Specific Functions" 1271.IX Subsection "Watcher-Specific Functions"
1226.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 1272.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4
1227.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" 1273.IX Item "ev_io_init (ev_io *, callback, int fd, int events)"
… …
1266.IX Subsection "ev_timer - relative and optionally repeating timeouts" 1312.IX Subsection "ev_timer - relative and optionally repeating timeouts"
1267Timer watchers are simple relative timers that generate an event after a 1313Timer watchers are simple relative timers that generate an event after a
1268given time, and optionally repeating in regular intervals after that. 1314given time, and optionally repeating in regular intervals after that.
1269.PP 1315.PP
1270The timers are based on real time, that is, if you register an event that 1316The timers are based on real time, that is, if you register an event that
1271times out after an hour and you reset your system clock to last years 1317times out after an hour and you reset your system clock to january last
1272time, it will still time out after (roughly) and hour. \*(L"Roughly\*(R" because 1318year, it will still time out after (roughly) and hour. \*(L"Roughly\*(R" because
1273detecting time jumps is hard, and some inaccuracies are unavoidable (the 1319detecting time jumps is hard, and some inaccuracies are unavoidable (the
1274monotonic clock option helps a lot here). 1320monotonic clock option helps a lot here).
1275.PP 1321.PP
1276The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR 1322The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
1277time. This is usually the right thing as this timestamp refers to the time 1323time. This is usually the right thing as this timestamp refers to the time
… …
1281.PP 1327.PP
1282.Vb 1 1328.Vb 1
1283\& ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.); 1329\& ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.);
1284.Ve 1330.Ve
1285.PP 1331.PP
1286The callback is guarenteed to be invoked only when its timeout has passed, 1332The callback is guarenteed to be invoked only after its timeout has passed,
1287but if multiple timers become ready during the same loop iteration then 1333but if multiple timers become ready during the same loop iteration then
1288order of execution is undefined. 1334order of execution is undefined.
1289.PP 1335.PP
1290\fIWatcher-Specific Functions and Data Members\fR 1336\fIWatcher-Specific Functions and Data Members\fR
1291.IX Subsection "Watcher-Specific Functions and Data Members" 1337.IX Subsection "Watcher-Specific Functions and Data Members"
… …
1293.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 1339.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
1294.PD 0 1340.PD 0
1295.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 1341.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
1296.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 1342.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
1297.PD 1343.PD
1298Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR is 1344Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR
1299\&\f(CW0.\fR, then it will automatically be stopped. If it is positive, then the 1345is \f(CW0.\fR, then it will automatically be stopped once the timeout is
1300timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds 1346reached. If it is positive, then the timer will automatically be
1301later, again, and again, until stopped manually. 1347configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again,
1348until stopped manually.
1302.Sp 1349.Sp
1303The timer itself will do a best-effort at avoiding drift, that is, if you 1350The timer itself will do a best-effort at avoiding drift, that is, if
1304configure a timer to trigger every 10 seconds, then it will trigger at 1351you configure a timer to trigger every 10 seconds, then it will normally
1305exactly 10 second intervals. If, however, your program cannot keep up with 1352trigger at exactly 10 second intervals. If, however, your program cannot
1306the timer (because it takes longer than those 10 seconds to do stuff) the 1353keep up with the timer (because it takes longer than those 10 seconds to
1307timer will not fire more than once per event loop iteration. 1354do stuff) the timer will not fire more than once per event loop iteration.
1308.IP "ev_timer_again (loop, ev_timer *)" 4 1355.IP "ev_timer_again (loop, ev_timer *)" 4
1309.IX Item "ev_timer_again (loop, ev_timer *)" 1356.IX Item "ev_timer_again (loop, ev_timer *)"
1310This will act as if the timer timed out and restart it again if it is 1357This will act as if the timer timed out and restart it again if it is
1311repeating. The exact semantics are: 1358repeating. The exact semantics are:
1312.Sp 1359.Sp
… …
1391Periodic watchers are also timers of a kind, but they are very versatile 1438Periodic watchers are also timers of a kind, but they are very versatile
1392(and unfortunately a bit complex). 1439(and unfortunately a bit complex).
1393.PP 1440.PP
1394Unlike \f(CW\*(C`ev_timer\*(C'\fR's, they are not based on real time (or relative time) 1441Unlike \f(CW\*(C`ev_timer\*(C'\fR's, they are not based on real time (or relative time)
1395but on wallclock time (absolute time). You can tell a periodic watcher 1442but on wallclock time (absolute time). You can tell a periodic watcher
1396to trigger \*(L"at\*(R" some specific point in time. For example, if you tell a 1443to trigger after some specific point in time. For example, if you tell a
1397periodic watcher to trigger in 10 seconds (by specifiying e.g. \f(CW\*(C`ev_now () 1444periodic watcher to trigger in 10 seconds (by specifiying e.g. \f(CW\*(C`ev_now ()
1398+ 10.\*(C'\fR) and then reset your system clock to the last year, then it will 1445+ 10.\*(C'\fR, that is, an absolute time not a delay) and then reset your system
1446clock to january of the previous year, then it will take more than year
1399take a year to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would trigger 1447to trigger the event (unlike an \f(CW\*(C`ev_timer\*(C'\fR, which would still trigger
1400roughly 10 seconds later). 1448roughly 10 seconds later as it uses a relative timeout).
1401.PP 1449.PP
1402They can also be used to implement vastly more complex timers, such as 1450\&\f(CW\*(C`ev_periodic\*(C'\fRs can also be used to implement vastly more complex timers,
1403triggering an event on each midnight, local time or other, complicated, 1451such as triggering an event on each \*(L"midnight, local time\*(R", or other
1404rules. 1452complicated, rules.
1405.PP 1453.PP
1406As with timers, the callback is guarenteed to be invoked only when the 1454As with timers, the callback is guarenteed to be invoked only when the
1407time (\f(CW\*(C`at\*(C'\fR) has been passed, but if multiple periodic timers become ready 1455time (\f(CW\*(C`at\*(C'\fR) has passed, but if multiple periodic timers become ready
1408during the same loop iteration then order of execution is undefined. 1456during the same loop iteration then order of execution is undefined.
1409.PP 1457.PP
1410\fIWatcher-Specific Functions and Data Members\fR 1458\fIWatcher-Specific Functions and Data Members\fR
1411.IX Subsection "Watcher-Specific Functions and Data Members" 1459.IX Subsection "Watcher-Specific Functions and Data Members"
1412.IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4 1460.IP "ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)" 4
… …
1419operation, and we will explain them from simplest to complex: 1467operation, and we will explain them from simplest to complex:
1420.RS 4 1468.RS 4
1421.IP "\(bu" 4 1469.IP "\(bu" 4
1422absolute timer (at = time, interval = reschedule_cb = 0) 1470absolute timer (at = time, interval = reschedule_cb = 0)
1423.Sp 1471.Sp
1424In this configuration the watcher triggers an event at the wallclock time 1472In this configuration the watcher triggers an event after the wallclock
1425\&\f(CW\*(C`at\*(C'\fR and doesn't repeat. It will not adjust when a time jump occurs, 1473time \f(CW\*(C`at\*(C'\fR has passed and doesn't repeat. It will not adjust when a time
1426that is, if it is to be run at January 1st 2011 then it will run when the 1474jump occurs, that is, if it is to be run at January 1st 2011 then it will
1427system time reaches or surpasses this time. 1475run when the system time reaches or surpasses this time.
1428.IP "\(bu" 4 1476.IP "\(bu" 4
1429repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1477repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1430.Sp 1478.Sp
1431In this mode the watcher will always be scheduled to time out at the next 1479In this mode the watcher will always be scheduled to time out at the next
1432\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative) 1480\&\f(CW\*(C`at + N * interval\*(C'\fR time (for some integer N, which can also be negative)
1433and then repeat, regardless of any time jumps. 1481and then repeat, regardless of any time jumps.
1434.Sp 1482.Sp
1435This can be used to create timers that do not drift with respect to system 1483This can be used to create timers that do not drift with respect to system
1436time: 1484time, for example, here is a \f(CW\*(C`ev_periodic\*(C'\fR that triggers each hour, on
1485the hour:
1437.Sp 1486.Sp
1438.Vb 1 1487.Vb 1
1439\& ev_periodic_set (&periodic, 0., 3600., 0); 1488\& ev_periodic_set (&periodic, 0., 3600., 0);
1440.Ve 1489.Ve
1441.Sp 1490.Sp
… …
1448\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible 1497\&\f(CW\*(C`ev_periodic\*(C'\fR will try to run the callback in this mode at the next possible
1449time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps. 1498time where \f(CW\*(C`time = at (mod interval)\*(C'\fR, regardless of any time jumps.
1450.Sp 1499.Sp
1451For numerical stability it is preferable that the \f(CW\*(C`at\*(C'\fR value is near 1500For numerical stability it is preferable that the \f(CW\*(C`at\*(C'\fR value is near
1452\&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for 1501\&\f(CW\*(C`ev_now ()\*(C'\fR (the current time), but there is no range requirement for
1453this value. 1502this value, and in fact is often specified as zero.
1503.Sp
1504Note also that there is an upper limit to how often a timer can fire (cpu
1505speed for example), so if \f(CW\*(C`interval\*(C'\fR is very small then timing stability
1506will of course detoriate. Libev itself tries to be exact to be about one
1507millisecond (if the \s-1OS\s0 supports it and the machine is fast enough).
1454.IP "\(bu" 4 1508.IP "\(bu" 4
1455manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1509manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1456.Sp 1510.Sp
1457In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being 1511In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`at\*(C'\fR are both being
1458ignored. Instead, each time the periodic watcher gets scheduled, the 1512ignored. Instead, each time the periodic watcher gets scheduled, the
1459reschedule callback will be called with the watcher as first, and the 1513reschedule callback will be called with the watcher as first, and the
1460current time as second argument. 1514current time as second argument.
1461.Sp 1515.Sp
1462\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher, 1516\&\s-1NOTE:\s0 \fIThis callback \s-1MUST\s0 \s-1NOT\s0 stop or destroy any periodic watcher,
1463ever, or make any event loop modifications\fR. If you need to stop it, 1517ever, or make \s-1ANY\s0 event loop modifications whatsoever\fR.
1464return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop it afterwards (e.g. by 1518.Sp
1519If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
1465starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is legal). 1520it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
1521only event loop modification you are allowed to do).
1466.Sp 1522.Sp
1467Its prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 1523The callback prototype is \f(CW\*(C`ev_tstamp (*reschedule_cb)(struct ev_periodic
1468ev_tstamp now)\*(C'\fR, e.g.: 1524*w, ev_tstamp now)\*(C'\fR, e.g.:
1469.Sp 1525.Sp
1470.Vb 4 1526.Vb 4
1471\& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1527\& static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
1472\& { 1528\& {
1473\& return now + 60.; 1529\& return now + 60.;
… …
1477It must return the next time to trigger, based on the passed time value 1533It must return the next time to trigger, based on the passed time value
1478(that is, the lowest time value larger than to the second argument). It 1534(that is, the lowest time value larger than to the second argument). It
1479will usually be called just before the callback will be triggered, but 1535will usually be called just before the callback will be triggered, but
1480might be called at other times, too. 1536might be called at other times, too.
1481.Sp 1537.Sp
1482\&\s-1NOTE:\s0 \fIThis callback must always return a time that is later than the 1538\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
1483passed \f(CI\*(C`now\*(C'\fI value\fR. Not even \f(CW\*(C`now\*(C'\fR itself will do, it \fImust\fR be larger. 1539equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
1484.Sp 1540.Sp
1485This can be used to create very complex timers, such as a timer that 1541This can be used to create very complex timers, such as a timer that
1486triggers on each midnight, local time. To do this, you would calculate the 1542triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the
1487next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How 1543next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How
1488you do this is, again, up to you (but it is not trivial, which is the main 1544you do this is, again, up to you (but it is not trivial, which is the main
1489reason I omitted it as an example). 1545reason I omitted it as an example).
1490.RE 1546.RE
1491.RS 4 1547.RS 4
… …
1494.IX Item "ev_periodic_again (loop, ev_periodic *)" 1550.IX Item "ev_periodic_again (loop, ev_periodic *)"
1495Simply stops and restarts the periodic watcher again. This is only useful 1551Simply stops and restarts the periodic watcher again. This is only useful
1496when you changed some parameters or the reschedule callback would return 1552when you changed some parameters or the reschedule callback would return
1497a different time than the last time it was called (e.g. in a crond like 1553a different time than the last time it was called (e.g. in a crond like
1498program when the crontabs have changed). 1554program when the crontabs have changed).
1555.IP "ev_tstamp ev_periodic_at (ev_periodic *)" 4
1556.IX Item "ev_tstamp ev_periodic_at (ev_periodic *)"
1557When active, returns the absolute time that the watcher is supposed to
1558trigger next.
1499.IP "ev_tstamp offset [read\-write]" 4 1559.IP "ev_tstamp offset [read\-write]" 4
1500.IX Item "ev_tstamp offset [read-write]" 1560.IX Item "ev_tstamp offset [read-write]"
1501When repeating, this contains the offset value, otherwise this is the 1561When repeating, this contains the offset value, otherwise this is the
1502absolute point in time (the \f(CW\*(C`at\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR). 1562absolute point in time (the \f(CW\*(C`at\*(C'\fR value passed to \f(CW\*(C`ev_periodic_set\*(C'\fR).
1503.Sp 1563.Sp
… …
1511.IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4 1571.IP "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read\-write]" 4
1512.IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]" 1572.IX Item "ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]"
1513The current reschedule callback, or \f(CW0\fR, if this functionality is 1573The current reschedule callback, or \f(CW0\fR, if this functionality is
1514switched off. Can be changed any time, but changes only take effect when 1574switched off. Can be changed any time, but changes only take effect when
1515the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called. 1575the periodic timer fires or \f(CW\*(C`ev_periodic_again\*(C'\fR is being called.
1516.IP "ev_tstamp at [read\-only]" 4
1517.IX Item "ev_tstamp at [read-only]"
1518When active, contains the absolute time that the watcher is supposed to
1519trigger next.
1520.PP 1576.PP
1521\fIExamples\fR 1577\fIExamples\fR
1522.IX Subsection "Examples" 1578.IX Subsection "Examples"
1523.PP 1579.PP
1524Example: Call a callback every hour, or, more precisely, whenever the 1580Example: Call a callback every hour, or, more precisely, whenever the
… …
1730as even with OS-supported change notifications, this can be 1786as even with OS-supported change notifications, this can be
1731resource-intensive. 1787resource-intensive.
1732.PP 1788.PP
1733At the time of this writing, only the Linux inotify interface is 1789At the time of this writing, only the Linux inotify interface is
1734implemented (implementing kqueue support is left as an exercise for the 1790implemented (implementing kqueue support is left as an exercise for the
1791reader, note, however, that the author sees no way of implementing ev_stat
1735reader). Inotify will be used to give hints only and should not change the 1792semantics with kqueue). Inotify will be used to give hints only and should
1736semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev sometimes needs 1793not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers, which means that libev
1737to fall back to regular polling again even with inotify, but changes are 1794sometimes needs to fall back to regular polling again even with inotify,
1738usually detected immediately, and if the file exists there will be no 1795but changes are usually detected immediately, and if the file exists there
1739polling. 1796will be no polling.
1797.PP
1798\fI\s-1ABI\s0 Issues (Largefile Support)\fR
1799.IX Subsection "ABI Issues (Largefile Support)"
1800.PP
1801Libev by default (unless the user overrides this) uses the default
1802compilation environment, which means that on systems with optionally
1803disabled large file support, you get the 32 bit version of the stat
1804structure. When using the library from programs that change the \s-1ABI\s0 to
1805use 64 bit file offsets the programs will fail. In that case you have to
1806compile libev with the same flags to get binary compatibility. This is
1807obviously the case with any flags that change the \s-1ABI\s0, but the problem is
1808most noticably with ev_stat and largefile support.
1740.PP 1809.PP
1741\fIInotify\fR 1810\fIInotify\fR
1742.IX Subsection "Inotify" 1811.IX Subsection "Inotify"
1743.PP 1812.PP
1744When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only 1813When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only
1745available on Linux) and present at runtime, it will be used to speed up 1814available on Linux) and present at runtime, it will be used to speed up
1746change detection where possible. The inotify descriptor will be created lazily 1815change detection where possible. The inotify descriptor will be created lazily
1747when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started. 1816when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started.
1748.PP 1817.PP
1749Inotify presense does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers 1818Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers
1750except that changes might be detected earlier, and in some cases, to avoid 1819except that changes might be detected earlier, and in some cases, to avoid
1751making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presense of inotify support 1820making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support
1752there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling. 1821there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling.
1753.PP 1822.PP
1754(There is no support for kqueue, as apparently it cannot be used to 1823(There is no support for kqueue, as apparently it cannot be used to
1755implement this functionality, due to the requirement of having a file 1824implement this functionality, due to the requirement of having a file
1756descriptor open on the object at all times). 1825descriptor open on the object at all times).
… …
1760.PP 1829.PP
1761The \f(CW\*(C`stat ()\*(C'\fR syscall only supports full-second resolution portably, and 1830The \f(CW\*(C`stat ()\*(C'\fR syscall only supports full-second resolution portably, and
1762even on systems where the resolution is higher, many filesystems still 1831even on systems where the resolution is higher, many filesystems still
1763only support whole seconds. 1832only support whole seconds.
1764.PP 1833.PP
1765That means that, if the time is the only thing that changes, you might 1834That means that, if the time is the only thing that changes, you can
1766miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and calls 1835easily miss updates: on the first update, \f(CW\*(C`ev_stat\*(C'\fR detects a change and
1767your callback, which does something. When there is another update within 1836calls your callback, which does something. When there is another update
1768the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect it. 1837within the same second, \f(CW\*(C`ev_stat\*(C'\fR will be unable to detect it as the stat
1838data does not change.
1769.PP 1839.PP
1770The solution to this is to delay acting on a change for a second (or till 1840The solution to this is to delay acting on a change for slightly more
1771the next second boundary), using a roughly one-second delay \f(CW\*(C`ev_timer\*(C'\fR 1841than a second (or till slightly after the next full second boundary), using
1772(\f(CW\*(C`ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)\*(C'\fR). The \f(CW.01\fR 1842a roughly one-second-delay \f(CW\*(C`ev_timer\*(C'\fR (e.g. \f(CW\*(C`ev_timer_set (w, 0., 1.02);
1773is added to work around small timing inconsistencies of some operating 1843ev_timer_again (loop, w)\*(C'\fR).
1774systems. 1844.PP
1845The \f(CW.02\fR offset is added to work around small timing inconsistencies
1846of some operating systems (where the second counter of the current time
1847might be be delayed. One such system is the Linux kernel, where a call to
1848\&\f(CW\*(C`gettimeofday\*(C'\fR might return a timestamp with a full second later than
1849a subsequent \f(CW\*(C`time\*(C'\fR call \- if the equivalent of \f(CW\*(C`time ()\*(C'\fR is used to
1850update file times then there will be a small window where the kernel uses
1851the previous second to update file times but libev might already execute
1852the timer callback).
1775.PP 1853.PP
1776\fIWatcher-Specific Functions and Data Members\fR 1854\fIWatcher-Specific Functions and Data Members\fR
1777.IX Subsection "Watcher-Specific Functions and Data Members" 1855.IX Subsection "Watcher-Specific Functions and Data Members"
1778.IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4 1856.IP "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 4
1779.IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)" 1857.IX Item "ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)"
… …
1785\&\f(CW\*(C`path\*(C'\fR. The \f(CW\*(C`interval\*(C'\fR is a hint on how quickly a change is expected to 1863\&\f(CW\*(C`path\*(C'\fR. The \f(CW\*(C`interval\*(C'\fR is a hint on how quickly a change is expected to
1786be detected and should normally be specified as \f(CW0\fR to let libev choose 1864be detected and should normally be specified as \f(CW0\fR to let libev choose
1787a suitable value. The memory pointed to by \f(CW\*(C`path\*(C'\fR must point to the same 1865a suitable value. The memory pointed to by \f(CW\*(C`path\*(C'\fR must point to the same
1788path for as long as the watcher is active. 1866path for as long as the watcher is active.
1789.Sp 1867.Sp
1790The callback will be receive \f(CW\*(C`EV_STAT\*(C'\fR when a change was detected, 1868The callback will receive \f(CW\*(C`EV_STAT\*(C'\fR when a change was detected, relative
1791relative to the attributes at the time the watcher was started (or the 1869to the attributes at the time the watcher was started (or the last change
1792last change was detected). 1870was detected).
1793.IP "ev_stat_stat (loop, ev_stat *)" 4 1871.IP "ev_stat_stat (loop, ev_stat *)" 4
1794.IX Item "ev_stat_stat (loop, ev_stat *)" 1872.IX Item "ev_stat_stat (loop, ev_stat *)"
1795Updates the stat buffer immediately with new values. If you change the 1873Updates the stat buffer immediately with new values. If you change the
1796watched path in your callback, you could call this fucntion to avoid 1874watched path in your callback, you could call this function to avoid
1797detecting this change (while introducing a race condition). Can also be 1875detecting this change (while introducing a race condition if you are not
1798useful simply to find out the new values. 1876the only one changing the path). Can also be useful simply to find out the
1877new values.
1799.IP "ev_statdata attr [read\-only]" 4 1878.IP "ev_statdata attr [read\-only]" 4
1800.IX Item "ev_statdata attr [read-only]" 1879.IX Item "ev_statdata attr [read-only]"
1801The most-recently detected attributes of the file. Although the type is of 1880The most-recently detected attributes of the file. Although the type is
1802\&\f(CW\*(C`ev_statdata\*(C'\fR, this is usually the (or one of the) \f(CW\*(C`struct stat\*(C'\fR types 1881\&\f(CW\*(C`ev_statdata\*(C'\fR, this is usually the (or one of the) \f(CW\*(C`struct stat\*(C'\fR types
1882suitable for your system, but you can only rely on the POSIX-standardised
1803suitable for your system. If the \f(CW\*(C`st_nlink\*(C'\fR member is \f(CW0\fR, then there 1883members to be present. If the \f(CW\*(C`st_nlink\*(C'\fR member is \f(CW0\fR, then there was
1804was some error while \f(CW\*(C`stat\*(C'\fRing the file. 1884some error while \f(CW\*(C`stat\*(C'\fRing the file.
1805.IP "ev_statdata prev [read\-only]" 4 1885.IP "ev_statdata prev [read\-only]" 4
1806.IX Item "ev_statdata prev [read-only]" 1886.IX Item "ev_statdata prev [read-only]"
1807The previous attributes of the file. The callback gets invoked whenever 1887The previous attributes of the file. The callback gets invoked whenever
1808\&\f(CW\*(C`prev\*(C'\fR != \f(CW\*(C`attr\*(C'\fR. 1888\&\f(CW\*(C`prev\*(C'\fR != \f(CW\*(C`attr\*(C'\fR, or, more precisely, one or more of these members
1889differ: \f(CW\*(C`st_dev\*(C'\fR, \f(CW\*(C`st_ino\*(C'\fR, \f(CW\*(C`st_mode\*(C'\fR, \f(CW\*(C`st_nlink\*(C'\fR, \f(CW\*(C`st_uid\*(C'\fR,
1890\&\f(CW\*(C`st_gid\*(C'\fR, \f(CW\*(C`st_rdev\*(C'\fR, \f(CW\*(C`st_size\*(C'\fR, \f(CW\*(C`st_atime\*(C'\fR, \f(CW\*(C`st_mtime\*(C'\fR, \f(CW\*(C`st_ctime\*(C'\fR.
1809.IP "ev_tstamp interval [read\-only]" 4 1891.IP "ev_tstamp interval [read\-only]" 4
1810.IX Item "ev_tstamp interval [read-only]" 1892.IX Item "ev_tstamp interval [read-only]"
1811The specified interval. 1893The specified interval.
1812.IP "const char *path [read\-only]" 4 1894.IP "const char *path [read\-only]" 4
1813.IX Item "const char *path [read-only]" 1895.IX Item "const char *path [read-only]"
… …
1867\& } 1949\& }
1868\& 1950\&
1869\& ... 1951\& ...
1870\& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); 1952\& ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1871\& ev_stat_start (loop, &passwd); 1953\& ev_stat_start (loop, &passwd);
1872\& ev_timer_init (&timer, timer_cb, 0., 1.01); 1954\& ev_timer_init (&timer, timer_cb, 0., 1.02);
1873.Ve 1955.Ve
1874.ie n .Sh """ev_idle"" \- when you've got nothing better to do..." 1956.ie n .Sh """ev_idle"" \- when you've got nothing better to do..."
1875.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..." 1957.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..."
1876.IX Subsection "ev_idle - when you've got nothing better to do..." 1958.IX Subsection "ev_idle - when you've got nothing better to do..."
1877Idle watchers trigger events when no other events of the same or higher 1959Idle watchers trigger events when no other events of the same or higher
… …
1963.PP 2045.PP
1964It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR) 2046It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR)
1965priority, to ensure that they are being run before any other watchers 2047priority, to ensure that they are being run before any other watchers
1966after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers, 2048after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers,
1967too) should not activate (\*(L"feed\*(R") events into libev. While libev fully 2049too) should not activate (\*(L"feed\*(R") events into libev. While libev fully
1968supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers 2050supports this, they might get executed before other \f(CW\*(C`ev_check\*(C'\fR watchers
1969did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other 2051did their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other
1970(non-libev) event loops those other event loops might be in an unusable 2052(non-libev) event loops those other event loops might be in an unusable
1971state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to 2053state until their \f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to
1972coexist peacefully with others). 2054coexist peacefully with others).
1973.PP 2055.PP
… …
1987.IX Subsection "Examples" 2069.IX Subsection "Examples"
1988.PP 2070.PP
1989There are a number of principal ways to embed other event loops or modules 2071There are a number of principal ways to embed other event loops or modules
1990into libev. Here are some ideas on how to include libadns into libev 2072into libev. Here are some ideas on how to include libadns into libev
1991(there is a Perl module named \f(CW\*(C`EV::ADNS\*(C'\fR that does this, which you could 2073(there is a Perl module named \f(CW\*(C`EV::ADNS\*(C'\fR that does this, which you could
1992use for an actually working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR 2074use as a working example. Another Perl module named \f(CW\*(C`EV::Glib\*(C'\fR embeds a
1993embeds a Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 2075Glib main context into libev, and finally, \f(CW\*(C`Glib::EV\*(C'\fR embeds \s-1EV\s0 into the
1994into the Glib event loop). 2076Glib event loop).
1995.PP 2077.PP
1996Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler, 2078Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler,
1997and in a check watcher, destroy them and call into libadns. What follows 2079and in a check watcher, destroy them and call into libadns. What follows
1998is pseudo-code only of course. This requires you to either use a low 2080is pseudo-code only of course. This requires you to either use a low
1999priority for the check watcher or use \f(CW\*(C`ev_clear_pending\*(C'\fR explicitly, as 2081priority for the check watcher or use \f(CW\*(C`ev_clear_pending\*(C'\fR explicitly, as
… …
2383section below on what exactly this means). 2465section below on what exactly this means).
2384.Sp 2466.Sp
2385This call incurs the overhead of a syscall only once per loop iteration, 2467This call incurs the overhead of a syscall only once per loop iteration,
2386so while the overhead might be noticable, it doesn't apply to repeated 2468so while the overhead might be noticable, it doesn't apply to repeated
2387calls to \f(CW\*(C`ev_async_send\*(C'\fR. 2469calls to \f(CW\*(C`ev_async_send\*(C'\fR.
2470.IP "bool = ev_async_pending (ev_async *)" 4
2471.IX Item "bool = ev_async_pending (ev_async *)"
2472Returns a non-zero value when \f(CW\*(C`ev_async_send\*(C'\fR has been called on the
2473watcher but the event has not yet been processed (or even noted) by the
2474event loop.
2475.Sp
2476\&\f(CW\*(C`ev_async_send\*(C'\fR sets a flag in the watcher and wakes up the loop. When
2477the loop iterates next and checks for the watcher to have become active,
2478it will reset the flag again. \f(CW\*(C`ev_async_pending\*(C'\fR can be used to very
2479quickly check wether invoking the loop might be a good idea.
2480.Sp
2481Not that this does \fInot\fR check wether the watcher itself is pending, only
2482wether it has been requested to make this watcher pending.
2388.SH "OTHER FUNCTIONS" 2483.SH "OTHER FUNCTIONS"
2389.IX Header "OTHER FUNCTIONS" 2484.IX Header "OTHER FUNCTIONS"
2390There are some other functions of possible interest. Described. Here. Now. 2485There are some other functions of possible interest. Described. Here. Now.
2391.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 2486.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4
2392.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 2487.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"
… …
2449it a private \s-1API\s0). 2544it a private \s-1API\s0).
2450.IP "\(bu" 4 2545.IP "\(bu" 4
2451Priorities are not currently supported. Initialising priorities 2546Priorities are not currently supported. Initialising priorities
2452will fail and all watchers will have the same priority, even though there 2547will fail and all watchers will have the same priority, even though there
2453is an ev_pri field. 2548is an ev_pri field.
2549.IP "\(bu" 4
2550In libevent, the last base created gets the signals, in libev, the
2551first base created (== the default loop) gets the signals.
2454.IP "\(bu" 4 2552.IP "\(bu" 4
2455Other members are not supported. 2553Other members are not supported.
2456.IP "\(bu" 4 2554.IP "\(bu" 4
2457The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need 2555The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need
2458to use the libev header file and library. 2556to use the libev header file and library.
… …
2687.ie n .IP """EV_DEFAULT""\fR, \f(CW""EV_DEFAULT_""" 4 2785.ie n .IP """EV_DEFAULT""\fR, \f(CW""EV_DEFAULT_""" 4
2688.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4 2786.el .IP "\f(CWEV_DEFAULT\fR, \f(CWEV_DEFAULT_\fR" 4
2689.IX Item "EV_DEFAULT, EV_DEFAULT_" 2787.IX Item "EV_DEFAULT, EV_DEFAULT_"
2690Similar to the other two macros, this gives you the value of the default 2788Similar to the other two macros, this gives you the value of the default
2691loop, if multiple loops are supported (\*(L"ev loop default\*(R"). 2789loop, if multiple loops are supported (\*(L"ev loop default\*(R").
2790.ie n .IP """EV_DEFAULT_UC""\fR, \f(CW""EV_DEFAULT_UC_""" 4
2791.el .IP "\f(CWEV_DEFAULT_UC\fR, \f(CWEV_DEFAULT_UC_\fR" 4
2792.IX Item "EV_DEFAULT_UC, EV_DEFAULT_UC_"
2793Usage identical to \f(CW\*(C`EV_DEFAULT\*(C'\fR and \f(CW\*(C`EV_DEFAULT_\*(C'\fR, but requires that the
2794default loop has been initialised (\f(CW\*(C`UC\*(C'\fR == unchecked). Their behaviour
2795is undefined when the default loop has not been initialised by a previous
2796execution of \f(CW\*(C`EV_DEFAULT\*(C'\fR, \f(CW\*(C`EV_DEFAULT_\*(C'\fR or \f(CW\*(C`ev_default_init (...)\*(C'\fR.
2797.Sp
2798It is often prudent to use \f(CW\*(C`EV_DEFAULT\*(C'\fR when initialising the first
2799watcher in a function but use \f(CW\*(C`EV_DEFAULT_UC\*(C'\fR afterwards.
2692.PP 2800.PP
2693Example: Declare and initialise a check watcher, utilising the above 2801Example: Declare and initialise a check watcher, utilising the above
2694macros so it will work regardless of whether multiple loops are supported 2802macros so it will work regardless of whether multiple loops are supported
2695or not. 2803or not.
2696.PP 2804.PP
… …
2806.Vb 1 2914.Vb 1
2807\& libev.m4 2915\& libev.m4
2808.Ve 2916.Ve
2809.Sh "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0" 2917.Sh "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0"
2810.IX Subsection "PREPROCESSOR SYMBOLS/MACROS" 2918.IX Subsection "PREPROCESSOR SYMBOLS/MACROS"
2811Libev can be configured via a variety of preprocessor symbols you have to define 2919Libev can be configured via a variety of preprocessor symbols you have to
2812before including any of its files. The default is not to build for multiplicity 2920define before including any of its files. The default in the absense of
2813and only include the select backend. 2921autoconf is noted for every option.
2814.IP "\s-1EV_STANDALONE\s0" 4 2922.IP "\s-1EV_STANDALONE\s0" 4
2815.IX Item "EV_STANDALONE" 2923.IX Item "EV_STANDALONE"
2816Must always be \f(CW1\fR if you do not use autoconf configuration, which 2924Must always be \f(CW1\fR if you do not use autoconf configuration, which
2817keeps libev from including \fIconfig.h\fR, and it also defines dummy 2925keeps libev from including \fIconfig.h\fR, and it also defines dummy
2818implementations for some libevent functions (such as logging, which is not 2926implementations for some libevent functions (such as logging, which is not
… …
2837note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. 2945note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though.
2838.IP "\s-1EV_USE_NANOSLEEP\s0" 4 2946.IP "\s-1EV_USE_NANOSLEEP\s0" 4
2839.IX Item "EV_USE_NANOSLEEP" 2947.IX Item "EV_USE_NANOSLEEP"
2840If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available 2948If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
2841and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. 2949and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
2950.IP "\s-1EV_USE_EVENTFD\s0" 4
2951.IX Item "EV_USE_EVENTFD"
2952If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
2953available and will probe for kernel support at runtime. This will improve
2954\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
2955If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
29562.7 or newer, otherwise disabled.
2842.IP "\s-1EV_USE_SELECT\s0" 4 2957.IP "\s-1EV_USE_SELECT\s0" 4
2843.IX Item "EV_USE_SELECT" 2958.IX Item "EV_USE_SELECT"
2844If undefined or defined to be \f(CW1\fR, libev will compile in support for the 2959If undefined or defined to be \f(CW1\fR, libev will compile in support for the
2845\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no 2960\&\f(CW\*(C`select\*(C'\fR(2) backend. No attempt at autodetection will be done: if no
2846other method takes over, select will be it. Otherwise the select backend 2961other method takes over, select will be it. Otherwise the select backend
… …
2877takes precedence over select. 2992takes precedence over select.
2878.IP "\s-1EV_USE_EPOLL\s0" 4 2993.IP "\s-1EV_USE_EPOLL\s0" 4
2879.IX Item "EV_USE_EPOLL" 2994.IX Item "EV_USE_EPOLL"
2880If defined to be \f(CW1\fR, libev will compile in support for the Linux 2995If defined to be \f(CW1\fR, libev will compile in support for the Linux
2881\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 2996\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
2882otherwise another method will be used as fallback. This is the 2997otherwise another method will be used as fallback. This is the preferred
2883preferred backend for GNU/Linux systems. 2998backend for GNU/Linux systems. If undefined, it will be enabled if the
2999headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
2884.IP "\s-1EV_USE_KQUEUE\s0" 4 3000.IP "\s-1EV_USE_KQUEUE\s0" 4
2885.IX Item "EV_USE_KQUEUE" 3001.IX Item "EV_USE_KQUEUE"
2886If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 3002If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
2887\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 3003\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
2888otherwise another method will be used as fallback. This is the preferred 3004otherwise another method will be used as fallback. This is the preferred
… …
2903reserved for future expansion, works like the \s-1USE\s0 symbols above. 3019reserved for future expansion, works like the \s-1USE\s0 symbols above.
2904.IP "\s-1EV_USE_INOTIFY\s0" 4 3020.IP "\s-1EV_USE_INOTIFY\s0" 4
2905.IX Item "EV_USE_INOTIFY" 3021.IX Item "EV_USE_INOTIFY"
2906If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify 3022If defined to be \f(CW1\fR, libev will compile in support for the Linux inotify
2907interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will 3023interface to speed up \f(CW\*(C`ev_stat\*(C'\fR watchers. Its actual availability will
2908be detected at runtime. 3024be detected at runtime. If undefined, it will be enabled if the headers
3025indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
2909.IP "\s-1EV_ATOMIC_T\s0" 4 3026.IP "\s-1EV_ATOMIC_T\s0" 4
2910.IX Item "EV_ATOMIC_T" 3027.IX Item "EV_ATOMIC_T"
2911Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 3028Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
2912access is atomic with respect to other threads or signal contexts. No such 3029access is atomic with respect to other threads or signal contexts. No such
2913type is easily found in the C language, so you can provide your own type 3030type is easily found in the C language, so you can provide your own type
… …
2988If undefined or defined to be \f(CW1\fR, then async watchers are supported. If 3105If undefined or defined to be \f(CW1\fR, then async watchers are supported. If
2989defined to be \f(CW0\fR, then they are not. 3106defined to be \f(CW0\fR, then they are not.
2990.IP "\s-1EV_MINIMAL\s0" 4 3107.IP "\s-1EV_MINIMAL\s0" 4
2991.IX Item "EV_MINIMAL" 3108.IX Item "EV_MINIMAL"
2992If you need to shave off some kilobytes of code at the expense of some 3109If you need to shave off some kilobytes of code at the expense of some
2993speed, define this symbol to \f(CW1\fR. Currently only used for gcc to override 3110speed, define this symbol to \f(CW1\fR. Currently this is used to override some
2994some inlining decisions, saves roughly 30% codesize of amd64. 3111inlining decisions, saves roughly 30% codesize of amd64. It also selects a
3112much smaller 2\-heap for timer management over the default 4\-heap.
2995.IP "\s-1EV_PID_HASHSIZE\s0" 4 3113.IP "\s-1EV_PID_HASHSIZE\s0" 4
2996.IX Item "EV_PID_HASHSIZE" 3114.IX Item "EV_PID_HASHSIZE"
2997\&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by 3115\&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by
2998pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more 3116pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more
2999than enough. If you need to manage thousands of children you might want to 3117than enough. If you need to manage thousands of children you might want to
… …
3003\&\f(CW\*(C`ev_stat\*(C'\fR watchers use a small hash table to distribute workload by 3121\&\f(CW\*(C`ev_stat\*(C'\fR watchers use a small hash table to distribute workload by
3004inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), 3122inotify watch id. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR),
3005usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR 3123usually more than enough. If you need to manage thousands of \f(CW\*(C`ev_stat\*(C'\fR
3006watchers you might want to increase this value (\fImust\fR be a power of 3124watchers you might want to increase this value (\fImust\fR be a power of
3007two). 3125two).
3126.IP "\s-1EV_USE_4HEAP\s0" 4
3127.IX Item "EV_USE_4HEAP"
3128Heaps are not very cache-efficient. To improve the cache-efficiency of the
3129timer and periodics heap, libev uses a 4\-heap when this symbol is defined
3130to \f(CW1\fR. The 4\-heap uses more complicated (longer) code but has
3131noticably faster performance with many (thousands) of watchers.
3132.Sp
3133The default is \f(CW1\fR unless \f(CW\*(C`EV_MINIMAL\*(C'\fR is set in which case it is \f(CW0\fR
3134(disabled).
3135.IP "\s-1EV_HEAP_CACHE_AT\s0" 4
3136.IX Item "EV_HEAP_CACHE_AT"
3137Heaps are not very cache-efficient. To improve the cache-efficiency of the
3138timer and periodics heap, libev can cache the timestamp (\fIat\fR) within
3139the heap structure (selected by defining \f(CW\*(C`EV_HEAP_CACHE_AT\*(C'\fR to \f(CW1\fR),
3140which uses 8\-12 bytes more per watcher and a few hundred bytes more code,
3141but avoids random read accesses on heap changes. This improves performance
3142noticably with with many (hundreds) of watchers.
3143.Sp
3144The default is \f(CW1\fR unless \f(CW\*(C`EV_MINIMAL\*(C'\fR is set in which case it is \f(CW0\fR
3145(disabled).
3146.IP "\s-1EV_VERIFY\s0" 4
3147.IX Item "EV_VERIFY"
3148Controls how much internal verification (see \f(CW\*(C`ev_loop_verify ()\*(C'\fR) will
3149be done: If set to \f(CW0\fR, no internal verification code will be compiled
3150in. If set to \f(CW1\fR, then verification code will be compiled in, but not
3151called. If set to \f(CW2\fR, then the internal verification code will be
3152called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
3153verification code will be called very frequently, which will slow down
3154libev considerably.
3155.Sp
3156The default is \f(CW1\fR, unless \f(CW\*(C`EV_MINIMAL\*(C'\fR is set, in which case it will be
3157\&\f(CW0.\fR
3008.IP "\s-1EV_COMMON\s0" 4 3158.IP "\s-1EV_COMMON\s0" 4
3009.IX Item "EV_COMMON" 3159.IX Item "EV_COMMON"
3010By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining 3160By default, all watchers have a \f(CW\*(C`void *data\*(C'\fR member. By redefining
3011this macro to a something else you can include more and other types of 3161this macro to a something else you can include more and other types of
3012members. You have to define it each time you include one of the files, 3162members. You have to define it each time you include one of the files,
… …
3094.PP 3244.PP
3095.Vb 2 3245.Vb 2
3096\& #include "ev_cpp.h" 3246\& #include "ev_cpp.h"
3097\& #include "ev.c" 3247\& #include "ev.c"
3098.Ve 3248.Ve
3249.SH "THREADS AND COROUTINES"
3250.IX Header "THREADS AND COROUTINES"
3251.Sh "\s-1THREADS\s0"
3252.IX Subsection "THREADS"
3253Libev itself is completely threadsafe, but it uses no locking. This
3254means that you can use as many loops as you want in parallel, as long as
3255only one thread ever calls into one libev function with the same loop
3256parameter.
3257.PP
3258Or put differently: calls with different loop parameters can be done in
3259parallel from multiple threads, calls with the same loop parameter must be
3260done serially (but can be done from different threads, as long as only one
3261thread ever is inside a call at any point in time, e.g. by using a mutex
3262per loop).
3263.PP
3264If you want to know which design is best for your problem, then I cannot
3265help you but by giving some generic advice:
3266.IP "\(bu" 4
3267most applications have a main thread: use the default libev loop
3268in that thread, or create a seperate thread running only the default loop.
3269.Sp
3270This helps integrating other libraries or software modules that use libev
3271themselves and don't care/know about threading.
3272.IP "\(bu" 4
3273one loop per thread is usually a good model.
3274.Sp
3275Doing this is almost never wrong, sometimes a better-performance model
3276exists, but it is always a good start.
3277.IP "\(bu" 4
3278other models exist, such as the leader/follower pattern, where one
3279loop is handed through multiple threads in a kind of round-robbin fashion.
3280.Sp
3281Chosing a model is hard \- look around, learn, know that usually you cna do
3282better than you currently do :\-)
3283.IP "\(bu" 4
3284often you need to talk to some other thread which blocks in the
3285event loop \- \f(CW\*(C`ev_async\*(C'\fR watchers can be used to wake them up from other
3286threads safely (or from signal contexts...).
3287.Sh "\s-1COROUTINES\s0"
3288.IX Subsection "COROUTINES"
3289Libev is much more accomodating to coroutines (\*(L"cooperative threads\*(R"):
3290libev fully supports nesting calls to it's functions from different
3291coroutines (e.g. you can call \f(CW\*(C`ev_loop\*(C'\fR on the same loop from two
3292different coroutines and switch freely between both coroutines running the
3293loop, as long as you don't confuse yourself). The only exception is that
3294you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks.
3295.PP
3296Care has been invested into making sure that libev does not keep local
3297state inside \f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow coroutine
3298switches.
3099.SH "COMPLEXITIES" 3299.SH "COMPLEXITIES"
3100.IX Header "COMPLEXITIES" 3300.IX Header "COMPLEXITIES"
3101In this section the complexities of (many of) the algorithms used inside 3301In this section the complexities of (many of) the algorithms used inside
3102libev will be explained. For complexity discussions about backends see the 3302libev will be explained. For complexity discussions about backends see the
3103documentation for \f(CW\*(C`ev_default_init\*(C'\fR. 3303documentation for \f(CW\*(C`ev_default_init\*(C'\fR.
… …
3128These watchers are stored in lists then need to be walked to find the 3328These watchers are stored in lists then need to be walked to find the
3129correct watcher to remove. The lists are usually short (you don't usually 3329correct watcher to remove. The lists are usually short (you don't usually
3130have many watchers waiting for the same fd or signal). 3330have many watchers waiting for the same fd or signal).
3131.IP "Finding the next timer in each loop iteration: O(1)" 4 3331.IP "Finding the next timer in each loop iteration: O(1)" 4
3132.IX Item "Finding the next timer in each loop iteration: O(1)" 3332.IX Item "Finding the next timer in each loop iteration: O(1)"
3133By virtue of using a binary heap, the next timer is always found at the 3333By virtue of using a binary or 4\-heap, the next timer is always found at a
3134beginning of the storage array. 3334fixed position in the storage array.
3135.IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 3335.IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4
3136.IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 3336.IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)"
3137A change means an I/O watcher gets started or stopped, which requires 3337A change means an I/O watcher gets started or stopped, which requires
3138libev to recalculate its status (and possibly tell the kernel, depending 3338libev to recalculate its status (and possibly tell the kernel, depending
3139on backend and wether \f(CW\*(C`ev_io_set\*(C'\fR was used). 3339on backend and wether \f(CW\*(C`ev_io_set\*(C'\fR was used).
… …
3165model. Libev still offers limited functionality on this platform in 3365model. Libev still offers limited functionality on this platform in
3166the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket 3366the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket
3167descriptors. This only applies when using Win32 natively, not when using 3367descriptors. This only applies when using Win32 natively, not when using
3168e.g. cygwin. 3368e.g. cygwin.
3169.PP 3369.PP
3370Lifting these limitations would basically require the full
3371re-implementation of the I/O system. If you are into these kinds of
3372things, then note that glib does exactly that for you in a very portable
3373way (note also that glib is the slowest event library known to man).
3374.PP
3170There is no supported compilation method available on windows except 3375There is no supported compilation method available on windows except
3171embedding it into other applications. 3376embedding it into other applications.
3172.PP 3377.PP
3173Due to the many, low, and arbitrary limits on the win32 platform and the 3378Due to the many, low, and arbitrary limits on the win32 platform and
3174abysmal performance of winsockets, using a large number of sockets is not 3379the abysmal performance of winsockets, using a large number of sockets
3175recommended (and not reasonable). If your program needs to use more than 3380is not recommended (and not reasonable). If your program needs to use
3176a hundred or so sockets, then likely it needs to use a totally different 3381more than a hundred or so sockets, then likely it needs to use a totally
3177implementation for windows, as libev offers the \s-1POSIX\s0 model, which cannot 3382different implementation for windows, as libev offers the \s-1POSIX\s0 readiness
3178be implemented efficiently on windows (microsoft monopoly games). 3383notification model, which cannot be implemented efficiently on windows
3384(microsoft monopoly games).
3179.IP "The winsocket select function" 4 3385.IP "The winsocket select function" 4
3180.IX Item "The winsocket select function" 3386.IX Item "The winsocket select function"
3181The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it requires 3387The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it
3182socket \fIhandles\fR and not socket \fIfile descriptors\fR. This makes select 3388requires socket \fIhandles\fR and not socket \fIfile descriptors\fR (it is
3183very inefficient, and also requires a mapping from file descriptors 3389also extremely buggy). This makes select very inefficient, and also
3184to socket handles. See the discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, 3390requires a mapping from file descriptors to socket handles. See the
3185\&\f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and \f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor 3391discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and
3186symbols for more info. 3392\&\f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor symbols for more info.
3187.Sp 3393.Sp
3188The configuration for a \*(L"naked\*(R" win32 using the microsoft runtime 3394The configuration for a \*(L"naked\*(R" win32 using the microsoft runtime
3189libraries and raw winsocket select is: 3395libraries and raw winsocket select is:
3190.Sp 3396.Sp
3191.Vb 2 3397.Vb 2
… …
3195.Sp 3401.Sp
3196Note that winsockets handling of fd sets is O(n), so you can easily get a 3402Note that winsockets handling of fd sets is O(n), so you can easily get a
3197complexity in the O(nA\*^X) range when using win32. 3403complexity in the O(nA\*^X) range when using win32.
3198.IP "Limited number of file descriptors" 4 3404.IP "Limited number of file descriptors" 4
3199.IX Item "Limited number of file descriptors" 3405.IX Item "Limited number of file descriptors"
3200Windows has numerous arbitrary (and low) limits on things. Early versions 3406Windows has numerous arbitrary (and low) limits on things.
3201of winsocket's select only supported waiting for a max. of \f(CW64\fR handles 3407.Sp
3202(probably owning to the fact that all windows kernels can only wait for 3408Early versions of winsocket's select only supported waiting for a maximum
3203\&\f(CW64\fR things at the same time internally; microsoft recommends spawning a 3409of \f(CW64\fR handles (probably owning to the fact that all windows kernels
3204chain of threads and wait for 63 handles and the previous thread in each). 3410can only wait for \f(CW64\fR things at the same time internally; microsoft
3411recommends spawning a chain of threads and wait for 63 handles and the
3412previous thread in each. Great).
3205.Sp 3413.Sp
3206Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR 3414Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR
3207to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select 3415to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select
3208call (which might be in libev or elsewhere, for example, perl does its own 3416call (which might be in libev or elsewhere, for example, perl does its own
3209select emulation on windows). 3417select emulation on windows).
… …
3217.Sp 3425.Sp
3218This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on 3426This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on
3219windows version and/or the phase of the moon). To get more, you need to 3427windows version and/or the phase of the moon). To get more, you need to
3220wrap all I/O functions and provide your own fd management, but the cost of 3428wrap all I/O functions and provide your own fd management, but the cost of
3221calling select (O(nA\*^X)) will likely make this unworkable. 3429calling select (O(nA\*^X)) will likely make this unworkable.
3430.SH "PORTABILITY REQUIREMENTS"
3431.IX Header "PORTABILITY REQUIREMENTS"
3432In addition to a working ISO-C implementation, libev relies on a few
3433additional extensions:
3434.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4
3435.el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4
3436.IX Item "sig_atomic_t volatile must be thread-atomic as well"
3437The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as
3438\&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic w.r.t. accesses from different
3439threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is
3440believed to be sufficiently portable.
3441.ie n .IP """sigprocmask"" must work in a threaded environment" 4
3442.el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4
3443.IX Item "sigprocmask must work in a threaded environment"
3444Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not
3445allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical
3446pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main
3447thread\*(R" or will block signals process-wide, both behaviours would
3448be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and
3449\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however.
3450.Sp
3451The most portable way to handle signals is to block signals in all threads
3452except the initial one, and run the default loop in the initial thread as
3453well.
3454.ie n .IP """long"" must be large enough for common memory allocation sizes" 4
3455.el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
3456.IX Item "long must be large enough for common memory allocation sizes"
3457To improve portability and simplify using libev, libev uses \f(CW\*(C`long\*(C'\fR
3458internally instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On
3459non-POSIX systems (Microsoft...) this might be unexpectedly low, but
3460is still at least 31 bits everywhere, which is enough for hundreds of
3461millions of watchers.
3462.ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4
3463.el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4
3464.IX Item "double must hold a time value in seconds with enough accuracy"
3465The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to
3466have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3467enough for at least into the year 4000. This requirement is fulfilled by
3468implementations implementing \s-1IEEE\s0 754 (basically all existing ones).
3469.PP
3470If you know of other additional requirements drop me a note.
3471.SH "COMPILER WARNINGS"
3472.IX Header "COMPILER WARNINGS"
3473Depending on your compiler and compiler settings, you might get no or a
3474lot of warnings when compiling libev code. Some people are apparently
3475scared by this.
3476.PP
3477However, these are unavoidable for many reasons. For one, each compiler
3478has different warnings, and each user has different tastes regarding
3479warning options. \*(L"Warn-free\*(R" code therefore cannot be a goal except when
3480targetting a specific compiler and compiler-version.
3481.PP
3482Another reason is that some compiler warnings require elaborate
3483workarounds, or other changes to the code that make it less clear and less
3484maintainable.
3485.PP
3486And of course, some compiler warnings are just plain stupid, or simply
3487wrong (because they don't actually warn about the cindition their message
3488seems to warn about).
3489.PP
3490While libev is written to generate as few warnings as possible,
3491\&\*(L"warn-free\*(R" code is not a goal, and it is recommended not to build libev
3492with any compiler warnings enabled unless you are prepared to cope with
3493them (e.g. by ignoring them). Remember that warnings are just that:
3494warnings, not errors, or proof of bugs.
3495.SH "VALGRIND"
3496.IX Header "VALGRIND"
3497Valgrind has a special section here because it is a popular tool that is
3498highly useful, but valgrind reports are very hard to interpret.
3499.PP
3500If you think you found a bug (memory leak, uninitialised data access etc.)
3501in libev, then check twice: If valgrind reports something like:
3502.PP
3503.Vb 3
3504\& ==2274== definitely lost: 0 bytes in 0 blocks.
3505\& ==2274== possibly lost: 0 bytes in 0 blocks.
3506\& ==2274== still reachable: 256 bytes in 1 blocks.
3507.Ve
3508.PP
3509then there is no memory leak. Similarly, under some circumstances,
3510valgrind might report kernel bugs as if it were a bug in libev, or it
3511might be confused (it is a very good tool, but only a tool).
3512.PP
3513If you are unsure about something, feel free to contact the mailing list
3514with the full valgrind report and an explanation on why you think this is
3515a bug in libev. However, don't be annoyed when you get a brisk \*(L"this is
3516no bug\*(R" answer and take the chance of learning how to interpret valgrind
3517properly.
3518.PP
3519If you need, for some reason, empty reports from valgrind for your project
3520I suggest using suppression lists.
3222.SH "AUTHOR" 3521.SH "AUTHOR"
3223.IX Header "AUTHOR" 3522.IX Header "AUTHOR"
3224Marc Lehmann <libev@schmorp.de>. 3523Marc Lehmann <libev@schmorp.de>.
3225.SH "POD ERRORS" 3524.SH "POD ERRORS"
3226.IX Header "POD ERRORS" 3525.IX Header "POD ERRORS"
3227Hey! \fBThe above document had some coding errors, which are explained below:\fR 3526Hey! \fBThe above document had some coding errors, which are explained below:\fR
3228.IP "Around line 2951:" 4 3527.IP "Around line 3107:" 4
3229.IX Item "Around line 2951:" 3528.IX Item "Around line 3107:"
3230You forgot a '=back' before '=head2' 3529You forgot a '=back' before '=head2'

Diff Legend

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