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

Comparing libev/ev.pod (file contents):
Revision 1.455 by root, Wed Jun 26 00:01:46 2019 UTC vs.
Revision 1.462 by root, Wed Jan 22 13:06:53 2020 UTC

… …
480unblocking the signals. 480unblocking the signals.
481 481
482It'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
483C<sigprocmask>, whose behaviour is officially unspecified. 483C<sigprocmask>, whose behaviour is officially unspecified.
484 484
485This 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.
486 495
487=item C<EVBACKEND_SELECT> (value 1, portable select backend) 496=item C<EVBACKEND_SELECT> (value 1, portable select backend)
488 497
489This is your standard select(2) backend. Not I<completely> standard, as 498This is your standard select(2) backend. Not I<completely> standard, as
490libev 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,
… …
1209with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher 1218with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
1210*) >>), and you can stop watching for events at any time by calling the 1219*) >>), and you can stop watching for events at any time by calling the
1211corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>. 1220corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
1212 1221
1213As long as your watcher is active (has been started but not stopped) you 1222As long as your watcher is active (has been started but not stopped) you
1214must not touch the values stored in it. Most specifically you must never 1223must not touch the values stored in it except when explicitly documented
1215reinitialise it or call its C<ev_TYPE_set> macro. 1224otherwise. Most specifically you must never reinitialise it or call its
1225C<ev_TYPE_set> macro.
1216 1226
1217Each and every callback receives the event loop pointer as first, the 1227Each and every callback receives the event loop pointer as first, the
1218registered watcher structure as second, and a bitset of received events as 1228registered watcher structure as second, and a bitset of received events as
1219third argument. 1229third argument.
1220 1230
… …
1535 1545
1536Many event loops support I<watcher priorities>, which are usually small 1546Many event loops support I<watcher priorities>, which are usually small
1537integers that influence the ordering of event callback invocation 1547integers that influence the ordering of event callback invocation
1538between watchers in some way, all else being equal. 1548between watchers in some way, all else being equal.
1539 1549
1540In libev, Watcher priorities can be set using C<ev_set_priority>. See its 1550In libev, watcher priorities can be set using C<ev_set_priority>. See its
1541description for the more technical details such as the actual priority 1551description for the more technical details such as the actual priority
1542range. 1552range.
1543 1553
1544There are two common ways how these these priorities are being interpreted 1554There are two common ways how these these priorities are being interpreted
1545by event loops: 1555by event loops:
… …
1639 1649
1640This section describes each watcher in detail, but will not repeat 1650This section describes each watcher in detail, but will not repeat
1641information given in the last section. Any initialisation/set macros, 1651information given in the last section. Any initialisation/set macros,
1642functions and members specific to the watcher type are explained. 1652functions and members specific to the watcher type are explained.
1643 1653
1644Members are additionally marked with either I<[read-only]>, meaning that, 1654Most members are additionally marked with either I<[read-only]>, meaning
1645while the watcher is active, you can look at the member and expect some 1655that, while the watcher is active, you can look at the member and expect
1646sensible content, but you must not modify it (you can modify it while the 1656some sensible content, but you must not modify it (you can modify it while
1647watcher is stopped to your hearts content), or I<[read-write]>, which 1657the watcher is stopped to your hearts content), or I<[read-write]>, which
1648means you can expect it to have some sensible content while the watcher 1658means you can expect it to have some sensible content while the watcher
1649is active, but you can also modify it. Modifying it may not do something 1659is active, but you can also modify it. Modifying it may not do something
1650sensible or take immediate effect (or do anything at all), but libev will 1660sensible or take immediate effect (or do anything at all), but libev will
1651not crash or malfunction in any way. 1661not crash or malfunction in any way.
1652 1662
1663In any case, the documentation for each member will explain what the
1664effects are, and if there are any additional access restrictions.
1653 1665
1654=head2 C<ev_io> - is this file descriptor readable or writable? 1666=head2 C<ev_io> - is this file descriptor readable or writable?
1655 1667
1656I/O watchers check whether a file descriptor is readable or writable 1668I/O watchers check whether a file descriptor is readable or writable
1657in each iteration of the event loop, or, more precisely, when reading 1669in each iteration of the event loop, or, more precisely, when reading
… …
1749when you rarely read from a file instead of from a socket, and want to 1761when you rarely read from a file instead of from a socket, and want to
1750reuse the same code path. 1762reuse the same code path.
1751 1763
1752=head3 The special problem of fork 1764=head3 The special problem of fork
1753 1765
1754Some backends (epoll, kqueue, probably linuxaio) do not support C<fork ()> 1766Some backends (epoll, kqueue, linuxaio, iouring) do not support C<fork ()>
1755at all or exhibit useless behaviour. Libev fully supports fork, but needs 1767at all or exhibit useless behaviour. Libev fully supports fork, but needs
1756to be told about it in the child if you want to continue to use it in the 1768to be told about it in the child if you want to continue to use it in the
1757child. 1769child.
1758 1770
1759To support fork in your child processes, you have to call C<ev_loop_fork 1771To support fork in your child processes, you have to call C<ev_loop_fork
… …
1817=item ev_io_init (ev_io *, callback, int fd, int events) 1829=item ev_io_init (ev_io *, callback, int fd, int events)
1818 1830
1819=item ev_io_set (ev_io *, int fd, int events) 1831=item ev_io_set (ev_io *, int fd, int events)
1820 1832
1821Configures an C<ev_io> watcher. The C<fd> is the file descriptor to 1833Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1822receive events for and C<events> is either C<EV_READ>, C<EV_WRITE> or 1834receive events for and C<events> is either C<EV_READ>, C<EV_WRITE>, both
1823C<EV_READ | EV_WRITE>, to express the desire to receive the given events. 1835C<EV_READ | EV_WRITE> or C<0>, to express the desire to receive the given
1836events.
1824 1837
1825=item int fd [read-only] 1838Note that setting the C<events> to C<0> and starting the watcher is
1839supported, but not specially optimized - if your program sometimes happens
1840to generate this combination this is fine, but if it is easy to avoid
1841starting an io watcher watching for no events you should do so.
1826 1842
1827The file descriptor being watched. 1843=item ev_io_modify (ev_io *, int events)
1828 1844
1845Similar to C<ev_io_set>, but only changes the event mask. Using this might
1846be faster with some backends, as libev can assume that the C<fd> still
1847refers to the same underlying file description, something it cannot do
1848when using C<ev_io_set>.
1849
1850=item int fd [no-modify]
1851
1852The file descriptor being watched. While it can be read at any time, you
1853must not modify this member even when the watcher is stopped - always use
1854C<ev_io_set> for that.
1855
1829=item int events [read-only] 1856=item int events [no-modify]
1830 1857
1831The events being watched. 1858The set of events the fd is being watched for, among other flags. Remember
1859that this is a bit set - to test for C<EV_READ>, use C<< w->events &
1860EV_READ >>, and similarly for C<EV_WRITE>.
1861
1862As with C<fd>, you must not modify this member even when the watcher is
1863stopped, always use C<ev_io_set> or C<ev_io_modify> for that.
1832 1864
1833=back 1865=back
1834 1866
1835=head3 Examples 1867=head3 Examples
1836 1868
… …
4234method. 4266method.
4235 4267
4236For C<ev::embed> watchers this method is called C<set_embed>, to avoid 4268For C<ev::embed> watchers this method is called C<set_embed>, to avoid
4237clashing with the C<set (loop)> method. 4269clashing with the C<set (loop)> method.
4238 4270
4271For C<ev::io> watchers there is an additional C<set> method that acepts a
4272new event mask only, and internally calls C<ev_io_modfify>.
4273
4239=item w->start () 4274=item w->start ()
4240 4275
4241Starts the watcher. Note that there is no C<loop> argument, as the 4276Starts the watcher. Note that there is no C<loop> argument, as the
4242constructor already stores the event loop. 4277constructor already stores the event loop.
4243 4278
… …
4484 4519
4485 ev_select.c only when select backend is enabled 4520 ev_select.c only when select backend is enabled
4486 ev_poll.c only when poll backend is enabled 4521 ev_poll.c only when poll backend is enabled
4487 ev_epoll.c only when the epoll backend is enabled 4522 ev_epoll.c only when the epoll backend is enabled
4488 ev_linuxaio.c only when the linux aio backend is enabled 4523 ev_linuxaio.c only when the linux aio backend is enabled
4524 ev_iouring.c only when the linux io_uring backend is enabled
4489 ev_kqueue.c only when the kqueue backend is enabled 4525 ev_kqueue.c only when the kqueue backend is enabled
4490 ev_port.c only when the solaris port backend is enabled 4526 ev_port.c only when the solaris port backend is enabled
4491 4527
4492F<ev.c> includes the backend files directly when enabled, so you only need 4528F<ev.c> includes the backend files directly when enabled, so you only need
4493to compile this single file. 4529to compile this single file.
… …
4614available and will probe for kernel support at runtime. This will improve 4650available and will probe for kernel support at runtime. This will improve
4615C<ev_signal> and C<ev_async> performance and reduce resource consumption. 4651C<ev_signal> and C<ev_async> performance and reduce resource consumption.
4616If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc 4652If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46172.7 or newer, otherwise disabled. 46532.7 or newer, otherwise disabled.
4618 4654
4655=item EV_USE_SIGNALFD
4656
4657If defined to be C<1>, then libev will assume that C<signalfd ()> is
4658available and will probe for kernel support at runtime. This enables
4659the use of EVFLAG_SIGNALFD for faster and simpler signal handling. If
4660undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46612.7 or newer, otherwise disabled.
4662
4663=item EV_USE_TIMERFD
4664
4665If defined to be C<1>, then libev will assume that C<timerfd ()> is
4666available and will probe for kernel support at runtime. This allows
4667libev to detect time jumps accurately. If undefined, it will be enabled
4668if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4669C<TFD_TIMER_CANCEL_ON_SET>, otherwise disabled.
4670
4671=item EV_USE_EVENTFD
4672
4673If defined to be C<1>, then libev will assume that C<eventfd ()> is
4674available and will probe for kernel support at runtime. This will improve
4675C<ev_signal> and C<ev_async> performance and reduce resource consumption.
4676If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46772.7 or newer, otherwise disabled.
4678
4619=item EV_USE_SELECT 4679=item EV_USE_SELECT
4620 4680
4621If undefined or defined to be C<1>, libev will compile in support for the 4681If undefined or defined to be C<1>, libev will compile in support for the
4622C<select>(2) backend. No attempt at auto-detection will be done: if no 4682C<select>(2) backend. No attempt at auto-detection will be done: if no
4623other method takes over, select will be it. Otherwise the select backend 4683other method takes over, select will be it. Otherwise the select backend
… …
4686backend for GNU/Linux systems. If undefined, it will be enabled if the 4746backend for GNU/Linux systems. If undefined, it will be enabled if the
4687headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4747headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4688 4748
4689=item EV_USE_LINUXAIO 4749=item EV_USE_LINUXAIO
4690 4750
4751If defined to be C<1>, libev will compile in support for the Linux aio
4752backend (C<EV_USE_EPOLL> must also be enabled). If undefined, it will be
4753enabled on linux, otherwise disabled.
4754
4755=item EV_USE_IOURING
4756
4691If defined to be C<1>, libev will compile in support for the Linux 4757If defined to be C<1>, libev will compile in support for the Linux
4692aio backend. Due to it's currenbt limitations it has to be requested 4758io_uring backend (C<EV_USE_EPOLL> must also be enabled). Due to it's
4693explicitly. If undefined, it will be enabled on linux, otherwise 4759current limitations it has to be requested explicitly. If undefined, it
4694disabled. 4760will be enabled on linux, otherwise disabled.
4695 4761
4696=item EV_USE_KQUEUE 4762=item EV_USE_KQUEUE
4697 4763
4698If defined to be C<1>, libev will compile in support for the BSD style 4764If defined to be C<1>, libev will compile in support for the BSD style
4699C<kqueue>(2) backend. Its actual availability will be detected at runtime, 4765C<kqueue>(2) backend. Its actual availability will be detected at runtime,

Diff Legend

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