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.457 by root, Fri Sep 6 22:17:52 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. 584io_submit(2) >>) event interface available in post-4.18 kernels (but libev
585only tries to use it in 4.19+).
586
587This is another Linux train wreck of an event interface.
581 588
582If 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
583experimental), it is the best event interface available on linux and might 590experimental), 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 591be well worth enabling it - if it isn't available in your kernel this will
585be detected and this backend will be skipped. 592be detected and this backend will be skipped.
586 593
587This backend can batch oneshot requests and supports a user-space ring 594This 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 595buffer 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 596problems 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 597the 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. 598being the Linux kernel, of course it suffers from a whole new set of
599limitations, forcing you to fall back to epoll, inheriting all its design
600issues.
592 601
593For 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
594an 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
595limit that can be configured in F</proc/sys/fs/aio-max-nr> - each loop 604limit 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. 605requests are left, this backend will be skipped during initialisation, and
606will switch to epoll when the loop is active.
598 607
599Most problematic in practise, however, is that not all file descriptors 608Most problematic in practice, however, is that not all file descriptors
600work 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,
601files, 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
602properly (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
603L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not 612L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
604(yet?) a generic event polling interface. 613(yet?) a generic event polling interface.
605 614
606Overall, 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
607generic event handling mechanism other than C<select> or C<poll>. 616generic event handling mechanism other than C<select> or C<poll>.
608 617
609To work around the fd type problem, the current version of libev uses 618To 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 619epoll 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 620falls back completely to epoll if the kernel acts up.
612problems and requires 1-3 extra syscalls per active fd every iteration.
613 621
614This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 622This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
615C<EVBACKEND_POLL>. 623C<EVBACKEND_POLL>.
616 624
617=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 625=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
618 626
619Kqueue deserves special mention, as at the time of this writing, it 627Kqueue deserves special mention, as at the time this backend was
620was broken on all BSDs except NetBSD (usually it doesn't work reliably 628implemented, it was broken on all BSDs except NetBSD (usually it doesn't
621with anything but sockets and pipes, except on Darwin, where of course 629work reliably with anything but sockets and pipes, except on Darwin,
622it's completely useless). Unlike epoll, however, whose brokenness 630where of course it's completely useless). Unlike epoll, however, whose
623is by design, these kqueue bugs can (and eventually will) be fixed 631brokenness 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 632fixed 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 633being "auto-detected" on all platforms unless you explicitly specify it
626C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 634in the flags (i.e. using C<EVBACKEND_KQUEUE>) or libev was compiled on a
627system like NetBSD. 635known-to-be-good (-enough) system like NetBSD.
628 636
629You still can embed kqueue into a normal poll or select backend and use it 637You 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 638only for sockets (after having made sure that sockets work with kqueue on
631the target platform). See C<ev_embed> watchers for more info. 639the target platform). See C<ev_embed> watchers for more info.
632 640
633It 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
634kernel is more efficient (which says nothing about its actual speed, of 642kernel is more efficient (which says nothing about its actual speed, of
635course). While stopping, setting and starting an I/O watcher does never 643course). 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 644cause 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 645two 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 646might have to leak fds on fork, but it's more sane than epoll) and it
639drops fds silently in similarly hard-to-detect cases. 647drops fds silently in similarly hard-to-detect cases.
640 648
641This backend usually performs well under most conditions. 649This backend usually performs well under most conditions.
642 650
643While nominally embeddable in other event loops, this doesn't work 651While nominally embeddable in other event loops, this doesn't work
… …
1527 1535
1528Many event loops support I<watcher priorities>, which are usually small 1536Many event loops support I<watcher priorities>, which are usually small
1529integers that influence the ordering of event callback invocation 1537integers that influence the ordering of event callback invocation
1530between watchers in some way, all else being equal. 1538between watchers in some way, all else being equal.
1531 1539
1532In libev, Watcher priorities can be set using C<ev_set_priority>. See its 1540In libev, watcher priorities can be set using C<ev_set_priority>. See its
1533description for the more technical details such as the actual priority 1541description for the more technical details such as the actual priority
1534range. 1542range.
1535 1543
1536There are two common ways how these these priorities are being interpreted 1544There are two common ways how these these priorities are being interpreted
1537by event loops: 1545by event loops:
… …
1741when you rarely read from a file instead of from a socket, and want to 1749when you rarely read from a file instead of from a socket, and want to
1742reuse the same code path. 1750reuse the same code path.
1743 1751
1744=head3 The special problem of fork 1752=head3 The special problem of fork
1745 1753
1746Some backends (epoll, kqueue, probably linuxaio) do not support C<fork ()> 1754Some backends (epoll, kqueue, linuxaio, iouring) do not support C<fork ()>
1747at all or exhibit useless behaviour. Libev fully supports fork, but needs 1755at all or exhibit useless behaviour. Libev fully supports fork, but needs
1748to be told about it in the child if you want to continue to use it in the 1756to be told about it in the child if you want to continue to use it in the
1749child. 1757child.
1750 1758
1751To support fork in your child processes, you have to call C<ev_loop_fork 1759To support fork in your child processes, you have to call C<ev_loop_fork
… …
4476 4484
4477 ev_select.c only when select backend is enabled 4485 ev_select.c only when select backend is enabled
4478 ev_poll.c only when poll backend is enabled 4486 ev_poll.c only when poll backend is enabled
4479 ev_epoll.c only when the epoll backend is enabled 4487 ev_epoll.c only when the epoll backend is enabled
4480 ev_linuxaio.c only when the linux aio backend is enabled 4488 ev_linuxaio.c only when the linux aio backend is enabled
4489 ev_iouring.c only when the linux io_uring backend is enabled
4481 ev_kqueue.c only when the kqueue backend is enabled 4490 ev_kqueue.c only when the kqueue backend is enabled
4482 ev_port.c only when the solaris port backend is enabled 4491 ev_port.c only when the solaris port backend is enabled
4483 4492
4484F<ev.c> includes the backend files directly when enabled, so you only need 4493F<ev.c> includes the backend files directly when enabled, so you only need
4485to compile this single file. 4494to compile this single file.
… …
4678backend for GNU/Linux systems. If undefined, it will be enabled if the 4687backend for GNU/Linux systems. If undefined, it will be enabled if the
4679headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4688headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4680 4689
4681=item EV_USE_LINUXAIO 4690=item EV_USE_LINUXAIO
4682 4691
4692If defined to be C<1>, libev will compile in support for the Linux aio
4693backend (C<EV_USE_EPOLL> must also be enabled). If undefined, it will be
4694enabled on linux, otherwise disabled.
4695
4696=item EV_USE_IOURING
4697
4683If defined to be C<1>, libev will compile in support for the Linux 4698If defined to be C<1>, libev will compile in support for the Linux
4684aio backend. Due to it's currenbt limitations it has to be requested 4699io_uring backend (C<EV_USE_EPOLL> must also be enabled). Due to it's
4685explicitly. If undefined, it will be enabled on linux, otherwise 4700current limitations it has to be requested explicitly. If undefined, it
4686disabled. 4701will be enabled on linux, otherwise disabled.
4687 4702
4688=item EV_USE_KQUEUE 4703=item EV_USE_KQUEUE
4689 4704
4690If defined to be C<1>, libev will compile in support for the BSD style 4705If defined to be C<1>, libev will compile in support for the BSD style
4691C<kqueue>(2) backend. Its actual availability will be detected at runtime, 4706C<kqueue>(2) backend. Its actual availability will be detected at runtime,
… …
4969called. If set to C<2>, then the internal verification code will be 4984called. If set to C<2>, then the internal verification code will be
4970called once per loop, which can slow down libev. If set to C<3>, then the 4985called once per loop, which can slow down libev. If set to C<3>, then the
4971verification code will be called very frequently, which will slow down 4986verification code will be called very frequently, which will slow down
4972libev considerably. 4987libev considerably.
4973 4988
4989Verification errors are reported via C's C<assert> mechanism, so if you
4990disable that (e.g. by defining C<NDEBUG>) then no errors will be reported.
4991
4974The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it 4992The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
4975will be C<0>. 4993will be C<0>.
4976 4994
4977=item EV_COMMON 4995=item EV_COMMON
4978 4996

Diff Legend

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