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

Comparing libev/ev.pod (file contents):
Revision 1.450 by root, Mon Jun 24 00:04:26 2019 UTC vs.
Revision 1.459 by root, Wed Jan 22 01:50:42 2020 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. 593io_submit(2) >>) event interface available in post-4.18 kernels (but libev
594only tries to use it in 4.19+).
595
596This is another Linux train wreck of an event interface.
581 597
582If 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
583experimental), it is the best event interface available on linux and might 599experimental), 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 600be well worth enabling it - if it isn't available in your kernel this will
585be detected and this backend will be skipped. 601be detected and this backend will be skipped.
586 602
587This backend can batch oneshot requests and supports a user-space ring 603This 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 604buffer 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 605problems of epoll (such as not being able to remove event sources from
590the 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
591being 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
592limitations. 608limitations, forcing you to fall back to epoll, inheriting all its design
609issues.
593 610
594For 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
595an 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
596limit that can be configured in F</proc/sys/fs/aio-max-nr> - each loop 613limit that can be configured in F</proc/sys/fs/aio-max-nr>. If no AIO
597currently requires C<61> of this number. If no aio requests are left, this
598backend will be skipped during initialisation. 614requests are left, this backend will be skipped during initialisation, and
615will switch to epoll when the loop is active.
599 616
600Most problematic in practise, however, is that not all file descriptors 617Most problematic in practice, however, is that not all file descriptors
601work 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,
602files, 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
603properly (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
604L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not 621L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
605(yet?) a generic event polling interface. 622(yet?) a generic event polling interface.
606 623
624Overall, it seems the Linux developers just don't want it to have a
625generic event handling mechanism other than C<select> or C<poll>.
626
607To work around this latter problem, the current version of libev uses 627To work around all these problem, the current version of libev uses its
608epoll as a fallback for file deescriptor types that do not work. Epoll 628epoll backend as a fallback for file descriptor types that do not work. Or
609is used in, kind of, slow mode that hopefully avoids most of its design 629falls back completely to epoll if the kernel acts up.
610problems and requires 1-3 extra syscalls per active fd every iteration.
611 630
612This 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
613C<EVBACKEND_POLL>. 632C<EVBACKEND_POLL>.
614 633
615=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 634=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
616 635
617Kqueue deserves special mention, as at the time of this writing, it 636Kqueue deserves special mention, as at the time this backend was
618was 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
619with anything but sockets and pipes, except on Darwin, where of course 638work reliably with anything but sockets and pipes, except on Darwin,
620it's completely useless). Unlike epoll, however, whose brokenness 639where of course it's completely useless). Unlike epoll, however, whose
621is by design, these kqueue bugs can (and eventually will) be fixed 640brokenness is by design, these kqueue bugs can be (and mostly have been)
622without 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
623"auto-detected" unless you explicitly specify it in the flags (i.e. using 642being "auto-detected" on all platforms unless you explicitly specify it
624C<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
625system like NetBSD. 644known-to-be-good (-enough) system like NetBSD.
626 645
627You 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
628only 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
629the target platform). See C<ev_embed> watchers for more info. 648the target platform). See C<ev_embed> watchers for more info.
630 649
631It 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
632kernel is more efficient (which says nothing about its actual speed, of 651kernel is more efficient (which says nothing about its actual speed, of
633course). While stopping, setting and starting an I/O watcher does never 652course). While stopping, setting and starting an I/O watcher does never
634cause 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
635two 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
636might 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
637drops fds silently in similarly hard-to-detect cases. 656drops fds silently in similarly hard-to-detect cases.
638 657
639This backend usually performs well under most conditions. 658This backend usually performs well under most conditions.
640 659
641While nominally embeddable in other event loops, this doesn't work 660While nominally embeddable in other event loops, this doesn't work
… …
1525 1544
1526Many event loops support I<watcher priorities>, which are usually small 1545Many event loops support I<watcher priorities>, which are usually small
1527integers that influence the ordering of event callback invocation 1546integers that influence the ordering of event callback invocation
1528between watchers in some way, all else being equal. 1547between watchers in some way, all else being equal.
1529 1548
1530In 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
1531description for the more technical details such as the actual priority 1550description for the more technical details such as the actual priority
1532range. 1551range.
1533 1552
1534There are two common ways how these these priorities are being interpreted 1553There are two common ways how these these priorities are being interpreted
1535by event loops: 1554by event loops:
… …
1629 1648
1630This section describes each watcher in detail, but will not repeat 1649This section describes each watcher in detail, but will not repeat
1631information given in the last section. Any initialisation/set macros, 1650information given in the last section. Any initialisation/set macros,
1632functions and members specific to the watcher type are explained. 1651functions and members specific to the watcher type are explained.
1633 1652
1634Members are additionally marked with either I<[read-only]>, meaning that, 1653Most members are additionally marked with either I<[read-only]>, meaning
1635while the watcher is active, you can look at the member and expect some 1654that, while the watcher is active, you can look at the member and expect
1636sensible content, but you must not modify it (you can modify it while the 1655some sensible content, but you must not modify it (you can modify it while
1637watcher is stopped to your hearts content), or I<[read-write]>, which 1656the watcher is stopped to your hearts content), or I<[read-write]>, which
1638means you can expect it to have some sensible content while the watcher 1657means you can expect it to have some sensible content while the watcher
1639is active, but you can also modify it. Modifying it may not do something 1658is active, but you can also modify it. Modifying it may not do something
1640sensible or take immediate effect (or do anything at all), but libev will 1659sensible or take immediate effect (or do anything at all), but libev will
1641not crash or malfunction in any way. 1660not crash or malfunction in any way.
1642 1661
1662In any case, the documentation for each member will explain what the
1663effects are, and if there are any additional access restrictions.
1643 1664
1644=head2 C<ev_io> - is this file descriptor readable or writable? 1665=head2 C<ev_io> - is this file descriptor readable or writable?
1645 1666
1646I/O watchers check whether a file descriptor is readable or writable 1667I/O watchers check whether a file descriptor is readable or writable
1647in each iteration of the event loop, or, more precisely, when reading 1668in each iteration of the event loop, or, more precisely, when reading
… …
1739when you rarely read from a file instead of from a socket, and want to 1760when you rarely read from a file instead of from a socket, and want to
1740reuse the same code path. 1761reuse the same code path.
1741 1762
1742=head3 The special problem of fork 1763=head3 The special problem of fork
1743 1764
1744Some backends (epoll, kqueue, probably linuxaio) do not support C<fork ()> 1765Some backends (epoll, kqueue, linuxaio, iouring) do not support C<fork ()>
1745at all or exhibit useless behaviour. Libev fully supports fork, but needs 1766at all or exhibit useless behaviour. Libev fully supports fork, but needs
1746to be told about it in the child if you want to continue to use it in the 1767to be told about it in the child if you want to continue to use it in the
1747child. 1768child.
1748 1769
1749To support fork in your child processes, you have to call C<ev_loop_fork 1770To support fork in your child processes, you have to call C<ev_loop_fork
… …
1810 1831
1811Configures an C<ev_io> watcher. The C<fd> is the file descriptor to 1832Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1812receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or 1833receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or
1813C<EV_READ | EV_WRITE>, to express the desire to receive the given events. 1834C<EV_READ | EV_WRITE>, to express the desire to receive the given events.
1814 1835
1815=item int fd [read-only] 1836=item ev_io_modify (ev_io *, int events)
1816 1837
1817The file descriptor being watched. 1838Similar to C<ev_io_set>, but only changes the event mask. Using this might
1839be faster with some backends, as libev can assume that the C<fd> still
1840refers to the same underlying file description, something it cannot do
1841when using C<ev_io_set>.
1818 1842
1843=item int fd [no-modify]
1844
1845The file descriptor being watched. While it can be read at any time, you
1846must not modify this member even when the watcher is stopped - always use
1847C<ev_io_set> for that.
1848
1819=item int events [read-only] 1849=item int events [no-modify]
1820 1850
1821The events being watched. 1851The set of events being watched, among other flags. This field is a
1852bit set - to test for C<EV_READ>, use C<< w->events & EV_READ >>, and
1853similarly for C<EV_WRITE>.
1854
1855As with C<fd>, you must not modify this member even when the watcher is
1856stopped, always use C<ev_io_set> or C<ev_io_modify> for that.
1822 1857
1823=back 1858=back
1824 1859
1825=head3 Examples 1860=head3 Examples
1826 1861
… …
4474 4509
4475 ev_select.c only when select backend is enabled 4510 ev_select.c only when select backend is enabled
4476 ev_poll.c only when poll backend is enabled 4511 ev_poll.c only when poll backend is enabled
4477 ev_epoll.c only when the epoll backend is enabled 4512 ev_epoll.c only when the epoll backend is enabled
4478 ev_linuxaio.c only when the linux aio backend is enabled 4513 ev_linuxaio.c only when the linux aio backend is enabled
4514 ev_iouring.c only when the linux io_uring backend is enabled
4479 ev_kqueue.c only when the kqueue backend is enabled 4515 ev_kqueue.c only when the kqueue backend is enabled
4480 ev_port.c only when the solaris port backend is enabled 4516 ev_port.c only when the solaris port backend is enabled
4481 4517
4482F<ev.c> includes the backend files directly when enabled, so you only need 4518F<ev.c> includes the backend files directly when enabled, so you only need
4483to compile this single file. 4519to compile this single file.
… …
4604available and will probe for kernel support at runtime. This will improve 4640available and will probe for kernel support at runtime. This will improve
4605C<ev_signal> and C<ev_async> performance and reduce resource consumption. 4641C<ev_signal> and C<ev_async> performance and reduce resource consumption.
4606If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc 4642If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46072.7 or newer, otherwise disabled. 46432.7 or newer, otherwise disabled.
4608 4644
4645=item EV_USE_SIGNALFD
4646
4647If defined to be C<1>, then libev will assume that C<signalfd ()> is
4648available and will probe for kernel support at runtime. This enables
4649the use of EVFLAG_SIGNALFD for faster and simpler signal handling. If
4650undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46512.7 or newer, otherwise disabled.
4652
4653=item EV_USE_TIMERFD
4654
4655If defined to be C<1>, then libev will assume that C<timerfd ()> is
4656available and will probe for kernel support at runtime. This allows
4657libev to detect time jumps accurately. If undefined, it will be enabled
4658if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4659C<TFD_TIMER_CANCEL_ON_SET>, otherwise disabled.
4660
4661=item EV_USE_EVENTFD
4662
4663If defined to be C<1>, then libev will assume that C<eventfd ()> is
4664available and will probe for kernel support at runtime. This will improve
4665C<ev_signal> and C<ev_async> performance and reduce resource consumption.
4666If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46672.7 or newer, otherwise disabled.
4668
4609=item EV_USE_SELECT 4669=item EV_USE_SELECT
4610 4670
4611If undefined or defined to be C<1>, libev will compile in support for the 4671If undefined or defined to be C<1>, libev will compile in support for the
4612C<select>(2) backend. No attempt at auto-detection will be done: if no 4672C<select>(2) backend. No attempt at auto-detection will be done: if no
4613other method takes over, select will be it. Otherwise the select backend 4673other method takes over, select will be it. Otherwise the select backend
… …
4676backend for GNU/Linux systems. If undefined, it will be enabled if the 4736backend for GNU/Linux systems. If undefined, it will be enabled if the
4677headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4737headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4678 4738
4679=item EV_USE_LINUXAIO 4739=item EV_USE_LINUXAIO
4680 4740
4741If defined to be C<1>, libev will compile in support for the Linux aio
4742backend (C<EV_USE_EPOLL> must also be enabled). If undefined, it will be
4743enabled on linux, otherwise disabled.
4744
4745=item EV_USE_IOURING
4746
4681If defined to be C<1>, libev will compile in support for the Linux 4747If defined to be C<1>, libev will compile in support for the Linux
4682aio backend. Due to it's currenbt limitations it has to be requested 4748io_uring backend (C<EV_USE_EPOLL> must also be enabled). Due to it's
4683explicitly. If undefined, it will be enabled on linux, otherwise 4749current limitations it has to be requested explicitly. If undefined, it
4684disabled. 4750will be enabled on linux, otherwise disabled.
4685 4751
4686=item EV_USE_KQUEUE 4752=item EV_USE_KQUEUE
4687 4753
4688If defined to be C<1>, libev will compile in support for the BSD style 4754If defined to be C<1>, libev will compile in support for the BSD style
4689C<kqueue>(2) backend. Its actual availability will be detected at runtime, 4755C<kqueue>(2) backend. Its actual availability will be detected at runtime,
… …
4967called. If set to C<2>, then the internal verification code will be 5033called. If set to C<2>, then the internal verification code will be
4968called once per loop, which can slow down libev. If set to C<3>, then the 5034called once per loop, which can slow down libev. If set to C<3>, then the
4969verification code will be called very frequently, which will slow down 5035verification code will be called very frequently, which will slow down
4970libev considerably. 5036libev considerably.
4971 5037
5038Verification errors are reported via C's C<assert> mechanism, so if you
5039disable that (e.g. by defining C<NDEBUG>) then no errors will be reported.
5040
4972The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it 5041The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
4973will be C<0>. 5042will be C<0>.
4974 5043
4975=item EV_COMMON 5044=item EV_COMMON
4976 5045

Diff Legend

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