… | |
… | |
4 | <head> |
4 | <head> |
5 | <title>libev</title> |
5 | <title>libev</title> |
6 | <meta name="description" content="Pod documentation for libev" /> |
6 | <meta name="description" content="Pod documentation for libev" /> |
7 | <meta name="inputfile" content="<standard input>" /> |
7 | <meta name="inputfile" content="<standard input>" /> |
8 | <meta name="outputfile" content="<standard output>" /> |
8 | <meta name="outputfile" content="<standard output>" /> |
9 | <meta name="created" content="Sat Nov 24 05:58:35 2007" /> |
9 | <meta name="created" content="Sat Nov 24 08:13:46 2007" /> |
10 | <meta name="generator" content="Pod::Xhtml 1.57" /> |
10 | <meta name="generator" content="Pod::Xhtml 1.57" /> |
11 | <link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head> |
11 | <link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head> |
12 | <body> |
12 | <body> |
13 | <div class="pod"> |
13 | <div class="pod"> |
14 | <!-- INDEX START --> |
14 | <!-- INDEX START --> |
… | |
… | |
21 | <li><a href="#CONVENTIONS">CONVENTIONS</a></li> |
21 | <li><a href="#CONVENTIONS">CONVENTIONS</a></li> |
22 | <li><a href="#TIME_REPRESENTATION">TIME REPRESENTATION</a></li> |
22 | <li><a href="#TIME_REPRESENTATION">TIME REPRESENTATION</a></li> |
23 | <li><a href="#GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</a></li> |
23 | <li><a href="#GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</a></li> |
24 | <li><a href="#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP">FUNCTIONS CONTROLLING THE EVENT LOOP</a></li> |
24 | <li><a href="#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP">FUNCTIONS CONTROLLING THE EVENT LOOP</a></li> |
25 | <li><a href="#ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</a> |
25 | <li><a href="#ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</a> |
|
|
26 | <ul><li><a href="#SUMMARY_OF_GENERIC_WATCHER_FUNCTIONS">SUMMARY OF GENERIC WATCHER FUNCTIONS</a></li> |
26 | <ul><li><a href="#ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</a></li> |
27 | <li><a href="#ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</a></li> |
27 | </ul> |
28 | </ul> |
28 | </li> |
29 | </li> |
29 | <li><a href="#WATCHER_TYPES">WATCHER TYPES</a> |
30 | <li><a href="#WATCHER_TYPES">WATCHER TYPES</a> |
30 | <ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable</a></li> |
31 | <ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable</a></li> |
31 | <li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring timeouts</a></li> |
32 | <li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring timeouts</a></li> |
… | |
… | |
535 | with a watcher-specific start function (<code>ev_<type>_start (loop, watcher |
536 | with a watcher-specific start function (<code>ev_<type>_start (loop, watcher |
536 | *)</code>), and you can stop watching for events at any time by calling the |
537 | *)</code>), and you can stop watching for events at any time by calling the |
537 | corresponding stop function (<code>ev_<type>_stop (loop, watcher *)</code>.</p> |
538 | corresponding stop function (<code>ev_<type>_stop (loop, watcher *)</code>.</p> |
538 | <p>As long as your watcher is active (has been started but not stopped) you |
539 | <p>As long as your watcher is active (has been started but not stopped) you |
539 | must not touch the values stored in it. Most specifically you must never |
540 | must not touch the values stored in it. Most specifically you must never |
540 | reinitialise it or call its set macro.</p> |
541 | reinitialise it or call its <code>set</code> macro.</p> |
541 | <p>You can check whether an event is active by calling the <code>ev_is_active |
|
|
542 | (watcher *)</code> macro. To see whether an event is outstanding (but the |
|
|
543 | callback for it has not been called yet) you can use the <code>ev_is_pending |
|
|
544 | (watcher *)</code> macro.</p> |
|
|
545 | <p>Each and every callback receives the event loop pointer as first, the |
542 | <p>Each and every callback receives the event loop pointer as first, the |
546 | registered watcher structure as second, and a bitset of received events as |
543 | registered watcher structure as second, and a bitset of received events as |
547 | third argument.</p> |
544 | third argument.</p> |
548 | <p>The received events usually include a single bit per event type received |
545 | <p>The received events usually include a single bit per event type received |
549 | (you can receive multiple events at the same time). The possible bit masks |
546 | (you can receive multiple events at the same time). The possible bit masks |
… | |
… | |
598 | your callbacks is well-written it can just attempt the operation and cope |
595 | your callbacks is well-written it can just attempt the operation and cope |
599 | with the error from read() or write(). This will not work in multithreaded |
596 | with the error from read() or write(). This will not work in multithreaded |
600 | programs, though, so beware.</p> |
597 | programs, though, so beware.</p> |
601 | </dd> |
598 | </dd> |
602 | </dl> |
599 | </dl> |
|
|
600 | |
|
|
601 | </div> |
|
|
602 | <h2 id="SUMMARY_OF_GENERIC_WATCHER_FUNCTIONS">SUMMARY OF GENERIC WATCHER FUNCTIONS</h2> |
|
|
603 | <div id="SUMMARY_OF_GENERIC_WATCHER_FUNCTIONS-2"> |
|
|
604 | <p>In the following description, <code>TYPE</code> stands for the watcher type, |
|
|
605 | e.g. <code>timer</code> for <code>ev_timer</code> watchers and <code>io</code> for <code>ev_io</code> watchers.</p> |
|
|
606 | <dl> |
|
|
607 | <dt><code>ev_init</code> (ev_TYPE *watcher, callback)</dt> |
|
|
608 | <dd> |
|
|
609 | <p>This macro initialises the generic portion of a watcher. The contents |
|
|
610 | of the watcher object can be arbitrary (so <code>malloc</code> will do). Only |
|
|
611 | the generic parts of the watcher are initialised, you <i>need</i> to call |
|
|
612 | the type-specific <code>ev_TYPE_set</code> macro afterwards to initialise the |
|
|
613 | type-specific parts. For each type there is also a <code>ev_TYPE_init</code> macro |
|
|
614 | which rolls both calls into one.</p> |
|
|
615 | <p>You can reinitialise a watcher at any time as long as it has been stopped |
|
|
616 | (or never started) and there are no pending events outstanding.</p> |
|
|
617 | <p>The callbakc is always of type <code>void (*)(ev_loop *loop, ev_TYPE *watcher, |
|
|
618 | int revents)</code>.</p> |
|
|
619 | </dd> |
|
|
620 | <dt><code>ev_TYPE_set</code> (ev_TYPE *, [args])</dt> |
|
|
621 | <dd> |
|
|
622 | <p>This macro initialises the type-specific parts of a watcher. You need to |
|
|
623 | call <code>ev_init</code> at least once before you call this macro, but you can |
|
|
624 | call <code>ev_TYPE_set</code> any number of times. You must not, however, call this |
|
|
625 | macro on a watcher that is active (it can be pending, however, which is a |
|
|
626 | difference to the <code>ev_init</code> macro).</p> |
|
|
627 | <p>Although some watcher types do not have type-specific arguments |
|
|
628 | (e.g. <code>ev_prepare</code>) you still need to call its <code>set</code> macro.</p> |
|
|
629 | </dd> |
|
|
630 | <dt><code>ev_TYPE_init</code> (ev_TYPE *watcher, callback, [args])</dt> |
|
|
631 | <dd> |
|
|
632 | <p>This convinience macro rolls both <code>ev_init</code> and <code>ev_TYPE_set</code> macro |
|
|
633 | calls into a single call. This is the most convinient method to initialise |
|
|
634 | a watcher. The same limitations apply, of course.</p> |
|
|
635 | </dd> |
|
|
636 | <dt><code>ev_TYPE_start</code> (loop *, ev_TYPE *watcher)</dt> |
|
|
637 | <dd> |
|
|
638 | <p>Starts (activates) the given watcher. Only active watchers will receive |
|
|
639 | events. If the watcher is already active nothing will happen.</p> |
|
|
640 | </dd> |
|
|
641 | <dt><code>ev_TYPE_stop</code> (loop *, ev_TYPE *watcher)</dt> |
|
|
642 | <dd> |
|
|
643 | <p>Stops the given watcher again (if active) and clears the pending |
|
|
644 | status. It is possible that stopped watchers are pending (for example, |
|
|
645 | non-repeating timers are being stopped when they become pending), but |
|
|
646 | <code>ev_TYPE_stop</code> ensures that the watcher is neither active nor pending. If |
|
|
647 | you want to free or reuse the memory used by the watcher it is therefore a |
|
|
648 | good idea to always call its <code>ev_TYPE_stop</code> function.</p> |
|
|
649 | </dd> |
|
|
650 | <dt>bool ev_is_active (ev_TYPE *watcher)</dt> |
|
|
651 | <dd> |
|
|
652 | <p>Returns a true value iff the watcher is active (i.e. it has been started |
|
|
653 | and not yet been stopped). As long as a watcher is active you must not modify |
|
|
654 | it.</p> |
|
|
655 | </dd> |
|
|
656 | <dt>bool ev_is_pending (ev_TYPE *watcher)</dt> |
|
|
657 | <dd> |
|
|
658 | <p>Returns a true value iff the watcher is pending, (i.e. it has outstanding |
|
|
659 | events but its callback has not yet been invoked). As long as a watcher |
|
|
660 | is pending (but not active) you must not call an init function on it (but |
|
|
661 | <code>ev_TYPE_set</code> is safe) and you must make sure the watcher is available to |
|
|
662 | libev (e.g. you cnanot <code>free ()</code> it).</p> |
|
|
663 | </dd> |
|
|
664 | <dt>callback = ev_cb (ev_TYPE *watcher)</dt> |
|
|
665 | <dd> |
|
|
666 | <p>Returns the callback currently set on the watcher.</p> |
|
|
667 | </dd> |
|
|
668 | <dt>ev_cb_set (ev_TYPE *watcher, callback)</dt> |
|
|
669 | <dd> |
|
|
670 | <p>Change the callback. You can change the callback at virtually any time |
|
|
671 | (modulo threads).</p> |
|
|
672 | </dd> |
|
|
673 | </dl> |
|
|
674 | |
|
|
675 | |
|
|
676 | |
|
|
677 | |
603 | |
678 | |
604 | </div> |
679 | </div> |
605 | <h2 id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</h2> |
680 | <h2 id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH">ASSOCIATING CUSTOM DATA WITH A WATCHER</h2> |
606 | <div id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH-2"> |
681 | <div id="ASSOCIATING_CUSTOM_DATA_WITH_A_WATCH-2"> |
607 | <p>Each watcher has, by default, a member <code>void *data</code> that you can change |
682 | <p>Each watcher has, by default, a member <code>void *data</code> that you can change |
… | |
… | |
1066 | |
1141 | |
1067 | </div> |
1142 | </div> |
1068 | <h2 id="code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough</h2> |
1143 | <h2 id="code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough</h2> |
1069 | <div id="code_ev_embed_code_when_one_backend_-2"> |
1144 | <div id="code_ev_embed_code_when_one_backend_-2"> |
1070 | <p>This is a rather advanced watcher type that lets you embed one event loop |
1145 | <p>This is a rather advanced watcher type that lets you embed one event loop |
1071 | into another.</p> |
1146 | into another (currently only <code>ev_io</code> events are supported in the embedded |
|
|
1147 | loop, other types of watchers might be handled in a delayed or incorrect |
|
|
1148 | fashion and must not be used).</p> |
1072 | <p>There are primarily two reasons you would want that: work around bugs and |
1149 | <p>There are primarily two reasons you would want that: work around bugs and |
1073 | prioritise I/O.</p> |
1150 | prioritise I/O.</p> |
1074 | <p>As an example for a bug workaround, the kqueue backend might only support |
1151 | <p>As an example for a bug workaround, the kqueue backend might only support |
1075 | sockets on some platform, so it is unusable as generic backend, but you |
1152 | sockets on some platform, so it is unusable as generic backend, but you |
1076 | still want to make use of it because you have many sockets and it scales |
1153 | still want to make use of it because you have many sockets and it scales |
… | |
… | |
1081 | <p>As for prioritising I/O: rarely you have the case where some fds have |
1158 | <p>As for prioritising I/O: rarely you have the case where some fds have |
1082 | to be watched and handled very quickly (with low latency), and even |
1159 | to be watched and handled very quickly (with low latency), and even |
1083 | priorities and idle watchers might have too much overhead. In this case |
1160 | priorities and idle watchers might have too much overhead. In this case |
1084 | you would put all the high priority stuff in one loop and all the rest in |
1161 | you would put all the high priority stuff in one loop and all the rest in |
1085 | a second one, and embed the second one in the first.</p> |
1162 | a second one, and embed the second one in the first.</p> |
|
|
1163 | <p>As long as the watcher is active, the callback will be invoked every time |
|
|
1164 | there might be events pending in the embedded loop. The callback must then |
|
|
1165 | call <code>ev_embed_sweep (mainloop, watcher)</code> to make a single sweep and invoke |
|
|
1166 | their callbacks (you could also start an idle watcher to give the embedded |
|
|
1167 | loop strictly lower priority for example). You can also set the callback |
|
|
1168 | to <code>0</code>, in which case the embed watcher will automatically execute the |
|
|
1169 | embedded loop sweep.</p> |
1086 | <p>As long as the watcher is started it will automatically handle events. The |
1170 | <p>As long as the watcher is started it will automatically handle events. The |
1087 | callback will be invoked whenever some events have been handled. You can |
1171 | callback will be invoked whenever some events have been handled. You can |
1088 | set the callback to <code>0</code> to avoid having to specify one if you are not |
1172 | set the callback to <code>0</code> to avoid having to specify one if you are not |
1089 | interested in that.</p> |
1173 | interested in that.</p> |
1090 | <p>Also, there have not currently been made special provisions for forking: |
1174 | <p>Also, there have not currently been made special provisions for forking: |
… | |
… | |
1117 | else |
1201 | else |
1118 | loop_lo = loop_hi; |
1202 | loop_lo = loop_hi; |
1119 | |
1203 | |
1120 | </pre> |
1204 | </pre> |
1121 | <dl> |
1205 | <dl> |
1122 | <dt>ev_embed_init (ev_embed *, callback, struct ev_loop *loop)</dt> |
1206 | <dt>ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)</dt> |
1123 | <dt>ev_embed_set (ev_embed *, callback, struct ev_loop *loop)</dt> |
1207 | <dt>ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)</dt> |
|
|
1208 | <dd> |
|
|
1209 | <p>Configures the watcher to embed the given loop, which must be |
|
|
1210 | embeddable. If the callback is <code>0</code>, then <code>ev_embed_sweep</code> will be |
|
|
1211 | invoked automatically, otherwise it is the responsibility of the callback |
|
|
1212 | to invoke it (it will continue to be called until the sweep has been done, |
|
|
1213 | if you do not want thta, you need to temporarily stop the embed watcher).</p> |
1124 | <dd> |
1214 | </dd> |
1125 | <p>Configures the watcher to embed the given loop, which must be embeddable.</p> |
1215 | <dt>ev_embed_sweep (loop, ev_embed *)</dt> |
|
|
1216 | <dd> |
|
|
1217 | <p>Make a single, non-blocking sweep over the embedded loop. This works |
|
|
1218 | similarly to <code>ev_loop (embedded_loop, EVLOOP_NONBLOCK)</code>, but in the most |
|
|
1219 | apropriate way for embedded loops.</p> |
1126 | </dd> |
1220 | </dd> |
1127 | </dl> |
1221 | </dl> |
1128 | |
1222 | |
1129 | |
1223 | |
1130 | |
1224 | |
… | |
… | |
1163 | |
1257 | |
1164 | ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
1258 | ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
1165 | |
1259 | |
1166 | </pre> |
1260 | </pre> |
1167 | </dd> |
1261 | </dd> |
1168 | <dt>ev_feed_event (loop, watcher, int events)</dt> |
1262 | <dt>ev_feed_event (ev_loop *, watcher *, int revents)</dt> |
1169 | <dd> |
1263 | <dd> |
1170 | <p>Feeds the given event set into the event loop, as if the specified event |
1264 | <p>Feeds the given event set into the event loop, as if the specified event |
1171 | had happened for the specified watcher (which must be a pointer to an |
1265 | had happened for the specified watcher (which must be a pointer to an |
1172 | initialised but not necessarily started event watcher).</p> |
1266 | initialised but not necessarily started event watcher).</p> |
1173 | </dd> |
1267 | </dd> |
1174 | <dt>ev_feed_fd_event (loop, int fd, int revents)</dt> |
1268 | <dt>ev_feed_fd_event (ev_loop *, int fd, int revents)</dt> |
1175 | <dd> |
1269 | <dd> |
1176 | <p>Feed an event on the given fd, as if a file descriptor backend detected |
1270 | <p>Feed an event on the given fd, as if a file descriptor backend detected |
1177 | the given events it.</p> |
1271 | the given events it.</p> |
1178 | </dd> |
1272 | </dd> |
1179 | <dt>ev_feed_signal_event (loop, int signum)</dt> |
1273 | <dt>ev_feed_signal_event (ev_loop *loop, int signum)</dt> |
1180 | <dd> |
1274 | <dd> |
1181 | <p>Feed an event as if the given signal occured (loop must be the default loop!).</p> |
1275 | <p>Feed an event as if the given signal occured (<code>loop</code> must be the default |
|
|
1276 | loop!).</p> |
1182 | </dd> |
1277 | </dd> |
1183 | </dl> |
1278 | </dl> |
1184 | |
1279 | |
1185 | |
1280 | |
1186 | |
1281 | |