… | |
… | |
212 | Return the set of all backends compiled into this binary of libev and also |
212 | Return the set of all backends compiled into this binary of libev and also |
213 | recommended for this platform. This set is often smaller than the one |
213 | recommended for this platform. This set is often smaller than the one |
214 | returned by \f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on |
214 | returned by \f(CW\*(C`ev_supported_backends\*(C'\fR, as for example kqueue is broken on |
215 | most BSDs and will not be autodetected unless you explicitly request it |
215 | most BSDs and will not be autodetected unless you explicitly request it |
216 | (assuming you know what you are doing). This is the set of backends that |
216 | (assuming you know what you are doing). This is the set of backends that |
217 | \&\f(CW\*(C`EVFLAG_AUTO\*(C'\fR will probe for. |
217 | libev will probe for if you specify no backends explicitly. |
218 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
218 | .IP "ev_set_allocator (void *(*cb)(void *ptr, long size))" 4 |
219 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
219 | .IX Item "ev_set_allocator (void *(*cb)(void *ptr, long size))" |
220 | Sets the allocation function to use (the prototype is similar to the |
220 | Sets the allocation function to use (the prototype is similar to the |
221 | realloc C function, the semantics are identical). It is used to allocate |
221 | realloc C function, the semantics are identical). It is used to allocate |
222 | and free memory (no surprises here). If it returns zero when memory |
222 | and free memory (no surprises here). If it returns zero when memory |
… | |
… | |
256 | .Sp |
256 | .Sp |
257 | If you don't know what event loop to use, use the one returned from this |
257 | If you don't know what event loop to use, use the one returned from this |
258 | function. |
258 | function. |
259 | .Sp |
259 | .Sp |
260 | The flags argument can be used to specify special behaviour or specific |
260 | The flags argument can be used to specify special behaviour or specific |
261 | backends to use, and is usually specified as \f(CW0\fR (or \s-1EVFLAG_AUTO\s0). |
261 | backends to use, and is usually specified as \f(CW0\fR (or \f(CW\*(C`EVFLAG_AUTO\*(C'\fR). |
262 | .Sp |
262 | .Sp |
263 | It supports the following flags: |
263 | The following flags are supported: |
264 | .RS 4 |
264 | .RS 4 |
265 | .ie n .IP """EVFLAG_AUTO""" 4 |
265 | .ie n .IP """EVFLAG_AUTO""" 4 |
266 | .el .IP "\f(CWEVFLAG_AUTO\fR" 4 |
266 | .el .IP "\f(CWEVFLAG_AUTO\fR" 4 |
267 | .IX Item "EVFLAG_AUTO" |
267 | .IX Item "EVFLAG_AUTO" |
268 | The default flags value. Use this if you have no clue (it's the right |
268 | The default flags value. Use this if you have no clue (it's the right |
… | |
… | |
312 | .el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
312 | .el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 |
313 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
313 | .IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" |
314 | Kqueue deserves special mention, as at the time of this writing, it |
314 | Kqueue deserves special mention, as at the time of this writing, it |
315 | was broken on all BSDs except NetBSD (usually it doesn't work with |
315 | was broken on all BSDs except NetBSD (usually it doesn't work with |
316 | anything but sockets and pipes, except on Darwin, where of course its |
316 | anything but sockets and pipes, except on Darwin, where of course its |
317 | completely useless). For this reason its not being \*(L"autodetected\*(R" unless |
317 | completely useless). For this reason its not being \*(L"autodetected\*(R" |
318 | you explicitly specify the flags (i.e. you don't use \s-1EVFLAG_AUTO\s0). |
318 | unless you explicitly specify it explicitly in the flags (i.e. using |
|
|
319 | \&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR). |
319 | .Sp |
320 | .Sp |
320 | It scales in the same way as the epoll backend, but the interface to the |
321 | It scales in the same way as the epoll backend, but the interface to the |
321 | kernel is more efficient (which says nothing about its actual speed, of |
322 | kernel is more efficient (which says nothing about its actual speed, of |
322 | course). While starting and stopping an I/O watcher does not cause an |
323 | course). While starting and stopping an I/O watcher does not cause an |
323 | extra syscall as with epoll, it still adds up to four event changes per |
324 | extra syscall as with epoll, it still adds up to four event changes per |
… | |
… | |
346 | .Sp |
347 | .Sp |
347 | If one or more of these are ored into the flags value, then only these |
348 | If one or more of these are ored into the flags value, then only these |
348 | backends will be tried (in the reverse order as given here). If none are |
349 | backends will be tried (in the reverse order as given here). If none are |
349 | specified, most compiled-in backend will be tried, usually in reverse |
350 | specified, most compiled-in backend will be tried, usually in reverse |
350 | order of their flag values :) |
351 | order of their flag values :) |
|
|
352 | .Sp |
|
|
353 | The most typical usage is like this: |
|
|
354 | .Sp |
|
|
355 | .Vb 2 |
|
|
356 | \& if (!ev_default_loop (0)) |
|
|
357 | \& fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); |
|
|
358 | .Ve |
|
|
359 | .Sp |
|
|
360 | Restrict libev to the select and poll backends, and do not allow |
|
|
361 | environment settings to be taken into account: |
|
|
362 | .Sp |
|
|
363 | .Vb 1 |
|
|
364 | \& ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV); |
|
|
365 | .Ve |
|
|
366 | .Sp |
|
|
367 | Use whatever libev has to offer, but make sure that kqueue is used if |
|
|
368 | available (warning, breaks stuff, best use only with your own private |
|
|
369 | event loop and only if you know the \s-1OS\s0 supports your types of fds): |
|
|
370 | .Sp |
|
|
371 | .Vb 1 |
|
|
372 | \& ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); |
|
|
373 | .Ve |
351 | .RE |
374 | .RE |
352 | .IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4 |
375 | .IP "struct ev_loop *ev_loop_new (unsigned int flags)" 4 |
353 | .IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" |
376 | .IX Item "struct ev_loop *ev_loop_new (unsigned int flags)" |
354 | Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is |
377 | Similar to \f(CW\*(C`ev_default_loop\*(C'\fR, but always creates a new event loop that is |
355 | always distinct from the default loop. Unlike the default loop, it cannot |
378 | always distinct from the default loop. Unlike the default loop, it cannot |
… | |
… | |
406 | .IX Item "ev_loop (loop, int flags)" |
429 | .IX Item "ev_loop (loop, int flags)" |
407 | Finally, this is it, the event handler. This function usually is called |
430 | Finally, this is it, the event handler. This function usually is called |
408 | after you initialised all your watchers and you want to start handling |
431 | after you initialised all your watchers and you want to start handling |
409 | events. |
432 | events. |
410 | .Sp |
433 | .Sp |
411 | If the flags argument is specified as 0, it will not return until either |
434 | If the flags argument is specified as \f(CW0\fR, it will not return until |
412 | no event watchers are active anymore or \f(CW\*(C`ev_unloop\*(C'\fR was called. |
435 | either no event watchers are active anymore or \f(CW\*(C`ev_unloop\*(C'\fR was called. |
413 | .Sp |
436 | .Sp |
414 | A flags value of \f(CW\*(C`EVLOOP_NONBLOCK\*(C'\fR will look for new events, will handle |
437 | A flags value of \f(CW\*(C`EVLOOP_NONBLOCK\*(C'\fR will look for new events, will handle |
415 | those events and any outstanding ones, but will not block your process in |
438 | those events and any outstanding ones, but will not block your process in |
416 | case there are no events and will return after one iteration of the loop. |
439 | case there are no events and will return after one iteration of the loop. |
417 | .Sp |
440 | .Sp |
418 | A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if |
441 | A flags value of \f(CW\*(C`EVLOOP_ONESHOT\*(C'\fR will look for new events (waiting if |
419 | neccessary) and will handle those and any outstanding ones. It will block |
442 | neccessary) and will handle those and any outstanding ones. It will block |
420 | your process until at least one new event arrives, and will return after |
443 | your process until at least one new event arrives, and will return after |
421 | one iteration of the loop. |
444 | one iteration of the loop. This is useful if you are waiting for some |
|
|
445 | external event in conjunction with something not expressible using other |
|
|
446 | libev watchers. However, a pair of \f(CW\*(C`ev_prepare\*(C'\fR/\f(CW\*(C`ev_check\*(C'\fR watchers is |
|
|
447 | usually a better approach for this kind of thing. |
422 | .Sp |
448 | .Sp |
423 | This flags value could be used to implement alternative looping |
|
|
424 | constructs, but the \f(CW\*(C`prepare\*(C'\fR and \f(CW\*(C`check\*(C'\fR watchers provide a better and |
|
|
425 | more generic mechanism. |
|
|
426 | .Sp |
|
|
427 | Here are the gory details of what ev_loop does: |
449 | Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does: |
428 | .Sp |
450 | .Sp |
429 | .Vb 15 |
451 | .Vb 18 |
430 | \& 1. If there are no active watchers (reference count is zero), return. |
452 | \& * If there are no active watchers (reference count is zero), return. |
431 | \& 2. Queue and immediately call all prepare watchers. |
453 | \& - Queue prepare watchers and then call all outstanding watchers. |
432 | \& 3. If we have been forked, recreate the kernel state. |
454 | \& - If we have been forked, recreate the kernel state. |
433 | \& 4. Update the kernel state with all outstanding changes. |
455 | \& - Update the kernel state with all outstanding changes. |
434 | \& 5. Update the "event loop time". |
456 | \& - Update the "event loop time". |
435 | \& 6. Calculate for how long to block. |
457 | \& - Calculate for how long to block. |
436 | \& 7. Block the process, waiting for events. |
458 | \& - Block the process, waiting for any events. |
|
|
459 | \& - Queue all outstanding I/O (fd) events. |
437 | \& 8. Update the "event loop time" and do time jump handling. |
460 | \& - Update the "event loop time" and do time jump handling. |
438 | \& 9. Queue all outstanding timers. |
461 | \& - Queue all outstanding timers. |
439 | \& 10. Queue all outstanding periodics. |
462 | \& - Queue all outstanding periodics. |
440 | \& 11. If no events are pending now, queue all idle watchers. |
463 | \& - If no events are pending now, queue all idle watchers. |
441 | \& 12. Queue all check watchers. |
464 | \& - Queue all check watchers. |
442 | \& 13. Call all queued watchers in reverse order (i.e. check watchers first). |
465 | \& - Call all queued watchers in reverse order (i.e. check watchers first). |
|
|
466 | \& Signals and child watchers are implemented as I/O watchers, and will |
|
|
467 | \& be handled here by queueing them when their watcher gets executed. |
443 | \& 14. If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
468 | \& - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
444 | \& was used, return, otherwise continue with step #1. |
469 | \& were used, return, otherwise continue with step *. |
445 | .Ve |
470 | .Ve |
446 | .IP "ev_unloop (loop, how)" 4 |
471 | .IP "ev_unloop (loop, how)" 4 |
447 | .IX Item "ev_unloop (loop, how)" |
472 | .IX Item "ev_unloop (loop, how)" |
448 | Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it |
473 | Can be used to make a call to \f(CW\*(C`ev_loop\*(C'\fR return early (but only after it |
449 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
474 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |