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

Comparing libev/ev.pod (file contents):
Revision 1.423 by root, Fri Nov 23 12:52:35 2012 UTC vs.
Revision 1.449 by root, Sun Jun 23 02:02:30 2019 UTC

1=encoding utf-8
2
1=head1 NAME 3=head1 NAME
2 4
3libev - a high performance full-featured event loop written in C 5libev - a high performance full-featured event loop written in C
4 6
5=head1 SYNOPSIS 7=head1 SYNOPSIS
103details of the event, and then hand it over to libev by I<starting> the 105details of the event, and then hand it over to libev by I<starting> the
104watcher. 106watcher.
105 107
106=head2 FEATURES 108=head2 FEATURES
107 109
108Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 110Libev supports C<select>, C<poll>, the Linux-specific aio and C<epoll>
109BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 111interfaces, the BSD-specific C<kqueue> and the Solaris-specific event port
110for file descriptor events (C<ev_io>), the Linux C<inotify> interface 112mechanisms for file descriptor events (C<ev_io>), the Linux C<inotify>
111(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner 113interface (for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
112inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative 114inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
113timers (C<ev_timer>), absolute timers with customised rescheduling 115timers (C<ev_timer>), absolute timers with customised rescheduling
114(C<ev_periodic>), synchronous signals (C<ev_signal>), process status 116(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
115change events (C<ev_child>), and event watchers dealing with the event 117change events (C<ev_child>), and event watchers dealing with the event
116loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and 118loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
263 265
264You could override this function in high-availability programs to, say, 266You could override this function in high-availability programs to, say,
265free some memory if it cannot allocate memory, to use a special allocator, 267free some memory if it cannot allocate memory, to use a special allocator,
266or even to sleep a while and retry until some memory is available. 268or even to sleep a while and retry until some memory is available.
267 269
270Example: The following is the C<realloc> function that libev itself uses
271which should work with C<realloc> and C<free> functions of all kinds and
272is probably a good basis for your own implementation.
273
274 static void *
275 ev_realloc_emul (void *ptr, long size) EV_NOEXCEPT
276 {
277 if (size)
278 return realloc (ptr, size);
279
280 free (ptr);
281 return 0;
282 }
283
268Example: Replace the libev allocator with one that waits a bit and then 284Example: Replace the libev allocator with one that waits a bit and then
269retries (example requires a standards-compliant C<realloc>). 285retries.
270 286
271 static void * 287 static void *
272 persistent_realloc (void *ptr, size_t size) 288 persistent_realloc (void *ptr, size_t size)
273 { 289 {
290 if (!size)
291 {
292 free (ptr);
293 return 0;
294 }
295
274 for (;;) 296 for (;;)
275 { 297 {
276 void *newptr = realloc (ptr, size); 298 void *newptr = realloc (ptr, size);
277 299
278 if (newptr) 300 if (newptr)
396 418
397If this flag bit is or'ed into the flag value (or the program runs setuid 419If this flag bit is or'ed into the flag value (or the program runs setuid
398or setgid) then libev will I<not> look at the environment variable 420or setgid) then libev will I<not> look at the environment variable
399C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 421C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
400override the flags completely if it is found in the environment. This is 422override the flags completely if it is found in the environment. This is
401useful to try out specific backends to test their performance, or to work 423useful to try out specific backends to test their performance, to work
402around bugs. 424around bugs, or to make libev threadsafe (accessing environment variables
425cannot be done in a threadsafe way, but usually it works if no other
426thread modifies them).
403 427
404=item C<EVFLAG_FORKCHECK> 428=item C<EVFLAG_FORKCHECK>
405 429
406Instead of calling C<ev_loop_fork> manually after a fork, you can also 430Instead of calling C<ev_loop_fork> manually after a fork, you can also
407make libev check for a fork in each iteration by enabling this flag. 431make libev check for a fork in each iteration by enabling this flag.
408 432
409This works by calling C<getpid ()> on every iteration of the loop, 433This works by calling C<getpid ()> on every iteration of the loop,
410and thus this might slow down your event loop if you do a lot of loop 434and thus this might slow down your event loop if you do a lot of loop
411iterations and little real work, but is usually not noticeable (on my 435iterations and little real work, but is usually not noticeable (on my
412GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 436GNU/Linux system for example, C<getpid> is actually a simple 5-insn
413without a system call and thus I<very> fast, but my GNU/Linux system also has 437sequence without a system call and thus I<very> fast, but my GNU/Linux
414C<pthread_atfork> which is even faster). 438system also has C<pthread_atfork> which is even faster). (Update: glibc
439versions 2.25 apparently removed the C<getpid> optimisation again).
415 440
416The big advantage of this flag is that you can forget about fork (and 441The big advantage of this flag is that you can forget about fork (and
417forget about forgetting to tell libev about forking) when you use this 442forget about forgetting to tell libev about forking, although you still
418flag. 443have to ignore C<SIGPIPE>) when you use this flag.
419 444
420This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 445This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
421environment variable. 446environment variable.
422 447
423=item C<EVFLAG_NOINOTIFY> 448=item C<EVFLAG_NOINOTIFY>
542All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or 567All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
543faster than epoll for maybe up to a hundred file descriptors, depending on 568faster than epoll for maybe up to a hundred file descriptors, depending on
544the usage. So sad. 569the usage. So sad.
545 570
546While nominally embeddable in other event loops, this feature is broken in 571While nominally embeddable in other event loops, this feature is broken in
547all kernel versions tested so far. 572a lot of kernel revisions, but probably(!) works in current versions.
573
574This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
575C<EVBACKEND_POLL>.
576
577=item C<EVBACKEND_LINUXAIO> (value 64, Linux)
578
579Use the linux-specific linux aio (I<not> C<< aio(7) >> but C<<
580io_submit(2) >>) event interface available in post-4.18 kernels.
581
582If this backend works for you (as of this writing, it was very
583experimental), it is the best event interface available on linux and might
584be well worth enabling it - if it isn't available in your kernel this will
585be detected and this backend will be skipped.
586
587This backend can batch oneshot requests and supports a user-space ring
588buffer to receive events. It also doesn't suffer from most of the design
589problems of epoll (such as not being able to remove event sources from
590the epoll set), and generally sounds too good to be true. Because, this
591being the linux kernel, of course it suffers from a whole new set of
592limitations.
593
594For one, it is not easily embeddable (but probably could be done using
595an event fd at some extra overhead). It also is subject to a system wide
596limit that can be configured in F</proc/sys/fs/aio-max-nr> - each loop
597currently requires C<61> of this number. If no aio requests are left, this
598backend will be skipped during initialisation.
599
600Most problematic in practise, however, is that not all file descriptors
601work with it. For example, in linux 5.1, tcp sockets, pipes, event fds,
602files, F</dev/null> and a few others are supported, but ttys do not work
603(probably because of a bug), so this is not (yet?) a generic event polling
604interface.
605
606To work around this latter problem, the current version of libev uses
607epoll as a fallback for file deescriptor types that do not work. Epoll
608is used in, kind of, slow mode that hopefully avoids most of its design
609problems and requires 1-3 extra syscalls per active fd every iteration.
548 610
549This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 611This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
550C<EVBACKEND_POLL>. 612C<EVBACKEND_POLL>.
551 613
552=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 614=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
653Example: Use whatever libev has to offer, but make sure that kqueue is 715Example: Use whatever libev has to offer, but make sure that kqueue is
654used if available. 716used if available.
655 717
656 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); 718 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
657 719
720Example: Similarly, on linux, you mgiht want to take advantage of the
721linux aio backend if possible, but fall back to something else if that
722isn't available.
723
724 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
725
658=item ev_loop_destroy (loop) 726=item ev_loop_destroy (loop)
659 727
660Destroys an event loop object (frees all memory and kernel state 728Destroys an event loop object (frees all memory and kernel state
661etc.). None of the active event watchers will be stopped in the normal 729etc.). None of the active event watchers will be stopped in the normal
662sense, so e.g. C<ev_is_active> might still return true. It is your 730sense, so e.g. C<ev_is_active> might still return true. It is your
678If you need dynamically allocated loops it is better to use C<ev_loop_new> 746If you need dynamically allocated loops it is better to use C<ev_loop_new>
679and C<ev_loop_destroy>. 747and C<ev_loop_destroy>.
680 748
681=item ev_loop_fork (loop) 749=item ev_loop_fork (loop)
682 750
683This function sets a flag that causes subsequent C<ev_run> iterations to 751This function sets a flag that causes subsequent C<ev_run> iterations
684reinitialise the kernel state for backends that have one. Despite the 752to reinitialise the kernel state for backends that have one. Despite
685name, you can call it anytime, but it makes most sense after forking, in 753the name, you can call it anytime you are allowed to start or stop
686the child process. You I<must> call it (or use C<EVFLAG_FORKCHECK>) in the 754watchers (except inside an C<ev_prepare> callback), but it makes most
755sense after forking, in the child process. You I<must> call it (or use
687child before resuming or calling C<ev_run>. 756C<EVFLAG_FORKCHECK>) in the child before resuming or calling C<ev_run>.
688 757
758In addition, if you want to reuse a loop (via this function or
759C<EVFLAG_FORKCHECK>), you I<also> have to ignore C<SIGPIPE>.
760
689Again, you I<have> to call it on I<any> loop that you want to re-use after 761Again, you I<have> to call it on I<any> loop that you want to re-use after
690a fork, I<even if you do not plan to use the loop in the parent>. This is 762a fork, I<even if you do not plan to use the loop in the parent>. This is
691because some kernel interfaces *cough* I<kqueue> *cough* do funny things 763because some kernel interfaces *cough* I<kqueue> *cough* do funny things
692during fork. 764during fork.
693 765
694On the other hand, you only need to call this function in the child 766On the other hand, you only need to call this function in the child
1601 1673
1602But really, best use non-blocking mode. 1674But really, best use non-blocking mode.
1603 1675
1604=head3 The special problem of disappearing file descriptors 1676=head3 The special problem of disappearing file descriptors
1605 1677
1606Some backends (e.g. kqueue, epoll) need to be told about closing a file 1678Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1607descriptor (either due to calling C<close> explicitly or any other means, 1679a file descriptor (either due to calling C<close> explicitly or any other
1608such as C<dup2>). The reason is that you register interest in some file 1680means, such as C<dup2>). The reason is that you register interest in some
1609descriptor, but when it goes away, the operating system will silently drop 1681file descriptor, but when it goes away, the operating system will silently
1610this interest. If another file descriptor with the same number then is 1682drop this interest. If another file descriptor with the same number then
1611registered with libev, there is no efficient way to see that this is, in 1683is registered with libev, there is no efficient way to see that this is,
1612fact, a different file descriptor. 1684in fact, a different file descriptor.
1613 1685
1614To avoid having to explicitly tell libev about such cases, libev follows 1686To avoid having to explicitly tell libev about such cases, libev follows
1615the following policy: Each time C<ev_io_set> is being called, libev 1687the following policy: Each time C<ev_io_set> is being called, libev
1616will assume that this is potentially a new file descriptor, otherwise 1688will assume that this is potentially a new file descriptor, otherwise
1617it is assumed that the file descriptor stays the same. That means that 1689it is assumed that the file descriptor stays the same. That means that
1666when you rarely read from a file instead of from a socket, and want to 1738when you rarely read from a file instead of from a socket, and want to
1667reuse the same code path. 1739reuse the same code path.
1668 1740
1669=head3 The special problem of fork 1741=head3 The special problem of fork
1670 1742
1671Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit 1743Some backends (epoll, kqueue, probably linuxaio) do not support C<fork ()>
1672useless behaviour. Libev fully supports fork, but needs to be told about 1744at all or exhibit useless behaviour. Libev fully supports fork, but needs
1673it in the child if you want to continue to use it in the child. 1745to be told about it in the child if you want to continue to use it in the
1746child.
1674 1747
1675To support fork in your child processes, you have to call C<ev_loop_fork 1748To support fork in your child processes, you have to call C<ev_loop_fork
1676()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to 1749()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to
1677C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. 1750C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1678 1751
2024 2097
2025The relative timeouts are calculated relative to the C<ev_now ()> 2098The relative timeouts are calculated relative to the C<ev_now ()>
2026time. This is usually the right thing as this timestamp refers to the time 2099time. This is usually the right thing as this timestamp refers to the time
2027of the event triggering whatever timeout you are modifying/starting. If 2100of the event triggering whatever timeout you are modifying/starting. If
2028you suspect event processing to be delayed and you I<need> to base the 2101you suspect event processing to be delayed and you I<need> to base the
2029timeout on the current time, use something like this to adjust for this: 2102timeout on the current time, use something like the following to adjust
2103for it:
2030 2104
2031 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 2105 ev_timer_set (&timer, after + (ev_time () - ev_now ()), 0.);
2032 2106
2033If the event loop is suspended for a long time, you can also force an 2107If the event loop is suspended for a long time, you can also force an
2034update of the time returned by C<ev_now ()> by calling C<ev_now_update 2108update of the time returned by C<ev_now ()> by calling C<ev_now_update
2035()>. 2109()>, although that will push the event time of all outstanding events
2110further into the future.
2036 2111
2037=head3 The special problem of unsynchronised clocks 2112=head3 The special problem of unsynchronised clocks
2038 2113
2039Modern systems have a variety of clocks - libev itself uses the normal 2114Modern systems have a variety of clocks - libev itself uses the normal
2040"wall clock" clock and, if available, the monotonic clock (to avoid time 2115"wall clock" clock and, if available, the monotonic clock (to avoid time
2103 2178
2104=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 2179=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
2105 2180
2106=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) 2181=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
2107 2182
2108Configure the timer to trigger after C<after> seconds. If C<repeat> 2183Configure the timer to trigger after C<after> seconds (fractional and
2109is C<0.>, then it will automatically be stopped once the timeout is 2184negative values are supported). If C<repeat> is C<0.>, then it will
2110reached. If it is positive, then the timer will automatically be 2185automatically be stopped once the timeout is reached. If it is positive,
2111configured to trigger again C<repeat> seconds later, again, and again, 2186then the timer will automatically be configured to trigger again C<repeat>
2112until stopped manually. 2187seconds later, again, and again, until stopped manually.
2113 2188
2114The timer itself will do a best-effort at avoiding drift, that is, if 2189The timer itself will do a best-effort at avoiding drift, that is, if
2115you configure a timer to trigger every 10 seconds, then it will normally 2190you configure a timer to trigger every 10 seconds, then it will normally
2116trigger at exactly 10 second intervals. If, however, your program cannot 2191trigger at exactly 10 second intervals. If, however, your program cannot
2117keep up with the timer (because it takes longer than those 10 seconds to 2192keep up with the timer (because it takes longer than those 10 seconds to
2199Periodic watchers are also timers of a kind, but they are very versatile 2274Periodic watchers are also timers of a kind, but they are very versatile
2200(and unfortunately a bit complex). 2275(and unfortunately a bit complex).
2201 2276
2202Unlike C<ev_timer>, periodic watchers are not based on real time (or 2277Unlike C<ev_timer>, periodic watchers are not based on real time (or
2203relative time, the physical time that passes) but on wall clock time 2278relative time, the physical time that passes) but on wall clock time
2204(absolute time, the thing you can read on your calender or clock). The 2279(absolute time, the thing you can read on your calendar or clock). The
2205difference is that wall clock time can run faster or slower than real 2280difference is that wall clock time can run faster or slower than real
2206time, and time jumps are not uncommon (e.g. when you adjust your 2281time, and time jumps are not uncommon (e.g. when you adjust your
2207wrist-watch). 2282wrist-watch).
2208 2283
2209You can tell a periodic watcher to trigger after some specific point 2284You can tell a periodic watcher to trigger after some specific point
2214C<ev_timer>, which would still trigger roughly 10 seconds after starting 2289C<ev_timer>, which would still trigger roughly 10 seconds after starting
2215it, as it uses a relative timeout). 2290it, as it uses a relative timeout).
2216 2291
2217C<ev_periodic> watchers can also be used to implement vastly more complex 2292C<ev_periodic> watchers can also be used to implement vastly more complex
2218timers, such as triggering an event on each "midnight, local time", or 2293timers, such as triggering an event on each "midnight, local time", or
2219other complicated rules. This cannot be done with C<ev_timer> watchers, as 2294other complicated rules. This cannot easily be done with C<ev_timer>
2220those cannot react to time jumps. 2295watchers, as those cannot react to time jumps.
2221 2296
2222As with timers, the callback is guaranteed to be invoked only when the 2297As with timers, the callback is guaranteed to be invoked only when the
2223point in time where it is supposed to trigger has passed. If multiple 2298point in time where it is supposed to trigger has passed. If multiple
2224timers become ready during the same loop iteration then the ones with 2299timers become ready during the same loop iteration then the ones with
2225earlier time-out values are invoked before ones with later time-out values 2300earlier time-out values are invoked before ones with later time-out values
2311 2386
2312NOTE: I<< This callback must always return a time that is higher than or 2387NOTE: I<< This callback must always return a time that is higher than or
2313equal to the passed C<now> value >>. 2388equal to the passed C<now> value >>.
2314 2389
2315This can be used to create very complex timers, such as a timer that 2390This can be used to create very complex timers, such as a timer that
2316triggers on "next midnight, local time". To do this, you would calculate the 2391triggers on "next midnight, local time". To do this, you would calculate
2317next midnight after C<now> and return the timestamp value for this. How 2392the next midnight after C<now> and return the timestamp value for
2318you do this is, again, up to you (but it is not trivial, which is the main 2393this. Here is a (completely untested, no error checking) example on how to
2319reason I omitted it as an example). 2394do this:
2395
2396 #include <time.h>
2397
2398 static ev_tstamp
2399 my_rescheduler (ev_periodic *w, ev_tstamp now)
2400 {
2401 time_t tnow = (time_t)now;
2402 struct tm tm;
2403 localtime_r (&tnow, &tm);
2404
2405 tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2406 ++tm.tm_mday; // midnight next day
2407
2408 return mktime (&tm);
2409 }
2410
2411Note: this code might run into trouble on days that have more then two
2412midnights (beginning and end).
2320 2413
2321=back 2414=back
2322 2415
2323=item ev_periodic_again (loop, ev_periodic *) 2416=item ev_periodic_again (loop, ev_periodic *)
2324 2417
2389 2482
2390 ev_periodic hourly_tick; 2483 ev_periodic hourly_tick;
2391 ev_periodic_init (&hourly_tick, clock_cb, 2484 ev_periodic_init (&hourly_tick, clock_cb,
2392 fmod (ev_now (loop), 3600.), 3600., 0); 2485 fmod (ev_now (loop), 3600.), 3600., 0);
2393 ev_periodic_start (loop, &hourly_tick); 2486 ev_periodic_start (loop, &hourly_tick);
2394 2487
2395 2488
2396=head2 C<ev_signal> - signal me when a signal gets signalled! 2489=head2 C<ev_signal> - signal me when a signal gets signalled!
2397 2490
2398Signal watchers will trigger an event when the process receives a specific 2491Signal watchers will trigger an event when the process receives a specific
2399signal one or more times. Even though signals are very asynchronous, libev 2492signal one or more times. Even though signals are very asynchronous, libev
2409only within the same loop, i.e. you can watch for C<SIGINT> in your 2502only within the same loop, i.e. you can watch for C<SIGINT> in your
2410default loop and for C<SIGIO> in another loop, but you cannot watch for 2503default loop and for C<SIGIO> in another loop, but you cannot watch for
2411C<SIGINT> in both the default loop and another loop at the same time. At 2504C<SIGINT> in both the default loop and another loop at the same time. At
2412the moment, C<SIGCHLD> is permanently tied to the default loop. 2505the moment, C<SIGCHLD> is permanently tied to the default loop.
2413 2506
2414When the first watcher gets started will libev actually register something 2507Only after the first watcher for a signal is started will libev actually
2415with the kernel (thus it coexists with your own signal handlers as long as 2508register something with the kernel. It thus coexists with your own signal
2416you don't register any with libev for the same signal). 2509handlers as long as you don't register any with libev for the same signal.
2417 2510
2418If possible and supported, libev will install its handlers with 2511If possible and supported, libev will install its handlers with
2419C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2512C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2420not be unduly interrupted. If you have a problem with system calls getting 2513not be unduly interrupted. If you have a problem with system calls getting
2421interrupted by signals you can block all signals in an C<ev_check> watcher 2514interrupted by signals you can block all signals in an C<ev_check> watcher
2606 2699
2607=head2 C<ev_stat> - did the file attributes just change? 2700=head2 C<ev_stat> - did the file attributes just change?
2608 2701
2609This watches a file system path for attribute changes. That is, it calls 2702This watches a file system path for attribute changes. That is, it calls
2610C<stat> on that path in regular intervals (or when the OS says it changed) 2703C<stat> on that path in regular intervals (or when the OS says it changed)
2611and sees if it changed compared to the last time, invoking the callback if 2704and sees if it changed compared to the last time, invoking the callback
2612it did. 2705if it did. Starting the watcher C<stat>'s the file, so only changes that
2706happen after the watcher has been started will be reported.
2613 2707
2614The path does not need to exist: changing from "path exists" to "path does 2708The path does not need to exist: changing from "path exists" to "path does
2615not exist" is a status change like any other. The condition "path does not 2709not exist" is a status change like any other. The condition "path does not
2616exist" (or more correctly "path cannot be stat'ed") is signified by the 2710exist" (or more correctly "path cannot be stat'ed") is signified by the
2617C<st_nlink> field being zero (which is otherwise always forced to be at 2711C<st_nlink> field being zero (which is otherwise always forced to be at
2902 2996
2903Prepare and check watchers are often (but not always) used in pairs: 2997Prepare and check watchers are often (but not always) used in pairs:
2904prepare watchers get invoked before the process blocks and check watchers 2998prepare watchers get invoked before the process blocks and check watchers
2905afterwards. 2999afterwards.
2906 3000
2907You I<must not> call C<ev_run> or similar functions that enter 3001You I<must not> call C<ev_run> (or similar functions that enter the
2908the current event loop from either C<ev_prepare> or C<ev_check> 3002current event loop) or C<ev_loop_fork> from either C<ev_prepare> or
2909watchers. Other loops than the current one are fine, however. The 3003C<ev_check> watchers. Other loops than the current one are fine,
2910rationale behind this is that you do not need to check for recursion in 3004however. The rationale behind this is that you do not need to check
2911those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 3005for recursion in those watchers, i.e. the sequence will always be
2912C<ev_check> so if you have one watcher of each kind they will always be 3006C<ev_prepare>, blocking, C<ev_check> so if you have one watcher of each
2913called in pairs bracketing the blocking call. 3007kind they will always be called in pairs bracketing the blocking call.
2914 3008
2915Their main purpose is to integrate other event mechanisms into libev and 3009Their main purpose is to integrate other event mechanisms into libev and
2916their use is somewhat advanced. They could be used, for example, to track 3010their use is somewhat advanced. They could be used, for example, to track
2917variable changes, implement your own watchers, integrate net-snmp or a 3011variable changes, implement your own watchers, integrate net-snmp or a
2918coroutine library and lots more. They are also occasionally useful if 3012coroutine library and lots more. They are also occasionally useful if
3177 3271
3178=over 4 3272=over 4
3179 3273
3180=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 3274=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
3181 3275
3182=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 3276=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)
3183 3277
3184Configures the watcher to embed the given loop, which must be 3278Configures the watcher to embed the given loop, which must be
3185embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be 3279embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
3186invoked automatically, otherwise it is the responsibility of the callback 3280invoked automatically, otherwise it is the responsibility of the callback
3187to invoke it (it will continue to be called until the sweep has been done, 3281to invoke it (it will continue to be called until the sweep has been done,
3208used). 3302used).
3209 3303
3210 struct ev_loop *loop_hi = ev_default_init (0); 3304 struct ev_loop *loop_hi = ev_default_init (0);
3211 struct ev_loop *loop_lo = 0; 3305 struct ev_loop *loop_lo = 0;
3212 ev_embed embed; 3306 ev_embed embed;
3213 3307
3214 // see if there is a chance of getting one that works 3308 // see if there is a chance of getting one that works
3215 // (remember that a flags value of 0 means autodetection) 3309 // (remember that a flags value of 0 means autodetection)
3216 loop_lo = ev_embeddable_backends () & ev_recommended_backends () 3310 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
3217 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 3311 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
3218 : 0; 3312 : 0;
3232C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). 3326C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
3233 3327
3234 struct ev_loop *loop = ev_default_init (0); 3328 struct ev_loop *loop = ev_default_init (0);
3235 struct ev_loop *loop_socket = 0; 3329 struct ev_loop *loop_socket = 0;
3236 ev_embed embed; 3330 ev_embed embed;
3237 3331
3238 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 3332 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
3239 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 3333 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
3240 { 3334 {
3241 ev_embed_init (&embed, 0, loop_socket); 3335 ev_embed_init (&embed, 0, loop_socket);
3242 ev_embed_start (loop, &embed); 3336 ev_embed_start (loop, &embed);
3258and calls it in the wrong process, the fork handlers will be invoked, too, 3352and calls it in the wrong process, the fork handlers will be invoked, too,
3259of course. 3353of course.
3260 3354
3261=head3 The special problem of life after fork - how is it possible? 3355=head3 The special problem of life after fork - how is it possible?
3262 3356
3263Most uses of C<fork()> consist of forking, then some simple calls to set 3357Most uses of C<fork ()> consist of forking, then some simple calls to set
3264up/change the process environment, followed by a call to C<exec()>. This 3358up/change the process environment, followed by a call to C<exec()>. This
3265sequence should be handled by libev without any problems. 3359sequence should be handled by libev without any problems.
3266 3360
3267This changes when the application actually wants to do event handling 3361This changes when the application actually wants to do event handling
3268in the child, or both parent in child, in effect "continuing" after the 3362in the child, or both parent in child, in effect "continuing" after the
3506 3600
3507There are some other functions of possible interest. Described. Here. Now. 3601There are some other functions of possible interest. Described. Here. Now.
3508 3602
3509=over 4 3603=over 4
3510 3604
3511=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 3605=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)
3512 3606
3513This function combines a simple timer and an I/O watcher, calls your 3607This function combines a simple timer and an I/O watcher, calls your
3514callback on whichever event happens first and automatically stops both 3608callback on whichever event happens first and automatically stops both
3515watchers. This is useful if you want to wait for a single event on an fd 3609watchers. This is useful if you want to wait for a single event on an fd
3516or timeout without having to allocate/configure/start/stop/free one or 3610or timeout without having to allocate/configure/start/stop/free one or
3892To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two 3986To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two
3893files, F<my_ev.h> and F<my_ev.c> that include the respective libev files: 3987files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
3894 3988
3895 // my_ev.h 3989 // my_ev.h
3896 #define EV_CB_DECLARE(type) struct my_coro *cb; 3990 #define EV_CB_DECLARE(type) struct my_coro *cb;
3897 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb); 3991 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
3898 #include "../libev/ev.h" 3992 #include "../libev/ev.h"
3899 3993
3900 // my_ev.c 3994 // my_ev.c
3901 #define EV_H "my_ev.h" 3995 #define EV_H "my_ev.h"
3902 #include "../libev/ev.c" 3996 #include "../libev/ev.c"
3948The normal C API should work fine when used from C++: both ev.h and the 4042The normal C API should work fine when used from C++: both ev.h and the
3949libev sources can be compiled as C++. Therefore, code that uses the C API 4043libev sources can be compiled as C++. Therefore, code that uses the C API
3950will work fine. 4044will work fine.
3951 4045
3952Proper exception specifications might have to be added to callbacks passed 4046Proper exception specifications might have to be added to callbacks passed
3953to libev: exceptions may be thrown only from watcher callbacks, all 4047to libev: exceptions may be thrown only from watcher callbacks, all other
3954other callbacks (allocator, syserr, loop acquire/release and periodic 4048callbacks (allocator, syserr, loop acquire/release and periodic reschedule
3955reschedule callbacks) must not throw exceptions, and might need a C<throw 4049callbacks) must not throw exceptions, and might need a C<noexcept>
3956()> specification. If you have code that needs to be compiled as both C 4050specification. If you have code that needs to be compiled as both C and
3957and C++ you can use the C<EV_THROW> macro for this: 4051C++ you can use the C<EV_NOEXCEPT> macro for this:
3958 4052
3959 static void 4053 static void
3960 fatal_error (const char *msg) EV_THROW 4054 fatal_error (const char *msg) EV_NOEXCEPT
3961 { 4055 {
3962 perror (msg); 4056 perror (msg);
3963 abort (); 4057 abort ();
3964 } 4058 }
3965 4059
3979Libev comes with some simplistic wrapper classes for C++ that mainly allow 4073Libev comes with some simplistic wrapper classes for C++ that mainly allow
3980you to use some convenience methods to start/stop watchers and also change 4074you to use some convenience methods to start/stop watchers and also change
3981the callback model to a model using method callbacks on objects. 4075the callback model to a model using method callbacks on objects.
3982 4076
3983To use it, 4077To use it,
3984 4078
3985 #include <ev++.h> 4079 #include <ev++.h>
3986 4080
3987This automatically includes F<ev.h> and puts all of its definitions (many 4081This automatically includes F<ev.h> and puts all of its definitions (many
3988of them macros) into the global namespace. All C++ specific things are 4082of them macros) into the global namespace. All C++ specific things are
3989put into the C<ev> namespace. It should support all the same embedding 4083put into the C<ev> namespace. It should support all the same embedding
4092 void operator() (ev::io &w, int revents) 4186 void operator() (ev::io &w, int revents)
4093 { 4187 {
4094 ... 4188 ...
4095 } 4189 }
4096 } 4190 }
4097 4191
4098 myfunctor f; 4192 myfunctor f;
4099 4193
4100 ev::io w; 4194 ev::io w;
4101 w.set (&f); 4195 w.set (&f);
4102 4196
4375 ev_vars.h 4469 ev_vars.h
4376 ev_wrap.h 4470 ev_wrap.h
4377 4471
4378 ev_win32.c required on win32 platforms only 4472 ev_win32.c required on win32 platforms only
4379 4473
4380 ev_select.c only when select backend is enabled (which is enabled by default) 4474 ev_select.c only when select backend is enabled
4381 ev_poll.c only when poll backend is enabled (disabled by default) 4475 ev_poll.c only when poll backend is enabled
4382 ev_epoll.c only when the epoll backend is enabled (disabled by default) 4476 ev_epoll.c only when the epoll backend is enabled
4477 ev_linuxaio.c only when the linux aio backend is enabled
4383 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4478 ev_kqueue.c only when the kqueue backend is enabled
4384 ev_port.c only when the solaris port backend is enabled (disabled by default) 4479 ev_port.c only when the solaris port backend is enabled
4385 4480
4386F<ev.c> includes the backend files directly when enabled, so you only need 4481F<ev.c> includes the backend files directly when enabled, so you only need
4387to compile this single file. 4482to compile this single file.
4388 4483
4389=head3 LIBEVENT COMPATIBILITY API 4484=head3 LIBEVENT COMPATIBILITY API
4577If defined to be C<1>, libev will compile in support for the Linux 4672If defined to be C<1>, libev will compile in support for the Linux
4578C<epoll>(7) backend. Its availability will be detected at runtime, 4673C<epoll>(7) backend. Its availability will be detected at runtime,
4579otherwise another method will be used as fallback. This is the preferred 4674otherwise another method will be used as fallback. This is the preferred
4580backend for GNU/Linux systems. If undefined, it will be enabled if the 4675backend for GNU/Linux systems. If undefined, it will be enabled if the
4581headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4676headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4677
4678=item EV_USE_LINUXAIO
4679
4680If defined to be C<1>, libev will compile in support for the Linux
4681aio backend. Due to it's currenbt limitations it has to be requested
4682explicitly. If undefined, it will be enabled on linux, otherwise
4683disabled.
4582 4684
4583=item EV_USE_KQUEUE 4685=item EV_USE_KQUEUE
4584 4686
4585If defined to be C<1>, libev will compile in support for the BSD style 4687If defined to be C<1>, libev will compile in support for the BSD style
4586C<kqueue>(2) backend. Its actual availability will be detected at runtime, 4688C<kqueue>(2) backend. Its actual availability will be detected at runtime,
4617different cpus (or different cpu cores). This reduces dependencies 4719different cpus (or different cpu cores). This reduces dependencies
4618and makes libev faster. 4720and makes libev faster.
4619 4721
4620=item EV_NO_THREADS 4722=item EV_NO_THREADS
4621 4723
4622If defined to be C<1>, libev will assume that it will never be called 4724If defined to be C<1>, libev will assume that it will never be called from
4623from different threads, which is a stronger assumption than C<EV_NO_SMP>, 4725different threads (that includes signal handlers), which is a stronger
4624above. This reduces dependencies and makes libev faster. 4726assumption than C<EV_NO_SMP>, above. This reduces dependencies and makes
4727libev faster.
4625 4728
4626=item EV_ATOMIC_T 4729=item EV_ATOMIC_T
4627 4730
4628Libev requires an integer type (suitable for storing C<0> or C<1>) whose 4731Libev requires an integer type (suitable for storing C<0> or C<1>) whose
4629access is atomic with respect to other threads or signal contexts. No 4732access is atomic with respect to other threads or signal contexts. No
5288structure (guaranteed by POSIX but not by ISO C for example), but it also 5391structure (guaranteed by POSIX but not by ISO C for example), but it also
5289assumes that the same (machine) code can be used to call any watcher 5392assumes that the same (machine) code can be used to call any watcher
5290callback: The watcher callbacks have different type signatures, but libev 5393callback: The watcher callbacks have different type signatures, but libev
5291calls them using an C<ev_watcher *> internally. 5394calls them using an C<ev_watcher *> internally.
5292 5395
5396=item null pointers and integer zero are represented by 0 bytes
5397
5398Libev uses C<memset> to initialise structs and arrays to C<0> bytes, and
5399relies on this setting pointers and integers to null.
5400
5293=item pointer accesses must be thread-atomic 5401=item pointer accesses must be thread-atomic
5294 5402
5295Accessing a pointer value must be atomic, it must both be readable and 5403Accessing a pointer value must be atomic, it must both be readable and
5296writable in one piece - this is the case on all current architectures. 5404writable in one piece - this is the case on all current architectures.
5297 5405
5425=over 4 5533=over 4
5426 5534
5427=item C<EV_COMPAT3> backwards compatibility mechanism 5535=item C<EV_COMPAT3> backwards compatibility mechanism
5428 5536
5429The backward compatibility mechanism can be controlled by 5537The backward compatibility mechanism can be controlled by
5430C<EV_COMPAT3>. See L</PREPROCESSOR SYMBOLS/MACROS> in the L</EMBEDDING> 5538C<EV_COMPAT3>. See L</"PREPROCESSOR SYMBOLS/MACROS"> in the L</EMBEDDING>
5431section. 5539section.
5432 5540
5433=item C<ev_default_destroy> and C<ev_default_fork> have been removed 5541=item C<ev_default_destroy> and C<ev_default_fork> have been removed
5434 5542
5435These calls can be replaced easily by their C<ev_loop_xxx> counterparts: 5543These calls can be replaced easily by their C<ev_loop_xxx> counterparts:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines