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.48 by root, Tue Nov 27 08:11:52 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 09:11:42 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>
39</ul> 40</ul>
40</li> 41</li>
… …
586 </dd> 587 </dd>
587 <dt><code>EV_CHILD</code></dt> 588 <dt><code>EV_CHILD</code></dt>
588 <dd> 589 <dd>
589 <p>The pid specified in the <code>ev_child</code> watcher has received a status change.</p> 590 <p>The pid specified in the <code>ev_child</code> watcher has received a status change.</p>
590 </dd> 591 </dd>
592 <dt><code>EV_STAT</code></dt>
593 <dd>
594 <p>The path specified in the <code>ev_stat</code> watcher changed its attributes somehow.</p>
595 </dd>
591 <dt><code>EV_IDLE</code></dt> 596 <dt><code>EV_IDLE</code></dt>
592 <dd> 597 <dd>
593 <p>The <code>ev_idle</code> watcher has determined that you have nothing better to do.</p> 598 <p>The <code>ev_idle</code> watcher has determined that you have nothing better to do.</p>
594 </dd> 599 </dd>
595 <dt><code>EV_PREPARE</code></dt> 600 <dt><code>EV_PREPARE</code></dt>
… …
732 737
733</div> 738</div>
734<h1 id="WATCHER_TYPES">WATCHER TYPES</h1><p><a href="#TOP" class="toplink">Top</a></p> 739<h1 id="WATCHER_TYPES">WATCHER TYPES</h1><p><a href="#TOP" class="toplink">Top</a></p>
735<div id="WATCHER_TYPES_CONTENT"> 740<div id="WATCHER_TYPES_CONTENT">
736<p>This section describes each watcher in detail, but will not repeat 741<p>This section describes each watcher in detail, but will not repeat
737information given in the last section.</p> 742information given in the last section. Any initialisation/set macros,
743functions and members specific to the watcher type are explained.</p>
744<p>Members are additionally marked with either <i>[read-only]</i>, meaning that,
745while the watcher is active, you can look at the member and expect some
746sensible content, but you must not modify it (you can modify it while the
747watcher is stopped to your hearts content), or <i>[read-write]</i>, which
748means you can expect it to have some sensible content while the watcher
749is active, but you can also modify it. Modifying it may not do something
750sensible or take immediate effect (or do anything at all), but libev will
751not crash or malfunction in any way.</p>
738 752
739 753
740 754
741 755
742 756
… …
781 <dd> 795 <dd>
782 <p>Configures an <code>ev_io</code> watcher. The <code>fd</code> is the file descriptor to 796 <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 797rceeive 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> 798<code>EV_READ | EV_WRITE</code> to receive the given events.</p>
785 </dd> 799 </dd>
800 <dt>int fd [read-only]</dt>
801 <dd>
802 <p>The file descriptor being watched.</p>
803 </dd>
804 <dt>int events [read-only]</dt>
805 <dd>
806 <p>The events being watched.</p>
807 </dd>
786</dl> 808</dl>
787<p>Example: call <code>stdin_readable_cb</code> when STDIN_FILENO has become, well 809<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 810readable, but only once. Since it is likely line-buffered, you could
789attempt to read a whole line in the callback:</p> 811attempt to read a whole line in the callback:</p>
790<pre> static void 812<pre> static void
… …
847repeating. The exact semantics are:</p> 869repeating. The exact semantics are:</p>
848 <p>If the timer is started but nonrepeating, stop it.</p> 870 <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 871 <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> 872value), or reset the running timer to the repeat value.</p>
851 <p>This sounds a bit complicated, but here is a useful and typical 873 <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 874example: 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 875idle 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 876say, 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 877this 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 878<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 879you 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> 880socket, you can stop the timer, and again will automatically restart it if
881need be.</p>
882 <p>You can also ignore the <code>after</code> value and <code>ev_timer_start</code> altogether
883and only ever use the <code>repeat</code> value:</p>
884<pre> ev_timer_init (timer, callback, 0., 5.);
885 ev_timer_again (loop, timer);
886 ...
887 timer-&gt;again = 17.;
888 ev_timer_again (loop, timer);
889 ...
890 timer-&gt;again = 10.;
891 ev_timer_again (loop, timer);
892
893</pre>
894 <p>This is more efficient then stopping/starting the timer eahc time you want
895to modify its timeout value.</p>
896 </dd>
897 <dt>ev_tstamp repeat [read-write]</dt>
898 <dd>
899 <p>The current <code>repeat</code> value. Will be used each time the watcher times out
900or <code>ev_timer_again</code> is called and determines the next timeout (if any),
901which is also when any modifications are taken into account.</p>
859 </dd> 902 </dd>
860</dl> 903</dl>
861<p>Example: create a timer that fires after 60 seconds.</p> 904<p>Example: create a timer that fires after 60 seconds.</p>
862<pre> static void 905<pre> static void
863 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents) 906 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 1024 <p>Simply stops and restarts the periodic watcher again. This is only useful
982when you changed some parameters or the reschedule callback would return 1025when 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 1026a different time than the last time it was called (e.g. in a crond like
984program when the crontabs have changed).</p> 1027program when the crontabs have changed).</p>
985 </dd> 1028 </dd>
1029 <dt>ev_tstamp interval [read-write]</dt>
1030 <dd>
1031 <p>The current interval value. Can be modified any time, but changes only
1032take effect when the periodic timer fires or <code>ev_periodic_again</code> is being
1033called.</p>
1034 </dd>
1035 <dt>ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]</dt>
1036 <dd>
1037 <p>The current reschedule callback, or <code>0</code>, if this functionality is
1038switched off. Can be changed any time, but changes only take effect when
1039the periodic timer fires or <code>ev_periodic_again</code> is being called.</p>
1040 </dd>
986</dl> 1041</dl>
987<p>Example: call a callback every hour, or, more precisely, whenever the 1042<p>Example: call a callback every hour, or, more precisely, whenever the
988system clock is divisible by 3600. The callback invocation times have 1043system clock is divisible by 3600. The callback invocation times have
989potentially a lot of jittering, but good long-term stability.</p> 1044potentially a lot of jittering, but good long-term stability.</p>
990<pre> static void 1045<pre> static void
… …
1039 <dt>ev_signal_set (ev_signal *, int signum)</dt> 1094 <dt>ev_signal_set (ev_signal *, int signum)</dt>
1040 <dd> 1095 <dd>
1041 <p>Configures the watcher to trigger on the given signal number (usually one 1096 <p>Configures the watcher to trigger on the given signal number (usually one
1042of the <code>SIGxxx</code> constants).</p> 1097of the <code>SIGxxx</code> constants).</p>
1043 </dd> 1098 </dd>
1099 <dt>int signum [read-only]</dt>
1100 <dd>
1101 <p>The signal the watcher watches out for.</p>
1102 </dd>
1044</dl> 1103</dl>
1045 1104
1046 1105
1047 1106
1048 1107
… …
1061at the <code>rstatus</code> member of the <code>ev_child</code> watcher structure to see 1120at 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 1121the 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 1122<code>waitpid</code> documentation). The <code>rpid</code> member contains the pid of the
1064process causing the status change.</p> 1123process causing the status change.</p>
1065 </dd> 1124 </dd>
1125 <dt>int pid [read-only]</dt>
1126 <dd>
1127 <p>The process id this watcher watches out for, or <code>0</code>, meaning any process id.</p>
1128 </dd>
1129 <dt>int rpid [read-write]</dt>
1130 <dd>
1131 <p>The process id that detected a status change.</p>
1132 </dd>
1133 <dt>int rstatus [read-write]</dt>
1134 <dd>
1135 <p>The process exit/trace status caused by <code>rpid</code> (see your systems
1136<code>waitpid</code> and <code>sys/wait.h</code> documentation for details).</p>
1137 </dd>
1066</dl> 1138</dl>
1067<p>Example: try to exit cleanly on SIGINT and SIGTERM.</p> 1139<p>Example: try to exit cleanly on SIGINT and SIGTERM.</p>
1068<pre> static void 1140<pre> static void
1069 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) 1141 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1070 { 1142 {
… …
1072 } 1144 }
1073 1145
1074 struct ev_signal signal_watcher; 1146 struct ev_signal signal_watcher;
1075 ev_signal_init (&amp;signal_watcher, sigint_cb, SIGINT); 1147 ev_signal_init (&amp;signal_watcher, sigint_cb, SIGINT);
1076 ev_signal_start (loop, &amp;sigint_cb); 1148 ev_signal_start (loop, &amp;sigint_cb);
1149
1150
1151
1152
1153</pre>
1154
1155</div>
1156<h2 id="code_ev_stat_code_did_the_file_attri"><code>ev_stat</code> - did the file attributes just change?</h2>
1157<div id="code_ev_stat_code_did_the_file_attri-2">
1158<p>This watches a filesystem path for attribute changes. That is, it calls
1159<code>stat</code> regularly (or when the OS says it changed) and sees if it changed
1160compared to the last time, invoking the callback if it did.</p>
1161<p>The path does not need to exist: changing from &quot;path exists&quot; to &quot;path does
1162not exist&quot; is a status change like any other. The condition &quot;path does
1163not exist&quot; is signified by the <code>st_nlink</code> field being zero (which is
1164otherwise always forced to be at least one) and all the other fields of
1165the stat buffer having unspecified contents.</p>
1166<p>Since there is no standard to do this, the portable implementation simply
1167calls <code>stat (2)</code> regulalry on the path to see if it changed somehow. You
1168can specify a recommended polling interval for this case. If you specify
1169a polling interval of <code>0</code> (highly recommended!) then a <i>suitable,
1170unspecified default</i> value will be used (which you can expect to be around
1171five seconds, although this might change dynamically). Libev will also
1172impose a minimum interval which is currently around <code>0.1</code>, but thats
1173usually overkill.</p>
1174<p>This watcher type is not meant for massive numbers of stat watchers,
1175as even with OS-supported change notifications, this can be
1176resource-intensive.</p>
1177<p>At the time of this writing, no specific OS backends are implemented, but
1178if demand increases, at least a kqueue and inotify backend will be added.</p>
1179<dl>
1180 <dt>ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)</dt>
1181 <dt>ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)</dt>
1182 <dd>
1183 <p>Configures the watcher to wait for status changes of the given
1184<code>path</code>. The <code>interval</code> is a hint on how quickly a change is expected to
1185be detected and should normally be specified as <code>0</code> to let libev choose
1186a suitable value. The memory pointed to by <code>path</code> must point to the same
1187path for as long as the watcher is active.</p>
1188 <p>The callback will be receive <code>EV_STAT</code> when a change was detected,
1189relative to the attributes at the time the watcher was started (or the
1190last change was detected).</p>
1191 </dd>
1192 <dt>ev_stat_stat (ev_stat *)</dt>
1193 <dd>
1194 <p>Updates the stat buffer immediately with new values. If you change the
1195watched path in your callback, you could call this fucntion to avoid
1196detecting this change (while introducing a race condition). Can also be
1197useful simply to find out the new values.</p>
1198 </dd>
1199 <dt>ev_statdata attr [read-only]</dt>
1200 <dd>
1201 <p>The most-recently detected attributes of the file. Although the type is of
1202<code>ev_statdata</code>, this is usually the (or one of the) <code>struct stat</code> types
1203suitable for your system. If the <code>st_nlink</code> member is <code>0</code>, then there
1204was some error while <code>stat</code>ing the file.</p>
1205 </dd>
1206 <dt>ev_statdata prev [read-only]</dt>
1207 <dd>
1208 <p>The previous attributes of the file. The callback gets invoked whenever
1209<code>prev</code> != <code>attr</code>.</p>
1210 </dd>
1211 <dt>ev_tstamp interval [read-only]</dt>
1212 <dd>
1213 <p>The specified interval.</p>
1214 </dd>
1215 <dt>const char *path [read-only]</dt>
1216 <dd>
1217 <p>The filesystem path that is being watched.</p>
1218 </dd>
1219</dl>
1220<p>Example: Watch <code>/etc/passwd</code> for attribute changes.</p>
1221<pre> static void
1222 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
1223 {
1224 /* /etc/passwd changed in some way */
1225 if (w-&gt;attr.st_nlink)
1226 {
1227 printf (&quot;passwd current size %ld\n&quot;, (long)w-&gt;attr.st_size);
1228 printf (&quot;passwd current atime %ld\n&quot;, (long)w-&gt;attr.st_mtime);
1229 printf (&quot;passwd current mtime %ld\n&quot;, (long)w-&gt;attr.st_mtime);
1230 }
1231 else
1232 /* you shalt not abuse printf for puts */
1233 puts (&quot;wow, /etc/passwd is not there, expect problems. &quot;
1234 &quot;if this is windows, they already arrived\n&quot;);
1235 }
1236
1237 ...
1238 ev_stat passwd;
1239
1240 ev_stat_init (&amp;passwd, passwd_cb, &quot;/etc/passwd&quot;);
1241 ev_stat_start (loop, &amp;passwd);
1077 1242
1078 1243
1079 1244
1080 1245
1081</pre> 1246</pre>
… …
1303 <dt>ev_embed_sweep (loop, ev_embed *)</dt> 1468 <dt>ev_embed_sweep (loop, ev_embed *)</dt>
1304 <dd> 1469 <dd>
1305 <p>Make a single, non-blocking sweep over the embedded loop. This works 1470 <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 1471similarly to <code>ev_loop (embedded_loop, EVLOOP_NONBLOCK)</code>, but in the most
1307apropriate way for embedded loops.</p> 1472apropriate way for embedded loops.</p>
1473 </dd>
1474 <dt>struct ev_loop *loop [read-only]</dt>
1475 <dd>
1476 <p>The embedded event loop.</p>
1308 </dd> 1477 </dd>
1309</dl> 1478</dl>
1310 1479
1311 1480
1312 1481
… …
1702will have the <code>struct ev_loop *</code> as first argument, and you can create 1871will have the <code>struct ev_loop *</code> as first argument, and you can create
1703additional independent event loops. Otherwise there will be no support 1872additional independent event loops. Otherwise there will be no support
1704for multiple event loops and there is no first event loop pointer 1873for multiple event loops and there is no first event loop pointer
1705argument. Instead, all functions act on the single default loop.</p> 1874argument. Instead, all functions act on the single default loop.</p>
1706 </dd> 1875 </dd>
1707 <dt>EV_PERIODICS</dt> 1876 <dt>EV_PERIODIC_ENABLE</dt>
1708 <dd> 1877 <dd>
1709 <p>If undefined or defined to be <code>1</code>, then periodic timers are supported, 1878 <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> 1879defined to be <code>0</code>, then they are not. Disabling them saves a few kB of
1880code.</p>
1881 </dd>
1882 <dt>EV_EMBED_ENABLE</dt>
1883 <dd>
1884 <p>If undefined or defined to be <code>1</code>, then embed watchers are supported. If
1885defined to be <code>0</code>, then they are not.</p>
1886 </dd>
1887 <dt>EV_STAT_ENABLE</dt>
1888 <dd>
1889 <p>If undefined or defined to be <code>1</code>, then stat watchers are supported. If
1890defined to be <code>0</code>, then they are not.</p>
1891 </dd>
1892 <dt>EV_MINIMAL</dt>
1893 <dd>
1894 <p>If you need to shave off some kilobytes of code at the expense of some
1895speed, define this symbol to <code>1</code>. Currently only used for gcc to override
1896some inlining decisions, saves roughly 30% codesize of amd64.</p>
1711 </dd> 1897 </dd>
1712 <dt>EV_COMMON</dt> 1898 <dt>EV_COMMON</dt>
1713 <dd> 1899 <dd>
1714 <p>By default, all watchers have a <code>void *data</code> member. By redefining 1900 <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 1901this macro to a something else you can include more and other types of

Diff Legend

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