--- libev/ev.pod 2007/11/26 10:20:43 1.46 +++ libev/ev.pod 2019/12/20 20:51:46 1.458 @@ -1,15 +1,99 @@ +=encoding utf-8 + =head1 NAME libev - a high performance full-featured event loop written in C =head1 SYNOPSIS - #include + #include + +=head2 EXAMPLE PROGRAM + + // a single header file is required + #include + + #include // for puts + + // every watcher type has its own typedef'd struct + // with the name ev_TYPE + ev_io stdin_watcher; + ev_timer timeout_watcher; + + // all watcher callbacks have a similar signature + // this callback is called when data is readable on stdin + static void + stdin_cb (EV_P_ ev_io *w, int revents) + { + puts ("stdin ready"); + // for one-shot events, one must manually stop the watcher + // with its corresponding stop function. + ev_io_stop (EV_A_ w); + + // this causes all nested ev_run's to stop iterating + ev_break (EV_A_ EVBREAK_ALL); + } + + // another callback, this time for a time-out + static void + timeout_cb (EV_P_ ev_timer *w, int revents) + { + puts ("timeout"); + // this causes the innermost ev_run to stop iterating + ev_break (EV_A_ EVBREAK_ONE); + } + + int + main (void) + { + // use the default event loop unless you have special needs + struct ev_loop *loop = EV_DEFAULT; -=head1 DESCRIPTION + // initialise an io watcher, then start it + // this one will watch for stdin to become readable + ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); + ev_io_start (loop, &stdin_watcher); + + // initialise a timer watcher, then start it + // simple non-repeating 5.5 second timeout + ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.); + ev_timer_start (loop, &timeout_watcher); + + // now wait for events to arrive + ev_run (loop, 0); + + // break was called, so exit + return 0; + } + +=head1 ABOUT THIS DOCUMENT + +This document documents the libev software package. + +The newest version of this document is also available as an html-formatted +web page you might find easier to navigate when reading it for the first +time: L. + +While this document tries to be as complete as possible in documenting +libev, its usage and the rationale behind its design, it is not a tutorial +on event-based programming, nor will it introduce event-based programming +with libev. + +Familiarity with event based programming techniques in general is assumed +throughout this document. + +=head1 WHAT TO READ WHEN IN A HURRY + +This manual tries to be very detailed, but unfortunately, this also makes +it very long. If you just want to know the basics of libev, I suggest +reading L, then the L above and +look up the missing functions in L and the C and +C sections in L. + +=head1 ABOUT LIBEV Libev is an event loop: you register interest in certain events (such as a -file descriptor being readable or a timeout occuring), and it will manage +file descriptor being readable or a timeout occurring), and it will manage these event sources and provide your program with events. To do this, it must take more or less complete control over your process @@ -21,34 +105,69 @@ details of the event, and then hand it over to libev by I the watcher. -=head1 FEATURES +=head2 FEATURES + +Libev supports C (files, many character devices...). + +Epoll is truly the train wreck among event poll mechanisms, a frankenpoll, +cobbled together in a hurry, no thought to design or interaction with +others. Oh, the pain, will it ever stop... + +While stopping, setting and starting an I/O watcher in the same iteration +will result in some caching, there is still a system call per such +incident (because the same I could point to a different +I now), so its best to avoid that. Also, C'ed +file descriptors might not work very well if you register events for both +file descriptors. + +Best performance from this backend is achieved by not unregistering all +watchers for a file descriptor until it has been closed, if possible, +i.e. keep at least one watcher active per fd at all times. Stopping and +starting a watcher (without re-setting it) also usually doesn't cause +extra overhead. A fork can both result in spurious notifications as well +as in libev having to destroy and recreate the epoll object, which can +take considerable time and thus should be avoided. + +All this means that, in practice, C can be as fast or +faster than epoll for maybe up to a hundred file descriptors, depending on +the usage. So sad. + +While nominally embeddable in other event loops, this feature is broken in +a lot of kernel revisions, but probably(!) works in current versions. + +This backend maps C and C in the same way as +C. + +=item C (value 64, Linux) + +Use the Linux-specific Linux AIO (I C<< aio(7) >> but C<< +io_submit(2) >>) event interface available in post-4.18 kernels (but libev +only tries to use it in 4.19+). + +This is another Linux train wreck of an event interface. + +If this backend works for you (as of this writing, it was very +experimental), it is the best event interface available on Linux and might +be well worth enabling it - if it isn't available in your kernel this will +be detected and this backend will be skipped. + +This backend can batch oneshot requests and supports a user-space ring +buffer to receive events. It also doesn't suffer from most of the design +problems of epoll (such as not being able to remove event sources from +the epoll set), and generally sounds too good to be true. Because, this +being the Linux kernel, of course it suffers from a whole new set of +limitations, forcing you to fall back to epoll, inheriting all its design +issues. + +For one, it is not easily embeddable (but probably could be done using +an event fd at some extra overhead). It also is subject to a system wide +limit that can be configured in F. If no AIO +requests are left, this backend will be skipped during initialisation, and +will switch to epoll when the loop is active. + +Most problematic in practice, however, is that not all file descriptors +work with it. For example, in Linux 5.1, TCP sockets, pipes, event fds, +files, F and many others are supported, but ttys do not work +properly (a known bug that the kernel developers don't care about, see +L), so this is not +(yet?) a generic event polling interface. + +Overall, it seems the Linux developers just don't want it to have a +generic event handling mechanism other than C which have a high +overhead for the actual polling but can deliver many events at once. + +By setting a higher I you allow libev to spend more +time collecting I/O events, so you can handle more events per iteration, +at the cost of increasing latency. Timeouts (both C and +C) will not be affected. Setting this to a non-null value will +introduce an additional C call into most loop iterations. The +sleep time ensures that libev will not poll for I/O events more often then +once per this interval, on average (as long as the host time resolution is +good enough). + +Likewise, by setting a higher I you allow libev +to spend more time collecting timeouts, at the expense of increased +latency/jitter/inexactness (the watcher callback will be called +later). C watchers will not be affected. Setting this to a non-null +value will not introduce any overhead in libev. + +Many (busy) programs can usually benefit by setting the I/O collect +interval to a value near C<0.1> or so, which is often enough for +interactive servers (of course not for games), likewise for timeouts. It +usually doesn't make much sense to set it to a lower value than C<0.01>, +as this approaches the timing granularity of most systems. Note that if +you do transactions with the outside world and you can't increase the +parallelity, then this setting will limit your transaction rate (if you +need to poll once per transaction and the I/O collect interval is 0.01, +then you can't do more than 100 transactions per second). + +Setting the I can improve the opportunity for +saving power, as the program will "bundle" timer callback invocations that +are "near" in time together, by delaying some, thus reducing the number of +times the process sleeps and wakes up again. Another useful technique to +reduce iterations/wake-ups is to use C watchers and make sure +they fire on, say, one-second boundaries only. + +Example: we only need 0.1s timeout granularity, and we wish not to poll +more often than 100 times per second: + + ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1); + ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01); + +=item ev_invoke_pending (loop) + +This call will simply invoke all pending watchers while resetting their +pending state. Normally, C does this automatically when required, +but when overriding the invoke callback this call comes handy. This +function can be invoked from a watcher - this can be useful for example +when you want to do some lengthy calculation and want to pass further +event handling to another thread (you still have to make sure only one +thread executes within C or C of course). + +=item int ev_pending_count (loop) + +Returns the number of pending watchers - zero indicates that no watchers +are pending. + +=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P)) + +This overrides the invoke pending functionality of the loop: Instead of +invoking all pending watchers when there are any, C will call +this callback instead. This is useful, for example, when you want to +invoke the actual watchers inside another context (another thread etc.). + +If you want to reset the callback, use C as new +callback. + +=item ev_set_loop_release_cb (loop, void (*release)(EV_P) throw (), void (*acquire)(EV_P) throw ()) + +Sometimes you want to share the same loop between multiple threads. This +can be done relatively simply by putting mutex_lock/unlock calls around +each call to a libev function. + +However, C can run an indefinite time, so it is not feasible +to wait for it to return. One way around this is to wake up the event +loop via C and C, another way is to set these +I and I callbacks on the loop. + +When set, then C will be called just before the thread is +suspended waiting for new events, and C is called just +afterwards. -Example: for some weird reason, unregister the above signal handler again. +Ideally, C will just call your mutex_unlock function, and +C will just call the mutex_lock function again. - ev_ref (myloop); - ev_signal_stop (myloop, &exitsig); +While event loop modifications are allowed between invocations of +C and C (that's their only purpose after all), no +modifications done will affect the event loop, i.e. adding watchers will +have no effect on the set of file descriptors being watched, or the time +waited. Use an C watcher to wake up C when you want it +to take note of any changes you made. + +In theory, threads executing C will be async-cancel safe between +invocations of C and C. + +See also the locking example in the C section later in this +document. + +=item ev_set_userdata (loop, void *data) + +=item void *ev_userdata (loop) + +Set and retrieve a single C associated with a loop. When +C has never been called, then C returns +C<0>. + +These two functions can be used to associate arbitrary data with a loop, +and are intended solely for the C, C and +C callbacks described above, but of course can be (ab-)used for +any other purpose as well. + +=item ev_verify (loop) + +This function only does something when C support has been +compiled in, which is the default for non-minimal builds. It tries to go +through all internal structures and checks them for validity. If anything +is found to be inconsistent, it will print an error message to standard +error and call C. + +This can be used to catch bugs inside libev itself: under normal +circumstances, this function will never abort as of course libev keeps its +data structures consistent. =back =head1 ANATOMY OF A WATCHER -A watcher is a structure that you create and register to record your -interest in some event. For instance, if you want to wait for STDIN to -become readable, you would create an C watcher for that: +In the following description, uppercase C in names stands for the +watcher type, e.g. C can mean C for timer +watchers and C for I/O watchers. + +A watcher is an opaque structure that you allocate and register to record +your interest in some event. To make a concrete example, imagine you want +to wait for STDIN to become readable, you would create an C watcher +for that: - static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) - { - ev_io_stop (w); - ev_unloop (loop, EVUNLOOP_ALL); - } + static void my_cb (struct ev_loop *loop, ev_io *w, int revents) + { + ev_io_stop (w); + ev_break (loop, EVBREAK_ALL); + } + + struct ev_loop *loop = ev_default_loop (0); + + ev_io stdin_watcher; + + ev_init (&stdin_watcher, my_cb); + ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); + ev_io_start (loop, &stdin_watcher); - struct ev_loop *loop = ev_default_loop (0); - struct ev_io stdin_watcher; - ev_init (&stdin_watcher, my_cb); - ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); - ev_io_start (loop, &stdin_watcher); - ev_loop (loop, 0); + ev_run (loop, 0); As you can see, you are responsible for allocating the memory for your -watcher structures (and it is usually a bad idea to do this on the stack, -although this can sometimes be quite valid). +watcher structures (and it is I a bad idea to do this on the +stack). -Each watcher structure must be initialised by a call to C, which expects a callback to be provided. This -callback gets invoked each time the event occurs (or, in the case of io -watchers, each time the event loop detects that the file descriptor given -is readable and/or writable). - -Each watcher type has its own C<< ev__set (watcher *, ...) >> macro -with arguments specific to this watcher type. There is also a macro -to combine initialisation and setting in one call: C<< ev__init -(watcher *, callback, ...) >>. +Each watcher has an associated watcher structure (called C +or simply C, as typedefs are provided for all watcher structs). + +Each watcher structure must be initialised by a call to C, which expects a callback to be provided. This callback is +invoked each time the event occurs (or, in the case of I/O watchers, each +time the event loop detects that the file descriptor given is readable +and/or writable). + +Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >> +macro to configure it, with arguments specific to the watcher type. There +is also a macro to combine initialisation and setting in one call: C<< +ev_TYPE_init (watcher *, callback, ...) >>. To make the watcher actually watch out for events, you have to start it -with a watcher-specific start function (C<< ev__start (loop, watcher +with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher *) >>), and you can stop watching for events at any time by calling the -corresponding stop function (C<< ev__stop (loop, watcher *) >>. +corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>. As long as your watcher is active (has been started but not stopped) you must not touch the values stored in it. Most specifically you must never -reinitialise it or call its C macro. +reinitialise it or call its C macro. Each and every callback receives the event loop pointer as first, the registered watcher structure as second, and a bitset of received events as @@ -531,7 +1240,7 @@ The file descriptor in the C watcher has become readable and/or writable. -=item C +=item C The C watcher has timed out. @@ -547,6 +1256,10 @@ The pid specified in the C watcher has received a status change. +=item C + +The path specified in the C watcher changed its attributes somehow. + =item C The C watcher has determined that you have nothing better to do. @@ -555,35 +1268,64 @@ =item C -All C watchers are invoked just I C starts -to gather new events, and all C watchers are invoked just after -C has gathered them, but before it invokes any callbacks for any -received events. Callbacks of both watcher types can start and stop as -many watchers as they want, and all of them will be taken into account -(for example, a C watcher might start an idle watcher to keep -C from blocking). +All C watchers are invoked just I C starts to +gather new events, and all C watchers are queued (not invoked) +just after C has gathered them, but before it queues any callbacks +for any received events. That means C watchers are the last +watchers invoked before the event loop sleeps or polls for new events, and +C watchers will be invoked before any other watchers of the same +or lower priority within an event loop iteration. + +Callbacks of both watcher types can start and stop as many watchers as +they want, and all of them will be taken into account (for example, a +C watcher might start an idle watcher to keep C from +blocking). + +=item C + +The embedded event loop specified in the C watcher needs attention. + +=item C + +The event loop has been resumed in the child process after fork (see +C). + +=item C + +The event loop is about to be destroyed (see C). + +=item C + +The given async watcher has been asynchronously notified (see C). + +=item C + +Not ever sent (or otherwise used) by libev itself, but can be freely used +by libev users to signal watchers (e.g. via C). =item C -An unspecified error has occured, the watcher has been stopped. This might +An unspecified error has occurred, the watcher has been stopped. This might happen because the watcher could not be properly started because libev ran out of memory, a file descriptor was found to be closed or any other -problem. You best act on it by reporting the problem and somehow coping -with the watcher being stopped. +problem. Libev considers these application bugs. -Libev will usually signal a few "dummy" events together with an error, -for example it might indicate that a fd is readable or writable, and if -your callbacks is well-written it can just attempt the operation and cope -with the error from read() or write(). This will not work in multithreaded -programs, though, so beware. +You best act on it by reporting the problem and somehow coping with the +watcher being stopped. Note that well-written programs should not receive +an error ever, so when your watcher receives it, this usually indicates a +bug in your program. + +Libev will usually signal a few "dummy" events together with an error, for +example it might indicate that a fd is readable or writable, and if your +callbacks is well-written it can just attempt the operation and cope with +the error from read() or write(). This will not work in multi-threaded +programs, though, as the fd could already be closed and reused for another +thing, so beware. =back =head2 GENERIC WATCHER FUNCTIONS -In the following description, C stands for the watcher type, -e.g. C for C watchers and C for C watchers. - =over 4 =item C (ev_TYPE *watcher, callback) @@ -598,10 +1340,16 @@ You can reinitialise a watcher at any time as long as it has been stopped (or never started) and there are no pending events outstanding. -The callback is always of type C. -=item C (ev_TYPE *, [args]) +Example: Initialise an C watcher in two steps. + + ev_io w; + ev_init (&w, my_cb); + ev_io_set (&w, STDIN_FILENO, EV_READ); + +=item C (ev_TYPE *watcher, [args]) This macro initialises the type-specific parts of a watcher. You need to call C at least once before you call this macro, but you can @@ -612,25 +1360,38 @@ Although some watcher types do not have type-specific arguments (e.g. C) you still need to call its C macro. +See C, above, for an example. + =item C (ev_TYPE *watcher, callback, [args]) -This convinience macro rolls both C and C macro -calls into a single call. This is the most convinient method to initialise +This convenience macro rolls both C and C macro +calls into a single call. This is the most convenient method to initialise a watcher. The same limitations apply, of course. -=item C (loop *, ev_TYPE *watcher) +Example: Initialise and set an C watcher in one step. + + ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); + +=item C (loop, ev_TYPE *watcher) Starts (activates) the given watcher. Only active watchers will receive events. If the watcher is already active nothing will happen. -=item C (loop *, ev_TYPE *watcher) +Example: Start the C watcher that is being abused as example in this +whole section. + + ev_io_start (EV_DEFAULT_UC, &w); + +=item C (loop, ev_TYPE *watcher) + +Stops the given watcher if active, and clears the pending status (whether +the watcher was active or not). -Stops the given watcher again (if active) and clears the pending -status. It is possible that stopped watchers are pending (for example, -non-repeating timers are being stopped when they become pending), but -C ensures that the watcher is neither active nor pending. If -you want to free or reuse the memory used by the watcher it is therefore a -good idea to always call its C function. +It is possible that stopped watchers are pending - for example, +non-repeating timers are being stopped when they become pending - but +calling C ensures that the watcher is neither active nor +pending. If you want to free or reuse the memory used by the watcher it is +therefore a good idea to always call its C function. =item bool ev_is_active (ev_TYPE *watcher) @@ -643,55 +1404,260 @@ Returns a true value iff the watcher is pending, (i.e. it has outstanding events but its callback has not yet been invoked). As long as a watcher is pending (but not active) you must not call an init function on it (but -C is safe) and you must make sure the watcher is available to -libev (e.g. you cnanot C it). +C is safe), you must not change its priority, and you must +make sure the watcher is available to libev (e.g. you cannot C +it). -=item callback = ev_cb (ev_TYPE *watcher) +=item callback ev_cb (ev_TYPE *watcher) Returns the callback currently set on the watcher. -=item ev_cb_set (ev_TYPE *watcher, callback) +=item ev_set_cb (ev_TYPE *watcher, callback) Change the callback. You can change the callback at virtually any time (modulo threads). +=item ev_set_priority (ev_TYPE *watcher, int priority) + +=item int ev_priority (ev_TYPE *watcher) + +Set and query the priority of the watcher. The priority is a small +integer between C (default: C<2>) and C +(default: C<-2>). Pending watchers with higher priority will be invoked +before watchers with lower priority, but priority will not keep watchers +from being executed (except for C watchers). + +If you need to suppress invocation when higher priority events are pending +you need to look at C watchers, which provide this functionality. + +You I change the priority of a watcher as long as it is active or +pending. + +Setting a priority outside the range of C to C is +fine, as long as you do not mind that the priority value you query might +or might not have been clamped to the valid range. + +The default priority used by watchers when no priority has been set is +always C<0>, which is supposed to not be too high and not be too low :). + +See L, below, for a more thorough treatment of +priorities. + +=item ev_invoke (loop, ev_TYPE *watcher, int revents) + +Invoke the C with the given C and C. Neither +C nor C need to be valid as long as the watcher callback +can deal with that fact, as both are simply passed through to the +callback. + +=item int ev_clear_pending (loop, ev_TYPE *watcher) + +If the watcher is pending, this function clears its pending status and +returns its C bitset (as if its callback was invoked). If the +watcher isn't pending it does nothing and returns C<0>. + +Sometimes it can be useful to "poll" a watcher instead of waiting for its +callback to be invoked, which can be accomplished with this function. + +=item ev_feed_event (loop, ev_TYPE *watcher, int revents) + +Feeds the given event set into the event loop, as if the specified event +had happened for the specified watcher (which must be a pointer to an +initialised but not necessarily started event watcher). Obviously you must +not free the watcher as long as it has pending events. + +Stopping the watcher, letting libev invoke it, or calling +C will clear the pending event, even if the watcher was +not started in the first place. + +See also C and C for related +functions that do not need a watcher. + =back +See also the L and L idioms. -=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER +=head2 WATCHER STATES -Each watcher has, by default, a member C that you can change -and read at any time, libev will completely ignore it. This can be used -to associate arbitrary data with your watcher. If you need more data and -don't want to allocate memory and store a pointer to it in that data -member, you can also "subclass" the watcher type and provide your own -data: +There are various watcher states mentioned throughout this manual - +active, pending and so on. In this section these states and the rules to +transition between them will be described in more detail - and while these +rules might look complicated, they usually do "the right thing". - struct my_io - { - struct ev_io io; - int otherfd; - void *somedata; - struct whatever *mostinteresting; - } +=over 4 -And since your callback will be called with a pointer to the watcher, you -can cast it back to your own type: +=item initialised - static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) - { - struct my_io *w = (struct my_io *)w_; - ... - } +Before a watcher can be registered with the event loop it has to be +initialised. This can be done with a call to C, or calls to +C followed by the watcher-specific C function. + +In this state it is simply some block of memory that is suitable for +use in an event loop. It can be moved around, freed, reused etc. at +will - as long as you either keep the memory contents intact, or call +C again. + +=item started/running/active + +Once a watcher has been started with a call to C it becomes +property of the event loop, and is actively waiting for events. While in +this state it cannot be accessed (except in a few documented ways), moved, +freed or anything else - the only legal thing is to keep a pointer to it, +and call libev functions on it that are documented to work on active watchers. + +=item pending + +If a watcher is active and libev determines that an event it is interested +in has occurred (such as a timer expiring), it will become pending. It will +stay in this pending state until either it is stopped or its callback is +about to be invoked, so it is not normally pending inside the watcher +callback. + +The watcher might or might not be active while it is pending (for example, +an expired non-repeating timer can be pending but no longer active). If it +is stopped, it can be freely accessed (e.g. by calling C), +but it is still property of the event loop at this time, so cannot be +moved, freed or reused. And if it is active the rules described in the +previous item still apply. + +It is also possible to feed an event on a watcher that is not active (e.g. +via C), in which case it becomes pending without being +active. + +=item stopped + +A watcher can be stopped implicitly by libev (in which case it might still +be pending), or explicitly by calling its C function. The +latter will clear any pending state the watcher might be in, regardless +of whether it was active or not, so stopping a watcher explicitly before +freeing it is often a good idea. + +While stopped (and not pending) the watcher is essentially in the +initialised state, that is, it can be reused, moved, modified in any way +you wish (but when you trash the memory block, you need to C +it again). + +=back + +=head2 WATCHER PRIORITY MODELS -More interesting and less C-conformant ways of catsing your callback type -have been omitted.... +Many event loops support I, which are usually small +integers that influence the ordering of event callback invocation +between watchers in some way, all else being equal. + +In libev, watcher priorities can be set using C. See its +description for the more technical details such as the actual priority +range. + +There are two common ways how these these priorities are being interpreted +by event loops: + +In the more common lock-out model, higher priorities "lock out" invocation +of lower priority watchers, which means as long as higher priority +watchers receive events, lower priority watchers are not being invoked. + +The less common only-for-ordering model uses priorities solely to order +callback invocation within a single event loop iteration: Higher priority +watchers are invoked before lower priority ones, but they all get invoked +before polling for new events. + +Libev uses the second (only-for-ordering) model for all its watchers +except for idle watchers (which use the lock-out model). + +The rationale behind this is that implementing the lock-out model for +watchers is not well supported by most kernel interfaces, and most event +libraries will just poll for the same events again and again as long as +their callbacks have not been executed, which is very inefficient in the +common case of one high-priority watcher locking out a mass of lower +priority ones. + +Static (ordering) priorities are most useful when you have two or more +watchers handling the same resource: a typical usage example is having an +C watcher to receive data, and an associated C to handle +timeouts. Under load, data might be received while the program handles +other jobs, but since timers normally get invoked first, the timeout +handler will be executed before checking for data. In that case, giving +the timer a lower priority than the I/O watcher ensures that I/O will be +handled first even under adverse conditions (which is usually, but not +always, what you want). + +Since idle watchers use the "lock-out" model, meaning that idle watchers +will only be executed when no same or higher priority watchers have +received events, they can be used to implement the "lock-out" model when +required. + +For example, to emulate how many other event libraries handle priorities, +you can associate an C watcher to each such watcher, and in +the normal watcher callback, you just start the idle watcher. The real +processing is done in the idle watcher callback. This causes libev to +continuously poll and process kernel event data for the watcher, but when +the lock-out case is known to be rare (which in turn is rare :), this is +workable. + +Usually, however, the lock-out model implemented that way will perform +miserably under the type of load it was designed to handle. In that case, +it might be preferable to stop the real watcher before starting the +idle watcher, so the kernel will not have to process the event in case +the actual processing will be delayed for considerable time. + +Here is an example of an I/O watcher that should run at a strictly lower +priority than the default, and which should only process data when no +other events are pending: + + ev_idle idle; // actual processing watcher + ev_io io; // actual event watcher + + static void + io_cb (EV_P_ ev_io *w, int revents) + { + // stop the I/O watcher, we received the event, but + // are not yet ready to handle it. + ev_io_stop (EV_A_ w); + + // start the idle watcher to handle the actual event. + // it will not be executed as long as other watchers + // with the default priority are receiving events. + ev_idle_start (EV_A_ &idle); + } + + static void + idle_cb (EV_P_ ev_idle *w, int revents) + { + // actual processing + read (STDIN_FILENO, ...); + + // have to start the I/O watcher again, as + // we have handled the event + ev_io_start (EV_P_ &io); + } + + // initialisation + ev_idle_init (&idle, idle_cb); + ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ); + ev_io_start (EV_DEFAULT_ &io); + +In the "real" world, it might also be beneficial to start a timer, so that +low-priority connections can not be locked out forever under load. This +enables your program to keep a lower latency for important connections +during short periods of high load, while not completely locking out less +important ones. =head1 WATCHER TYPES This section describes each watcher in detail, but will not repeat -information given in the last section. +information given in the last section. Any initialisation/set macros, +functions and members specific to the watcher type are explained. + +Members are additionally marked with either I<[read-only]>, meaning that, +while the watcher is active, you can look at the member and expect some +sensible content, but you must not modify it (you can modify it while the +watcher is stopped to your hearts content), or I<[read-write]>, which +means you can expect it to have some sensible content while the watcher +is active, but you can also modify it. Modifying it may not do something +sensible or take immediate effect (or do anything at all), but libev will +not crash or malfunction in any way. =head2 C - is this file descriptor readable or writable? @@ -709,30 +1675,151 @@ descriptors to non-blocking mode is also usually a good idea (but not required if you know what you are doing). -You have to be careful with dup'ed file descriptors, though. Some backends -(the linux epoll backend is a notable example) cannot handle dup'ed file -descriptors correctly if you register interest in two or more fds pointing -to the same underlying file/socket/etc. description (that is, they share -the same underlying "file open"). - -If you must do this, then force the use of a known-to-be-good backend -(at the time of this writing, this includes only C and -C). - Another thing you have to watch out for is that it is quite easy to -receive "spurious" readyness notifications, that is your callback might +receive "spurious" readiness notifications, that is, your callback might be called with C but a subsequent C(2) will actually block -because there is no data. Not only are some backends known to create a -lot of those (for example solaris ports), it is very easy to get into -this situation even with a relatively standard program structure. Thus -it is best to always use non-blocking I/O: An extra C(2) returning -C is far preferable to a program hanging until some data arrives. - -If you cannot run the fd in non-blocking mode (for example you should not -play around with an Xlib connection), then you have to seperately re-test -wether a file descriptor is really ready with a known-to-be good interface -such as poll (fortunately in our Xlib example, Xlib already does this on -its own, so its quite safe to use). +because there is no data. It is very easy to get into this situation even +with a relatively standard program structure. Thus it is best to always +use non-blocking I/O: An extra C(2) returning C is far +preferable to a program hanging until some data arrives. + +If you cannot run the fd in non-blocking mode (for example you should +not play around with an Xlib connection), then you have to separately +re-test whether a file descriptor is really ready with a known-to-be good +interface such as poll (fortunately in the case of Xlib, it already does +this on its own, so its quite safe to use). Some people additionally +use C and an interval timer, just to be sure you won't block +indefinitely. + +But really, best use non-blocking mode. + +=head3 The special problem of disappearing file descriptors + +Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing +a file descriptor (either due to calling C explicitly or any other +means, such as C). The reason is that you register interest in some +file descriptor, but when it goes away, the operating system will silently +drop this interest. If another file descriptor with the same number then +is registered with libev, there is no efficient way to see that this is, +in fact, a different file descriptor. + +To avoid having to explicitly tell libev about such cases, libev follows +the following policy: Each time C is being called, libev +will assume that this is potentially a new file descriptor, otherwise +it is assumed that the file descriptor stays the same. That means that +you I to call C (or C) when you change the +descriptor even if the file descriptor number itself did not change. + +This is how one would do it normally anyway, the important point is that +the libev application should not optimise around libev but should leave +optimisations to libev. + +=head3 The special problem of dup'ed file descriptors + +Some backends (e.g. epoll), cannot register events for file descriptors, +but only events for the underlying file descriptions. That means when you +have C'ed file descriptors or weirder constellations, and register +events for them, only one file descriptor might actually receive events. + +There is no workaround possible except not registering events +for potentially C'ed file descriptors, or to resort to +C or C. + +=head3 The special problem of files + +Many people try to use C. + +=item EV_USE_EVENTFD + +If defined to be C<1>, then libev will assume that C is +available and will probe for kernel support at runtime. This will improve +C and C performance and reduce resource consumption. +If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc +2.7 or newer, otherwise disabled. + +=item EV_USE_SIGNALFD + +If defined to be C<1>, then libev will assume that C is +available and will probe for kernel support at runtime. This enables +the use of EVFLAG_SIGNALFD for faster and simpler signal handling. If +undefined, it will be enabled if the headers indicate GNU/Linux + Glibc +2.7 or newer, otherwise disabled. + +=item EV_USE_TIMERFD + +If defined to be C<1>, then libev will assume that C is +available and will probe for kernel support at runtime. This allows +libev to detect time jumps accurately. If undefined, it will be enabled +if the headers indicate GNU/Linux + Glibc 2.8 or newer and define +C, otherwise disabled. + +=item EV_USE_EVENTFD + +If defined to be C<1>, then libev will assume that C is +available and will probe for kernel support at runtime. This will improve +C and C performance and reduce resource consumption. +If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc +2.7 or newer, otherwise disabled. =item EV_USE_SELECT If undefined or defined to be C<1>, libev will compile in support for the -C(2) backend. No attempt at auto-detection will be done: if no other method takes over, select will be it. Otherwise the select backend will not be compiled in. @@ -1618,11 +4661,11 @@ If defined to C<1>, then the select backend will use the system C structure. This is useful if libev doesn't compile due to a missing -C or C definition or it misguesses the bitset layout on -exotic systems. This usually limits the range of file descriptors to some -low limit such as 1024 or might have other limitations (winsocket only -allows 64 sockets). The C macro, set before compilation, might -influence the size of the C used. +C or C definition or it mis-guesses the bitset layout +on exotic systems. This usually limits the range of file descriptors to +some low limit such as 1024 or might have other limitations (winsocket +only allows 64 sockets). The C macro, set before compilation, +configures the maximum size of the C. =item EV_SELECT_IS_WINSOCKET @@ -1634,6 +4677,35 @@ it is assumed that all these functions actually work on fds, even on win32. Should not be defined on non-win32 platforms. +=item EV_FD_TO_WIN32_HANDLE(fd) + +If C is enabled, then libev needs a way to map +file descriptors to socket handles. When not defining this symbol (the +default), then libev will call C<_get_osfhandle>, which is usually +correct. In some cases, programs use their own file descriptor management, +in which case they can provide this function to map fds to socket handles. + +=item EV_WIN32_HANDLE_TO_FD(handle) + +If C then libev maps handles to file descriptors +using the standard C<_open_osfhandle> function. For programs implementing +their own fd to handle mapping, overwriting this function makes it easier +to do so. This can be done by defining this macro to an appropriate value. + +=item EV_WIN32_CLOSE_FD(fd) + +If programs implement their own fd to handle mapping on win32, then this +macro can be used to override the C function, useful to unregister +file descriptors again. Note that the replacement function has to close +the underlying OS handle. + +=item EV_USE_WSASOCKET + +If defined to be C<1>, libev will use C to create its internal +communication socket, which works better in some environments. Otherwise, +the normal C function will be used, which works better in other +environments. + =item EV_USE_POLL If defined to be C<1>, libev will compile in support for the C(2) @@ -1644,8 +4716,22 @@ If defined to be C<1>, libev will compile in support for the Linux C(7) backend. Its availability will be detected at runtime, -otherwise another method will be used as fallback. This is the -preferred backend for GNU/Linux systems. +otherwise another method will be used as fallback. This is the preferred +backend for GNU/Linux systems. If undefined, it will be enabled if the +headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. + +=item EV_USE_LINUXAIO + +If defined to be C<1>, libev will compile in support for the Linux aio +backend (C must also be enabled). If undefined, it will be +enabled on linux, otherwise disabled. + +=item EV_USE_IOURING + +If defined to be C<1>, libev will compile in support for the Linux +io_uring backend (C must also be enabled). Due to it's +current limitations it has to be requested explicitly. If undefined, it +will be enabled on linux, otherwise disabled. =item EV_USE_KQUEUE @@ -1668,26 +4754,59 @@ =item EV_USE_DEVPOLL -reserved for future expansion, works like the USE symbols above. +Reserved for future expansion, works like the USE symbols above. + +=item EV_USE_INOTIFY + +If defined to be C<1>, libev will compile in support for the Linux inotify +interface to speed up C watchers. Its actual availability will +be detected at runtime. If undefined, it will be enabled if the headers +indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. + +=item EV_NO_SMP + +If defined to be C<1>, libev will assume that memory is always coherent +between threads, that is, threads can be used, but threads never run on +different cpus (or different cpu cores). This reduces dependencies +and makes libev faster. + +=item EV_NO_THREADS -=item EV_H +If defined to be C<1>, libev will assume that it will never be called from +different threads (that includes signal handlers), which is a stronger +assumption than C, above. This reduces dependencies and makes +libev faster. + +=item EV_ATOMIC_T + +Libev requires an integer type (suitable for storing C<0> or C<1>) whose +access is atomic with respect to other threads or signal contexts. No +such type is easily found in the C language, so you can provide your own +type that you know is safe for your purposes. It is used both for signal +handler "locking" as well as for signal and thread safety in C +watchers. + +In the absence of this define, libev will use C +(from F), which is usually good enough on most platforms. + +=item EV_H (h) The name of the F header file used to include it. The default if -undefined is C<< >> in F and C<"ev.h"> in F. This -can be used to virtually rename the F header file in case of conflicts. +undefined is C<"ev.h"> in F, F and F. This can be +used to virtually rename the F header file in case of conflicts. -=item EV_CONFIG_H +=item EV_CONFIG_H (h) If C isn't C<1>, this variable can be used to override F's idea of where to find the F file, similarly to C, above. -=item EV_EVENT_H +=item EV_EVENT_H (h) Similarly to C, this macro can be used to override F's idea -of how the F header can be found. +of how the F header can be found, the default is C<"event.h">. -=item EV_PROTOTYPES +=item EV_PROTOTYPES (h) If defined to be C<0>, then F will not define any function prototypes, but still define all the structs and other symbols. This is @@ -1702,23 +4821,222 @@ for multiple event loops and there is no first event loop pointer argument. Instead, all functions act on the single default loop. -=item EV_PERIODICS +Note that C and C will no longer provide a +default loop when multiplicity is switched off - you always have to +initialise the loop manually in this case. + +=item EV_MINPRI + +=item EV_MAXPRI + +The range of allowed priorities. C must be smaller or equal to +C, but otherwise there are no non-obvious limitations. You can +provide for more priorities by overriding those symbols (usually defined +to be C<-2> and C<2>, respectively). + +When doing priority-based operations, libev usually has to linearly search +all the priorities, so having many of them (hundreds) uses a lot of space +and time, so using the defaults of five priorities (-2 .. +2) is usually +fine. + +If your embedding application does not need any priorities, defining these +both to C<0> will save some memory and CPU. + +=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE, +EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE, +EV_ASYNC_ENABLE, EV_CHILD_ENABLE. + +If undefined or defined to be C<1> (and the platform supports it), then +the respective watcher type is supported. If defined to be C<0>, then it +is not. Disabling watcher types mainly saves code size. + +=item EV_FEATURES + +If you need to shave off some kilobytes of code at the expense of some +speed (but with the full API), you can define this symbol to request +certain subsets of functionality. The default is to enable all features +that can be enabled on the platform. + +A typical way to use this symbol is to define it to C<0> (or to a bitset +with some broad features you want) and then selectively re-enable +additional parts you want, for example if you want everything minimal, +but multiple event loop support, async and child watchers and the poll +backend, use this: + + #define EV_FEATURES 0 + #define EV_MULTIPLICITY 1 + #define EV_USE_POLL 1 + #define EV_CHILD_ENABLE 1 + #define EV_ASYNC_ENABLE 1 + +The actual value is a bitset, it can be a combination of the following +values (by default, all of these are enabled): + +=over 4 -If undefined or defined to be C<1>, then periodic timers are supported, -otherwise not. This saves a few kb of code. +=item C<1> - faster/larger code + +Use larger code to speed up some operations. + +Currently this is used to override some inlining decisions (enlarging the +code size by roughly 30% on amd64). + +When optimising for size, use of compiler flags such as C<-Os> with +gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of +assertions. + +The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler +(e.g. gcc with C<-Os>). + +=item C<2> - faster/larger data structures + +Replaces the small 2-heap for timer management by a faster 4-heap, larger +hash table sizes and so on. This will usually further increase code size +and can additionally have an effect on the size of data structures at +runtime. + +The default is off when C<__OPTIMIZE_SIZE__> is defined by your compiler +(e.g. gcc with C<-Os>). + +=item C<4> - full API configuration + +This enables priorities (sets C=2 and C=-2), and +enables multiplicity (C=1). + +=item C<8> - full API + +This enables a lot of the "lesser used" API functions. See C for +details on which parts of the API are still available without this +feature, and do not complain if this subset changes over time. + +=item C<16> - enable all optional watcher types + +Enables all optional watcher types. If you want to selectively enable +only some watcher types other than I/O and timers (e.g. prepare, +embed, async, child...) you can enable them manually by defining +C to C<1> instead. + +=item C<32> - enable all backends + +This enables all backends - without this feature, you need to enable at +least one backend manually (C is a good choice). + +=item C<64> - enable OS-specific "helper" APIs + +Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by +default. + +=back + +Compiling with C +reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb +code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O +watchers, timers and monotonic clock support. + +With an intelligent-enough linker (gcc+binutils are intelligent enough +when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by +your program might be left out as well - a binary starting a timer and an +I/O watcher then might come out at only 5Kb. + +=item EV_API_STATIC + +If this symbol is defined (by default it is not), then all identifiers +will have static linkage. This means that libev will not export any +identifiers, and you cannot link against libev anymore. This can be useful +when you embed libev, only want to use libev functions in a single file, +and do not want its identifiers to be visible. + +To use this, define C and include F in the file that +wants to use libev. + +This option only works when libev is compiled with a C compiler, as C++ +doesn't support the required declaration syntax. + +=item EV_AVOID_STDIO + +If this is set to C<1> at compiletime, then libev will avoid using stdio +functions (printf, scanf, perror etc.). This will increase the code size +somewhat, but if your program doesn't otherwise depend on stdio and your +libc allows it, this avoids linking in the stdio library which is quite +big. + +Note that error messages might become less precise when this option is +enabled. + +=item EV_NSIG + +The highest supported signal number, +1 (or, the number of +signals): Normally, libev tries to deduce the maximum number of signals +automatically, but sometimes this fails, in which case it can be +specified. Also, using a lower number than detected (C<32> should be +good for about any system in existence) can save some memory, as libev +statically allocates some 12-24 bytes per signal number. + +=item EV_PID_HASHSIZE + +C watchers use a small hash table to distribute workload by +pid. The default size is C<16> (or C<1> with C disabled), +usually more than enough. If you need to manage thousands of children you +might want to increase this value (I be a power of two). + +=item EV_INOTIFY_HASHSIZE + +C watchers use a small hash table to distribute workload by +inotify watch id. The default size is C<16> (or C<1> with C +disabled), usually more than enough. If you need to manage thousands of +C watchers you might want to increase this value (I be a +power of two). + +=item EV_USE_4HEAP + +Heaps are not very cache-efficient. To improve the cache-efficiency of the +timer and periodics heaps, libev uses a 4-heap when this symbol is defined +to C<1>. The 4-heap uses more complicated (longer) code but has noticeably +faster performance with many (thousands) of watchers. + +The default is C<1>, unless C overrides it, in which case it +will be C<0>. + +=item EV_HEAP_CACHE_AT + +Heaps are not very cache-efficient. To improve the cache-efficiency of the +timer and periodics heaps, libev can cache the timestamp (I) within +the heap structure (selected by defining C to C<1>), +which uses 8-12 bytes more per watcher and a few hundred bytes more code, +but avoids random read accesses on heap changes. This improves performance +noticeably with many (hundreds) of watchers. + +The default is C<1>, unless C overrides it, in which case it +will be C<0>. + +=item EV_VERIFY + +Controls how much internal verification (see C) will +be done: If set to C<0>, no internal verification code will be compiled +in. If set to C<1>, then verification code will be compiled in, but not +called. If set to C<2>, then the internal verification code will be +called once per loop, which can slow down libev. If set to C<3>, then the +verification code will be called very frequently, which will slow down +libev considerably. + +Verification errors are reported via C's C mechanism, so if you +disable that (e.g. by defining C) then no errors will be reported. + +The default is C<1>, unless C overrides it, in which case it +will be C<0>. =item EV_COMMON By default, all watchers have a C member. By redefining -this macro to a something else you can include more and other types of +this macro to something else you can include more and other types of members. You have to define it each time you include one of the files, though, and it must be identical each time. For example, the perl EV module uses something like this: - #define EV_COMMON \ - SV *self; /* contains this struct */ \ - SV *cb_sv, *fh /* note no trailing ";" */ + #define EV_COMMON \ + SV *self; /* contains this struct */ \ + SV *cb_sv, *fh /* note no trailing ";" */ =item EV_CB_DECLARE (type) @@ -1728,11 +5046,38 @@ Can be used to change the callback member declaration in each watcher, and the way callbacks are invoked and set. Must expand to a struct member -definition and a statement, respectively. See the F header file for +definition and a statement, respectively. See the F header file for their default definitions. One possible use for overriding these is to avoid the C as first argument in all cases, or to use method calls instead of plain function calls in C++. +=back + +=head2 EXPORTED API SYMBOLS + +If you need to re-export the API (e.g. via a DLL) and you need a list of +exported symbols, you can use the provided F files which list +all public symbols, one per line: + + Symbols.ev for libev proper + Symbols.event for the libevent emulation + +This can also be used to rename all public symbols to avoid clashes with +multiple versions of libev linked together (which is obviously bad in +itself, but sometimes it is inconvenient to avoid this). + +A sed command like this will create wrapper C<#define>'s that you need to +include before including F: + + wrap.h + +This would create a file F which essentially looks like this: + + #define ev_backend myprefix_ev_backend + #define ev_check_start myprefix_ev_check_start + #define ev_check_stop myprefix_ev_check_stop + ... + =head2 EXAMPLES For a real-world example of a program the includes libev @@ -1744,49 +5089,626 @@ file. The usage in rxvt-unicode is simpler. It has a F header file -that everybody includes and which overrides some autoconf choices: +that everybody includes and which overrides some configure choices: - #define EV_USE_POLL 0 - #define EV_MULTIPLICITY 0 - #define EV_PERIODICS 0 - #define EV_CONFIG_H + #define EV_FEATURES 8 + #define EV_USE_SELECT 1 + #define EV_PREPARE_ENABLE 1 + #define EV_IDLE_ENABLE 1 + #define EV_SIGNAL_ENABLE 1 + #define EV_CHILD_ENABLE 1 + #define EV_USE_STDEXCEPT 0 + #define EV_CONFIG_H - #include "ev++.h" + #include "ev++.h" And a F implementation file that contains libev proper and is compiled: - #include "ev_cpp.h" - #include "ev.c" + #include "ev_cpp.h" + #include "ev.c" + +=head1 INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT + +=head2 THREADS AND COROUTINES + +=head3 THREADS + +All libev functions are reentrant and thread-safe unless explicitly +documented otherwise, but libev implements no locking itself. This means +that you can use as many loops as you want in parallel, as long as there +are no concurrent calls into any libev function with the same loop +parameter (C calls have an implicit default loop parameter, +of course): libev guarantees that different event loops share no data +structures that need any locking. + +Or to put it differently: calls with different loop parameters can be done +concurrently from multiple threads, calls with the same loop parameter +must be done serially (but can be done from different threads, as long as +only one thread ever is inside a call at any point in time, e.g. by using +a mutex per loop). + +Specifically to support threads (and signal handlers), libev implements +so-called C watchers, which allow some limited form of +concurrency on the same event loop, namely waking it up "from the +outside". + +If you want to know which design (one loop, locking, or multiple loops +without or something else still) is best for your problem, then I cannot +help you, but here is some generic advice: + +=over 4 + +=item * most applications have a main thread: use the default libev loop +in that thread, or create a separate thread running only the default loop. + +This helps integrating other libraries or software modules that use libev +themselves and don't care/know about threading. + +=item * one loop per thread is usually a good model. + +Doing this is almost never wrong, sometimes a better-performance model +exists, but it is always a good start. + +=item * other models exist, such as the leader/follower pattern, where one +loop is handed through multiple threads in a kind of round-robin fashion. + +Choosing a model is hard - look around, learn, know that usually you can do +better than you currently do :-) + +=item * often you need to talk to some other thread which blocks in the +event loop. + +C watchers can be used to wake them up from other threads safely +(or from signal contexts...). + +An example use would be to communicate signals or other events that only +work in the default loop by registering the signal watcher with the +default loop and triggering an C watcher from the default loop +watcher callback into the event loop interested in the signal. + +=back + +See also L. + +=head3 COROUTINES + +Libev is very accommodating to coroutines ("cooperative threads"): +libev fully supports nesting calls to its functions from different +coroutines (e.g. you can call C on the same loop from two +different coroutines, and switch freely between both coroutines running +the loop, as long as you don't confuse yourself). The only exception is +that you must not do this from C reschedule callbacks. + +Care has been taken to ensure that libev does not keep local state inside +C, and other calls do not usually allow for coroutine switches as +they do not call any callbacks. + +=head2 COMPILER WARNINGS + +Depending on your compiler and compiler settings, you might get no or a +lot of warnings when compiling libev code. Some people are apparently +scared by this. + +However, these are unavoidable for many reasons. For one, each compiler +has different warnings, and each user has different tastes regarding +warning options. "Warn-free" code therefore cannot be a goal except when +targeting a specific compiler and compiler-version. + +Another reason is that some compiler warnings require elaborate +workarounds, or other changes to the code that make it less clear and less +maintainable. + +And of course, some compiler warnings are just plain stupid, or simply +wrong (because they don't actually warn about the condition their message +seems to warn about). For example, certain older gcc versions had some +warnings that resulted in an extreme number of false positives. These have +been fixed, but some people still insist on making code warn-free with +such buggy versions. + +While libev is written to generate as few warnings as possible, +"warn-free" code is not a goal, and it is recommended not to build libev +with any compiler warnings enabled unless you are prepared to cope with +them (e.g. by ignoring them). Remember that warnings are just that: +warnings, not errors, or proof of bugs. + + +=head2 VALGRIND + +Valgrind has a special section here because it is a popular tool that is +highly useful. Unfortunately, valgrind reports are very hard to interpret. + +If you think you found a bug (memory leak, uninitialised data access etc.) +in libev, then check twice: If valgrind reports something like: + + ==2274== definitely lost: 0 bytes in 0 blocks. + ==2274== possibly lost: 0 bytes in 0 blocks. + ==2274== still reachable: 256 bytes in 1 blocks. + +Then there is no memory leak, just as memory accounted to global variables +is not a memleak - the memory is still being referenced, and didn't leak. + +Similarly, under some circumstances, valgrind might report kernel bugs +as if it were a bug in libev (e.g. in realloc or in the poll backend, +although an acceptable workaround has been found here), or it might be +confused. + +Keep in mind that valgrind is a very good tool, but only a tool. Don't +make it into some kind of religion. + +If you are unsure about something, feel free to contact the mailing list +with the full valgrind report and an explanation on why you think this +is a bug in libev (best check the archives, too :). However, don't be +annoyed when you get a brisk "this is no bug" answer and take the chance +of learning how to interpret valgrind properly. + +If you need, for some reason, empty reports from valgrind for your project +I suggest using suppression lists. + + +=head1 PORTABILITY NOTES + +=head2 GNU/LINUX 32 BIT LIMITATIONS + +GNU/Linux is the only common platform that supports 64 bit file/large file +interfaces but I them by default. + +That means that libev compiled in the default environment doesn't support +files larger than 2GiB or so, which mainly affects C watchers. + +Unfortunately, many programs try to work around this GNU/Linux issue +by enabling the large file API, which makes them incompatible with the +standard libev compiled for their system. + +Likewise, libev cannot enable the large file API itself as this would +suddenly make it incompatible to the default compile time environment, +i.e. all programs not using special compile switches. + +=head2 OS/X AND DARWIN BUGS + +The whole thing is a bug if you ask me - basically any system interface +you touch is broken, whether it is locales, poll, kqueue or even the +OpenGL drivers. + +=head3 C is buggy + +The kqueue syscall is broken in all known versions - most versions support +only sockets, many support pipes. + +Libev tries to work around this by not using C by default on this +rotten platform, but of course you can still ask for it when creating a +loop - embedding a socket-only kqueue loop into a select-based one is +probably going to work well. + +=head3 C is buggy + +Instead of fixing C, Apple replaced their (working) C +implementation by something calling C internally around the 10.5.6 +release, so now C I C are broken. + +Libev tries to work around this by not using C by default on +this rotten platform, but of course you can still ask for it when creating +a loop. + +=head3 C, and of course Apple found a way to fuck this +one up as well: On OS/X, C backends. + +=head2 AIX POLL BUG + +AIX unfortunately has a broken C header. Libev works around +this by trying to avoid the poll backend altogether (i.e. it's not even +compiled in), which normally isn't a big problem as C function + +The winsocket C