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

Comparing libev/ev.pod (file contents):
Revision 1.65 by ayin, Sat Dec 1 15:38:54 2007 UTC vs.
Revision 1.68 by root, Fri Dec 7 18:09:43 2007 UTC

… …
429=item ev_loop_fork (loop) 429=item ev_loop_fork (loop)
430 430
431Like C<ev_default_fork>, but acts on an event loop created by 431Like C<ev_default_fork>, but acts on an event loop created by
432C<ev_loop_new>. Yes, you have to call this on every allocated event loop 432C<ev_loop_new>. Yes, you have to call this on every allocated event loop
433after fork, and how you do this is entirely your own problem. 433after fork, and how you do this is entirely your own problem.
434
435=item unsigned int ev_loop_count (loop)
436
437Returns the count of loop iterations for the loop, which is identical to
438the number of times libev did poll for new events. It starts at C<0> and
439happily wraps around with enough iterations.
440
441This value can sometimes be useful as a generation counter of sorts (it
442"ticks" the number of loop iterations), as it roughly corresponds with
443C<ev_prepare> and C<ev_check> calls.
434 444
435=item unsigned int ev_backend (loop) 445=item unsigned int ev_backend (loop)
436 446
437Returns one of the C<EVBACKEND_*> flags indicating the event backend in 447Returns one of the C<EVBACKEND_*> flags indicating the event backend in
438use. 448use.
… …
734=item ev_cb_set (ev_TYPE *watcher, callback) 744=item ev_cb_set (ev_TYPE *watcher, callback)
735 745
736Change the callback. You can change the callback at virtually any time 746Change the callback. You can change the callback at virtually any time
737(modulo threads). 747(modulo threads).
738 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
739=back 774=back
740 775
741 776
742=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 777=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
743 778
… …
848it 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
849C<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.
850 885
851If 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
852play 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
853wether 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
854such 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
855its own, so its quite safe to use). 890its own, so its quite safe to use).
856 891
857=over 4 892=over 4
858 893
… …
1341 ev_stat_start (loop, &passwd); 1376 ev_stat_start (loop, &passwd);
1342 1377
1343 1378
1344=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...
1345 1380
1346Idle watchers trigger events when there are no other events are pending 1381Idle watchers trigger events when no other events of the same or higher
1347(prepare, check and other idle watchers do not count). That is, as long 1382priority are pending (prepare, check and other idle watchers do not
1348as your process is busy handling sockets or timeouts (or even signals, 1383count).
1349imagine) it will not be triggered. But when your process is idle all idle 1384
1350watchers 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
1351until stopped, that is, or your process receives more events and becomes 1389iteration - until stopped, that is, or your process receives more events
1352busy. 1390and becomes busy again with higher priority stuff.
1353 1391
1354The 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
1355active, the process will not block when waiting for new events. 1393active, the process will not block when waiting for new events.
1356 1394
1357Apart from keeping your process non-blocking (which is a useful 1395Apart from keeping your process non-blocking (which is a useful
… …
1806 1844
1807 1845
1808=head1 MACRO MAGIC 1846=head1 MACRO MAGIC
1809 1847
1810Libev 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
1811C<EV_MULTIPLICITY>. This option determines wether (most) functions and 1849C<EV_MULTIPLICITY>. This option determines whether (most) functions and
1812callbacks have an initial C<struct ev_loop *> argument. 1850callbacks have an initial C<struct ev_loop *> argument.
1813 1851
1814To 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
1815following macros are defined: 1853following macros are defined:
1816 1854
… …
1850loop, if multiple loops are supported ("ev loop default"). 1888loop, if multiple loops are supported ("ev loop default").
1851 1889
1852=back 1890=back
1853 1891
1854Example: Declare and initialise a check watcher, utilising the above 1892Example: Declare and initialise a check watcher, utilising the above
1855macros so it will work regardless of wether multiple loops are supported 1893macros so it will work regardless of whether multiple loops are supported
1856or not. 1894or not.
1857 1895
1858 static void 1896 static void
1859 check_cb (EV_P_ ev_timer *w, int revents) 1897 check_cb (EV_P_ ev_timer *w, int revents)
1860 { 1898 {
… …
2091 2129
2092If 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
2093defined 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
2094code. 2132code.
2095 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
2096=item EV_EMBED_ENABLE 2140=item EV_EMBED_ENABLE
2097 2141
2098If 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
2099defined to be C<0>, then they are not. 2143defined to be C<0>, then they are not.
2100 2144

Diff Legend

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