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

Comparing libev/ev.3 (file contents):
Revision 1.108 by root, Sat Jul 28 04:15:15 2018 UTC vs.
Revision 1.110 by root, Thu Jun 20 22:44:59 2019 UTC

1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) 1.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
… …
44.\" 44.\"
45.\" Escape single quotes in literal strings from groff's Unicode transform. 45.\" Escape single quotes in literal strings from groff's Unicode transform.
46.ie \n(.g .ds Aq \(aq 46.ie \n(.g .ds Aq \(aq
47.el .ds Aq ' 47.el .ds Aq '
48.\" 48.\"
49.\" If the F register is turned on, we'll generate index entries on stderr for 49.\" If the F register is >0, we'll generate index entries on stderr for
50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51.\" entries marked with X<> in POD. Of course, you'll have to process the 51.\" entries marked with X<> in POD. Of course, you'll have to process the
52.\" output yourself in some meaningful fashion. 52.\" output yourself in some meaningful fashion.
53.\" 53.\"
54.\" Avoid warning from groff about undefined register 'F'. 54.\" Avoid warning from groff about undefined register 'F'.
55.de IX 55.de IX
56.. 56..
57.nr rF 0 57.nr rF 0
58.if \n(.g .if rF .nr rF 1 58.if \n(.g .if rF .nr rF 1
59.if (\n(rF:(\n(.g==0)) \{ 59.if (\n(rF:(\n(.g==0)) \{\
60. if \nF \{ 60. if \nF \{\
61. de IX 61. de IX
62. tm Index:\\$1\t\\n%\t"\\$2" 62. tm Index:\\$1\t\\n%\t"\\$2"
63.. 63..
64. if !\nF==2 \{ 64. if !\nF==2 \{\
65. nr % 0 65. nr % 0
66. nr F 2 66. nr F 2
67. \} 67. \}
68. \} 68. \}
69.\} 69.\}
… …
131.\} 131.\}
132.rm #[ #] #H #V #F C 132.rm #[ #] #H #V #F C
133.\" ======================================================================== 133.\" ========================================================================
134.\" 134.\"
135.IX Title "LIBEV 3" 135.IX Title "LIBEV 3"
136.TH LIBEV 3 "2017-11-14" "libev-4.24" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2019-06-20" "libev-4.25" "libev - high performance full featured event loop"
137.\" For nroff, turn off justification. Always turn off hyphenation; it makes 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
138.\" way too many mistakes in technical documents. 138.\" way too many mistakes in technical documents.
139.if n .ad l 139.if n .ad l
140.nh 140.nh
141.SH "NAME" 141.SH "NAME"
… …
392.Sp 392.Sp
393You could override this function in high-availability programs to, say, 393You could override this function in high-availability programs to, say,
394free some memory if it cannot allocate memory, to use a special allocator, 394free some memory if it cannot allocate memory, to use a special allocator,
395or even to sleep a while and retry until some memory is available. 395or even to sleep a while and retry until some memory is available.
396.Sp 396.Sp
397Example: The following is the \f(CW\*(C`realloc\*(C'\fR function that libev itself uses
398which should work with \f(CW\*(C`realloc\*(C'\fR and \f(CW\*(C`free\*(C'\fR functions of all kinds and
399is probably a good basis for your own implementation.
400.Sp
401.Vb 5
402\& static void *
403\& ev_realloc_emul (void *ptr, long size) EV_NOEXCEPT
404\& {
405\& if (size)
406\& return realloc (ptr, size);
407\&
408\& free (ptr);
409\& return 0;
410\& }
411.Ve
412.Sp
397Example: Replace the libev allocator with one that waits a bit and then 413Example: Replace the libev allocator with one that waits a bit and then
398retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR). 414retries.
399.Sp 415.Sp
400.Vb 6 416.Vb 8
401\& static void * 417\& static void *
402\& persistent_realloc (void *ptr, size_t size) 418\& persistent_realloc (void *ptr, size_t size)
403\& { 419\& {
420\& if (!size)
421\& {
422\& free (ptr);
423\& return 0;
424\& }
425\&
404\& for (;;) 426\& for (;;)
405\& { 427\& {
406\& void *newptr = realloc (ptr, size); 428\& void *newptr = realloc (ptr, size);
407\& 429\&
408\& if (newptr) 430\& if (newptr)
… …
585.Sp 607.Sp
586This flag's behaviour will become the default in future versions of libev. 608This flag's behaviour will become the default in future versions of libev.
587.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 609.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
588.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 610.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
589.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 611.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
590This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 612This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
591libev tries to roll its own fd_set with no limits on the number of fds, 613libev tries to roll its own fd_set with no limits on the number of fds,
592but if that fails, expect a fairly low limit on the number of fds when 614but if that fails, expect a fairly low limit on the number of fds when
593using this backend. It doesn't scale too well (O(highest_fd)), but its 615using this backend. It doesn't scale too well (O(highest_fd)), but its
594usually the fastest backend for a low number of (low-numbered :) fds. 616usually the fastest backend for a low number of (low-numbered :) fds.
595.Sp 617.Sp
… …
604\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the 626\&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the
605\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform). 627\&\f(CW\*(C`exceptfds\*(C'\fR set on that platform).
606.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4 628.ie n .IP """EVBACKEND_POLL"" (value 2, poll backend, available everywhere except on windows)" 4
607.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4 629.el .IP "\f(CWEVBACKEND_POLL\fR (value 2, poll backend, available everywhere except on windows)" 4
608.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)" 630.IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
609And this is your standard \fIpoll\fR\|(2) backend. It's more complicated 631And this is your standard \fBpoll\fR\|(2) backend. It's more complicated
610than select, but handles sparse fds better and has no artificial 632than select, but handles sparse fds better and has no artificial
611limit on the number of fds you can use (except it will slow down 633limit on the number of fds you can use (except it will slow down
612considerably with a lot of inactive fds). It scales similarly to select, 634considerably with a lot of inactive fds). It scales similarly to select,
613i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for 635i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
614performance tips. 636performance tips.
… …
616This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and 638This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and
617\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. 639\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR.
618.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 640.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
619.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 641.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
620.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 642.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
621Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 643Use the linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
622kernels). 644kernels).
623.Sp 645.Sp
624For few fds, this backend is a bit little slower than poll and select, but 646For few fds, this backend is a bit little slower than poll and select, but
625it scales phenomenally better. While poll and select usually scale like 647it scales phenomenally better. While poll and select usually scale like
626O(total_fds) where total_fds is the total number of fds (or the highest 648O(total_fds) where total_fds is the total number of fds (or the highest
… …
1365bug in your program. 1387bug in your program.
1366.Sp 1388.Sp
1367Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for 1389Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for
1368example it might indicate that a fd is readable or writable, and if your 1390example it might indicate that a fd is readable or writable, and if your
1369callbacks is well-written it can just attempt the operation and cope with 1391callbacks is well-written it can just attempt the operation and cope with
1370the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded 1392the error from \fBread()\fR or \fBwrite()\fR. This will not work in multi-threaded
1371programs, though, as the fd could already be closed and reused for another 1393programs, though, as the fd could already be closed and reused for another
1372thing, so beware. 1394thing, so beware.
1373.SS "\s-1GENERIC WATCHER FUNCTIONS\s0" 1395.SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
1374.IX Subsection "GENERIC WATCHER FUNCTIONS" 1396.IX Subsection "GENERIC WATCHER FUNCTIONS"
1375.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 1397.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
… …
1811when writing to a pipe whose other end has been closed, your program gets 1833when writing to a pipe whose other end has been closed, your program gets
1812sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs 1834sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
1813this is sensible behaviour, for daemons, this is usually undesirable. 1835this is sensible behaviour, for daemons, this is usually undesirable.
1814.PP 1836.PP
1815So when you encounter spurious, unexplained daemon exits, make sure you 1837So when you encounter spurious, unexplained daemon exits, make sure you
1816ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon 1838ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
1817somewhere, as that would have given you a big clue). 1839somewhere, as that would have given you a big clue).
1818.PP 1840.PP
1819\fIThe special problem of \fIaccept()\fIing when you can't\fR 1841\fIThe special problem of \f(BIaccept()\fIing when you can't\fR
1820.IX Subsection "The special problem of accept()ing when you can't" 1842.IX Subsection "The special problem of accept()ing when you can't"
1821.PP 1843.PP
1822Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example, 1844Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example,
1823found in post\-2004 Linux) have the peculiar behaviour of not removing a 1845found in post\-2004 Linux) have the peculiar behaviour of not removing a
1824connection from the pending queue in all error cases. 1846connection from the pending queue in all error cases.
1825.PP 1847.PP
1826For example, larger servers often run out of file descriptors (because 1848For example, larger servers often run out of file descriptors (because
1827of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not 1849of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not
… …
2251.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 2273.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
2252.PD 0 2274.PD 0
2253.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 2275.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
2254.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 2276.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
2255.PD 2277.PD
2256Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR 2278Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds (fractional and
2257is \f(CW0.\fR, then it will automatically be stopped once the timeout is 2279negative values are supported). If \f(CW\*(C`repeat\*(C'\fR is \f(CW0.\fR, then it will
2258reached. If it is positive, then the timer will automatically be 2280automatically be stopped once the timeout is reached. If it is positive,
2259configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again, 2281then the timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR
2260until stopped manually. 2282seconds later, again, and again, until stopped manually.
2261.Sp 2283.Sp
2262The timer itself will do a best-effort at avoiding drift, that is, if 2284The timer itself will do a best-effort at avoiding drift, that is, if
2263you configure a timer to trigger every 10 seconds, then it will normally 2285you configure a timer to trigger every 10 seconds, then it will normally
2264trigger at exactly 10 second intervals. If, however, your program cannot 2286trigger at exactly 10 second intervals. If, however, your program cannot
2265keep up with the timer (because it takes longer than those 10 seconds to 2287keep up with the timer (because it takes longer than those 10 seconds to
… …
2362\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting 2384\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting
2363it, as it uses a relative timeout). 2385it, as it uses a relative timeout).
2364.PP 2386.PP
2365\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex 2387\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex
2366timers, such as triggering an event on each \*(L"midnight, local time\*(R", or 2388timers, such as triggering an event on each \*(L"midnight, local time\*(R", or
2367other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as 2389other complicated rules. This cannot easily be done with \f(CW\*(C`ev_timer\*(C'\fR
2368those cannot react to time jumps. 2390watchers, as those cannot react to time jumps.
2369.PP 2391.PP
2370As with timers, the callback is guaranteed to be invoked only when the 2392As with timers, the callback is guaranteed to be invoked only when the
2371point in time where it is supposed to trigger has passed. If multiple 2393point in time where it is supposed to trigger has passed. If multiple
2372timers become ready during the same loop iteration then the ones with 2394timers become ready during the same loop iteration then the ones with
2373earlier time-out values are invoked before ones with later time-out values 2395earlier time-out values are invoked before ones with later time-out values
… …
2434In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being 2456In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being
2435ignored. Instead, each time the periodic watcher gets scheduled, the 2457ignored. Instead, each time the periodic watcher gets scheduled, the
2436reschedule callback will be called with the watcher as first, and the 2458reschedule callback will be called with the watcher as first, and the
2437current time as second argument. 2459current time as second argument.
2438.Sp 2460.Sp
2439\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever, 2461\&\s-1NOTE:\s0 \fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
2440or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly 2462or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
2441allowed by documentation here\fR. 2463allowed by documentation here\fR.
2442.Sp 2464.Sp
2443If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop 2465If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
2444it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the 2466it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
… …
2458It must return the next time to trigger, based on the passed time value 2480It must return the next time to trigger, based on the passed time value
2459(that is, the lowest time value larger than to the second argument). It 2481(that is, the lowest time value larger than to the second argument). It
2460will usually be called just before the callback will be triggered, but 2482will usually be called just before the callback will be triggered, but
2461might be called at other times, too. 2483might be called at other times, too.
2462.Sp 2484.Sp
2463\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or 2485\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
2464equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2486equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2465.Sp 2487.Sp
2466This can be used to create very complex timers, such as a timer that 2488This can be used to create very complex timers, such as a timer that
2467triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the 2489triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate
2468next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How 2490the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for
2469you do this is, again, up to you (but it is not trivial, which is the main 2491this. Here is a (completely untested, no error checking) example on how to
2470reason I omitted it as an example). 2492do this:
2493.Sp
2494.Vb 1
2495\& #include <time.h>
2496\&
2497\& static ev_tstamp
2498\& my_rescheduler (ev_periodic *w, ev_tstamp now)
2499\& {
2500\& time_t tnow = (time_t)now;
2501\& struct tm tm;
2502\& localtime_r (&tnow, &tm);
2503\&
2504\& tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2505\& ++tm.tm_mday; // midnight next day
2506\&
2507\& return mktime (&tm);
2508\& }
2509.Ve
2510.Sp
2511Note: this code might run into trouble on days that have more then two
2512midnights (beginning and end).
2471.RE 2513.RE
2472.RS 4 2514.RS 4
2473.RE 2515.RE
2474.IP "ev_periodic_again (loop, ev_periodic *)" 4 2516.IP "ev_periodic_again (loop, ev_periodic *)" 4
2475.IX Item "ev_periodic_again (loop, ev_periodic *)" 2517.IX Item "ev_periodic_again (loop, ev_periodic *)"
… …
2593The simplest way to ensure that the signal mask is reset in the child is 2635The simplest way to ensure that the signal mask is reset in the child is
2594to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will 2636to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will
2595catch fork calls done by libraries (such as the libc) as well. 2637catch fork calls done by libraries (such as the libc) as well.
2596.PP 2638.PP
2597In current versions of libev, the signal will not be blocked indefinitely 2639In current versions of libev, the signal will not be blocked indefinitely
2598unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces 2640unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
2599the window of opportunity for problems, it will not go away, as libev 2641the window of opportunity for problems, it will not go away, as libev
2600\&\fIhas\fR to modify the signal mask, at least temporarily. 2642\&\fIhas\fR to modify the signal mask, at least temporarily.
2601.PP 2643.PP
2602So I can't stress this enough: \fIIf you do not reset your signal mask when 2644So I can't stress this enough: \fIIf you do not reset your signal mask when
2603you expect it to be empty, you have a race condition in your code\fR. This 2645you expect it to be empty, you have a race condition in your code\fR. This
… …
3645is a time window between the event loop checking and resetting the async 3687is a time window between the event loop checking and resetting the async
3646notification, and the callback being invoked. 3688notification, and the callback being invoked.
3647.SH "OTHER FUNCTIONS" 3689.SH "OTHER FUNCTIONS"
3648.IX Header "OTHER FUNCTIONS" 3690.IX Header "OTHER FUNCTIONS"
3649There are some other functions of possible interest. Described. Here. Now. 3691There are some other functions of possible interest. Described. Here. Now.
3650.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 3692.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)" 4
3651.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 3693.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)"
3652This function combines a simple timer and an I/O watcher, calls your 3694This function combines a simple timer and an I/O watcher, calls your
3653callback on whichever event happens first and automatically stops both 3695callback on whichever event happens first and automatically stops both
3654watchers. This is useful if you want to wait for a single event on an fd 3696watchers. This is useful if you want to wait for a single event on an fd
3655or timeout without having to allocate/configure/start/stop/free one or 3697or timeout without having to allocate/configure/start/stop/free one or
3656more watchers yourself. 3698more watchers yourself.
… …
4106The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the 4148The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4107libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 4149libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4108will work fine. 4150will work fine.
4109.PP 4151.PP
4110Proper exception specifications might have to be added to callbacks passed 4152Proper exception specifications might have to be added to callbacks passed
4111to libev: exceptions may be thrown only from watcher callbacks, all 4153to libev: exceptions may be thrown only from watcher callbacks, all other
4112other callbacks (allocator, syserr, loop acquire/release and periodic 4154callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4113reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw 4155callbacks) must not throw exceptions, and might need a \f(CW\*(C`noexcept\*(C'\fR
4114()\*(C'\fR specification. If you have code that needs to be compiled as both C 4156specification. If you have code that needs to be compiled as both C and
4115and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: 4157\&\*(C+ you can use the \f(CW\*(C`EV_NOEXCEPT\*(C'\fR macro for this:
4116.PP 4158.PP
4117.Vb 6 4159.Vb 6
4118\& static void 4160\& static void
4119\& fatal_error (const char *msg) EV_THROW 4161\& fatal_error (const char *msg) EV_NOEXCEPT
4120\& { 4162\& {
4121\& perror (msg); 4163\& perror (msg);
4122\& abort (); 4164\& abort ();
4123\& } 4165\& }
4124\& 4166\&
… …
4498\& #include "ev.c" 4540\& #include "ev.c"
4499.Ve 4541.Ve
4500.PP 4542.PP
4501This will automatically include \fIev.h\fR, too, and should be done in a 4543This will automatically include \fIev.h\fR, too, and should be done in a
4502single C source file only to provide the function implementations. To use 4544single C source file only to provide the function implementations. To use
4503it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best 4545it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
4504done by writing a wrapper around \fIev.h\fR that you can include instead and 4546done by writing a wrapper around \fIev.h\fR that you can include instead and
4505where you can put other configuration options): 4547where you can put other configuration options):
4506.PP 4548.PP
4507.Vb 2 4549.Vb 2
4508\& #define EV_STANDALONE 1 4550\& #define EV_STANDALONE 1
… …
4581values when compiling libev vs. including \fIev.h\fR, so it is permissible 4623values when compiling libev vs. including \fIev.h\fR, so it is permissible
4582to redefine them before including \fIev.h\fR without breaking compatibility 4624to redefine them before including \fIev.h\fR without breaking compatibility
4583to a compiled library. All other symbols change the \s-1ABI,\s0 which means all 4625to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
4584users of libev and the libev code itself must be compiled with compatible 4626users of libev and the libev code itself must be compiled with compatible
4585settings. 4627settings.
4586.IP "\s-1EV_COMPAT3 \s0(h)" 4 4628.IP "\s-1EV_COMPAT3\s0 (h)" 4
4587.IX Item "EV_COMPAT3 (h)" 4629.IX Item "EV_COMPAT3 (h)"
4588Backwards compatibility is a major concern for libev. This is why this 4630Backwards compatibility is a major concern for libev. This is why this
4589release of libev comes with wrappers for the functions and symbols that 4631release of libev comes with wrappers for the functions and symbols that
4590have been renamed between libev version 3 and 4. 4632have been renamed between libev version 3 and 4.
4591.Sp 4633.Sp
… …
4596typedef in that case. 4638typedef in that case.
4597.Sp 4639.Sp
4598In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR, 4640In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
4599and in some even more future version the compatibility code will be 4641and in some even more future version the compatibility code will be
4600removed completely. 4642removed completely.
4601.IP "\s-1EV_STANDALONE \s0(h)" 4 4643.IP "\s-1EV_STANDALONE\s0 (h)" 4
4602.IX Item "EV_STANDALONE (h)" 4644.IX Item "EV_STANDALONE (h)"
4603Must always be \f(CW1\fR if you do not use autoconf configuration, which 4645Must always be \f(CW1\fR if you do not use autoconf configuration, which
4604keeps libev from including \fIconfig.h\fR, and it also defines dummy 4646keeps libev from including \fIconfig.h\fR, and it also defines dummy
4605implementations for some libevent functions (such as logging, which is not 4647implementations for some libevent functions (such as logging, which is not
4606supported). It will also not define any of the structs usually found in 4648supported). It will also not define any of the structs usually found in
… …
4764handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR 4806handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4765watchers. 4807watchers.
4766.Sp 4808.Sp
4767In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4809In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4768(from \fIsignal.h\fR), which is usually good enough on most platforms. 4810(from \fIsignal.h\fR), which is usually good enough on most platforms.
4769.IP "\s-1EV_H \s0(h)" 4 4811.IP "\s-1EV_H\s0 (h)" 4
4770.IX Item "EV_H (h)" 4812.IX Item "EV_H (h)"
4771The name of the \fIev.h\fR header file used to include it. The default if 4813The name of the \fIev.h\fR header file used to include it. The default if
4772undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4814undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4773used to virtually rename the \fIev.h\fR header file in case of conflicts. 4815used to virtually rename the \fIev.h\fR header file in case of conflicts.
4774.IP "\s-1EV_CONFIG_H \s0(h)" 4 4816.IP "\s-1EV_CONFIG_H\s0 (h)" 4
4775.IX Item "EV_CONFIG_H (h)" 4817.IX Item "EV_CONFIG_H (h)"
4776If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override 4818If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
4777\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to 4819\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
4778\&\f(CW\*(C`EV_H\*(C'\fR, above. 4820\&\f(CW\*(C`EV_H\*(C'\fR, above.
4779.IP "\s-1EV_EVENT_H \s0(h)" 4 4821.IP "\s-1EV_EVENT_H\s0 (h)" 4
4780.IX Item "EV_EVENT_H (h)" 4822.IX Item "EV_EVENT_H (h)"
4781Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea 4823Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
4782of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR. 4824of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
4783.IP "\s-1EV_PROTOTYPES \s0(h)" 4 4825.IP "\s-1EV_PROTOTYPES\s0 (h)" 4
4784.IX Item "EV_PROTOTYPES (h)" 4826.IX Item "EV_PROTOTYPES (h)"
4785If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function 4827If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
4786prototypes, but still define all the structs and other symbols. This is 4828prototypes, but still define all the structs and other symbols. This is
4787occasionally useful if you want to provide your own wrapper functions 4829occasionally useful if you want to provide your own wrapper functions
4788around libev functions. 4830around libev functions.
… …
4997.Vb 3 5039.Vb 3
4998\& #define EV_COMMON \e 5040\& #define EV_COMMON \e
4999\& SV *self; /* contains this struct */ \e 5041\& SV *self; /* contains this struct */ \e
5000\& SV *cb_sv, *fh /* note no trailing ";" */ 5042\& SV *cb_sv, *fh /* note no trailing ";" */
5001.Ve 5043.Ve
5002.IP "\s-1EV_CB_DECLARE \s0(type)" 4 5044.IP "\s-1EV_CB_DECLARE\s0 (type)" 4
5003.IX Item "EV_CB_DECLARE (type)" 5045.IX Item "EV_CB_DECLARE (type)"
5004.PD 0 5046.PD 0
5005.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4 5047.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
5006.IX Item "EV_CB_INVOKE (watcher, revents)" 5048.IX Item "EV_CB_INVOKE (watcher, revents)"
5007.IP "ev_set_cb (ev, cb)" 4 5049.IP "ev_set_cb (ev, cb)" 4
5008.IX Item "ev_set_cb (ev, cb)" 5050.IX Item "ev_set_cb (ev, cb)"
5009.PD 5051.PD
5010Can be used to change the callback member declaration in each watcher, 5052Can be used to change the callback member declaration in each watcher,
… …
5013their default definitions. One possible use for overriding these is to 5055their default definitions. One possible use for overriding these is to
5014avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use 5056avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
5015method calls instead of plain function calls in \*(C+. 5057method calls instead of plain function calls in \*(C+.
5016.SS "\s-1EXPORTED API SYMBOLS\s0" 5058.SS "\s-1EXPORTED API SYMBOLS\s0"
5017.IX Subsection "EXPORTED API SYMBOLS" 5059.IX Subsection "EXPORTED API SYMBOLS"
5018If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of 5060If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
5019exported symbols, you can use the provided \fISymbol.*\fR files which list 5061exported symbols, you can use the provided \fISymbol.*\fR files which list
5020all public symbols, one per line: 5062all public symbols, one per line:
5021.PP 5063.PP
5022.Vb 2 5064.Vb 2
5023\& Symbols.ev for libev proper 5065\& Symbols.ev for libev proper
… …
5255.PP 5297.PP
5256\fI\f(CI\*(C`select\*(C'\fI is buggy\fR 5298\fI\f(CI\*(C`select\*(C'\fI is buggy\fR
5257.IX Subsection "select is buggy" 5299.IX Subsection "select is buggy"
5258.PP 5300.PP
5259All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this 5301All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
5260one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file 5302one up as well: On \s-1OS/X,\s0 \f(CW\*(C`select\*(C'\fR actively limits the number of file
5261descriptors you can pass in to 1024 \- your program suddenly crashes when 5303descriptors you can pass in to 1024 \- your program suddenly crashes when
5262you use more. 5304you use more.
5263.PP 5305.PP
5264There is an undocumented \*(L"workaround\*(R" for this \- defining 5306There is an undocumented \*(L"workaround\*(R" for this \- defining
5265\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR 5307\&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR

Diff Legend

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