[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.47 by root, Mon Nov 26 19:49:36 2007 UTC vs.
Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC

…		…
545		545
546	=item C<EV_CHILD>	546	=item C<EV_CHILD>
547		547
548	The pid specified in the C<ev_child> watcher has received a status change.	548	The pid specified in the C<ev_child> watcher has received a status change.
549		549
		550	=item C<EV_STAT>
		551
		552	The path specified in the C<ev_stat> watcher changed its attributes somehow.
		553
550	=item C<EV_IDLE>	554	=item C<EV_IDLE>
551		555
552	The C<ev_idle> watcher has determined that you have nothing better to do.	556	The C<ev_idle> watcher has determined that you have nothing better to do.
553		557
554	=item C<EV_PREPARE>	558	=item C<EV_PREPARE>
…		…
689		693
690		694
691	=head1 WATCHER TYPES	695	=head1 WATCHER TYPES
692		696
693	This section describes each watcher in detail, but will not repeat	697	This section describes each watcher in detail, but will not repeat
694	information given in the last section.	698	information given in the last section. Any initialisation/set macros,
		699	functions and members specific to the watcher type are explained.
		700
		701	Members are additionally marked with either I<[read-only]>, meaning that,
		702	while the watcher is active, you can look at the member and expect some
		703	sensible content, but you must not modify it (you can modify it while the
		704	watcher is stopped to your hearts content), or I<[read-write]>, which
		705	means you can expect it to have some sensible content while the watcher
		706	is active, but you can also modify it. Modifying it may not do something
		707	sensible or take immediate effect (or do anything at all), but libev will
		708	not crash or malfunction in any way.
695		709
696		710
697	=head2 C<ev_io> - is this file descriptor readable or writable?	711	=head2 C<ev_io> - is this file descriptor readable or writable?
698		712
699	I/O watchers check whether a file descriptor is readable or writable	713	I/O watchers check whether a file descriptor is readable or writable
…		…
742		756
743	Configures an C<ev_io> watcher. The C<fd> is the file descriptor to	757	Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
744	rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or	758	rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or
745	C<EV_READ \| EV_WRITE> to receive the given events.	759	C<EV_READ \| EV_WRITE> to receive the given events.
746		760
		761	=item int fd [read-only]
		762
		763	The file descriptor being watched.
		764
		765	=item int events [read-only]
		766
		767	The events being watched.
		768
747	=back	769	=back
748		770
749	Example: call C<stdin_readable_cb> when STDIN_FILENO has become, well	771	Example: call C<stdin_readable_cb> when STDIN_FILENO has become, well
750	readable, but only once. Since it is likely line-buffered, you could	772	readable, but only once. Since it is likely line-buffered, you could
751	attempt to read a whole line in the callback:	773	attempt to read a whole line in the callback:
…		…
814		836
815	If the timer is repeating, either start it if necessary (with the repeat	837	If the timer is repeating, either start it if necessary (with the repeat
816	value), or reset the running timer to the repeat value.	838	value), or reset the running timer to the repeat value.
817		839
818	This sounds a bit complicated, but here is a useful and typical	840	This sounds a bit complicated, but here is a useful and typical
819	example: Imagine you have a tcp connection and you want a so-called idle	841	example: Imagine you have a tcp connection and you want a so-called
820	timeout, that is, you want to be called when there have been, say, 60	842	idle timeout, that is, you want to be called when there have been,
821	seconds of inactivity on the socket. The easiest way to do this is to	843	say, 60 seconds of inactivity on the socket. The easiest way to do
822	configure an C<ev_timer> with after=repeat=60 and calling ev_timer_again each	844	this is to configure an C<ev_timer> with C<after>=C<repeat>=C<60> and calling
823	time you successfully read or write some data. If you go into an idle	845	C<ev_timer_again> each time you successfully read or write some data. If
824	state where you do not expect data to travel on the socket, you can stop	846	you go into an idle state where you do not expect data to travel on the
825	the timer, and again will automatically restart it if need be.	847	socket, you can stop the timer, and again will automatically restart it if
		848	need be.
		849
		850	You can also ignore the C<after> value and C<ev_timer_start> altogether
		851	and only ever use the C<repeat> value:
		852
		853	ev_timer_init (timer, callback, 0., 5.);
		854	ev_timer_again (loop, timer);
		855	...
		856	timer->again = 17.;
		857	ev_timer_again (loop, timer);
		858	...
		859	timer->again = 10.;
		860	ev_timer_again (loop, timer);
		861
		862	This is more efficient then stopping/starting the timer eahc time you want
		863	to modify its timeout value.
		864
		865	=item ev_tstamp repeat [read-write]
		866
		867	The current C<repeat> value. Will be used each time the watcher times out
		868	or C<ev_timer_again> is called and determines the next timeout (if any),
		869	which is also when any modifications are taken into account.
826		870
827	=back	871	=back
828		872
829	Example: create a timer that fires after 60 seconds.	873	Example: create a timer that fires after 60 seconds.
830		874
…		…
957	Simply stops and restarts the periodic watcher again. This is only useful	1001	Simply stops and restarts the periodic watcher again. This is only useful
958	when you changed some parameters or the reschedule callback would return	1002	when you changed some parameters or the reschedule callback would return
959	a different time than the last time it was called (e.g. in a crond like	1003	a different time than the last time it was called (e.g. in a crond like
960	program when the crontabs have changed).	1004	program when the crontabs have changed).
961		1005
		1006	=item ev_tstamp interval [read-write]
		1007
		1008	The current interval value. Can be modified any time, but changes only
		1009	take effect when the periodic timer fires or C<ev_periodic_again> is being
		1010	called.
		1011
		1012	=item ev_tstamp (reschedule_cb)(struct ev_periodic w, ev_tstamp now) [read-write]
		1013
		1014	The current reschedule callback, or C<0>, if this functionality is
		1015	switched off. Can be changed any time, but changes only take effect when
		1016	the periodic timer fires or C<ev_periodic_again> is being called.
		1017
962	=back	1018	=back
963		1019
964	Example: call a callback every hour, or, more precisely, whenever the	1020	Example: call a callback every hour, or, more precisely, whenever the
965	system clock is divisible by 3600. The callback invocation times have	1021	system clock is divisible by 3600. The callback invocation times have
966	potentially a lot of jittering, but good long-term stability.	1022	potentially a lot of jittering, but good long-term stability.
…		…
1016	=item ev_signal_set (ev_signal *, int signum)	1072	=item ev_signal_set (ev_signal *, int signum)
1017		1073
1018	Configures the watcher to trigger on the given signal number (usually one	1074	Configures the watcher to trigger on the given signal number (usually one
1019	of the C<SIGxxx> constants).	1075	of the C<SIGxxx> constants).
1020		1076
		1077	=item int signum [read-only]
		1078
		1079	The signal the watcher watches out for.
		1080
1021	=back	1081	=back
1022		1082
1023		1083
1024	=head2 C<ev_child> - watch out for process status changes	1084	=head2 C<ev_child> - watch out for process status changes
1025		1085
…		…
1037	at the C<rstatus> member of the C<ev_child> watcher structure to see	1097	at the C<rstatus> member of the C<ev_child> watcher structure to see
1038	the status word (use the macros from C<sys/wait.h> and see your systems	1098	the status word (use the macros from C<sys/wait.h> and see your systems
1039	C<waitpid> documentation). The C<rpid> member contains the pid of the	1099	C<waitpid> documentation). The C<rpid> member contains the pid of the
1040	process causing the status change.	1100	process causing the status change.
1041		1101
		1102	=item int pid [read-only]
		1103
		1104	The process id this watcher watches out for, or C<0>, meaning any process id.
		1105
		1106	=item int rpid [read-write]
		1107
		1108	The process id that detected a status change.
		1109
		1110	=item int rstatus [read-write]
		1111
		1112	The process exit/trace status caused by C<rpid> (see your systems
		1113	C<waitpid> and C<sys/wait.h> documentation for details).
		1114
1042	=back	1115	=back
1043		1116
1044	Example: try to exit cleanly on SIGINT and SIGTERM.	1117	Example: try to exit cleanly on SIGINT and SIGTERM.
1045		1118
1046	static void	1119	static void
…		…
1050	}	1123	}
1051		1124
1052	struct ev_signal signal_watcher;	1125	struct ev_signal signal_watcher;
1053	ev_signal_init (&signal_watcher, sigint_cb, SIGINT);	1126	ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1054	ev_signal_start (loop, &sigint_cb);	1127	ev_signal_start (loop, &sigint_cb);
		1128
		1129
		1130	=head2 C<ev_stat> - did the file attributes just change?
		1131
		1132	This watches a filesystem path for attribute changes. That is, it calls
		1133	C<stat> regularly (or when the OS says it changed) and sees if it changed
		1134	compared to the last time, invoking the callback if it did.
		1135
		1136	The path does not need to exist: changing from "path exists" to "path does
		1137	not exist" is a status change like any other. The condition "path does
		1138	not exist" is signified by the C<st_nlink> field being zero (which is
		1139	otherwise always forced to be at least one) and all the other fields of
		1140	the stat buffer having unspecified contents.
		1141
		1142	Since there is no standard to do this, the portable implementation simply
		1143	calls C<stat (2)> regulalry on the path to see if it changed somehow. You
		1144	can specify a recommended polling interval for this case. If you specify
		1145	a polling interval of C<0> (highly recommended!) then a I<suitable,
		1146	unspecified default> value will be used (which you can expect to be around
		1147	five seconds, although this might change dynamically). Libev will also
		1148	impose a minimum interval which is currently around C<0.1>, but thats
		1149	usually overkill.
		1150
		1151	This watcher type is not meant for massive numbers of stat watchers,
		1152	as even with OS-supported change notifications, this can be
		1153	resource-intensive.
		1154
		1155	At the time of this writing, no specific OS backends are implemented, but
		1156	if demand increases, at least a kqueue and inotify backend will be added.
		1157
		1158	=over 4
		1159
		1160	=item ev_stat_init (ev_stat , callback, const char path, ev_tstamp interval)
		1161
		1162	=item ev_stat_set (ev_stat , const char path, ev_tstamp interval)
		1163
		1164	Configures the watcher to wait for status changes of the given
		1165	C<path>. The C<interval> is a hint on how quickly a change is expected to
		1166	be detected and should normally be specified as C<0> to let libev choose
		1167	a suitable value. The memory pointed to by C<path> must point to the same
		1168	path for as long as the watcher is active.
		1169
		1170	The callback will be receive C<EV_STAT> when a change was detected,
		1171	relative to the attributes at the time the watcher was started (or the
		1172	last change was detected).
		1173
		1174	=item ev_stat_stat (ev_stat *)
		1175
		1176	Updates the stat buffer immediately with new values. If you change the
		1177	watched path in your callback, you could call this fucntion to avoid
		1178	detecting this change (while introducing a race condition). Can also be
		1179	useful simply to find out the new values.
		1180
		1181	=item ev_statdata attr [read-only]
		1182
		1183	The most-recently detected attributes of the file. Although the type is of
		1184	C<ev_statdata>, this is usually the (or one of the) C<struct stat> types
		1185	suitable for your system. If the C<st_nlink> member is C<0>, then there
		1186	was some error while C<stat>ing the file.
		1187
		1188	=item ev_statdata prev [read-only]
		1189
		1190	The previous attributes of the file. The callback gets invoked whenever
		1191	C<prev> != C<attr>.
		1192
		1193	=item ev_tstamp interval [read-only]
		1194
		1195	The specified interval.
		1196
		1197	=item const char *path [read-only]
		1198
		1199	The filesystem path that is being watched.
		1200
		1201	=back
		1202
		1203	Example: Watch C</etc/passwd> for attribute changes.
		1204
		1205	static void
		1206	passwd_cb (struct ev_loop loop, ev_stat w, int revents)
		1207	{
		1208	/* /etc/passwd changed in some way */
		1209	if (w->attr.st_nlink)
		1210	{
		1211	printf ("passwd current size %ld\n", (long)w->attr.st_size);
		1212	printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
		1213	printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
		1214	}
		1215	else
		1216	/* you shalt not abuse printf for puts */
		1217	puts ("wow, /etc/passwd is not there, expect problems. "
		1218	"if this is windows, they already arrived\n");
		1219	}
		1220
		1221	...
		1222	ev_stat passwd;
		1223
		1224	ev_stat_init (&passwd, passwd_cb, "/etc/passwd");
		1225	ev_stat_start (loop, &passwd);
1055		1226
1056		1227
1057	=head2 C<ev_idle> - when you've got nothing better to do...	1228	=head2 C<ev_idle> - when you've got nothing better to do...
1058		1229
1059	Idle watchers trigger events when there are no other events are pending	1230	Idle watchers trigger events when there are no other events are pending
…		…
1292		1463
1293	Make a single, non-blocking sweep over the embedded loop. This works	1464	Make a single, non-blocking sweep over the embedded loop. This works
1294	similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most	1465	similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
1295	apropriate way for embedded loops.	1466	apropriate way for embedded loops.
1296		1467
		1468	=item struct ev_loop *loop [read-only]
		1469
		1470	The embedded event loop.
		1471
1297	=back	1472	=back
1298		1473
1299		1474
1300	=head1 OTHER FUNCTIONS	1475	=head1 OTHER FUNCTIONS
1301		1476

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.47 by root, Mon Nov 26 19:49:36 2007 UTC vs. Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.47 by root, Mon Nov 26 19:49:36 2007 UTC vs.
Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC