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

Comparing libev/ev.pod (file contents):
Revision 1.310 by root, Thu Oct 21 12:32:47 2010 UTC vs.
Revision 1.311 by root, Thu Oct 21 14:40:07 2010 UTC

… …
293=back 293=back
294 294
295=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 295=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
296 296
297An event loop is described by a C<struct ev_loop *> (the C<struct> is 297An event loop is described by a C<struct ev_loop *> (the C<struct> is
298I<not> optional in case unless libev 3 compatibility is disabled, as libev 298I<not> optional in this case unless libev 3 compatibility is disabled, as
2993 had an C<ev_loop> function colliding with the struct name). 299libev 3 had an C<ev_loop> function colliding with the struct name).
300 300
301The library knows two types of such loops, the I<default> loop, which 301The library knows two types of such loops, the I<default> loop, which
302supports signals and child events, and dynamically created event loops 302supports signals and child events, and dynamically created event loops
303which do not. 303which do not.
304 304
… …
990 990
991In the following description, uppercase C<TYPE> in names stands for the 991In the following description, uppercase C<TYPE> in names stands for the
992watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer 992watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
993watchers and C<ev_io_start> for I/O watchers. 993watchers and C<ev_io_start> for I/O watchers.
994 994
995A watcher is a structure that you create and register to record your 995A watcher is an opaque structure that you allocate and register to record
996interest in some event. For instance, if you want to wait for STDIN to 996your interest in some event. To make a concrete example, imagine you want
997become readable, you would create an C<ev_io> watcher for that: 997to wait for STDIN to become readable, you would create an C<ev_io> watcher
998for that:
998 999
999 static void my_cb (struct ev_loop *loop, ev_io *w, int revents) 1000 static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
1000 { 1001 {
1001 ev_io_stop (w); 1002 ev_io_stop (w);
1002 ev_break (loop, EVBREAK_ALL); 1003 ev_break (loop, EVBREAK_ALL);
… …
1017stack). 1018stack).
1018 1019
1019Each watcher has an associated watcher structure (called C<struct ev_TYPE> 1020Each watcher has an associated watcher structure (called C<struct ev_TYPE>
1020or simply C<ev_TYPE>, as typedefs are provided for all watcher structs). 1021or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
1021 1022
1022Each watcher structure must be initialised by a call to C<ev_init 1023Each watcher structure must be initialised by a call to C<ev_init (watcher
1023(watcher *, callback)>, which expects a callback to be provided. This 1024*, callback)>, which expects a callback to be provided. This callback is
1024callback gets invoked each time the event occurs (or, in the case of I/O 1025invoked each time the event occurs (or, in the case of I/O watchers, each
1025watchers, each time the event loop detects that the file descriptor given 1026time the event loop detects that the file descriptor given is readable
1026is readable and/or writable). 1027and/or writable).
1027 1028
1028Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >> 1029Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
1029macro to configure it, with arguments specific to the watcher type. There 1030macro to configure it, with arguments specific to the watcher type. There
1030is also a macro to combine initialisation and setting in one call: C<< 1031is also a macro to combine initialisation and setting in one call: C<<
1031ev_TYPE_init (watcher *, callback, ...) >>. 1032ev_TYPE_init (watcher *, callback, ...) >>.
… …
1126example it might indicate that a fd is readable or writable, and if your 1127example it might indicate that a fd is readable or writable, and if your
1127callbacks is well-written it can just attempt the operation and cope with 1128callbacks is well-written it can just attempt the operation and cope with
1128the error from read() or write(). This will not work in multi-threaded 1129the error from read() or write(). This will not work in multi-threaded
1129programs, though, as the fd could already be closed and reused for another 1130programs, though, as the fd could already be closed and reused for another
1130thing, so beware. 1131thing, so beware.
1132
1133=back
1134
1135=head2 WATCHER STATES
1136
1137There are various watcher states mentioned throughout this manual -
1138active, pending and so on. In this section these states and the rules to
1139transition between them will be described in more detail - and while these
1140rules might look complicated, they usually do "the right thing".
1141
1142=over 4
1143
1144=item initialiased
1145
1146Before a watcher can be registered with the event looop it has to be
1147initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
1148C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1149
1150In this state it is simply some block of memory that is suitable for use
1151in an event loop. It can be moved around, freed, reused etc. at will.
1152
1153=item started/running/active
1154
1155Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
1156property of the event loop, and is actively waiting for events. While in
1157this state it cannot be accessed (except in a few documented ways), moved,
1158freed or anything else - the only legal thing is to keep a pointer to it,
1159and call libev functions on it that are documented to work on active watchers.
1160
1161=item pending
1162
1163If a watcher is active and libev determines that an event it is interested
1164in has occured (such as a timer expiring), it will become pending. It will
1165stay in this pending state until either it is stopped or its callback is
1166about to be invoked, so it is not normally pending inside the watcher
1167callback.
1168
1169The watcher might or might not be active while it is pending (for example,
1170an expired non-repeating timer can be pending but no longer active). If it
1171is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
1172but it is still property of the event loop at this time, so cannot be
1173moved, freed or reused. And if it is active the rules described in the
1174previous item still apply.
1175
1176It is also possible to feed an event on a watcher that is not active (e.g.
1177via C<ev_feed_event>), in which case it becomes pending without being
1178active.
1179
1180=item stopped
1181
1182A watcher can be stopped implicitly by libev (in which case it might still
1183be pending), or explicitly by calling its C<ev_TYPE_stop> function. The
1184latter will clear any pending state the watcher might be in, regardless
1185of whether it was active or not, so stopping a watcher explicitly before
1186freeing it is often a good idea.
1187
1188While stopped (and not pending) the watcher is essentially in the
1189initialised state, that is it can be reused, moved, modified in any way
1190you wish.
1131 1191
1132=back 1192=back
1133 1193
1134=head2 GENERIC WATCHER FUNCTIONS 1194=head2 GENERIC WATCHER FUNCTIONS
1135 1195

Diff Legend

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