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

Comparing libev/ev.pod (file contents):
Revision 1.454 by root, Tue Jun 25 05:17:50 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,
… …
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:
… …
1635 1648
1636This section describes each watcher in detail, but will not repeat 1649This section describes each watcher in detail, but will not repeat
1637information given in the last section. Any initialisation/set macros, 1650information given in the last section. Any initialisation/set macros,
1638functions and members specific to the watcher type are explained. 1651functions and members specific to the watcher type are explained.
1639 1652
1640Members are additionally marked with either I<[read-only]>, meaning that, 1653Most members are additionally marked with either I<[read-only]>, meaning
1641while 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
1642sensible 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
1643watcher is stopped to your hearts content), or I<[read-write]>, which 1656the watcher is stopped to your hearts content), or I<[read-write]>, which
1644means 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
1645is 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
1646sensible 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
1647not crash or malfunction in any way. 1660not crash or malfunction in any way.
1648 1661
1662In any case, the documentation for each member will explain what the
1663effects are, and if there are any additional access restrictions.
1649 1664
1650=head2 C<ev_io> - is this file descriptor readable or writable? 1665=head2 C<ev_io> - is this file descriptor readable or writable?
1651 1666
1652I/O watchers check whether a file descriptor is readable or writable 1667I/O watchers check whether a file descriptor is readable or writable
1653in each iteration of the event loop, or, more precisely, when reading 1668in each iteration of the event loop, or, more precisely, when reading
… …
1745when 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
1746reuse the same code path. 1761reuse the same code path.
1747 1762
1748=head3 The special problem of fork 1763=head3 The special problem of fork
1749 1764
1750Some backends (epoll, kqueue, probably linuxaio) do not support C<fork ()> 1765Some backends (epoll, kqueue, linuxaio, iouring) do not support C<fork ()>
1751at all or exhibit useless behaviour. Libev fully supports fork, but needs 1766at 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 1767to be told about it in the child if you want to continue to use it in the
1753child. 1768child.
1754 1769
1755To 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
… …
1816 1831
1817Configures 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
1818receive 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
1819C<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.
1820 1835
1821=item int fd [read-only] 1836=item ev_io_modify (ev_io *, int events)
1822 1837
1823The 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>.
1824 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
1825=item int events [read-only] 1849=item int events [no-modify]
1826 1850
1827The 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.
1828 1857
1829=back 1858=back
1830 1859
1831=head3 Examples 1860=head3 Examples
1832 1861
… …
4480 4509
4481 ev_select.c only when select backend is enabled 4510 ev_select.c only when select backend is enabled
4482 ev_poll.c only when poll backend is enabled 4511 ev_poll.c only when poll backend is enabled
4483 ev_epoll.c only when the epoll backend is enabled 4512 ev_epoll.c only when the epoll backend is enabled
4484 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
4485 ev_kqueue.c only when the kqueue backend is enabled 4515 ev_kqueue.c only when the kqueue backend is enabled
4486 ev_port.c only when the solaris port backend is enabled 4516 ev_port.c only when the solaris port backend is enabled
4487 4517
4488F<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
4489to compile this single file. 4519to compile this single file.
… …
4610available and will probe for kernel support at runtime. This will improve 4640available and will probe for kernel support at runtime. This will improve
4611C<ev_signal> and C<ev_async> performance and reduce resource consumption. 4641C<ev_signal> and C<ev_async> performance and reduce resource consumption.
4612If 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
46132.7 or newer, otherwise disabled. 46432.7 or newer, otherwise disabled.
4614 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
4615=item EV_USE_SELECT 4669=item EV_USE_SELECT
4616 4670
4617If 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
4618C<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
4619other method takes over, select will be it. Otherwise the select backend 4673other method takes over, select will be it. Otherwise the select backend
… …
4682backend 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
4683headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4737headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4684 4738
4685=item EV_USE_LINUXAIO 4739=item EV_USE_LINUXAIO
4686 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
4687If 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
4688aio 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
4689explicitly. If undefined, it will be enabled on linux, otherwise 4749current limitations it has to be requested explicitly. If undefined, it
4690disabled. 4750will be enabled on linux, otherwise disabled.
4691 4751
4692=item EV_USE_KQUEUE 4752=item EV_USE_KQUEUE
4693 4753
4694If 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
4695C<kqueue>(2) backend. Its actual availability will be detected at runtime, 4755C<kqueue>(2) backend. Its actual availability will be detected at runtime,
… …
4973called. 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
4974called 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
4975verification code will be called very frequently, which will slow down 5035verification code will be called very frequently, which will slow down
4976libev considerably. 5036libev considerably.
4977 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
4978The 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
4979will be C<0>. 5042will be C<0>.
4980 5043
4981=item EV_COMMON 5044=item EV_COMMON
4982 5045

Diff Legend

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