… | |
… | |
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="Fri Nov 23 17:17:04 2007" /> |
9 | <meta name="created" content="Sat Nov 24 05:58:35 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 --> |
… | |
… | |
32 | <li><a href="#code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron</a></li> |
32 | <li><a href="#code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron</a></li> |
33 | <li><a href="#code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled</a></li> |
33 | <li><a href="#code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled</a></li> |
34 | <li><a href="#code_ev_child_code_wait_for_pid_stat"><code>ev_child</code> - wait for pid status changes</a></li> |
34 | <li><a href="#code_ev_child_code_wait_for_pid_stat"><code>ev_child</code> - wait for pid status changes</a></li> |
35 | <li><a href="#code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do</a></li> |
35 | <li><a href="#code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do</a></li> |
36 | <li><a href="#code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop</a></li> |
36 | <li><a href="#code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop</a></li> |
|
|
37 | <li><a href="#code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough</a></li> |
37 | </ul> |
38 | </ul> |
38 | </li> |
39 | </li> |
39 | <li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li> |
40 | <li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li> |
40 | <li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li> |
41 | <li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li> |
41 | <li><a href="#C_SUPPORT">C++ SUPPORT</a></li> |
42 | <li><a href="#C_SUPPORT">C++ SUPPORT</a></li> |
… | |
… | |
156 | recommended for this platform. This set is often smaller than the one |
157 | recommended for this platform. This set is often smaller than the one |
157 | returned by <code>ev_supported_backends</code>, as for example kqueue is broken on |
158 | returned by <code>ev_supported_backends</code>, as for example kqueue is broken on |
158 | most BSDs and will not be autodetected unless you explicitly request it |
159 | most BSDs and will not be autodetected unless you explicitly request it |
159 | (assuming you know what you are doing). This is the set of backends that |
160 | (assuming you know what you are doing). This is the set of backends that |
160 | libev will probe for if you specify no backends explicitly.</p> |
161 | libev will probe for if you specify no backends explicitly.</p> |
|
|
162 | </dd> |
|
|
163 | <dt>unsigned int ev_embeddable_backends ()</dt> |
|
|
164 | <dd> |
|
|
165 | <p>Returns the set of backends that are embeddable in other event loops. This |
|
|
166 | is the theoretical, all-platform, value. To find which backends |
|
|
167 | might be supported on the current system, you would need to look at |
|
|
168 | <code>ev_embeddable_backends () & ev_supported_backends ()</code>, likewise for |
|
|
169 | recommended ones.</p> |
|
|
170 | <p>See the description of <code>ev_embed</code> watchers for more info.</p> |
161 | </dd> |
171 | </dd> |
162 | <dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt> |
172 | <dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt> |
163 | <dd> |
173 | <dd> |
164 | <p>Sets the allocation function to use (the prototype is similar to the |
174 | <p>Sets the allocation function to use (the prototype is similar to the |
165 | realloc C function, the semantics are identical). It is used to allocate |
175 | realloc C function, the semantics are identical). It is used to allocate |
… | |
… | |
931 | <p>Configures the watcher to trigger on the given signal number (usually one |
941 | <p>Configures the watcher to trigger on the given signal number (usually one |
932 | of the <code>SIGxxx</code> constants).</p> |
942 | of the <code>SIGxxx</code> constants).</p> |
933 | </dd> |
943 | </dd> |
934 | </dl> |
944 | </dl> |
935 | |
945 | |
|
|
946 | |
|
|
947 | |
|
|
948 | |
|
|
949 | |
936 | </div> |
950 | </div> |
937 | <h2 id="code_ev_child_code_wait_for_pid_stat"><code>ev_child</code> - wait for pid status changes</h2> |
951 | <h2 id="code_ev_child_code_wait_for_pid_stat"><code>ev_child</code> - wait for pid status changes</h2> |
938 | <div id="code_ev_child_code_wait_for_pid_stat-2"> |
952 | <div id="code_ev_child_code_wait_for_pid_stat-2"> |
939 | <p>Child watchers trigger when your process receives a SIGCHLD in response to |
953 | <p>Child watchers trigger when your process receives a SIGCHLD in response to |
940 | some child status changes (most typically when a child of yours dies).</p> |
954 | some child status changes (most typically when a child of yours dies).</p> |
… | |
… | |
1013 | <h2 id="code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop</h2> |
1027 | <h2 id="code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop</h2> |
1014 | <div id="code_ev_prepare_code_and_code_ev_che-2"> |
1028 | <div id="code_ev_prepare_code_and_code_ev_che-2"> |
1015 | <p>Prepare and check watchers are usually (but not always) used in tandem: |
1029 | <p>Prepare and check watchers are usually (but not always) used in tandem: |
1016 | prepare watchers get invoked before the process blocks and check watchers |
1030 | prepare watchers get invoked before the process blocks and check watchers |
1017 | afterwards.</p> |
1031 | afterwards.</p> |
1018 | <p>Their main purpose is to integrate other event mechanisms into libev. This |
1032 | <p>Their main purpose is to integrate other event mechanisms into libev and |
1019 | could be used, for example, to track variable changes, implement your own |
1033 | their use is somewhat advanced. This could be used, for example, to track |
1020 | watchers, integrate net-snmp or a coroutine library and lots more.</p> |
1034 | variable changes, implement your own watchers, integrate net-snmp or a |
|
|
1035 | coroutine library and lots more.</p> |
1021 | <p>This is done by examining in each prepare call which file descriptors need |
1036 | <p>This is done by examining in each prepare call which file descriptors need |
1022 | to be watched by the other library, registering <code>ev_io</code> watchers for |
1037 | to be watched by the other library, registering <code>ev_io</code> watchers for |
1023 | them and starting an <code>ev_timer</code> watcher for any timeouts (many libraries |
1038 | them and starting an <code>ev_timer</code> watcher for any timeouts (many libraries |
1024 | provide just this functionality). Then, in the check watcher you check for |
1039 | provide just this functionality). Then, in the check watcher you check for |
1025 | any events that occured (by checking the pending status of all watchers |
1040 | any events that occured (by checking the pending status of all watchers |
… | |
… | |
1042 | parameters of any kind. There are <code>ev_prepare_set</code> and <code>ev_check_set</code> |
1057 | parameters of any kind. There are <code>ev_prepare_set</code> and <code>ev_check_set</code> |
1043 | macros, but using them is utterly, utterly and completely pointless.</p> |
1058 | macros, but using them is utterly, utterly and completely pointless.</p> |
1044 | </dd> |
1059 | </dd> |
1045 | </dl> |
1060 | </dl> |
1046 | <p>Example: *TODO*.</p> |
1061 | <p>Example: *TODO*.</p> |
|
|
1062 | |
|
|
1063 | |
|
|
1064 | |
|
|
1065 | |
|
|
1066 | |
|
|
1067 | </div> |
|
|
1068 | <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"> |
|
|
1070 | <p>This is a rather advanced watcher type that lets you embed one event loop |
|
|
1071 | into another.</p> |
|
|
1072 | <p>There are primarily two reasons you would want that: work around bugs and |
|
|
1073 | prioritise I/O.</p> |
|
|
1074 | <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 |
|
|
1076 | still want to make use of it because you have many sockets and it scales |
|
|
1077 | so nicely. In this case, you would create a kqueue-based loop and embed it |
|
|
1078 | into your default loop (which might use e.g. poll). Overall operation will |
|
|
1079 | be a bit slower because first libev has to poll and then call kevent, but |
|
|
1080 | at least you can use both at what they are best.</p> |
|
|
1081 | <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 |
|
|
1083 | 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 |
|
|
1085 | a second one, and embed the second one in the first.</p> |
|
|
1086 | <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 |
|
|
1088 | set the callback to <code>0</code> to avoid having to specify one if you are not |
|
|
1089 | interested in that.</p> |
|
|
1090 | <p>Also, there have not currently been made special provisions for forking: |
|
|
1091 | when you fork, you not only have to call <code>ev_loop_fork</code> on both loops, |
|
|
1092 | but you will also have to stop and restart any <code>ev_embed</code> watchers |
|
|
1093 | yourself.</p> |
|
|
1094 | <p>Unfortunately, not all backends are embeddable, only the ones returned by |
|
|
1095 | <code>ev_embeddable_backends</code> are, which, unfortunately, does not include any |
|
|
1096 | portable one.</p> |
|
|
1097 | <p>So when you want to use this feature you will always have to be prepared |
|
|
1098 | that you cannot get an embeddable loop. The recommended way to get around |
|
|
1099 | this is to have a separate variables for your embeddable loop, try to |
|
|
1100 | create it, and if that fails, use the normal loop for everything:</p> |
|
|
1101 | <pre> struct ev_loop *loop_hi = ev_default_init (0); |
|
|
1102 | struct ev_loop *loop_lo = 0; |
|
|
1103 | struct ev_embed embed; |
|
|
1104 | |
|
|
1105 | // see if there is a chance of getting one that works |
|
|
1106 | // (remember that a flags value of 0 means autodetection) |
|
|
1107 | loop_lo = ev_embeddable_backends () & ev_recommended_backends () |
|
|
1108 | ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) |
|
|
1109 | : 0; |
|
|
1110 | |
|
|
1111 | // if we got one, then embed it, otherwise default to loop_hi |
|
|
1112 | if (loop_lo) |
|
|
1113 | { |
|
|
1114 | ev_embed_init (&embed, 0, loop_lo); |
|
|
1115 | ev_embed_start (loop_hi, &embed); |
|
|
1116 | } |
|
|
1117 | else |
|
|
1118 | loop_lo = loop_hi; |
|
|
1119 | |
|
|
1120 | </pre> |
|
|
1121 | <dl> |
|
|
1122 | <dt>ev_embed_init (ev_embed *, callback, struct ev_loop *loop)</dt> |
|
|
1123 | <dt>ev_embed_set (ev_embed *, callback, struct ev_loop *loop)</dt> |
|
|
1124 | <dd> |
|
|
1125 | <p>Configures the watcher to embed the given loop, which must be embeddable.</p> |
|
|
1126 | </dd> |
|
|
1127 | </dl> |
1047 | |
1128 | |
1048 | |
1129 | |
1049 | |
1130 | |
1050 | |
1131 | |
1051 | |
1132 | |