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

Comparing libev/ev.pod (file contents):
Revision 1.66 by root, Mon Dec 3 13:41:25 2007 UTC vs.
Revision 1.68 by root, Fri Dec 7 18:09:43 2007 UTC

… …
744=item ev_cb_set (ev_TYPE *watcher, callback) 744=item ev_cb_set (ev_TYPE *watcher, callback)
745 745
746Change the callback. You can change the callback at virtually any time 746Change the callback. You can change the callback at virtually any time
747(modulo threads). 747(modulo threads).
748 748
749=item ev_set_priority (ev_TYPE *watcher, priority)
750
751=item int ev_priority (ev_TYPE *watcher)
752
753Set and query the priority of the watcher. The priority is a small
754integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
755(default: C<-2>). Pending watchers with higher priority will be invoked
756before watchers with lower priority, but priority will not keep watchers
757from being executed (except for C<ev_idle> watchers).
758
759This means that priorities are I<only> used for ordering callback
760invocation after new events have been received. This is useful, for
761example, to reduce latency after idling, or more often, to bind two
762watchers on the same event and make sure one is called first.
763
764If you need to suppress invocation when higher priority events are pending
765you need to look at C<ev_idle> watchers, which provide this functionality.
766
767The default priority used by watchers when no priority has been set is
768always C<0>, which is supposed to not be too high and not be too low :).
769
770Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
771fine, as long as you do not mind that the priority value you query might
772or might not have been adjusted to be within valid range.
773
749=back 774=back
750 775
751 776
752=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 777=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
753 778
… …
858it is best to always use non-blocking I/O: An extra C<read>(2) returning 883it is best to always use non-blocking I/O: An extra C<read>(2) returning
859C<EAGAIN> is far preferable to a program hanging until some data arrives. 884C<EAGAIN> is far preferable to a program hanging until some data arrives.
860 885
861If you cannot run the fd in non-blocking mode (for example you should not 886If you cannot run the fd in non-blocking mode (for example you should not
862play around with an Xlib connection), then you have to seperately re-test 887play around with an Xlib connection), then you have to seperately re-test
863wether a file descriptor is really ready with a known-to-be good interface 888whether a file descriptor is really ready with a known-to-be good interface
864such as poll (fortunately in our Xlib example, Xlib already does this on 889such as poll (fortunately in our Xlib example, Xlib already does this on
865its own, so its quite safe to use). 890its own, so its quite safe to use).
866 891
867=over 4 892=over 4
868 893
… …
1351 ev_stat_start (loop, &passwd); 1376 ev_stat_start (loop, &passwd);
1352 1377
1353 1378
1354=head2 C<ev_idle> - when you've got nothing better to do... 1379=head2 C<ev_idle> - when you've got nothing better to do...
1355 1380
1356Idle watchers trigger events when there are no other events are pending 1381Idle watchers trigger events when no other events of the same or higher
1357(prepare, check and other idle watchers do not count). That is, as long 1382priority are pending (prepare, check and other idle watchers do not
1358as your process is busy handling sockets or timeouts (or even signals, 1383count).
1359imagine) it will not be triggered. But when your process is idle all idle 1384
1360watchers are being called again and again, once per event loop iteration - 1385That is, as long as your process is busy handling sockets or timeouts
1386(or even signals, imagine) of the same or higher priority it will not be
1387triggered. But when your process is idle (or only lower-priority watchers
1388are pending), the idle watchers are being called once per event loop
1361until stopped, that is, or your process receives more events and becomes 1389iteration - until stopped, that is, or your process receives more events
1362busy. 1390and becomes busy again with higher priority stuff.
1363 1391
1364The most noteworthy effect is that as long as any idle watchers are 1392The most noteworthy effect is that as long as any idle watchers are
1365active, the process will not block when waiting for new events. 1393active, the process will not block when waiting for new events.
1366 1394
1367Apart from keeping your process non-blocking (which is a useful 1395Apart from keeping your process non-blocking (which is a useful
… …
1816 1844
1817 1845
1818=head1 MACRO MAGIC 1846=head1 MACRO MAGIC
1819 1847
1820Libev can be compiled with a variety of options, the most fundemantal is 1848Libev can be compiled with a variety of options, the most fundemantal is
1821C<EV_MULTIPLICITY>. This option determines wether (most) functions and 1849C<EV_MULTIPLICITY>. This option determines whether (most) functions and
1822callbacks have an initial C<struct ev_loop *> argument. 1850callbacks have an initial C<struct ev_loop *> argument.
1823 1851
1824To make it easier to write programs that cope with either variant, the 1852To make it easier to write programs that cope with either variant, the
1825following macros are defined: 1853following macros are defined:
1826 1854
… …
1860loop, if multiple loops are supported ("ev loop default"). 1888loop, if multiple loops are supported ("ev loop default").
1861 1889
1862=back 1890=back
1863 1891
1864Example: Declare and initialise a check watcher, utilising the above 1892Example: Declare and initialise a check watcher, utilising the above
1865macros so it will work regardless of wether multiple loops are supported 1893macros so it will work regardless of whether multiple loops are supported
1866or not. 1894or not.
1867 1895
1868 static void 1896 static void
1869 check_cb (EV_P_ ev_timer *w, int revents) 1897 check_cb (EV_P_ ev_timer *w, int revents)
1870 { 1898 {
… …
2101 2129
2102If undefined or defined to be C<1>, then periodic timers are supported. If 2130If undefined or defined to be C<1>, then periodic timers are supported. If
2103defined to be C<0>, then they are not. Disabling them saves a few kB of 2131defined to be C<0>, then they are not. Disabling them saves a few kB of
2104code. 2132code.
2105 2133
2134=item EV_IDLE_ENABLE
2135
2136If undefined or defined to be C<1>, then idle watchers are supported. If
2137defined to be C<0>, then they are not. Disabling them saves a few kB of
2138code.
2139
2106=item EV_EMBED_ENABLE 2140=item EV_EMBED_ENABLE
2107 2141
2108If undefined or defined to be C<1>, then embed watchers are supported. If 2142If undefined or defined to be C<1>, then embed watchers are supported. If
2109defined to be C<0>, then they are not. 2143defined to be C<0>, then they are not.
2110 2144

Diff Legend

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