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

Comparing libev/ev.pod (file contents):
Revision 1.452 by root, Tue Jun 25 04:58:36 2019 UTC vs.
Revision 1.458 by root, Fri Dec 20 20:51: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
… …
476unblocking the signals. 480unblocking the signals.
477 481
478It's also required by POSIX in a threaded program, as libev calls 482It's also required by POSIX in a threaded program, as libev calls
479C<sigprocmask>, whose behaviour is officially unspecified. 483C<sigprocmask>, whose behaviour is officially unspecified.
480 484
481This flag's behaviour will become the default in future versions of libev. 485=item C<EVFLAG_NOTIMERFD>
486
487When this flag is specified, the libev will avoid using a C<timerfd> to
488detect time jumps. It will still be able to detect time jumps, but takes
489longer and has a lower accuracy in doing so, but saves a file descriptor
490per loop.
491
492The current implementation only tries to use a C<timerfd> when the first
493C<ev_periodic> watcher is started and falls back on other methods if it
494cannot be created, but this behaviour might change in the future.
482 495
483=item C<EVBACKEND_SELECT> (value 1, portable select backend) 496=item C<EVBACKEND_SELECT> (value 1, portable select backend)
484 497
485This is your standard select(2) backend. Not I<completely> standard, as 498This is your standard select(2) backend. Not I<completely> standard, as
486libev tries to roll its own fd_set with no limits on the number of fds, 499libev tries to roll its own fd_set with no limits on the number of fds,
… …
511This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 524This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
512C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 525C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
513 526
514=item C<EVBACKEND_EPOLL> (value 4, Linux) 527=item C<EVBACKEND_EPOLL> (value 4, Linux)
515 528
516Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9 529Use the Linux-specific epoll(7) interface (for both pre- and post-2.6.9
517kernels). 530kernels).
518 531
519For few fds, this backend is a bit little slower than poll and select, but 532For 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 533it 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 534O(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 587This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
575C<EVBACKEND_POLL>. 588C<EVBACKEND_POLL>.
576 589
577=item C<EVBACKEND_LINUXAIO> (value 64, Linux) 590=item C<EVBACKEND_LINUXAIO> (value 64, Linux)
578 591
579Use the linux-specific linux aio (I<not> C<< aio(7) >> but C<< 592Use 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 593io_submit(2) >>) event interface available in post-4.18 kernels (but libev
581only tries to use it in 4.19+). 594only tries to use it in 4.19+).
582 595
583This is another linux trainwreck of an event interface. 596This is another Linux train wreck of an event interface.
584 597
585If this backend works for you (as of this writing, it was very 598If this backend works for you (as of this writing, it was very
586experimental), it is the best event interface available on linux and might 599experimental), 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 600be well worth enabling it - if it isn't available in your kernel this will
588be detected and this backend will be skipped. 601be detected and this backend will be skipped.
589 602
590This backend can batch oneshot requests and supports a user-space ring 603This 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 604buffer 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 605problems 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 606the 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 607being 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 608limitations, forcing you to fall back to epoll, inheriting all its design
596issues. 609issues.
597 610
598For one, it is not easily embeddable (but probably could be done using 611For 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 612an 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 613limit 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 614requests are left, this backend will be skipped during initialisation, and
602will switch to epoll when the loop is active. 615will switch to epoll when the loop is active.
603 616
604Most problematic in practice, however, is that not all file descriptors 617Most problematic in practice, however, is that not all file descriptors
605work with it. For example, in linux 5.1, tcp sockets, pipes, event fds, 618work 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 619files, 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 620properly (a known bug that the kernel developers don't care about, see
608L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not 621L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
609(yet?) a generic event polling interface. 622(yet?) a generic event polling interface.
610 623
611Overall, it seems the linux developers just don't want it to have a 624Overall, it seems the Linux developers just don't want it to have a
612generic event handling mechanism other than C<select> or C<poll>. 625generic event handling mechanism other than C<select> or C<poll>.
613 626
614To work around all these problem, the current version of libev uses its 627To 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 628epoll backend as a fallback for file descriptor types that do not work. Or
616falls back completely to epoll if the kernel acts up. 629falls back completely to epoll if the kernel acts up.
… …
618This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 631This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
619C<EVBACKEND_POLL>. 632C<EVBACKEND_POLL>.
620 633
621=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 634=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
622 635
623Kqueue deserves special mention, as at the time of this writing, it 636Kqueue deserves special mention, as at the time this backend was
624was broken on all BSDs except NetBSD (usually it doesn't work reliably 637implemented, it was broken on all BSDs except NetBSD (usually it doesn't
625with anything but sockets and pipes, except on Darwin, where of course 638work reliably with anything but sockets and pipes, except on Darwin,
626it's completely useless). Unlike epoll, however, whose brokenness 639where of course it's completely useless). Unlike epoll, however, whose
627is by design, these kqueue bugs can (and eventually will) be fixed 640brokenness is by design, these kqueue bugs can be (and mostly have been)
628without API changes to existing programs. For this reason it's not being 641fixed without API changes to existing programs. For this reason it's not
629"auto-detected" unless you explicitly specify it in the flags (i.e. using 642being "auto-detected" on all platforms unless you explicitly specify it
630C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 643in the flags (i.e. using C<EVBACKEND_KQUEUE>) or libev was compiled on a
631system like NetBSD. 644known-to-be-good (-enough) system like NetBSD.
632 645
633You still can embed kqueue into a normal poll or select backend and use it 646You still can embed kqueue into a normal poll or select backend and use it
634only for sockets (after having made sure that sockets work with kqueue on 647only for sockets (after having made sure that sockets work with kqueue on
635the target platform). See C<ev_embed> watchers for more info. 648the target platform). See C<ev_embed> watchers for more info.
636 649
637It scales in the same way as the epoll backend, but the interface to the 650It 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 651kernel is more efficient (which says nothing about its actual speed, of
639course). While stopping, setting and starting an I/O watcher does never 652course). 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 653cause 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 654two 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 655might have to leak fds on fork, but it's more sane than epoll) and it
643drops fds silently in similarly hard-to-detect cases. 656drops fds silently in similarly hard-to-detect cases.
644 657
645This backend usually performs well under most conditions. 658This backend usually performs well under most conditions.
646 659
647While nominally embeddable in other event loops, this doesn't work 660While nominally embeddable in other event loops, this doesn't work
… …
1531 1544
1532Many event loops support I<watcher priorities>, which are usually small 1545Many event loops support I<watcher priorities>, which are usually small
1533integers that influence the ordering of event callback invocation 1546integers that influence the ordering of event callback invocation
1534between watchers in some way, all else being equal. 1547between watchers in some way, all else being equal.
1535 1548
1536In libev, Watcher priorities can be set using C<ev_set_priority>. See its 1549In libev, watcher priorities can be set using C<ev_set_priority>. See its
1537description for the more technical details such as the actual priority 1550description for the more technical details such as the actual priority
1538range. 1551range.
1539 1552
1540There are two common ways how these these priorities are being interpreted 1553There are two common ways how these these priorities are being interpreted
1541by event loops: 1554by event loops:
… …
1745when you rarely read from a file instead of from a socket, and want to 1758when you rarely read from a file instead of from a socket, and want to
1746reuse the same code path. 1759reuse the same code path.
1747 1760
1748=head3 The special problem of fork 1761=head3 The special problem of fork
1749 1762
1750Some backends (epoll, kqueue, probably linuxaio) do not support C<fork ()> 1763Some backends (epoll, kqueue, linuxaio, iouring) do not support C<fork ()>
1751at all or exhibit useless behaviour. Libev fully supports fork, but needs 1764at all or exhibit useless behaviour. Libev fully supports fork, but needs
1752to be told about it in the child if you want to continue to use it in the 1765to be told about it in the child if you want to continue to use it in the
1753child. 1766child.
1754 1767
1755To support fork in your child processes, you have to call C<ev_loop_fork 1768To support fork in your child processes, you have to call C<ev_loop_fork
… …
4480 4493
4481 ev_select.c only when select backend is enabled 4494 ev_select.c only when select backend is enabled
4482 ev_poll.c only when poll backend is enabled 4495 ev_poll.c only when poll backend is enabled
4483 ev_epoll.c only when the epoll backend is enabled 4496 ev_epoll.c only when the epoll backend is enabled
4484 ev_linuxaio.c only when the linux aio backend is enabled 4497 ev_linuxaio.c only when the linux aio backend is enabled
4498 ev_iouring.c only when the linux io_uring backend is enabled
4485 ev_kqueue.c only when the kqueue backend is enabled 4499 ev_kqueue.c only when the kqueue backend is enabled
4486 ev_port.c only when the solaris port backend is enabled 4500 ev_port.c only when the solaris port backend is enabled
4487 4501
4488F<ev.c> includes the backend files directly when enabled, so you only need 4502F<ev.c> includes the backend files directly when enabled, so you only need
4489to compile this single file. 4503to compile this single file.
… …
4610available and will probe for kernel support at runtime. This will improve 4624available and will probe for kernel support at runtime. This will improve
4611C<ev_signal> and C<ev_async> performance and reduce resource consumption. 4625C<ev_signal> and C<ev_async> performance and reduce resource consumption.
4612If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc 4626If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46132.7 or newer, otherwise disabled. 46272.7 or newer, otherwise disabled.
4614 4628
4629=item EV_USE_SIGNALFD
4630
4631If defined to be C<1>, then libev will assume that C<signalfd ()> is
4632available and will probe for kernel support at runtime. This enables
4633the use of EVFLAG_SIGNALFD for faster and simpler signal handling. If
4634undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46352.7 or newer, otherwise disabled.
4636
4637=item EV_USE_TIMERFD
4638
4639If defined to be C<1>, then libev will assume that C<timerfd ()> is
4640available and will probe for kernel support at runtime. This allows
4641libev to detect time jumps accurately. If undefined, it will be enabled
4642if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4643C<TFD_TIMER_CANCEL_ON_SET>, otherwise disabled.
4644
4645=item EV_USE_EVENTFD
4646
4647If defined to be C<1>, then libev will assume that C<eventfd ()> is
4648available and will probe for kernel support at runtime. This will improve
4649C<ev_signal> and C<ev_async> performance and reduce resource consumption.
4650If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46512.7 or newer, otherwise disabled.
4652
4615=item EV_USE_SELECT 4653=item EV_USE_SELECT
4616 4654
4617If undefined or defined to be C<1>, libev will compile in support for the 4655If undefined or defined to be C<1>, libev will compile in support for the
4618C<select>(2) backend. No attempt at auto-detection will be done: if no 4656C<select>(2) backend. No attempt at auto-detection will be done: if no
4619other method takes over, select will be it. Otherwise the select backend 4657other method takes over, select will be it. Otherwise the select backend
… …
4682backend for GNU/Linux systems. If undefined, it will be enabled if the 4720backend for GNU/Linux systems. If undefined, it will be enabled if the
4683headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4721headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4684 4722
4685=item EV_USE_LINUXAIO 4723=item EV_USE_LINUXAIO
4686 4724
4725If defined to be C<1>, libev will compile in support for the Linux aio
4726backend (C<EV_USE_EPOLL> must also be enabled). If undefined, it will be
4727enabled on linux, otherwise disabled.
4728
4729=item EV_USE_IOURING
4730
4687If defined to be C<1>, libev will compile in support for the Linux 4731If defined to be C<1>, libev will compile in support for the Linux
4688aio backend. Due to it's currenbt limitations it has to be requested 4732io_uring backend (C<EV_USE_EPOLL> must also be enabled). Due to it's
4689explicitly. If undefined, it will be enabled on linux, otherwise 4733current limitations it has to be requested explicitly. If undefined, it
4690disabled. 4734will be enabled on linux, otherwise disabled.
4691 4735
4692=item EV_USE_KQUEUE 4736=item EV_USE_KQUEUE
4693 4737
4694If defined to be C<1>, libev will compile in support for the BSD style 4738If defined to be C<1>, libev will compile in support for the BSD style
4695C<kqueue>(2) backend. Its actual availability will be detected at runtime, 4739C<kqueue>(2) backend. Its actual availability will be detected at runtime,
… …
4973called. If set to C<2>, then the internal verification code will be 5017called. 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 5018called 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 5019verification code will be called very frequently, which will slow down
4976libev considerably. 5020libev considerably.
4977 5021
5022Verification errors are reported via C's C<assert> mechanism, so if you
5023disable that (e.g. by defining C<NDEBUG>) then no errors will be reported.
5024
4978The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it 5025The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
4979will be C<0>. 5026will be C<0>.
4980 5027
4981=item EV_COMMON 5028=item EV_COMMON
4982 5029

Diff Legend

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