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

Comparing libev/ev.pod (file contents):
Revision 1.457 by root, Fri Sep 6 22:17:52 2019 UTC vs.
Revision 1.464 by root, Sun Jan 26 06:04:20 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
… …
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 is
1649is active, but you can also modify it. Modifying it may not do something 1659active, but you can also modify it (within the same thread as the event
1660loop, i.e. without creating data races). Modifying it may not do something
1650sensible or take immediate effect (or do anything at all), but libev will 1661sensible or take immediate effect (or do anything at all), but libev will
1651not crash or malfunction in any way. 1662not crash or malfunction in any way.
1652 1663
1664In any case, the documentation for each member will explain what the
1665effects are, and if there are any additional access restrictions.
1653 1666
1654=head2 C<ev_io> - is this file descriptor readable or writable? 1667=head2 C<ev_io> - is this file descriptor readable or writable?
1655 1668
1656I/O watchers check whether a file descriptor is readable or writable 1669I/O watchers check whether a file descriptor is readable or writable
1657in each iteration of the event loop, or, more precisely, when reading 1670in each iteration of the event loop, or, more precisely, when reading
… …
1817=item ev_io_init (ev_io *, callback, int fd, int events) 1830=item ev_io_init (ev_io *, callback, int fd, int events)
1818 1831
1819=item ev_io_set (ev_io *, int fd, int events) 1832=item ev_io_set (ev_io *, int fd, int events)
1820 1833
1821Configures an C<ev_io> watcher. The C<fd> is the file descriptor to 1834Configures 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 1835receive 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. 1836C<EV_READ | EV_WRITE> or C<0>, to express the desire to receive the given
1837events.
1824 1838
1825=item int fd [read-only] 1839Note that setting the C<events> to C<0> and starting the watcher is
1840supported, but not specially optimized - if your program sometimes happens
1841to generate this combination this is fine, but if it is easy to avoid
1842starting an io watcher watching for no events you should do so.
1826 1843
1827The file descriptor being watched. 1844=item ev_io_modify (ev_io *, int events)
1828 1845
1846Similar to C<ev_io_set>, but only changes the requested events. Using this
1847might be faster with some backends, as libev can assume that the C<fd>
1848still refers to the same underlying file description, something it cannot
1849do when using C<ev_io_set>.
1850
1851=item int fd [no-modify]
1852
1853The file descriptor being watched. While it can be read at any time, you
1854must not modify this member even when the watcher is stopped - always use
1855C<ev_io_set> for that.
1856
1829=item int events [read-only] 1857=item int events [no-modify]
1830 1858
1831The events being watched. 1859The set of events the fd is being watched for, among other flags. Remember
1860that this is a bit set - to test for C<EV_READ>, use C<< w->events &
1861EV_READ >>, and similarly for C<EV_WRITE>.
1862
1863As with C<fd>, you must not modify this member even when the watcher is
1864stopped, always use C<ev_io_set> or C<ev_io_modify> for that.
1832 1865
1833=back 1866=back
1834 1867
1835=head3 Examples 1868=head3 Examples
1836 1869
… …
4234method. 4267method.
4235 4268
4236For C<ev::embed> watchers this method is called C<set_embed>, to avoid 4269For C<ev::embed> watchers this method is called C<set_embed>, to avoid
4237clashing with the C<set (loop)> method. 4270clashing with the C<set (loop)> method.
4238 4271
4272For C<ev::io> watchers there is an additional C<set> method that acepts a
4273new event mask only, and internally calls C<ev_io_modfify>.
4274
4239=item w->start () 4275=item w->start ()
4240 4276
4241Starts the watcher. Note that there is no C<loop> argument, as the 4277Starts the watcher. Note that there is no C<loop> argument, as the
4242constructor already stores the event loop. 4278constructor already stores the event loop.
4243 4279
… …
4606 4642
4607=item EV_USE_NANOSLEEP 4643=item EV_USE_NANOSLEEP
4608 4644
4609If defined to be C<1>, libev will assume that C<nanosleep ()> is available 4645If defined to be C<1>, libev will assume that C<nanosleep ()> is available
4610and will use it for delays. Otherwise it will use C<select ()>. 4646and will use it for delays. Otherwise it will use C<select ()>.
4647
4648=item EV_USE_EVENTFD
4649
4650If defined to be C<1>, then libev will assume that C<eventfd ()> is
4651available and will probe for kernel support at runtime. This will improve
4652C<ev_signal> and C<ev_async> performance and reduce resource consumption.
4653If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46542.7 or newer, otherwise disabled.
4655
4656=item EV_USE_SIGNALFD
4657
4658If defined to be C<1>, then libev will assume that C<signalfd ()> is
4659available and will probe for kernel support at runtime. This enables
4660the use of EVFLAG_SIGNALFD for faster and simpler signal handling. If
4661undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
46622.7 or newer, otherwise disabled.
4663
4664=item EV_USE_TIMERFD
4665
4666If defined to be C<1>, then libev will assume that C<timerfd ()> is
4667available and will probe for kernel support at runtime. This allows
4668libev to detect time jumps accurately. If undefined, it will be enabled
4669if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4670C<TFD_TIMER_CANCEL_ON_SET>, otherwise disabled.
4611 4671
4612=item EV_USE_EVENTFD 4672=item EV_USE_EVENTFD
4613 4673
4614If defined to be C<1>, then libev will assume that C<eventfd ()> is 4674If defined to be C<1>, then libev will assume that C<eventfd ()> is
4615available and will probe for kernel support at runtime. This will improve 4675available and will probe for kernel support at runtime. This will improve

Diff Legend

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