… | |
… | |
359 | writing a server, you should C<accept ()> in a loop to accept as many |
359 | writing a server, you should C<accept ()> in a loop to accept as many |
360 | connections as possible during one iteration. You might also want to have |
360 | connections as possible during one iteration. You might also want to have |
361 | a look at C<ev_set_io_collect_interval ()> to increase the amount of |
361 | a look at C<ev_set_io_collect_interval ()> to increase the amount of |
362 | readiness notifications you get per iteration. |
362 | readiness notifications you get per iteration. |
363 | |
363 | |
|
|
364 | This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the |
|
|
365 | C<writefds> set (and to work around Microsoft Windows bugs, also onto the |
|
|
366 | C<exceptfds> set on that platform). |
|
|
367 | |
364 | =item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) |
368 | =item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) |
365 | |
369 | |
366 | And this is your standard poll(2) backend. It's more complicated |
370 | And this is your standard poll(2) backend. It's more complicated |
367 | than select, but handles sparse fds better and has no artificial |
371 | than select, but handles sparse fds better and has no artificial |
368 | limit on the number of fds you can use (except it will slow down |
372 | limit on the number of fds you can use (except it will slow down |
369 | considerably with a lot of inactive fds). It scales similarly to select, |
373 | considerably with a lot of inactive fds). It scales similarly to select, |
370 | i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for |
374 | i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for |
371 | performance tips. |
375 | performance tips. |
|
|
376 | |
|
|
377 | This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and |
|
|
378 | C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. |
372 | |
379 | |
373 | =item C<EVBACKEND_EPOLL> (value 4, Linux) |
380 | =item C<EVBACKEND_EPOLL> (value 4, Linux) |
374 | |
381 | |
375 | For few fds, this backend is a bit little slower than poll and select, |
382 | For few fds, this backend is a bit little slower than poll and select, |
376 | but it scales phenomenally better. While poll and select usually scale |
383 | but it scales phenomenally better. While poll and select usually scale |
… | |
… | |
395 | keep at least one watcher active per fd at all times. |
402 | keep at least one watcher active per fd at all times. |
396 | |
403 | |
397 | While nominally embeddable in other event loops, this feature is broken in |
404 | While nominally embeddable in other event loops, this feature is broken in |
398 | all kernel versions tested so far. |
405 | all kernel versions tested so far. |
399 | |
406 | |
|
|
407 | This backend maps C<EV_READ> and C<EV_WRITE> in the same way as |
|
|
408 | C<EVBACKEND_POLL>. |
|
|
409 | |
400 | =item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) |
410 | =item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) |
401 | |
411 | |
402 | Kqueue deserves special mention, as at the time of this writing, it |
412 | Kqueue deserves special mention, as at the time of this writing, it |
403 | was broken on all BSDs except NetBSD (usually it doesn't work reliably |
413 | was broken on all BSDs except NetBSD (usually it doesn't work reliably |
404 | with anything but sockets and pipes, except on Darwin, where of course |
414 | with anything but sockets and pipes, except on Darwin, where of course |
… | |
… | |
425 | almost everywhere, you should only use it when you have a lot of sockets |
435 | almost everywhere, you should only use it when you have a lot of sockets |
426 | (for which it usually works), by embedding it into another event loop |
436 | (for which it usually works), by embedding it into another event loop |
427 | (e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for |
437 | (e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for |
428 | sockets. |
438 | sockets. |
429 | |
439 | |
|
|
440 | This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with |
|
|
441 | C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with |
|
|
442 | C<NOTE_EOF>. |
|
|
443 | |
430 | =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) |
444 | =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) |
431 | |
445 | |
432 | This is not implemented yet (and might never be, unless you send me an |
446 | This is not implemented yet (and might never be, unless you send me an |
433 | implementation). According to reports, C</dev/poll> only supports sockets |
447 | implementation). According to reports, C</dev/poll> only supports sockets |
434 | and is not embeddable, which would limit the usefulness of this backend |
448 | and is not embeddable, which would limit the usefulness of this backend |
… | |
… | |
449 | might perform better. |
463 | might perform better. |
450 | |
464 | |
451 | On the positive side, ignoring the spurious readiness notifications, this |
465 | On the positive side, ignoring the spurious readiness notifications, this |
452 | backend actually performed to specification in all tests and is fully |
466 | backend actually performed to specification in all tests and is fully |
453 | embeddable, which is a rare feat among the OS-specific backends. |
467 | embeddable, which is a rare feat among the OS-specific backends. |
|
|
468 | |
|
|
469 | This backend maps C<EV_READ> and C<EV_WRITE> in the same way as |
|
|
470 | C<EVBACKEND_POLL>. |
454 | |
471 | |
455 | =item C<EVBACKEND_ALL> |
472 | =item C<EVBACKEND_ALL> |
456 | |
473 | |
457 | Try all backends (even potentially broken ones that wouldn't be tried |
474 | Try all backends (even potentially broken ones that wouldn't be tried |
458 | with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as |
475 | with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as |
… | |
… | |
3223 | |
3240 | |
3224 | =head1 THREADS AND COROUTINES |
3241 | =head1 THREADS AND COROUTINES |
3225 | |
3242 | |
3226 | =head2 THREADS |
3243 | =head2 THREADS |
3227 | |
3244 | |
3228 | Libev itself is completely thread-safe, but it uses no locking. This |
3245 | Libev itself is thread-safe (unless the opposite is specifically |
|
|
3246 | documented for a function), but it uses no locking itself. This means that |
3229 | means that you can use as many loops as you want in parallel, as long as |
3247 | you can use as many loops as you want in parallel, as long as only one |
3230 | only one thread ever calls into one libev function with the same loop |
3248 | thread ever calls into one libev function with the same loop parameter: |
3231 | parameter. |
3249 | libev guarentees that different event loops share no data structures that |
|
|
3250 | need locking. |
3232 | |
3251 | |
3233 | Or put differently: calls with different loop parameters can be done in |
3252 | Or to put it differently: calls with different loop parameters can be done |
3234 | parallel from multiple threads, calls with the same loop parameter must be |
3253 | concurrently from multiple threads, calls with the same loop parameter |
3235 | done serially (but can be done from different threads, as long as only one |
3254 | must be done serially (but can be done from different threads, as long as |
3236 | thread ever is inside a call at any point in time, e.g. by using a mutex |
3255 | only one thread ever is inside a call at any point in time, e.g. by using |
3237 | per loop). |
3256 | a mutex per loop). |
|
|
3257 | |
|
|
3258 | Specifically to support threads (and signal handlers), libev implements |
|
|
3259 | so-called C<ev_async> watchers, which allow some limited form of |
|
|
3260 | concurrency on the same event loop. |
3238 | |
3261 | |
3239 | If you want to know which design (one loop, locking, or multiple loops |
3262 | If you want to know which design (one loop, locking, or multiple loops |
3240 | without or something else still) is best for your problem, then I cannot |
3263 | without or something else still) is best for your problem, then I cannot |
3241 | help you. I can give some generic advice however: |
3264 | help you. I can give some generic advice however: |
3242 | |
3265 | |
… | |
… | |
3260 | better than you currently do :-) |
3283 | better than you currently do :-) |
3261 | |
3284 | |
3262 | =item * often you need to talk to some other thread which blocks in the |
3285 | =item * often you need to talk to some other thread which blocks in the |
3263 | event loop - C<ev_async> watchers can be used to wake them up from other |
3286 | event loop - C<ev_async> watchers can be used to wake them up from other |
3264 | threads safely (or from signal contexts...). |
3287 | threads safely (or from signal contexts...). |
|
|
3288 | |
|
|
3289 | =item * some watcher types are only supported in the default loop - use |
|
|
3290 | C<ev_async> watchers to tell your other loops about any such events. |
3265 | |
3291 | |
3266 | =back |
3292 | =back |
3267 | |
3293 | |
3268 | =head2 COROUTINES |
3294 | =head2 COROUTINES |
3269 | |
3295 | |
… | |
… | |
3272 | coroutines (e.g. you can call C<ev_loop> on the same loop from two |
3298 | coroutines (e.g. you can call C<ev_loop> on the same loop from two |
3273 | different coroutines and switch freely between both coroutines running the |
3299 | different coroutines and switch freely between both coroutines running the |
3274 | loop, as long as you don't confuse yourself). The only exception is that |
3300 | loop, as long as you don't confuse yourself). The only exception is that |
3275 | you must not do this from C<ev_periodic> reschedule callbacks. |
3301 | you must not do this from C<ev_periodic> reschedule callbacks. |
3276 | |
3302 | |
3277 | Care has been invested into making sure that libev does not keep local |
3303 | Care has been taken to ensure that libev does not keep local state inside |
3278 | state inside C<ev_loop>, and other calls do not usually allow coroutine |
3304 | C<ev_loop>, and other calls do not usually allow coroutine switches. |
3279 | switches. |
|
|
3280 | |
3305 | |
3281 | |
3306 | |
3282 | =head1 COMPLEXITIES |
3307 | =head1 COMPLEXITIES |
3283 | |
3308 | |
3284 | In this section the complexities of (many of) the algorithms used inside |
3309 | In this section the complexities of (many of) the algorithms used inside |