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

Comparing libev/ev.pod (file contents):
Revision 1.453 by root, Tue Jun 25 05:01:22 2019 UTC vs.
Revision 1.455 by root, Wed Jun 26 00:01:46 2019 UTC

… …
159When libev detects a usage error such as a negative timer interval, then 159When libev detects a usage error such as a negative timer interval, then
160it will print a diagnostic message and abort (via the C<assert> mechanism, 160it will print a diagnostic message and abort (via the C<assert> mechanism,
161so C<NDEBUG> will disable this checking): these are programming errors in 161so C<NDEBUG> will disable this checking): these are programming errors in
162the libev caller and need to be fixed there. 162the libev caller and need to be fixed there.
163 163
164Via the C<EV_FREQUENT> macro you can compile in and/or enable extensive
165consistency checking code inside libev that can be used to check for
166internal inconsistencies, suually caused by application bugs.
167
164Libev also has a few internal error-checking C<assert>ions, and also has 168Libev also has a few internal error-checking C<assert>ions. These do not
165extensive consistency checking code. These do not trigger under normal
166circumstances, as they indicate either a bug in libev or worse. 169trigger under normal circumstances, as they indicate either a bug in libev
170or worse.
167 171
168 172
169=head1 GLOBAL FUNCTIONS 173=head1 GLOBAL FUNCTIONS
170 174
171These functions can be called anytime, even before initialising the 175These functions can be called anytime, even before initialising the
… …
511This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 515This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
512C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 516C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
513 517
514=item C<EVBACKEND_EPOLL> (value 4, Linux) 518=item C<EVBACKEND_EPOLL> (value 4, Linux)
515 519
516Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9 520Use the Linux-specific epoll(7) interface (for both pre- and post-2.6.9
517kernels). 521kernels).
518 522
519For few fds, this backend is a bit little slower than poll and select, but 523For 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 524it 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 525O(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 578This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
575C<EVBACKEND_POLL>. 579C<EVBACKEND_POLL>.
576 580
577=item C<EVBACKEND_LINUXAIO> (value 64, Linux) 581=item C<EVBACKEND_LINUXAIO> (value 64, Linux)
578 582
579Use the linux-specific linux aio (I<not> C<< aio(7) >> but C<< 583Use the Linux-specific Linux AIO (I<not> C<< aio(7) >> but C<<
580io_submit(2) >>) event interface available in post-4.18 kernels (but libev 584io_submit(2) >>) event interface available in post-4.18 kernels (but libev
581only tries to use it in 4.19+). 585only tries to use it in 4.19+).
582 586
583This is another linux trainwreck of an event interface. 587This is another Linux train wreck of an event interface.
584 588
585If this backend works for you (as of this writing, it was very 589If this backend works for you (as of this writing, it was very
586experimental), it is the best event interface available on linux and might 590experimental), it is the best event interface available on Linux and might
587be well worth enabling it - if it isn't available in your kernel this will 591be well worth enabling it - if it isn't available in your kernel this will
588be detected and this backend will be skipped. 592be detected and this backend will be skipped.
589 593
590This backend can batch oneshot requests and supports a user-space ring 594This backend can batch oneshot requests and supports a user-space ring
591buffer to receive events. It also doesn't suffer from most of the design 595buffer to receive events. It also doesn't suffer from most of the design
592problems of epoll (such as not being able to remove event sources from 596problems of epoll (such as not being able to remove event sources from
593the epoll set), and generally sounds too good to be true. Because, this 597the epoll set), and generally sounds too good to be true. Because, this
594being the linux kernel, of course it suffers from a whole new set of 598being 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 599limitations, forcing you to fall back to epoll, inheriting all its design
596issues. 600issues.
597 601
598For one, it is not easily embeddable (but probably could be done using 602For one, it is not easily embeddable (but probably could be done using
599an event fd at some extra overhead). It also is subject to a system wide 603an event fd at some extra overhead). It also is subject to a system wide
600limit that can be configured in F</proc/sys/fs/aio-max-nr>. If no aio 604limit that can be configured in F</proc/sys/fs/aio-max-nr>. If no AIO
601requests are left, this backend will be skipped during initialisation, and 605requests are left, this backend will be skipped during initialisation, and
602will switch to epoll when the loop is active. 606will switch to epoll when the loop is active.
603 607
604Most problematic in practice, however, is that not all file descriptors 608Most problematic in practice, however, is that not all file descriptors
605work with it. For example, in linux 5.1, tcp sockets, pipes, event fds, 609work with it. For example, in Linux 5.1, TCP sockets, pipes, event fds,
606files, F</dev/null> and a few others are supported, but ttys do not work 610files, F</dev/null> and many others are supported, but ttys do not work
607properly (a known bug that the kernel developers don't care about, see 611properly (a known bug that the kernel developers don't care about, see
608L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not 612L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
609(yet?) a generic event polling interface. 613(yet?) a generic event polling interface.
610 614
611Overall, it seems the linux developers just don't want it to have a 615Overall, it seems the Linux developers just don't want it to have a
612generic event handling mechanism other than C<select> or C<poll>. 616generic event handling mechanism other than C<select> or C<poll>.
613 617
614To work around all these problem, the current version of libev uses its 618To work around all these problem, the current version of libev uses its
615epoll backend as a fallback for file descriptor types that do not work. Or 619epoll backend as a fallback for file descriptor types that do not work. Or
616falls back completely to epoll if the kernel acts up. 620falls back completely to epoll if the kernel acts up.
… …
637It scales in the same way as the epoll backend, but the interface to the 641It scales in the same way as the epoll backend, but the interface to the
638kernel is more efficient (which says nothing about its actual speed, of 642kernel is more efficient (which says nothing about its actual speed, of
639course). While stopping, setting and starting an I/O watcher does never 643course). While stopping, setting and starting an I/O watcher does never
640cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 644cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
641two event changes per incident. Support for C<fork ()> is very bad (you 645two event changes per incident. Support for C<fork ()> is very bad (you
642might have to leak fd's on fork, but it's more sane than epoll) and it 646might have to leak fds on fork, but it's more sane than epoll) and it
643drops fds silently in similarly hard-to-detect cases. 647drops fds silently in similarly hard-to-detect cases.
644 648
645This backend usually performs well under most conditions. 649This backend usually performs well under most conditions.
646 650
647While nominally embeddable in other event loops, this doesn't work 651While nominally embeddable in other event loops, this doesn't work
… …
4973called. If set to C<2>, then the internal verification code will be 4977called. If set to C<2>, then the internal verification code will be
4974called once per loop, which can slow down libev. If set to C<3>, then the 4978called once per loop, which can slow down libev. If set to C<3>, then the
4975verification code will be called very frequently, which will slow down 4979verification code will be called very frequently, which will slow down
4976libev considerably. 4980libev considerably.
4977 4981
4982Verification errors are reported via C's C<assert> mechanism, so if you
4983disable that (e.g. by defining C<NDEBUG>) then no errors will be reported.
4984
4978The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it 4985The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
4979will be C<0>. 4986will be C<0>.
4980 4987
4981=item EV_COMMON 4988=item EV_COMMON
4982 4989

Diff Legend

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