--- libev/ev.html 2007/11/12 08:35:36 1.13 +++ libev/ev.html 2007/11/12 08:45:49 1.14 @@ -6,7 +6,7 @@ - +
@@ -28,7 +28,7 @@ev_io
- is this file descriptor readable or writableev_timer
- relative and optionally recurring timeoutsev_periodic
- to cron or not to cron itev_periodic
- to cron or not to cronev_signal
- signal me when a signal gets signalledev_child
- wait for pid status changesev_idle
- when you've got nothing better to doAs 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 whether an event is active by calling the You can check whether an event is active by calling the 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
+ The received events usually include a single bit per event type received
(you can receive multiple events at the same time). The possible bit masks
are: Each watcher has, by default, a member I/O watchers check whether 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
+condition persists. Remember you can stop the watcher if you don't want to
act on the event and neither want to receive future events). In general you can register as many read and/or write event watchers oer
fd as you want (as long as you don't confuse yourself). Setting all file
@@ -507,7 +507,7 @@
Periodic watchers are also timers of a kind, but they are very versatile
(and unfortunately a bit complex). You cna configure as many watchers as you like per signal. Only when the
+ You can 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
@@ -632,19 +632,22 @@
Configures the watcher to wait for status changes of process 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. Idle watchers trigger events when there are no other events are pending
+(prepare, check and other idle watchers do not count). That is, as long
+as your process is busy handling sockets or timeouts (or even signals,
+imagine) it will not be triggered. But when your process is idle all idle
+watchers are being called again and again, once per event loop iteration -
+until stopped, that is, or your process receives more events and becomes
+busy. 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
@@ -663,36 +666,42 @@
Prepare and check watchers usually (but not always) are used in
-tandom. Prepare watchers get invoked before the process blocks and check
-watchers afterwards. Prepare and check watchers are usually (but not always) used in tandem:
+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 As another example, the perl Coro module uses these hooks to integrate
+to be watched by the other library, registering 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. Initialises and configures the prepare or check watcher - they have no
parameters of any kind. There are There are some other fucntions of possible interest. Described. Here. Now. There are some other functions of possible interest. Described. Here. Now. If If If The callback has the type The callback has the type 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). Feed an event on the given fd, as if a file descriptor backend detected it. Feed an event on the given fd, as if a file descriptor backend detected
+the given events it.ev_is_active
+
ev_is_active
(watcher *)
macro. To see whether an event is outstanding (but the
-callback for it has not been called yet) you cna use the ev_is_pending
+callback for it has not been called yet) you can use the
ev_is_pending
(watcher *)
macro.
@@ -391,7 +391,7 @@
ASSOCIATING CUSTOM DATA WITH A WATCHER
void *data
that you can change
-and read at any time, libev will completely ignore it. This cna be used
+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
@@ -433,7 +433,7 @@
+ev_periodic
- to cron or not to cron itev_periodic
- to cron or not to cronpid
(or
any process if pid
is specified as 0
). The callback can look
at the rstatus
member of the ev_child
watcher structure to see
-the status word (use the macros from sys/wait.h
). The rpid
member
-contains the pid of the process causing the status change.sys/wait.h
and see your systems
+waitpid
documentation). The rpid
member contains the pid of the
+process causing the status change.
ev_idle
- when you've got nothing better to doprepare and check - your hooks into the event loop
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.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 checking the pending status of all watchers
+and stopping them) and call back into the library. The I/O and timer
+callbacks will never actually be called (but must be valid neverthelles,
+because you never know, you know?).
ev_prepare_set
and ev_check_set
-macros, but using them is utterly, utterly pointless.OTHER FUNCTIONS
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 fd
and events
set
-will be craeted and started.fd
is less than 0, then no I/O watcher will be started and events
+is being ignored. Otherwise, an ev_io
watcher for the given fd
and
+events
set will be craeted and started.timeout
is less than 0, then no timeout watcher will be
-started. Otherwise an ev_timer
watcher with after = timeout
(and repeat
-= 0) will be started.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 arg
value passed to ev_once
:ev_timer
watcher with after = timeout
(and
+repeat = 0) will be started. While 0
is a valid timeout, it is of
+dubious value.
+ void (*cb)(int revents, void *arg)
and gets
+passed an events set like normal event callbacks (with a combination of
+EV_ERROR
, EV_READ
, EV_WRITE
or EV_TIMEOUT
) and the arg
+value passed to ev_once
: static void stdin_ready (int revents, void *arg)
{
if (revents & EV_TIMEOUT)
- /* doh, nothing entered */
+ /* doh, nothing entered */;
else if (revents & EV_READ)
- /* stdin might have data for us, joy! */
+ /* stdin might have data for us, joy! */;
}
- ev_once (STDIN_FILENO, EV_READm 10., stdin_ready, 0);
+ ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);