summaryrefslogtreecommitdiff
path: root/ev.pod
diff options
context:
space:
mode:
authorroot <root>2007-11-12 07:58:13 +0000
committerroot <root>2007-11-12 07:58:13 +0000
commit80b007e04bb3f75ae92cf173ccb6af0510b214ba (patch)
treec1b2fd61637169a31fd831455ec35bbf2c537f1d /ev.pod
parentf0d2fe1a1309889f165d0924a77cca204395737b (diff)
*** empty log message ***
Diffstat (limited to 'ev.pod')
-rw-r--r--ev.pod725
1 files changed, 725 insertions, 0 deletions
diff --git a/ev.pod b/ev.pod
new file mode 100644
index 0000000..e409a03
--- /dev/null
+++ b/ev.pod
@@ -0,0 +1,725 @@
+=head1 NAME
+
+libev - a high performance full-featured event loop written in C
+
+=head1 SYNOPSIS
+
+ #include <ev.h>
+
+=head1 DESCRIPTION
+
+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
+these event sources and provide your program events.
+
+To do this, it must take more or less complete control over your process
+(or thread) by executing the I<event loop> handler, and will then
+communicate events via a callback mechanism.
+
+You register interest in certain events by registering so-called I<event
+watchers>, which are relatively small C structures you initialise with the
+details of the event, and then hand it over to libev by I<starting> the
+watcher.
+
+=head1 FEATURES
+
+Libev supports select, poll, the linux-specific epoll and the bsd-specific
+kqueue mechanisms for file descriptor events, relative timers, absolute
+timers with customised rescheduling, signal events, process status change
+events (related to SIGCHLD), and event watchers dealing with the event
+loop mechanism itself (idle, prepare and check watchers).
+
+=head1 CONVENTIONS
+
+Libev is very configurable. In this manual the default configuration
+will be described, which supports multiple event loops. For more info
+about various configuraiton options please have a look at the file
+F<README.embed> in the libev distribution. If libev was configured without
+support for multiple event loops, then all functions taking an initial
+argument of name C<loop> (which is always of type C<struct ev_loop *>)
+will not have this argument.
+
+=head1 TIME AND OTHER GLOBAL FUNCTIONS
+
+Libev represents time as a single floating point number. This type is
+called C<ev_tstamp>, which is what you should use too. It usually aliases
+to the double type in C.
+
+=over 4
+
+=item ev_tstamp ev_time ()
+
+Returns the current time as libev would use it.
+
+=item int ev_version_major ()
+
+=item int ev_version_minor ()
+
+You can find out the major and minor version numbers of the library
+you linked against by calling the functions C<ev_version_major> and
+C<ev_version_minor>. If you want, you can compare against the global
+symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
+version of the library your program was compiled against.
+
+Usually, its a good idea to terminate if the major versions mismatch,
+as this indicates an incompatible change. Minor versions are usually
+compatible to older versions, so a larger minor version alone is usually
+not a problem.
+
+=item ev_set_allocator (void *(*cb)(void *ptr, long size))
+
+Sets the allocation function to use (the prototype is similar to the
+realloc function). It is used to allocate and free memory (no surprises
+here). If it returns zero when memory needs to be allocated, the library
+might abort or take some potentially destructive action. The default is
+your system realloc function.
+
+You could override this function in high-availability programs to, say,
+free some memory if it cannot allocate memory, to use a special allocator,
+or even to sleep a while and retry until some memory is available.
+
+=item ev_set_syserr_cb (void (*cb)(const char *msg));
+
+Set the callback function to call on a retryable syscall error (such
+as failed select, poll, epoll_wait). The message is a printable string
+indicating the system call or subsystem causing the problem. If this
+callback is set, then libev will expect it to remedy the sitution, no
+matter what, when it returns. That is, libev will geenrally retry the
+requested operation, or, if the condition doesn't go away, do bad stuff
+(such as abort).
+
+=back
+
+=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
+
+An event loop is described by a C<struct ev_loop *>. The library knows two
+types of such loops, the I<default> loop, which supports signals and child
+events, and dynamically created loops which do not.
+
+If you use threads, a common model is to run the default event loop
+in your main thread (or in a separate thrad) and for each thread you
+create, you also create another event loop. Libev itself does no lockign
+whatsoever, so if you mix calls to different event loops, make sure you
+lock (this is usually a bad idea, though, even if done right).
+
+=over 4
+
+=item struct ev_loop *ev_default_loop (unsigned int flags)
+
+This will initialise the default event loop if it hasn't been initialised
+yet and return it. If the default loop could not be initialised, returns
+false. If it already was initialised it simply returns it (and ignores the
+flags).
+
+If you don't know what event loop to use, use the one returned from this
+function.
+
+The flags argument can be used to specify special behaviour or specific
+backends to use, and is usually specified as 0 (or EVFLAG_AUTO)
+
+It supports the following flags:
+
+=over 4
+
+=item EVFLAG_AUTO
+
+The default flags value. Use this if you have no clue (its the right
+thing, believe me).
+
+=item EVFLAG_NOENV
+
+If this flag bit is ored into the flag value then libev will I<not> look
+at the environment variable C<LIBEV_FLAGS>. Otherwise (the default), this
+environment variable will override the flags completely. This is useful
+to try out specific backends to tets their performance, or to work around
+bugs.
+
+=item EVMETHOD_SELECT portable select backend
+
+=item EVMETHOD_POLL poll backend (everywhere except windows)
+
+=item EVMETHOD_EPOLL linux only
+
+=item EVMETHOD_KQUEUE some bsds only
+
+=item EVMETHOD_DEVPOLL solaris 8 only
+
+=item EVMETHOD_PORT solaris 10 only
+
+If one or more of these are ored into the flags value, then only these
+backends will be tried (in the reverse order as given here). If one are
+specified, any backend will do.
+
+=back
+
+=item struct ev_loop *ev_loop_new (unsigned int flags)
+
+Similar to C<ev_default_loop>, but always creates a new event loop that is
+always distinct from the default loop. Unlike the default loop, it cannot
+handle signal and child watchers, and attempts to do so will be greeted by
+undefined behaviour (or a failed assertion if assertions are enabled).
+
+=item ev_default_destroy ()
+
+Destroys the default loop again (frees all memory and kernel state
+etc.). This stops all registered event watchers (by not touching them in
+any way whatsoever, although you cnanot rely on this :).
+
+=item ev_loop_destroy (loop)
+
+Like C<ev_default_destroy>, but destroys an event loop created by an
+earlier call to C<ev_loop_new>.
+
+=item ev_default_fork ()
+
+This function reinitialises the kernel state for backends that have
+one. Despite the name, you can call it anytime, but it makes most sense
+after forking, in either the parent or child process (or both, but that
+again makes little sense).
+
+You I<must> call this function after forking if and only if you want to
+use the event library in both processes. If you just fork+exec, you don't
+have to call it.
+
+The function itself is quite fast and its usually not a problem to call
+it just in case after a fork. To make this easy, the function will fit in
+quite nicely into a call to C<pthread_atfork>:
+
+ pthread_atfork (0, 0, ev_default_fork);
+
+=item ev_loop_fork (loop)
+
+Like C<ev_default_fork>, but acts on an event loop created by
+C<ev_loop_new>. Yes, you have to call this on every allocated event loop
+after fork, and how you do this is entirely your own problem.
+
+=item unsigned int ev_method (loop)
+
+Returns one of the C<EVMETHOD_*> flags indicating the event backend in
+use.
+
+=item ev_tstamp = ev_now (loop)
+
+Returns the current "event loop time", which is the time the event loop
+got events and started processing them. This timestamp does not change
+as long as callbacks are being processed, and this is also the base time
+used for relative timers. You can treat it as the timestamp of the event
+occuring (or more correctly, the mainloop finding out about it).
+
+=item ev_loop (loop, int flags)
+
+Finally, this is it, the event handler. This function usually is called
+after you initialised all your watchers and you want to start handling
+events.
+
+If the flags argument is specified as 0, it will not return until either
+no event watchers are active anymore or C<ev_unloop> was called.
+
+A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
+those events and any outstanding ones, but will not block your process in
+case there are no events.
+
+A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
+neccessary) and will handle those and any outstanding ones. It will block
+your process until at least one new event arrives.
+
+This flags value could be used to implement alternative looping
+constructs, but the C<prepare> and C<check> watchers provide a better and
+more generic mechanism.
+
+=item ev_unloop (loop, how)
+
+Can be used to make a call to C<ev_loop> return early. The C<how> argument
+must be either C<EVUNLOOP_ONCE>, which will make the innermost C<ev_loop>
+call return, or C<EVUNLOOP_ALL>, which will make all nested C<ev_loop>
+calls return.
+
+=item ev_ref (loop)
+
+=item ev_unref (loop)
+
+Ref/unref can be used to add or remove a refcount on the event loop: Every
+watcher keeps one reference. If you have a long-runing watcher you never
+unregister that should not keep ev_loop from running, ev_unref() after
+starting, and ev_ref() before stopping it. Libev itself uses this for
+example for its internal signal pipe: It is not visible to you as a user
+and should not keep C<ev_loop> from exiting if the work is done. It is
+also an excellent way to do this for generic recurring timers or from
+within third-party libraries. Just remember to unref after start and ref
+before stop.
+
+=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 ev_io 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);
+ }
+
+ 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);
+
+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).
+
+Each watcher structure must be initialised by a call to C<ev_init
+(watcher *, callback)>, 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_<type>_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_<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_<type>_start (loop, watcher
+*) >>), and you can stop watching for events at any time by calling the
+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 set method.
+
+You cna check wether an event is active by calling the C<ev_is_active
+(watcher *)> macro. To see wether an event is outstanding (but the
+callback for it has not been called yet) you cna use the C<ev_is_pending
+(watcher *)> 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
+third argument.
+
+The rceeived events usually include a single bit per event type received
+(you can receive multiple events at the same time). The possible bit masks
+are:
+
+=over 4
+
+=item EV_READ
+
+=item EV_WRITE
+
+The file descriptor in the ev_io watcher has become readable and/or
+writable.
+
+=item EV_TIMEOUT
+
+The ev_timer watcher has timed out.
+
+=item EV_PERIODIC
+
+The ev_periodic watcher has timed out.
+
+=item EV_SIGNAL
+
+The signal specified in the ev_signal watcher has been received by a thread.
+
+=item EV_CHILD
+
+The pid specified in the ev_child watcher has received a status change.
+
+=item EV_IDLE
+
+The ev_idle watcher has determined that you have nothing better to do.
+
+=item EV_PREPARE
+
+=item EV_CHECK
+
+All ev_prepare watchers are invoked just I<before> C<ev_loop> starts
+to gather new events, and all ev_check watchers are invoked just after
+C<ev_loop> 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 ev_prepare watcher might start an idle watcher to keep
+C<ev_loop> from blocking).
+
+=item EV_ERROR
+
+An unspecified error has occured, 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.
+
+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.
+
+=back
+
+=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
+
+Each watcher has, by default, a member C<void *data> that you can change
+and read at any time, libev will completely ignore it. This cna 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:
+
+ struct my_io
+ {
+ struct ev_io io;
+ int otherfd;
+ void *somedata;
+ struct whatever *mostinteresting;
+ }
+
+And since your callback will be called with a pointer to the watcher, you
+can cast it back to your own type:
+
+ static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
+ {
+ struct my_io *w = (struct my_io *)w_;
+ ...
+ }
+
+More interesting and less C-conformant ways of catsing your callback type
+have been omitted....
+
+
+=head1 WATCHER TYPES
+
+This section describes each watcher in detail, but will not repeat
+information given in the last section.
+
+=head2 struct ev_io - is my file descriptor readable or writable
+
+I/O watchers check wether a file descriptor is readable or writable
+in each iteration of the event loop (This behaviour is called
+level-triggering because you keep receiving events as long as the
+condition persists. Remember you cna stop the watcher if you don't want to
+act on the event and neither want to receive future events).
+
+=over 4
+
+=item ev_io_init (ev_io *, callback, int fd, int events)
+
+=item ev_io_set (ev_io *, int fd, int events)
+
+Configures an ev_io watcher. The fd is the file descriptor to rceeive
+events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ |
+EV_WRITE> to receive the given events.
+
+=back
+
+=head2 struct ev_timer - relative and optionally recurring timeouts
+
+Timer watchers are simple relative timers that generate an event after a
+given time, and optionally repeating in regular intervals after that.
+
+The timers are based on real time, that is, if you register an event that
+times out after an hour and youreset your system clock to last years
+time, it will still time out after (roughly) and hour. "Roughly" because
+detecting time jumps is hard, and soem inaccuracies are unavoidable (the
+monotonic clock option helps a lot here).
+
+=over 4
+
+=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
+
+=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
+
+Configure the timer to trigger after C<after> seconds. If C<repeat> is
+C<0.>, then it will automatically be stopped. If it is positive, then the
+timer will automatically be configured to trigger again C<repeat> seconds
+later, again, and again, until stopped manually.
+
+The timer itself will do a best-effort at avoiding drift, that is, if you
+configure a timer to trigger every 10 seconds, then it will trigger at
+exactly 10 second intervals. If, however, your program cannot keep up with
+the timer (ecause it takes longer than those 10 seconds to do stuff) the
+timer will not fire more than once per event loop iteration.
+
+=item ev_timer_again (loop)
+
+This will act as if the timer timed out and restart it again if it is
+repeating. The exact semantics are:
+
+If the timer is started but nonrepeating, stop it.
+
+If the timer is repeating, either start it if necessary (with the repeat
+value), or reset the running timer to the repeat value.
+
+This sounds a bit complicated, but here is a useful and typical
+example: Imagine you have a tcp connection and you want a so-called idle
+timeout, that is, you want to be called when there have been, say, 60
+seconds of inactivity on the socket. The easiest way to do this is to
+configure an ev_timer with after=repeat=60 and calling ev_timer_again each
+time you successfully read or write some data. If you go into an idle
+state where you do not expect data to travel on the socket, you can stop
+the timer, and again will automatically restart it if need be.
+
+=back
+
+=head2 ev_periodic
+
+Periodic watchers are also timers of a kind, but they are very versatile
+(and unfortunately a bit complex).
+
+Unlike ev_timer's, they are not based on real time (or relative time)
+but on wallclock time (absolute time). You can tell a periodic watcher
+to trigger "at" some specific point in time. For example, if you tell a
+periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now ()
++ 10.>) and then reset your system clock to the last year, then it will
+take a year to trigger the event (unlike an ev_timer, which would trigger
+roughly 10 seconds later and of course not if you reset your system time
+again).
+
+They can also be used to implement vastly more complex timers, such as
+triggering an event on eahc midnight, local time.
+
+=over 4
+
+=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
+
+=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
+
+Lots of arguments, lets sort it out... There are basically three modes of
+operation, and we will explain them from simplest to complex:
+
+
+=over 4
+
+=item * absolute timer (interval = reschedule_cb = 0)
+
+In this configuration the watcher triggers an event at the wallclock time
+C<at> and doesn't repeat. It will not adjust when a time jump occurs,
+that is, if it is to be run at January 1st 2011 then it will run when the
+system time reaches or surpasses this time.
+
+=item * non-repeating interval timer (interval > 0, reschedule_cb = 0)
+
+In this mode the watcher will always be scheduled to time out at the next
+C<at + N * interval> time (for some integer N) and then repeat, regardless
+of any time jumps.
+
+This can be used to create timers that do not drift with respect to system
+time:
+
+ ev_periodic_set (&periodic, 0., 3600., 0);
+
+This doesn't mean there will always be 3600 seconds in between triggers,
+but only that the the callback will be called when the system time shows a
+full hour (UTC), or more correct, when the system time is evenly divisible
+by 3600.
+
+Another way to think about it (for the mathematically inclined) is that
+ev_periodic will try to run the callback in this mode at the next possible
+time where C<time = at (mod interval)>, regardless of any time jumps.
+
+=item * manual reschedule mode (reschedule_cb = callback)
+
+In this mode the values for C<interval> and C<at> are both being
+ignored. Instead, each time the periodic watcher gets scheduled, the
+reschedule callback will be called with the watcher as first, and the
+current time as second argument.
+
+NOTE: I<This callback MUST NOT stop or destroy the periodic or any other
+periodic watcher, ever, or make any event loop modificstions>. If you need
+to stop it, return 1e30 (or so, fudge fudge) and stop it afterwards.
+
+Its prototype is c<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
+ev_tstamp now)>, e.g.:
+
+ static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
+ {
+ return now + 60.;
+ }
+
+It must return the next time to trigger, based on the passed time value
+(that is, the lowest time value larger than to the second argument). It
+will usually be called just before the callback will be triggered, but
+might be called at other times, too.
+
+This can be used to create very complex timers, such as a timer that
+triggers on each midnight, local time. To do this, you would calculate the
+next midnight after C<now> and return the timestamp value for this. How you do this
+is, again, up to you (but it is not trivial).
+
+=back
+
+=item ev_periodic_again (loop, ev_periodic *)
+
+Simply stops and restarts the periodic watcher again. This is only useful
+when you changed some parameters or the reschedule callback would return
+a different time than the last time it was called (e.g. in a crond like
+program when the crontabs have changed).
+
+=back
+
+=head2 ev_signal - signal me when a signal gets signalled
+
+Signal watchers will trigger an event when the process receives a specific
+signal one or more times. Even though signals are very asynchronous, libev
+will try its best to deliver signals synchronously, i.e. as part of the
+normal event processing, like any other event.
+
+You cna configure as many watchers as you like per signal. Only when the
+first watcher gets started will libev actually register a signal watcher
+with the kernel (thus it coexists with your own signal handlers as long
+as you don't register any with libev). Similarly, when the last signal
+watcher for a signal is stopped libev will reset the signal handler to
+SIG_DFL (regardless of what it was set to before).
+
+=over 4
+
+=item ev_signal_init (ev_signal *, callback, int signum)
+
+=item ev_signal_set (ev_signal *, int signum)
+
+Configures the watcher to trigger on the given signal number (usually one
+of the C<SIGxxx> constants).
+
+=back
+
+=head2 ev_child - wait for pid status changes
+
+Child watchers trigger when your process receives a SIGCHLD in response to
+some child status changes (most typically when a child of yours dies).
+
+=over 4
+
+=item ev_child_init (ev_child *, callback, int pid)
+
+=item ev_child_set (ev_child *, int pid)
+
+Configures the watcher to wait for status changes of process C<pid> (or
+I<any> process if C<pid> is specified as C<0>). The callback can look
+at the C<rstatus> member of the C<ev_child> watcher structure to see
+the status word (use the macros from C<sys/wait.h>). The C<rpid> member
+contains the pid of the process causing the status change.
+
+=back
+
+=head2 ev_idle - when you've got nothing better to do
+
+Idle watchers trigger events when there are no other I/O or timer (or
+periodic) events pending. That is, as long as your process is busy
+handling sockets or timeouts it will not be called. But when your process
+is idle all idle watchers are being called again and again - until
+stopped, that is, or your process receives more events.
+
+The most noteworthy effect is that as long as any idle watchers are
+active, the process will not block when waiting for new events.
+
+Apart from keeping your process non-blocking (which is a useful
+effect on its own sometimes), idle watchers are a good place to do
+"pseudo-background processing", or delay processing stuff to after the
+event loop has handled all outstanding events.
+
+=over 4
+
+=item ev_idle_init (ev_signal *, callback)
+
+Initialises and configures the idle watcher - it has no parameters of any
+kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
+believe me.
+
+=back
+
+=head2 prepare and check - your hooks into the event loop
+
+Prepare and check watchers usually (but not always) are used in
+tandom. Prepare watchers get invoked before the process blocks and check
+watchers afterwards.
+
+Their main purpose is to integrate other event mechanisms into libev. This
+could be used, for example, to track variable changes, implement your own
+watchers, integrate net-snmp or a coroutine library and lots more.
+
+This is done by examining in each prepare call which file descriptors need
+to be watched by the other library, registering ev_io watchers for them
+and starting an ev_timer watcher for any timeouts (many libraries provide
+just this functionality). Then, in the check watcher you check for any
+events that occured (by making your callbacks set soem flags for example)
+and call back into the library.
+
+As another example, the perl Coro module uses these hooks to integrate
+coroutines into libev programs, by yielding to other active coroutines
+during each prepare and only letting the process block if no coroutines
+are ready to run.
+
+=over 4
+
+=item ev_prepare_init (ev_prepare *, callback)
+
+=item ev_check_init (ev_check *, callback)
+
+Initialises and configures the prepare or check watcher - they have no
+parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
+macros, but using them is utterly, utterly pointless.
+
+=back
+
+=head1 OTHER FUNCTIONS
+
+There are some other fucntions of possible interest. Described. Here. Now.
+
+=over 4
+
+=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
+
+This function combines a simple timer and an I/O watcher, calls your
+callback on whichever event happens first and automatically stop both
+watchers. This is useful if you want to wait for a single event on an fd
+or timeout without havign to allocate/configure/start/stop/free one or
+more watchers yourself.
+
+If C<fd> is less than 0, then no I/O watcher will be started and events is
+ignored. Otherwise, an ev_io watcher for the given C<fd> and C<events> set
+will be craeted and started.
+
+If C<timeout> is less than 0, then no timeout watcher will be
+started. Otherwise an ev_timer watcher with after = C<timeout> (and repeat
+= 0) will be started.
+
+The callback has the type C<void (*cb)(int revents, void *arg)> and
+gets passed an events set (normally a combination of EV_ERROR, EV_READ,
+EV_WRITE or EV_TIMEOUT) and the C<arg> value passed to C<ev_once>:
+
+ static void stdin_ready (int revents, void *arg)
+ {
+ if (revents & EV_TIMEOUT)
+ /* doh, nothing entered */
+ else if (revents & EV_READ)
+ /* stdin might have data for us, joy! */
+ }
+
+ ev_once (STDIN_FILENO, EV_READm 10., stdin_ready, 0);
+
+=item ev_feed_event (loop, watcher, int events)
+
+Feeds the given event set into the event loop, as if the specified event
+has happened for the specified watcher (which must be a pointer to an
+initialised but not necessarily active event watcher).
+
+=item ev_feed_fd_event (loop, int fd, int revents)
+
+Feed an event on the given fd, as if a file descriptor backend detected it.
+
+=item ev_feed_signal_event (loop, int signum)
+
+Feed an event as if the given signal occured (loop must be the default loop!).
+
+=back
+
+=head1 AUTHOR
+
+Marc Lehmann <libev@schmorp.de>.
+