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

Comparing libev/ev.html (file contents):
Revision 1.47 by root, Mon Nov 26 10:20:43 2007 UTC vs.
Revision 1.53 by root, Tue Nov 27 20:15:02 2007 UTC

… …
4<head> 4<head>
5 <title>libev</title> 5 <title>libev</title>
6 <meta name="description" content="Pod documentation for libev" /> 6 <meta name="description" content="Pod documentation for libev" />
7 <meta name="inputfile" content="&lt;standard input&gt;" /> 7 <meta name="inputfile" content="&lt;standard input&gt;" />
8 <meta name="outputfile" content="&lt;standard output&gt;" /> 8 <meta name="outputfile" content="&lt;standard output&gt;" />
9 <meta name="created" content="Mon Nov 26 11:20:35 2007" /> 9 <meta name="created" content="Tue Nov 27 21:14:27 2007" />
10 <meta name="generator" content="Pod::Xhtml 1.57" /> 10 <meta name="generator" content="Pod::Xhtml 1.57" />
11<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head> 11<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
12<body> 12<body>
13<div class="pod"> 13<div class="pod">
14<!-- INDEX START --> 14<!-- INDEX START -->
… …
31<ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable?</a></li> 31<ul><li><a href="#code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable?</a></li>
32<li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally repeating timeouts</a></li> 32<li><a href="#code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally repeating timeouts</a></li>
33<li><a href="#code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron?</a></li> 33<li><a href="#code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron?</a></li>
34<li><a href="#code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled!</a></li> 34<li><a href="#code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled!</a></li>
35<li><a href="#code_ev_child_code_watch_out_for_pro"><code>ev_child</code> - watch out for process status changes</a></li> 35<li><a href="#code_ev_child_code_watch_out_for_pro"><code>ev_child</code> - watch out for process status changes</a></li>
36<li><a href="#code_ev_stat_code_did_the_file_attri"><code>ev_stat</code> - did the file attributes just change?</a></li>
36<li><a href="#code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do...</a></li> 37<li><a href="#code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do...</a></li>
37<li><a href="#code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop!</a></li> 38<li><a href="#code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop!</a></li>
38<li><a href="#code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough...</a></li> 39<li><a href="#code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough...</a></li>
40<li><a href="#code_ev_fork_code_the_audacity_to_re"><code>ev_fork</code> - the audacity to resume the event loop after a fork</a></li>
39</ul> 41</ul>
40</li> 42</li>
41<li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li> 43<li><a href="#OTHER_FUNCTIONS">OTHER FUNCTIONS</a></li>
42<li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li> 44<li><a href="#LIBEVENT_EMULATION">LIBEVENT EMULATION</a></li>
43<li><a href="#C_SUPPORT">C++ SUPPORT</a></li> 45<li><a href="#C_SUPPORT">C++ SUPPORT</a></li>
46<li><a href="#MACRO_MAGIC">MACRO MAGIC</a></li>
44<li><a href="#EMBEDDING">EMBEDDING</a> 47<li><a href="#EMBEDDING">EMBEDDING</a>
45<ul><li><a href="#FILESETS">FILESETS</a> 48<ul><li><a href="#FILESETS">FILESETS</a>
46<ul><li><a href="#CORE_EVENT_LOOP">CORE EVENT LOOP</a></li> 49<ul><li><a href="#CORE_EVENT_LOOP">CORE EVENT LOOP</a></li>
47<li><a href="#LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</a></li> 50<li><a href="#LIBEVENT_COMPATIBILITY_API">LIBEVENT COMPATIBILITY API</a></li>
48<li><a href="#AUTOCONF_SUPPORT">AUTOCONF SUPPORT</a></li> 51<li><a href="#AUTOCONF_SUPPORT">AUTOCONF SUPPORT</a></li>
… …
63<p>libev - a high performance full-featured event loop written in C</p> 66<p>libev - a high performance full-featured event loop written in C</p>
64 67
65</div> 68</div>
66<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p> 69<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
67<div id="SYNOPSIS_CONTENT"> 70<div id="SYNOPSIS_CONTENT">
71<pre> /* this is the only header you need */
68<pre> #include &lt;ev.h&gt; 72 #include &lt;ev.h&gt;
73
74 /* what follows is a fully working example program */
75 ev_io stdin_watcher;
76 ev_timer timeout_watcher;
77
78 /* called when data readable on stdin */
79 static void
80 stdin_cb (EV_P_ struct ev_io *w, int revents)
81 {
82 /* puts (&quot;stdin ready&quot;); */
83 ev_io_stop (EV_A_ w); /* just a syntax example */
84 ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
85 }
86
87 static void
88 timeout_cb (EV_P_ struct ev_timer *w, int revents)
89 {
90 /* puts (&quot;timeout&quot;); */
91 ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
92 }
93
94 int
95 main (void)
96 {
97 struct ev_loop *loop = ev_default_loop (0);
98
99 /* initialise an io watcher, then start it */
100 ev_io_init (&amp;stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
101 ev_io_start (loop, &amp;stdin_watcher);
102
103 /* simple non-repeating 5.5 second timeout */
104 ev_timer_init (&amp;timeout_watcher, timeout_cb, 5.5, 0.);
105 ev_timer_start (loop, &amp;timeout_watcher);
106
107 /* loop till timeout or data ready */
108 ev_loop (loop, 0);
109
110 return 0;
111 }
69 112
70</pre> 113</pre>
71 114
72</div> 115</div>
73<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p> 116<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
… …
112(fractional) number of seconds since the (POSIX) epoch (somewhere near 155(fractional) number of seconds since the (POSIX) epoch (somewhere near
113the beginning of 1970, details are complicated, don't ask). This type is 156the beginning of 1970, details are complicated, don't ask). This type is
114called <code>ev_tstamp</code>, which is what you should use too. It usually aliases 157called <code>ev_tstamp</code>, which is what you should use too. It usually aliases
115to the <code>double</code> type in C, and when you need to do any calculations on 158to the <code>double</code> type in C, and when you need to do any calculations on
116it, you should treat it as such.</p> 159it, you should treat it as such.</p>
117
118
119
120
121 160
122</div> 161</div>
123<h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p> 162<h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>
124<div id="GLOBAL_FUNCTIONS_CONTENT"> 163<div id="GLOBAL_FUNCTIONS_CONTENT">
125<p>These functions can be called anytime, even before initialising the 164<p>These functions can be called anytime, even before initialising the
… …
180might be supported on the current system, you would need to look at 219might be supported on the current system, you would need to look at
181<code>ev_embeddable_backends () &amp; ev_supported_backends ()</code>, likewise for 220<code>ev_embeddable_backends () &amp; ev_supported_backends ()</code>, likewise for
182recommended ones.</p> 221recommended ones.</p>
183 <p>See the description of <code>ev_embed</code> watchers for more info.</p> 222 <p>See the description of <code>ev_embed</code> watchers for more info.</p>
184 </dd> 223 </dd>
185 <dt>ev_set_allocator (void *(*cb)(void *ptr, long size))</dt> 224 <dt>ev_set_allocator (void *(*cb)(void *ptr, size_t size))</dt>
186 <dd> 225 <dd>
187 <p>Sets the allocation function to use (the prototype is similar to the 226 <p>Sets the allocation function to use (the prototype and semantics are
188realloc C function, the semantics are identical). It is used to allocate 227identical to the realloc C function). It is used to allocate and free
189and free memory (no surprises here). If it returns zero when memory 228memory (no surprises here). If it returns zero when memory needs to be
190needs to be allocated, the library might abort or take some potentially 229allocated, the library might abort or take some potentially destructive
191destructive action. The default is your system realloc function.</p> 230action. The default is your system realloc function.</p>
192 <p>You could override this function in high-availability programs to, say, 231 <p>You could override this function in high-availability programs to, say,
193free some memory if it cannot allocate memory, to use a special allocator, 232free some memory if it cannot allocate memory, to use a special allocator,
194or even to sleep a while and retry until some memory is available.</p> 233or even to sleep a while and retry until some memory is available.</p>
195 <p>Example: replace the libev allocator with one that waits a bit and then 234 <p>Example: replace the libev allocator with one that waits a bit and then
196retries: better than mine).</p> 235retries: better than mine).</p>
197<pre> static void * 236<pre> static void *
198 persistent_realloc (void *ptr, long size) 237 persistent_realloc (void *ptr, size_t size)
199 { 238 {
200 for (;;) 239 for (;;)
201 { 240 {
202 void *newptr = realloc (ptr, size); 241 void *newptr = realloc (ptr, size);
203 242
… …
586 </dd> 625 </dd>
587 <dt><code>EV_CHILD</code></dt> 626 <dt><code>EV_CHILD</code></dt>
588 <dd> 627 <dd>
589 <p>The pid specified in the <code>ev_child</code> watcher has received a status change.</p> 628 <p>The pid specified in the <code>ev_child</code> watcher has received a status change.</p>
590 </dd> 629 </dd>
630 <dt><code>EV_STAT</code></dt>
631 <dd>
632 <p>The path specified in the <code>ev_stat</code> watcher changed its attributes somehow.</p>
633 </dd>
591 <dt><code>EV_IDLE</code></dt> 634 <dt><code>EV_IDLE</code></dt>
592 <dd> 635 <dd>
593 <p>The <code>ev_idle</code> watcher has determined that you have nothing better to do.</p> 636 <p>The <code>ev_idle</code> watcher has determined that you have nothing better to do.</p>
594 </dd> 637 </dd>
595 <dt><code>EV_PREPARE</code></dt> 638 <dt><code>EV_PREPARE</code></dt>
… …
600<code>ev_loop</code> has gathered them, but before it invokes any callbacks for any 643<code>ev_loop</code> has gathered them, but before it invokes any callbacks for any
601received events. Callbacks of both watcher types can start and stop as 644received events. Callbacks of both watcher types can start and stop as
602many watchers as they want, and all of them will be taken into account 645many watchers as they want, and all of them will be taken into account
603(for example, a <code>ev_prepare</code> watcher might start an idle watcher to keep 646(for example, a <code>ev_prepare</code> watcher might start an idle watcher to keep
604<code>ev_loop</code> from blocking).</p> 647<code>ev_loop</code> from blocking).</p>
648 </dd>
649 <dt><code>EV_EMBED</code></dt>
650 <dd>
651 <p>The embedded event loop specified in the <code>ev_embed</code> watcher needs attention.</p>
652 </dd>
653 <dt><code>EV_FORK</code></dt>
654 <dd>
655 <p>The event loop has been resumed in the child process after fork (see
656<code>ev_fork</code>).</p>
605 </dd> 657 </dd>
606 <dt><code>EV_ERROR</code></dt> 658 <dt><code>EV_ERROR</code></dt>
607 <dd> 659 <dd>
608 <p>An unspecified error has occured, the watcher has been stopped. This might 660 <p>An unspecified error has occured, the watcher has been stopped. This might
609happen because the watcher could not be properly started because libev 661happen because the watcher could not be properly started because libev
… …
732 784
733</div> 785</div>
734<h1 id="WATCHER_TYPES">WATCHER TYPES</h1><p><a href="#TOP" class="toplink">Top</a></p> 786<h1 id="WATCHER_TYPES">WATCHER TYPES</h1><p><a href="#TOP" class="toplink">Top</a></p>
735<div id="WATCHER_TYPES_CONTENT"> 787<div id="WATCHER_TYPES_CONTENT">
736<p>This section describes each watcher in detail, but will not repeat 788<p>This section describes each watcher in detail, but will not repeat
737information given in the last section.</p> 789information given in the last section. Any initialisation/set macros,
790functions and members specific to the watcher type are explained.</p>
791<p>Members are additionally marked with either <i>[read-only]</i>, meaning that,
792while the watcher is active, you can look at the member and expect some
793sensible content, but you must not modify it (you can modify it while the
794watcher is stopped to your hearts content), or <i>[read-write]</i>, which
795means you can expect it to have some sensible content while the watcher
796is active, but you can also modify it. Modifying it may not do something
797sensible or take immediate effect (or do anything at all), but libev will
798not crash or malfunction in any way.</p>
738 799
739 800
740 801
741 802
742 803
… …
781 <dd> 842 <dd>
782 <p>Configures an <code>ev_io</code> watcher. The <code>fd</code> is the file descriptor to 843 <p>Configures an <code>ev_io</code> watcher. The <code>fd</code> is the file descriptor to
783rceeive events for and events is either <code>EV_READ</code>, <code>EV_WRITE</code> or 844rceeive events for and events is either <code>EV_READ</code>, <code>EV_WRITE</code> or
784<code>EV_READ | EV_WRITE</code> to receive the given events.</p> 845<code>EV_READ | EV_WRITE</code> to receive the given events.</p>
785 </dd> 846 </dd>
847 <dt>int fd [read-only]</dt>
848 <dd>
849 <p>The file descriptor being watched.</p>
850 </dd>
851 <dt>int events [read-only]</dt>
852 <dd>
853 <p>The events being watched.</p>
854 </dd>
786</dl> 855</dl>
787<p>Example: call <code>stdin_readable_cb</code> when STDIN_FILENO has become, well 856<p>Example: call <code>stdin_readable_cb</code> when STDIN_FILENO has become, well
788readable, but only once. Since it is likely line-buffered, you could 857readable, but only once. Since it is likely line-buffered, you could
789attempt to read a whole line in the callback:</p> 858attempt to read a whole line in the callback:</p>
790<pre> static void 859<pre> static void
… …
847repeating. The exact semantics are:</p> 916repeating. The exact semantics are:</p>
848 <p>If the timer is started but nonrepeating, stop it.</p> 917 <p>If the timer is started but nonrepeating, stop it.</p>
849 <p>If the timer is repeating, either start it if necessary (with the repeat 918 <p>If the timer is repeating, either start it if necessary (with the repeat
850value), or reset the running timer to the repeat value.</p> 919value), or reset the running timer to the repeat value.</p>
851 <p>This sounds a bit complicated, but here is a useful and typical 920 <p>This sounds a bit complicated, but here is a useful and typical
852example: Imagine you have a tcp connection and you want a so-called idle 921example: Imagine you have a tcp connection and you want a so-called
853timeout, that is, you want to be called when there have been, say, 60 922idle timeout, that is, you want to be called when there have been,
854seconds of inactivity on the socket. The easiest way to do this is to 923say, 60 seconds of inactivity on the socket. The easiest way to do
855configure an <code>ev_timer</code> with after=repeat=60 and calling ev_timer_again each 924this is to configure an <code>ev_timer</code> with <code>after</code>=<code>repeat</code>=<code>60</code> and calling
856time you successfully read or write some data. If you go into an idle 925<code>ev_timer_again</code> each time you successfully read or write some data. If
857state where you do not expect data to travel on the socket, you can stop 926you go into an idle state where you do not expect data to travel on the
858the timer, and again will automatically restart it if need be.</p> 927socket, you can stop the timer, and again will automatically restart it if
928need be.</p>
929 <p>You can also ignore the <code>after</code> value and <code>ev_timer_start</code> altogether
930and only ever use the <code>repeat</code> value:</p>
931<pre> ev_timer_init (timer, callback, 0., 5.);
932 ev_timer_again (loop, timer);
933 ...
934 timer-&gt;again = 17.;
935 ev_timer_again (loop, timer);
936 ...
937 timer-&gt;again = 10.;
938 ev_timer_again (loop, timer);
939
940</pre>
941 <p>This is more efficient then stopping/starting the timer eahc time you want
942to modify its timeout value.</p>
943 </dd>
944 <dt>ev_tstamp repeat [read-write]</dt>
945 <dd>
946 <p>The current <code>repeat</code> value. Will be used each time the watcher times out
947or <code>ev_timer_again</code> is called and determines the next timeout (if any),
948which is also when any modifications are taken into account.</p>
859 </dd> 949 </dd>
860</dl> 950</dl>
861<p>Example: create a timer that fires after 60 seconds.</p> 951<p>Example: create a timer that fires after 60 seconds.</p>
862<pre> static void 952<pre> static void
863 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 953 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
… …
981 <p>Simply stops and restarts the periodic watcher again. This is only useful 1071 <p>Simply stops and restarts the periodic watcher again. This is only useful
982when you changed some parameters or the reschedule callback would return 1072when you changed some parameters or the reschedule callback would return
983a different time than the last time it was called (e.g. in a crond like 1073a different time than the last time it was called (e.g. in a crond like
984program when the crontabs have changed).</p> 1074program when the crontabs have changed).</p>
985 </dd> 1075 </dd>
1076 <dt>ev_tstamp interval [read-write]</dt>
1077 <dd>
1078 <p>The current interval value. Can be modified any time, but changes only
1079take effect when the periodic timer fires or <code>ev_periodic_again</code> is being
1080called.</p>
1081 </dd>
1082 <dt>ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]</dt>
1083 <dd>
1084 <p>The current reschedule callback, or <code>0</code>, if this functionality is
1085switched off. Can be changed any time, but changes only take effect when
1086the periodic timer fires or <code>ev_periodic_again</code> is being called.</p>
1087 </dd>
986</dl> 1088</dl>
987<p>Example: call a callback every hour, or, more precisely, whenever the 1089<p>Example: call a callback every hour, or, more precisely, whenever the
988system clock is divisible by 3600. The callback invocation times have 1090system clock is divisible by 3600. The callback invocation times have
989potentially a lot of jittering, but good long-term stability.</p> 1091potentially a lot of jittering, but good long-term stability.</p>
990<pre> static void 1092<pre> static void
… …
1039 <dt>ev_signal_set (ev_signal *, int signum)</dt> 1141 <dt>ev_signal_set (ev_signal *, int signum)</dt>
1040 <dd> 1142 <dd>
1041 <p>Configures the watcher to trigger on the given signal number (usually one 1143 <p>Configures the watcher to trigger on the given signal number (usually one
1042of the <code>SIGxxx</code> constants).</p> 1144of the <code>SIGxxx</code> constants).</p>
1043 </dd> 1145 </dd>
1146 <dt>int signum [read-only]</dt>
1147 <dd>
1148 <p>The signal the watcher watches out for.</p>
1149 </dd>
1044</dl> 1150</dl>
1045 1151
1046 1152
1047 1153
1048 1154
… …
1061at the <code>rstatus</code> member of the <code>ev_child</code> watcher structure to see 1167at the <code>rstatus</code> member of the <code>ev_child</code> watcher structure to see
1062the status word (use the macros from <code>sys/wait.h</code> and see your systems 1168the status word (use the macros from <code>sys/wait.h</code> and see your systems
1063<code>waitpid</code> documentation). The <code>rpid</code> member contains the pid of the 1169<code>waitpid</code> documentation). The <code>rpid</code> member contains the pid of the
1064process causing the status change.</p> 1170process causing the status change.</p>
1065 </dd> 1171 </dd>
1172 <dt>int pid [read-only]</dt>
1173 <dd>
1174 <p>The process id this watcher watches out for, or <code>0</code>, meaning any process id.</p>
1175 </dd>
1176 <dt>int rpid [read-write]</dt>
1177 <dd>
1178 <p>The process id that detected a status change.</p>
1179 </dd>
1180 <dt>int rstatus [read-write]</dt>
1181 <dd>
1182 <p>The process exit/trace status caused by <code>rpid</code> (see your systems
1183<code>waitpid</code> and <code>sys/wait.h</code> documentation for details).</p>
1184 </dd>
1066</dl> 1185</dl>
1067<p>Example: try to exit cleanly on SIGINT and SIGTERM.</p> 1186<p>Example: try to exit cleanly on SIGINT and SIGTERM.</p>
1068<pre> static void 1187<pre> static void
1069 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1188 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1070 { 1189 {
… …
1072 } 1191 }
1073 1192
1074 struct ev_signal signal_watcher; 1193 struct ev_signal signal_watcher;
1075 ev_signal_init (&amp;signal_watcher, sigint_cb, SIGINT); 1194 ev_signal_init (&amp;signal_watcher, sigint_cb, SIGINT);
1076 ev_signal_start (loop, &amp;sigint_cb); 1195 ev_signal_start (loop, &amp;sigint_cb);
1196
1197
1198
1199
1200</pre>
1201
1202</div>
1203<h2 id="code_ev_stat_code_did_the_file_attri"><code>ev_stat</code> - did the file attributes just change?</h2>
1204<div id="code_ev_stat_code_did_the_file_attri-2">
1205<p>This watches a filesystem path for attribute changes. That is, it calls
1206<code>stat</code> regularly (or when the OS says it changed) and sees if it changed
1207compared to the last time, invoking the callback if it did.</p>
1208<p>The path does not need to exist: changing from &quot;path exists&quot; to &quot;path does
1209not exist&quot; is a status change like any other. The condition &quot;path does
1210not exist&quot; is signified by the <code>st_nlink</code> field being zero (which is
1211otherwise always forced to be at least one) and all the other fields of
1212the stat buffer having unspecified contents.</p>
1213<p>Since there is no standard to do this, the portable implementation simply
1214calls <code>stat (2)</code> regulalry on the path to see if it changed somehow. You
1215can specify a recommended polling interval for this case. If you specify
1216a polling interval of <code>0</code> (highly recommended!) then a <i>suitable,
1217unspecified default</i> value will be used (which you can expect to be around
1218five seconds, although this might change dynamically). Libev will also
1219impose a minimum interval which is currently around <code>0.1</code>, but thats
1220usually overkill.</p>
1221<p>This watcher type is not meant for massive numbers of stat watchers,
1222as even with OS-supported change notifications, this can be
1223resource-intensive.</p>
1224<p>At the time of this writing, no specific OS backends are implemented, but
1225if demand increases, at least a kqueue and inotify backend will be added.</p>
1226<dl>
1227 <dt>ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)</dt>
1228 <dt>ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)</dt>
1229 <dd>
1230 <p>Configures the watcher to wait for status changes of the given
1231<code>path</code>. The <code>interval</code> is a hint on how quickly a change is expected to
1232be detected and should normally be specified as <code>0</code> to let libev choose
1233a suitable value. The memory pointed to by <code>path</code> must point to the same
1234path for as long as the watcher is active.</p>
1235 <p>The callback will be receive <code>EV_STAT</code> when a change was detected,
1236relative to the attributes at the time the watcher was started (or the
1237last change was detected).</p>
1238 </dd>
1239 <dt>ev_stat_stat (ev_stat *)</dt>
1240 <dd>
1241 <p>Updates the stat buffer immediately with new values. If you change the
1242watched path in your callback, you could call this fucntion to avoid
1243detecting this change (while introducing a race condition). Can also be
1244useful simply to find out the new values.</p>
1245 </dd>
1246 <dt>ev_statdata attr [read-only]</dt>
1247 <dd>
1248 <p>The most-recently detected attributes of the file. Although the type is of
1249<code>ev_statdata</code>, this is usually the (or one of the) <code>struct stat</code> types
1250suitable for your system. If the <code>st_nlink</code> member is <code>0</code>, then there
1251was some error while <code>stat</code>ing the file.</p>
1252 </dd>
1253 <dt>ev_statdata prev [read-only]</dt>
1254 <dd>
1255 <p>The previous attributes of the file. The callback gets invoked whenever
1256<code>prev</code> != <code>attr</code>.</p>
1257 </dd>
1258 <dt>ev_tstamp interval [read-only]</dt>
1259 <dd>
1260 <p>The specified interval.</p>
1261 </dd>
1262 <dt>const char *path [read-only]</dt>
1263 <dd>
1264 <p>The filesystem path that is being watched.</p>
1265 </dd>
1266</dl>
1267<p>Example: Watch <code>/etc/passwd</code> for attribute changes.</p>
1268<pre> static void
1269 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1270 {
1271 /* /etc/passwd changed in some way */
1272 if (w-&gt;attr.st_nlink)
1273 {
1274 printf (&quot;passwd current size %ld\n&quot;, (long)w-&gt;attr.st_size);
1275 printf (&quot;passwd current atime %ld\n&quot;, (long)w-&gt;attr.st_mtime);
1276 printf (&quot;passwd current mtime %ld\n&quot;, (long)w-&gt;attr.st_mtime);
1277 }
1278 else
1279 /* you shalt not abuse printf for puts */
1280 puts (&quot;wow, /etc/passwd is not there, expect problems. &quot;
1281 &quot;if this is windows, they already arrived\n&quot;);
1282 }
1283
1284 ...
1285 ev_stat passwd;
1286
1287 ev_stat_init (&amp;passwd, passwd_cb, &quot;/etc/passwd&quot;);
1288 ev_stat_start (loop, &amp;passwd);
1077 1289
1078 1290
1079 1291
1080 1292
1081</pre> 1293</pre>
… …
1303 <dt>ev_embed_sweep (loop, ev_embed *)</dt> 1515 <dt>ev_embed_sweep (loop, ev_embed *)</dt>
1304 <dd> 1516 <dd>
1305 <p>Make a single, non-blocking sweep over the embedded loop. This works 1517 <p>Make a single, non-blocking sweep over the embedded loop. This works
1306similarly to <code>ev_loop (embedded_loop, EVLOOP_NONBLOCK)</code>, but in the most 1518similarly to <code>ev_loop (embedded_loop, EVLOOP_NONBLOCK)</code>, but in the most
1307apropriate way for embedded loops.</p> 1519apropriate way for embedded loops.</p>
1520 </dd>
1521 <dt>struct ev_loop *loop [read-only]</dt>
1522 <dd>
1523 <p>The embedded event loop.</p>
1524 </dd>
1525</dl>
1526
1527
1528
1529
1530
1531</div>
1532<h2 id="code_ev_fork_code_the_audacity_to_re"><code>ev_fork</code> - the audacity to resume the event loop after a fork</h2>
1533<div id="code_ev_fork_code_the_audacity_to_re-2">
1534<p>Fork watchers are called when a <code>fork ()</code> was detected (usually because
1535whoever is a good citizen cared to tell libev about it by calling
1536<code>ev_default_fork</code> or <code>ev_loop_fork</code>). The invocation is done before the
1537event loop blocks next and before <code>ev_check</code> watchers are being called,
1538and only in the child after the fork. If whoever good citizen calling
1539<code>ev_default_fork</code> cheats and calls it in the wrong process, the fork
1540handlers will be invoked, too, of course.</p>
1541<dl>
1542 <dt>ev_fork_init (ev_signal *, callback)</dt>
1543 <dd>
1544 <p>Initialises and configures the fork watcher - it has no parameters of any
1545kind. There is a <code>ev_fork_set</code> macro, but using it is utterly pointless,
1546believe me.</p>
1308 </dd> 1547 </dd>
1309</dl> 1548</dl>
1310 1549
1311 1550
1312 1551
… …
1462 </dd> 1701 </dd>
1463 <dt>w-&gt;sweep () <code>ev::embed</code> only</dt> 1702 <dt>w-&gt;sweep () <code>ev::embed</code> only</dt>
1464 <dd> 1703 <dd>
1465 <p>Invokes <code>ev_embed_sweep</code>.</p> 1704 <p>Invokes <code>ev_embed_sweep</code>.</p>
1466 </dd> 1705 </dd>
1706 <dt>w-&gt;update () <code>ev::stat</code> only</dt>
1707 <dd>
1708 <p>Invokes <code>ev_stat_stat</code>.</p>
1709 </dd>
1467 </dl> 1710 </dl>
1468 </p> 1711 </p>
1469 </dd> 1712 </dd>
1470</dl> 1713</dl>
1471<p>Example: Define a class with an IO and idle watcher, start one of them in 1714<p>Example: Define a class with an IO and idle watcher, start one of them in
… …
1482 : io (this, &amp;myclass::io_cb), 1725 : io (this, &amp;myclass::io_cb),
1483 idle (this, &amp;myclass::idle_cb) 1726 idle (this, &amp;myclass::idle_cb)
1484 { 1727 {
1485 io.start (fd, ev::READ); 1728 io.start (fd, ev::READ);
1486 } 1729 }
1730
1731
1732
1733
1734</pre>
1735
1736</div>
1737<h1 id="MACRO_MAGIC">MACRO MAGIC</h1><p><a href="#TOP" class="toplink">Top</a></p>
1738<div id="MACRO_MAGIC_CONTENT">
1739<p>Libev can be compiled with a variety of options, the most fundemantal is
1740<code>EV_MULTIPLICITY</code>. This option determines wether (most) functions and
1741callbacks have an initial <code>struct ev_loop *</code> argument.</p>
1742<p>To make it easier to write programs that cope with either variant, the
1743following macros are defined:</p>
1744<dl>
1745 <dt><code>EV_A</code>, <code>EV_A_</code></dt>
1746 <dd>
1747 <p>This provides the loop <i>argument</i> for functions, if one is required (&quot;ev
1748loop argument&quot;). The <code>EV_A</code> form is used when this is the sole argument,
1749<code>EV_A_</code> is used when other arguments are following. Example:</p>
1750<pre> ev_unref (EV_A);
1751 ev_timer_add (EV_A_ watcher);
1752 ev_loop (EV_A_ 0);
1753
1754</pre>
1755 <p>It assumes the variable <code>loop</code> of type <code>struct ev_loop *</code> is in scope,
1756which is often provided by the following macro.</p>
1757 </dd>
1758 <dt><code>EV_P</code>, <code>EV_P_</code></dt>
1759 <dd>
1760 <p>This provides the loop <i>parameter</i> for functions, if one is required (&quot;ev
1761loop parameter&quot;). The <code>EV_P</code> form is used when this is the sole parameter,
1762<code>EV_P_</code> is used when other parameters are following. Example:</p>
1763<pre> // this is how ev_unref is being declared
1764 static void ev_unref (EV_P);
1765
1766 // this is how you can declare your typical callback
1767 static void cb (EV_P_ ev_timer *w, int revents)
1768
1769</pre>
1770 <p>It declares a parameter <code>loop</code> of type <code>struct ev_loop *</code>, quite
1771suitable for use with <code>EV_A</code>.</p>
1772 </dd>
1773 <dt><code>EV_DEFAULT</code>, <code>EV_DEFAULT_</code></dt>
1774 <dd>
1775 <p>Similar to the other two macros, this gives you the value of the default
1776loop, if multiple loops are supported (&quot;ev loop default&quot;).</p>
1777 </dd>
1778</dl>
1779<p>Example: Declare and initialise a check watcher, working regardless of
1780wether multiple loops are supported or not.</p>
1781<pre> static void
1782 check_cb (EV_P_ ev_timer *w, int revents)
1783 {
1784 ev_check_stop (EV_A_ w);
1785 }
1786
1787 ev_check check;
1788 ev_check_init (&amp;check, check_cb);
1789 ev_check_start (EV_DEFAULT_ &amp;check);
1790 ev_loop (EV_DEFAULT_ 0);
1791
1792
1793
1487 1794
1488</pre> 1795</pre>
1489 1796
1490</div> 1797</div>
1491<h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p> 1798<h1 id="EMBEDDING">EMBEDDING</h1><p><a href="#TOP" class="toplink">Top</a></p>
… …
1702will have the <code>struct ev_loop *</code> as first argument, and you can create 2009will have the <code>struct ev_loop *</code> as first argument, and you can create
1703additional independent event loops. Otherwise there will be no support 2010additional independent event loops. Otherwise there will be no support
1704for multiple event loops and there is no first event loop pointer 2011for multiple event loops and there is no first event loop pointer
1705argument. Instead, all functions act on the single default loop.</p> 2012argument. Instead, all functions act on the single default loop.</p>
1706 </dd> 2013 </dd>
1707 <dt>EV_PERIODICS</dt> 2014 <dt>EV_PERIODIC_ENABLE</dt>
1708 <dd> 2015 <dd>
1709 <p>If undefined or defined to be <code>1</code>, then periodic timers are supported, 2016 <p>If undefined or defined to be <code>1</code>, then periodic timers are supported. If
1710otherwise not. This saves a few kb of code.</p> 2017defined to be <code>0</code>, then they are not. Disabling them saves a few kB of
2018code.</p>
2019 </dd>
2020 <dt>EV_EMBED_ENABLE</dt>
2021 <dd>
2022 <p>If undefined or defined to be <code>1</code>, then embed watchers are supported. If
2023defined to be <code>0</code>, then they are not.</p>
2024 </dd>
2025 <dt>EV_STAT_ENABLE</dt>
2026 <dd>
2027 <p>If undefined or defined to be <code>1</code>, then stat watchers are supported. If
2028defined to be <code>0</code>, then they are not.</p>
2029 </dd>
2030 <dt>EV_FORK_ENABLE</dt>
2031 <dd>
2032 <p>If undefined or defined to be <code>1</code>, then fork watchers are supported. If
2033defined to be <code>0</code>, then they are not.</p>
2034 </dd>
2035 <dt>EV_MINIMAL</dt>
2036 <dd>
2037 <p>If you need to shave off some kilobytes of code at the expense of some
2038speed, define this symbol to <code>1</code>. Currently only used for gcc to override
2039some inlining decisions, saves roughly 30% codesize of amd64.</p>
2040 </dd>
2041 <dt>EV_PID_HASHSIZE</dt>
2042 <dd>
2043 <p><code>ev_child</code> watchers use a small hash table to distribute workload by
2044pid. The default size is <code>16</code> (or <code>1</code> with <code>EV_MINIMAL</code>), usually more
2045than enough. If you need to manage thousands of children you might want to
2046increase this value.</p>
1711 </dd> 2047 </dd>
1712 <dt>EV_COMMON</dt> 2048 <dt>EV_COMMON</dt>
1713 <dd> 2049 <dd>
1714 <p>By default, all watchers have a <code>void *data</code> member. By redefining 2050 <p>By default, all watchers have a <code>void *data</code> member. By redefining
1715this macro to a something else you can include more and other types of 2051this macro to a something else you can include more and other types of

Diff Legend

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