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

Comparing libev/ev.pod (file contents):
Revision 1.63 by root, Thu Nov 29 20:05:59 2007 UTC vs.
Revision 1.68 by root, Fri Dec 7 18:09:43 2007 UTC

… …
274a fork, you can also make libev check for a fork in each iteration by 274a fork, you can also make libev check for a fork in each iteration by
275enabling this flag. 275enabling this flag.
276 276
277This works by calling C<getpid ()> on every iteration of the loop, 277This works by calling C<getpid ()> on every iteration of the loop,
278and thus this might slow down your event loop if you do a lot of loop 278and thus this might slow down your event loop if you do a lot of loop
279iterations and little real work, but is usually not noticable (on my 279iterations and little real work, but is usually not noticeable (on my
280Linux system for example, C<getpid> is actually a simple 5-insn sequence 280Linux system for example, C<getpid> is actually a simple 5-insn sequence
281without a syscall and thus I<very> fast, but my Linux system also has 281without a syscall and thus I<very> fast, but my Linux system also has
282C<pthread_atfork> which is even faster). 282C<pthread_atfork> which is even faster).
283 283
284The big advantage of this flag is that you can forget about fork (and 284The big advantage of this flag is that you can forget about fork (and
… …
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
… …
1457 1495
1458 // create io watchers for each fd and a timer before blocking 1496 // create io watchers for each fd and a timer before blocking
1459 static void 1497 static void
1460 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 1498 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1461 { 1499 {
1462 int timeout = 3600000;truct pollfd fds [nfd]; 1500 int timeout = 3600000;
1501 struct pollfd fds [nfd];
1463 // actual code will need to loop here and realloc etc. 1502 // actual code will need to loop here and realloc etc.
1464 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 1503 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1465 1504
1466 /* the callback is illegal, but won't be called as we stop during check */ 1505 /* the callback is illegal, but won't be called as we stop during check */
1467 ev_timer_init (&tw, 0, timeout * 1e-3); 1506 ev_timer_init (&tw, 0, timeout * 1e-3);
… …
1805 1844
1806 1845
1807=head1 MACRO MAGIC 1846=head1 MACRO MAGIC
1808 1847
1809Libev 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
1810C<EV_MULTIPLICITY>. This option determines wether (most) functions and 1849C<EV_MULTIPLICITY>. This option determines whether (most) functions and
1811callbacks have an initial C<struct ev_loop *> argument. 1850callbacks have an initial C<struct ev_loop *> argument.
1812 1851
1813To 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
1814following macros are defined: 1853following macros are defined:
1815 1854
… …
1849loop, if multiple loops are supported ("ev loop default"). 1888loop, if multiple loops are supported ("ev loop default").
1850 1889
1851=back 1890=back
1852 1891
1853Example: Declare and initialise a check watcher, utilising the above 1892Example: Declare and initialise a check watcher, utilising the above
1854macros so it will work regardless of wether multiple loops are supported 1893macros so it will work regardless of whether multiple loops are supported
1855or not. 1894or not.
1856 1895
1857 static void 1896 static void
1858 check_cb (EV_P_ ev_timer *w, int revents) 1897 check_cb (EV_P_ ev_timer *w, int revents)
1859 { 1898 {
… …
2090 2129
2091If 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
2092defined 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
2093code. 2132code.
2094 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
2095=item EV_EMBED_ENABLE 2140=item EV_EMBED_ENABLE
2096 2141
2097If 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
2098defined to be C<0>, then they are not. 2143defined to be C<0>, then they are not.
2099 2144

Diff Legend

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