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

Comparing libev/ev.pod (file contents):
Revision 1.458 by root, Fri Dec 20 20:51:46 2019 UTC vs.
Revision 1.462 by root, Wed Jan 22 13:06:53 2020 UTC

… …
1218with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher 1218with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
1219*) >>), 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
1220corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>. 1220corresponding stop function (C<< ev_TYPE_stop (loop, watcher *) >>.
1221 1221
1222As 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
1223must not touch the values stored in it. Most specifically you must never 1223must not touch the values stored in it except when explicitly documented
1224reinitialise 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.
1225 1226
1226Each and every callback receives the event loop pointer as first, the 1227Each and every callback receives the event loop pointer as first, the
1227registered watcher structure as second, and a bitset of received events as 1228registered watcher structure as second, and a bitset of received events as
1228third argument. 1229third argument.
1229 1230
… …
1648 1649
1649This section describes each watcher in detail, but will not repeat 1650This section describes each watcher in detail, but will not repeat
1650information given in the last section. Any initialisation/set macros, 1651information given in the last section. Any initialisation/set macros,
1651functions and members specific to the watcher type are explained. 1652functions and members specific to the watcher type are explained.
1652 1653
1653Members are additionally marked with either I<[read-only]>, meaning that, 1654Most members are additionally marked with either I<[read-only]>, meaning
1654while 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
1655sensible 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
1656watcher is stopped to your hearts content), or I<[read-write]>, which 1657the watcher is stopped to your hearts content), or I<[read-write]>, which
1657means 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
1658is 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
1659sensible 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
1660not crash or malfunction in any way. 1661not crash or malfunction in any way.
1661 1662
1663In any case, the documentation for each member will explain what the
1664effects are, and if there are any additional access restrictions.
1662 1665
1663=head2 C<ev_io> - is this file descriptor readable or writable? 1666=head2 C<ev_io> - is this file descriptor readable or writable?
1664 1667
1665I/O watchers check whether a file descriptor is readable or writable 1668I/O watchers check whether a file descriptor is readable or writable
1666in each iteration of the event loop, or, more precisely, when reading 1669in each iteration of the event loop, or, more precisely, when reading
… …
1826=item ev_io_init (ev_io *, callback, int fd, int events) 1829=item ev_io_init (ev_io *, callback, int fd, int events)
1827 1830
1828=item ev_io_set (ev_io *, int fd, int events) 1831=item ev_io_set (ev_io *, int fd, int events)
1829 1832
1830Configures 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
1831receive 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
1832C<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.
1833 1837
1834=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.
1835 1842
1836The file descriptor being watched. 1843=item ev_io_modify (ev_io *, int events)
1837 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
1838=item int events [read-only] 1856=item int events [no-modify]
1839 1857
1840The 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.
1841 1864
1842=back 1865=back
1843 1866
1844=head3 Examples 1867=head3 Examples
1845 1868
… …
4243method. 4266method.
4244 4267
4245For 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
4246clashing with the C<set (loop)> method. 4269clashing with the C<set (loop)> method.
4247 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
4248=item w->start () 4274=item w->start ()
4249 4275
4250Starts 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
4251constructor already stores the event loop. 4277constructor already stores the event loop.
4252 4278

Diff Legend

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