ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.451 by root, Mon Jun 24 00:19:26 2019 UTC vs.
Revision 1.454 by root, Tue Jun 25 05:17:50 2019 UTC

… …
511This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 511This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
512C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 512C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
513 513
514=item C<EVBACKEND_EPOLL> (value 4, Linux) 514=item C<EVBACKEND_EPOLL> (value 4, Linux)
515 515
516Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9 516Use the Linux-specific epoll(7) interface (for both pre- and post-2.6.9
517kernels). 517kernels).
518 518
519For few fds, this backend is a bit little slower than poll and select, but 519For few fds, this backend is a bit little slower than poll and select, but
520it scales phenomenally better. While poll and select usually scale like 520it scales phenomenally better. While poll and select usually scale like
521O(total_fds) where total_fds is the total number of fds (or the highest 521O(total_fds) where total_fds is the total number of fds (or the highest
… …
574This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 574This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
575C<EVBACKEND_POLL>. 575C<EVBACKEND_POLL>.
576 576
577=item C<EVBACKEND_LINUXAIO> (value 64, Linux) 577=item C<EVBACKEND_LINUXAIO> (value 64, Linux)
578 578
579Use the linux-specific linux aio (I<not> C<< aio(7) >> but C<< 579Use the Linux-specific Linux AIO (I<not> C<< aio(7) >> but C<<
580io_submit(2) >>) event interface available in post-4.18 kernels. 580io_submit(2) >>) event interface available in post-4.18 kernels (but libev
581only tries to use it in 4.19+).
582
583This is another Linux train wreck of an event interface.
581 584
582If this backend works for you (as of this writing, it was very 585If this backend works for you (as of this writing, it was very
583experimental), it is the best event interface available on linux and might 586experimental), it is the best event interface available on Linux and might
584be well worth enabling it - if it isn't available in your kernel this will 587be well worth enabling it - if it isn't available in your kernel this will
585be detected and this backend will be skipped. 588be detected and this backend will be skipped.
586 589
587This backend can batch oneshot requests and supports a user-space ring 590This backend can batch oneshot requests and supports a user-space ring
588buffer to receive events. It also doesn't suffer from most of the design 591buffer to receive events. It also doesn't suffer from most of the design
589problems of epoll (such as not being able to remove event sources from the 592problems of epoll (such as not being able to remove event sources from
590epoll set), and generally sounds too good to be true. Because, this being 593the epoll set), and generally sounds too good to be true. Because, this
591the linux kernel, of course it suffers from a whole new set of limitations. 594being the Linux kernel, of course it suffers from a whole new set of
595limitations, forcing you to fall back to epoll, inheriting all its design
596issues.
592 597
593For one, it is not easily embeddable (but probably could be done using 598For one, it is not easily embeddable (but probably could be done using
594an event fd at some extra overhead). It also is subject to a system wide 599an event fd at some extra overhead). It also is subject to a system wide
595limit that can be configured in F</proc/sys/fs/aio-max-nr> - each loop 600limit that can be configured in F</proc/sys/fs/aio-max-nr>. If no AIO
596currently requires C<61> of this number. If no aio requests are left, this
597backend will be skipped during initialisation. 601requests are left, this backend will be skipped during initialisation, and
602will switch to epoll when the loop is active.
598 603
599Most problematic in practise, however, is that not all file descriptors 604Most problematic in practice, however, is that not all file descriptors
600work with it. For example, in linux 5.1, tcp sockets, pipes, event fds, 605work with it. For example, in Linux 5.1, TCP sockets, pipes, event fds,
601files, F</dev/null> and a few others are supported, but ttys do not work 606files, F</dev/null> and many others are supported, but ttys do not work
602properly (a known bug that the kernel developers don't care about, see 607properly (a known bug that the kernel developers don't care about, see
603L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not 608L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
604(yet?) a generic event polling interface. 609(yet?) a generic event polling interface.
605 610
606Overall, it seems the linux developers just don't want it to have a 611Overall, it seems the Linux developers just don't want it to have a
607generic event handling mechanism other than C<select> or C<poll>. 612generic event handling mechanism other than C<select> or C<poll>.
608 613
609To work around the fd type problem, the current version of libev uses 614To work around all these problem, the current version of libev uses its
610epoll as a fallback for file deescriptor types that do not work. Epoll 615epoll backend as a fallback for file descriptor types that do not work. Or
611is used in, kind of, slow mode that hopefully avoids most of its design 616falls back completely to epoll if the kernel acts up.
612problems and requires 1-3 extra syscalls per active fd every iteration.
613 617
614This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 618This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
615C<EVBACKEND_POLL>. 619C<EVBACKEND_POLL>.
616 620
617=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 621=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
618 622
619Kqueue deserves special mention, as at the time of this writing, it 623Kqueue deserves special mention, as at the time this backend was
620was broken on all BSDs except NetBSD (usually it doesn't work reliably 624implemented, it was broken on all BSDs except NetBSD (usually it doesn't
621with anything but sockets and pipes, except on Darwin, where of course 625work reliably with anything but sockets and pipes, except on Darwin,
622it's completely useless). Unlike epoll, however, whose brokenness 626where of course it's completely useless). Unlike epoll, however, whose
623is by design, these kqueue bugs can (and eventually will) be fixed 627brokenness is by design, these kqueue bugs can be (and mostly have been)
624without API changes to existing programs. For this reason it's not being 628fixed without API changes to existing programs. For this reason it's not
625"auto-detected" unless you explicitly specify it in the flags (i.e. using 629being "auto-detected" on all platforms unless you explicitly specify it
626C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 630in the flags (i.e. using C<EVBACKEND_KQUEUE>) or libev was compiled on a
627system like NetBSD. 631known-to-be-good (-enough) system like NetBSD.
628 632
629You still can embed kqueue into a normal poll or select backend and use it 633You still can embed kqueue into a normal poll or select backend and use it
630only for sockets (after having made sure that sockets work with kqueue on 634only for sockets (after having made sure that sockets work with kqueue on
631the target platform). See C<ev_embed> watchers for more info. 635the target platform). See C<ev_embed> watchers for more info.
632 636
633It scales in the same way as the epoll backend, but the interface to the 637It scales in the same way as the epoll backend, but the interface to the
634kernel is more efficient (which says nothing about its actual speed, of 638kernel is more efficient (which says nothing about its actual speed, of
635course). While stopping, setting and starting an I/O watcher does never 639course). While stopping, setting and starting an I/O watcher does never
636cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 640cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
637two event changes per incident. Support for C<fork ()> is very bad (you 641two event changes per incident. Support for C<fork ()> is very bad (you
638might have to leak fd's on fork, but it's more sane than epoll) and it 642might have to leak fds on fork, but it's more sane than epoll) and it
639drops fds silently in similarly hard-to-detect cases. 643drops fds silently in similarly hard-to-detect cases.
640 644
641This backend usually performs well under most conditions. 645This backend usually performs well under most conditions.
642 646
643While nominally embeddable in other event loops, this doesn't work 647While nominally embeddable in other event loops, this doesn't work

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines