… | |
… | |
274 | a fork, you can also make libev check for a fork in each iteration by |
274 | a fork, you can also make libev check for a fork in each iteration by |
275 | enabling this flag. |
275 | enabling this flag. |
276 | |
276 | |
277 | This works by calling C<getpid ()> on every iteration of the loop, |
277 | This works by calling C<getpid ()> on every iteration of the loop, |
278 | and thus this might slow down your event loop if you do a lot of loop |
278 | and thus this might slow down your event loop if you do a lot of loop |
279 | iterations and little real work, but is usually not noticable (on my |
279 | iterations and little real work, but is usually not noticeable (on my |
280 | Linux system for example, C<getpid> is actually a simple 5-insn sequence |
280 | Linux system for example, C<getpid> is actually a simple 5-insn sequence |
281 | without a syscall and thus I<very> fast, but my Linux system also has |
281 | without a syscall and thus I<very> fast, but my Linux system also has |
282 | C<pthread_atfork> which is even faster). |
282 | C<pthread_atfork> which is even faster). |
283 | |
283 | |
284 | The big advantage of this flag is that you can forget about fork (and |
284 | The 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 | |
431 | Like C<ev_default_fork>, but acts on an event loop created by |
431 | Like C<ev_default_fork>, but acts on an event loop created by |
432 | C<ev_loop_new>. Yes, you have to call this on every allocated event loop |
432 | C<ev_loop_new>. Yes, you have to call this on every allocated event loop |
433 | after fork, and how you do this is entirely your own problem. |
433 | after fork, and how you do this is entirely your own problem. |
|
|
434 | |
|
|
435 | =item unsigned int ev_loop_count (loop) |
|
|
436 | |
|
|
437 | Returns the count of loop iterations for the loop, which is identical to |
|
|
438 | the number of times libev did poll for new events. It starts at C<0> and |
|
|
439 | happily wraps around with enough iterations. |
|
|
440 | |
|
|
441 | This value can sometimes be useful as a generation counter of sorts (it |
|
|
442 | "ticks" the number of loop iterations), as it roughly corresponds with |
|
|
443 | C<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 | |
437 | Returns one of the C<EVBACKEND_*> flags indicating the event backend in |
447 | Returns one of the C<EVBACKEND_*> flags indicating the event backend in |
438 | use. |
448 | use. |
… | |
… | |
734 | =item ev_cb_set (ev_TYPE *watcher, callback) |
744 | =item ev_cb_set (ev_TYPE *watcher, callback) |
735 | |
745 | |
736 | Change the callback. You can change the callback at virtually any time |
746 | Change 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 | |
|
|
753 | Set and query the priority of the watcher. The priority is a small |
|
|
754 | integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> |
|
|
755 | (default: C<-2>). Pending watchers with higher priority will be invoked |
|
|
756 | before watchers with lower priority, but priority will not keep watchers |
|
|
757 | from being executed (except for C<ev_idle> watchers). |
|
|
758 | |
|
|
759 | This means that priorities are I<only> used for ordering callback |
|
|
760 | invocation after new events have been received. This is useful, for |
|
|
761 | example, to reduce latency after idling, or more often, to bind two |
|
|
762 | watchers on the same event and make sure one is called first. |
|
|
763 | |
|
|
764 | If you need to suppress invocation when higher priority events are pending |
|
|
765 | you need to look at C<ev_idle> watchers, which provide this functionality. |
|
|
766 | |
|
|
767 | The default priority used by watchers when no priority has been set is |
|
|
768 | always C<0>, which is supposed to not be too high and not be too low :). |
|
|
769 | |
|
|
770 | Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is |
|
|
771 | fine, as long as you do not mind that the priority value you query might |
|
|
772 | or 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 | |
… | |
… | |
848 | it is best to always use non-blocking I/O: An extra C<read>(2) returning |
883 | it is best to always use non-blocking I/O: An extra C<read>(2) returning |
849 | C<EAGAIN> is far preferable to a program hanging until some data arrives. |
884 | C<EAGAIN> is far preferable to a program hanging until some data arrives. |
850 | |
885 | |
851 | If you cannot run the fd in non-blocking mode (for example you should not |
886 | If you cannot run the fd in non-blocking mode (for example you should not |
852 | play around with an Xlib connection), then you have to seperately re-test |
887 | play around with an Xlib connection), then you have to seperately re-test |
853 | wether a file descriptor is really ready with a known-to-be good interface |
888 | whether a file descriptor is really ready with a known-to-be good interface |
854 | such as poll (fortunately in our Xlib example, Xlib already does this on |
889 | such as poll (fortunately in our Xlib example, Xlib already does this on |
855 | its own, so its quite safe to use). |
890 | its 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 | |
1346 | Idle watchers trigger events when there are no other events are pending |
1381 | Idle 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 |
1382 | priority are pending (prepare, check and other idle watchers do not |
1348 | as your process is busy handling sockets or timeouts (or even signals, |
1383 | count). |
1349 | imagine) it will not be triggered. But when your process is idle all idle |
1384 | |
1350 | watchers are being called again and again, once per event loop iteration - |
1385 | That 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 |
|
|
1387 | triggered. But when your process is idle (or only lower-priority watchers |
|
|
1388 | are pending), the idle watchers are being called once per event loop |
1351 | until stopped, that is, or your process receives more events and becomes |
1389 | iteration - until stopped, that is, or your process receives more events |
1352 | busy. |
1390 | and becomes busy again with higher priority stuff. |
1353 | |
1391 | |
1354 | The most noteworthy effect is that as long as any idle watchers are |
1392 | The most noteworthy effect is that as long as any idle watchers are |
1355 | active, the process will not block when waiting for new events. |
1393 | active, the process will not block when waiting for new events. |
1356 | |
1394 | |
1357 | Apart from keeping your process non-blocking (which is a useful |
1395 | Apart from keeping your process non-blocking (which is a useful |
… | |
… | |
1806 | |
1844 | |
1807 | |
1845 | |
1808 | =head1 MACRO MAGIC |
1846 | =head1 MACRO MAGIC |
1809 | |
1847 | |
1810 | Libev can be compiled with a variety of options, the most fundemantal is |
1848 | Libev can be compiled with a variety of options, the most fundemantal is |
1811 | C<EV_MULTIPLICITY>. This option determines wether (most) functions and |
1849 | C<EV_MULTIPLICITY>. This option determines whether (most) functions and |
1812 | callbacks have an initial C<struct ev_loop *> argument. |
1850 | callbacks have an initial C<struct ev_loop *> argument. |
1813 | |
1851 | |
1814 | To make it easier to write programs that cope with either variant, the |
1852 | To make it easier to write programs that cope with either variant, the |
1815 | following macros are defined: |
1853 | following macros are defined: |
1816 | |
1854 | |
… | |
… | |
1850 | loop, if multiple loops are supported ("ev loop default"). |
1888 | loop, if multiple loops are supported ("ev loop default"). |
1851 | |
1889 | |
1852 | =back |
1890 | =back |
1853 | |
1891 | |
1854 | Example: Declare and initialise a check watcher, utilising the above |
1892 | Example: Declare and initialise a check watcher, utilising the above |
1855 | macros so it will work regardless of wether multiple loops are supported |
1893 | macros so it will work regardless of whether multiple loops are supported |
1856 | or not. |
1894 | or 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 | |
2092 | If undefined or defined to be C<1>, then periodic timers are supported. If |
2130 | If undefined or defined to be C<1>, then periodic timers are supported. If |
2093 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
2131 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
2094 | code. |
2132 | code. |
2095 | |
2133 | |
|
|
2134 | =item EV_IDLE_ENABLE |
|
|
2135 | |
|
|
2136 | If undefined or defined to be C<1>, then idle watchers are supported. If |
|
|
2137 | defined to be C<0>, then they are not. Disabling them saves a few kB of |
|
|
2138 | code. |
|
|
2139 | |
2096 | =item EV_EMBED_ENABLE |
2140 | =item EV_EMBED_ENABLE |
2097 | |
2141 | |
2098 | If undefined or defined to be C<1>, then embed watchers are supported. If |
2142 | If undefined or defined to be C<1>, then embed watchers are supported. If |
2099 | defined to be C<0>, then they are not. |
2143 | defined to be C<0>, then they are not. |
2100 | |
2144 | |