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