… | |
… | |
127 | .\} |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
129 | .\" ======================================================================== |
130 | .\" |
130 | .\" |
131 | .IX Title ""<STANDARD INPUT>" 1" |
131 | .IX Title ""<STANDARD INPUT>" 1" |
132 | .TH "<STANDARD INPUT>" 1 "2007-11-23" "perl v5.8.8" "User Contributed Perl Documentation" |
132 | .TH "<STANDARD INPUT>" 1 "2007-11-24" "perl v5.8.8" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
133 | .SH "NAME" |
134 | libev \- a high performance full\-featured event loop written in C |
134 | libev \- a high performance full\-featured event loop written in C |
135 | .SH "SYNOPSIS" |
135 | .SH "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
137 | .Vb 1 |
137 | .Vb 1 |
… | |
… | |
231 | recommended for this platform. This set is often smaller than the one |
231 | recommended for this platform. This set is often smaller than the one |
232 | returned by \f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on |
232 | returned by \f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on |
233 | most BSDs and will not be autodetected unless you explicitly request it |
233 | most BSDs and will not be autodetected unless you explicitly request it |
234 | (assuming you know what you are doing). This is the set of backends that |
234 | (assuming you know what you are doing). This is the set of backends that |
235 | libev will probe for if you specify no backends explicitly. |
235 | libev will probe for if you specify no backends explicitly. |
|
|
236 | .IP "unsigned int ev_embeddable_backends ()" 4 |
|
|
237 | .IX Item "unsigned int ev_embeddable_backends ()" |
|
|
238 | Returns the set of backends that are embeddable in other event loops. This |
|
|
239 | is the theoretical, all\-platform, value. To find which backends |
|
|
240 | might be supported on the current system, you would need to look at |
|
|
241 | \&\f(CW\*(C`ev_embeddable_backends () & ev_supported_backends ()\*(C'\fR, likewise for |
|
|
242 | recommended ones. |
|
|
243 | .Sp |
|
|
244 | See the description of \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. |
236 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
245 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
237 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
246 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
238 | Sets the allocation function to use (the prototype is similar to the |
247 | Sets the allocation function to use (the prototype is similar to the |
239 | realloc C function, the semantics are identical). It is used to allocate |
248 | realloc C function, the semantics are identical). It is used to allocate |
240 | and free memory (no surprises here). If it returns zero when memory |
249 | and free memory (no surprises here). If it returns zero when memory |
… | |
… | |
1159 | .IX Subsection "ev_prepare and ev_check - customise your event loop" |
1168 | .IX Subsection "ev_prepare and ev_check - customise your event loop" |
1160 | Prepare and check watchers are usually (but not always) used in tandem: |
1169 | Prepare and check watchers are usually (but not always) used in tandem: |
1161 | prepare watchers get invoked before the process blocks and check watchers |
1170 | prepare watchers get invoked before the process blocks and check watchers |
1162 | afterwards. |
1171 | afterwards. |
1163 | .PP |
1172 | .PP |
1164 | Their main purpose is to integrate other event mechanisms into libev. This |
1173 | Their main purpose is to integrate other event mechanisms into libev and |
1165 | could be used, for example, to track variable changes, implement your own |
1174 | their use is somewhat advanced. This could be used, for example, to track |
1166 | watchers, integrate net-snmp or a coroutine library and lots more. |
1175 | variable changes, implement your own watchers, integrate net-snmp or a |
|
|
1176 | coroutine library and lots more. |
1167 | .PP |
1177 | .PP |
1168 | This is done by examining in each prepare call which file descriptors need |
1178 | This is done by examining in each prepare call which file descriptors need |
1169 | to be watched by the other library, registering \f(CW\*(C`ev_io\*(C'\fR watchers for |
1179 | to be watched by the other library, registering \f(CW\*(C`ev_io\*(C'\fR watchers for |
1170 | them and starting an \f(CW\*(C`ev_timer\*(C'\fR watcher for any timeouts (many libraries |
1180 | them and starting an \f(CW\*(C`ev_timer\*(C'\fR watcher for any timeouts (many libraries |
1171 | provide just this functionality). Then, in the check watcher you check for |
1181 | provide just this functionality). Then, in the check watcher you check for |
… | |
… | |
1191 | Initialises and configures the prepare or check watcher \- they have no |
1201 | Initialises and configures the prepare or check watcher \- they have no |
1192 | parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR |
1202 | parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR |
1193 | macros, but using them is utterly, utterly and completely pointless. |
1203 | macros, but using them is utterly, utterly and completely pointless. |
1194 | .PP |
1204 | .PP |
1195 | Example: *TODO*. |
1205 | Example: *TODO*. |
|
|
1206 | .ie n .Sh """ev_embed"" \- when one backend isn't enough" |
|
|
1207 | .el .Sh "\f(CWev_embed\fP \- when one backend isn't enough" |
|
|
1208 | .IX Subsection "ev_embed - when one backend isn't enough" |
|
|
1209 | This is a rather advanced watcher type that lets you embed one event loop |
|
|
1210 | into another. |
|
|
1211 | .PP |
|
|
1212 | There are primarily two reasons you would want that: work around bugs and |
|
|
1213 | prioritise I/O. |
|
|
1214 | .PP |
|
|
1215 | As an example for a bug workaround, the kqueue backend might only support |
|
|
1216 | sockets on some platform, so it is unusable as generic backend, but you |
|
|
1217 | still want to make use of it because you have many sockets and it scales |
|
|
1218 | so nicely. In this case, you would create a kqueue-based loop and embed it |
|
|
1219 | into your default loop (which might use e.g. poll). Overall operation will |
|
|
1220 | be a bit slower because first libev has to poll and then call kevent, but |
|
|
1221 | at least you can use both at what they are best. |
|
|
1222 | .PP |
|
|
1223 | As for prioritising I/O: rarely you have the case where some fds have |
|
|
1224 | to be watched and handled very quickly (with low latency), and even |
|
|
1225 | priorities and idle watchers might have too much overhead. In this case |
|
|
1226 | you would put all the high priority stuff in one loop and all the rest in |
|
|
1227 | a second one, and embed the second one in the first. |
|
|
1228 | .PP |
|
|
1229 | As long as the watcher is started it will automatically handle events. The |
|
|
1230 | callback will be invoked whenever some events have been handled. You can |
|
|
1231 | set the callback to \f(CW0\fR to avoid having to specify one if you are not |
|
|
1232 | interested in that. |
|
|
1233 | .PP |
|
|
1234 | Also, there have not currently been made special provisions for forking: |
|
|
1235 | when you fork, you not only have to call \f(CW\*(C`ev_loop_fork\*(C'\fR on both loops, |
|
|
1236 | but you will also have to stop and restart any \f(CW\*(C`ev_embed\*(C'\fR watchers |
|
|
1237 | yourself. |
|
|
1238 | .PP |
|
|
1239 | Unfortunately, not all backends are embeddable, only the ones returned by |
|
|
1240 | \&\f(CW\*(C`ev_embeddable_backends\*(C'\fR are, which, unfortunately, does not include any |
|
|
1241 | portable one. |
|
|
1242 | .PP |
|
|
1243 | So when you want to use this feature you will always have to be prepared |
|
|
1244 | that you cannot get an embeddable loop. The recommended way to get around |
|
|
1245 | this is to have a separate variables for your embeddable loop, try to |
|
|
1246 | create it, and if that fails, use the normal loop for everything: |
|
|
1247 | .PP |
|
|
1248 | .Vb 3 |
|
|
1249 | \& struct ev_loop *loop_hi = ev_default_init (0); |
|
|
1250 | \& struct ev_loop *loop_lo = 0; |
|
|
1251 | \& struct ev_embed embed; |
|
|
1252 | .Ve |
|
|
1253 | .PP |
|
|
1254 | .Vb 5 |
|
|
1255 | \& // see if there is a chance of getting one that works |
|
|
1256 | \& // (remember that a flags value of 0 means autodetection) |
|
|
1257 | \& loop_lo = ev_embeddable_backends () & ev_recommended_backends () |
|
|
1258 | \& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) |
|
|
1259 | \& : 0; |
|
|
1260 | .Ve |
|
|
1261 | .PP |
|
|
1262 | .Vb 8 |
|
|
1263 | \& // if we got one, then embed it, otherwise default to loop_hi |
|
|
1264 | \& if (loop_lo) |
|
|
1265 | \& { |
|
|
1266 | \& ev_embed_init (&embed, 0, loop_lo); |
|
|
1267 | \& ev_embed_start (loop_hi, &embed); |
|
|
1268 | \& } |
|
|
1269 | \& else |
|
|
1270 | \& loop_lo = loop_hi; |
|
|
1271 | .Ve |
|
|
1272 | .IP "ev_embed_init (ev_embed *, callback, struct ev_loop *loop)" 4 |
|
|
1273 | .IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *loop)" |
|
|
1274 | .PD 0 |
|
|
1275 | .IP "ev_embed_set (ev_embed *, callback, struct ev_loop *loop)" 4 |
|
|
1276 | .IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *loop)" |
|
|
1277 | .PD |
|
|
1278 | Configures the watcher to embed the given loop, which must be embeddable. |
1196 | .SH "OTHER FUNCTIONS" |
1279 | .SH "OTHER FUNCTIONS" |
1197 | .IX Header "OTHER FUNCTIONS" |
1280 | .IX Header "OTHER FUNCTIONS" |
1198 | There are some other functions of possible interest. Described. Here. Now. |
1281 | There are some other functions of possible interest. Described. Here. Now. |
1199 | .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
1282 | .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
1200 | .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |
1283 | .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |