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

Comparing libev/ev.pod (file contents):
Revision 1.229 by root, Wed Apr 15 17:49:27 2009 UTC vs.
Revision 1.234 by root, Thu Apr 16 07:49:23 2009 UTC

…		…
633	This function is rarely useful, but when some event callback runs for a	633	This function is rarely useful, but when some event callback runs for a
634	very long time without entering the event loop, updating libev's idea of	634	very long time without entering the event loop, updating libev's idea of
635	the current time is a good idea.	635	the current time is a good idea.
636		636
637	See also "The special problem of time updates" in the C<ev_timer> section.	637	See also "The special problem of time updates" in the C<ev_timer> section.
		638
		639	=item ev_suspend (loop)
		640
		641	=item ev_resume (loop)
		642
		643	These two functions suspend and resume a loop, for use when the loop is
		644	not used for a while and timeouts should not be processed.
		645
		646	A typical use case would be an interactive program such as a game: When
		647	the user presses C<^Z> to suspend the game and resumes it an hour later it
		648	would be best to handle timeouts as if no time had actually passed while
		649	the program was suspended. This can be achieved by calling C<ev_suspend>
		650	in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
		651	C<ev_resume> directly afterwards to resume timer processing.
		652
		653	Effectively, all C<ev_timer> watchers will be delayed by the time spend
		654	between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
		655	will be rescheduled (that is, they will lose any events that would have
		656	occured while suspended).
		657
		658	After calling C<ev_suspend> you B<must not> call I<any> function on the
		659	given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
		660	without a previous call to C<ev_suspend>.
		661
		662	Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
		663	event loop time (see C<ev_now_update>).
638		664
639	=item ev_loop (loop, int flags)	665	=item ev_loop (loop, int flags)
640		666
641	Finally, this is it, the event handler. This function usually is called	667	Finally, this is it, the event handler. This function usually is called
642	after you initialised all your watchers and you want to start handling	668	after you initialised all your watchers and you want to start handling
…		…
1057	integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>	1083	integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1058	(default: C<-2>). Pending watchers with higher priority will be invoked	1084	(default: C<-2>). Pending watchers with higher priority will be invoked
1059	before watchers with lower priority, but priority will not keep watchers	1085	before watchers with lower priority, but priority will not keep watchers
1060	from being executed (except for C<ev_idle> watchers).	1086	from being executed (except for C<ev_idle> watchers).
1061		1087
1062	This means that priorities are I<only> used for ordering callback
1063	invocation after new events have been received. This is useful, for
1064	example, to reduce latency after idling, or more often, to bind two
1065	watchers on the same event and make sure one is called first.
1066
1067	If you need to suppress invocation when higher priority events are pending	1088	If you need to suppress invocation when higher priority events are pending
1068	you need to look at C<ev_idle> watchers, which provide this functionality.	1089	you need to look at C<ev_idle> watchers, which provide this functionality.
1069		1090
1070	You I<must not> change the priority of a watcher as long as it is active or	1091	You I<must not> change the priority of a watcher as long as it is active or
1071	pending.	1092	pending.
1072
1073	The default priority used by watchers when no priority has been set is
1074	always C<0>, which is supposed to not be too high and not be too low :).
1075		1093
1076	Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is	1094	Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1077	fine, as long as you do not mind that the priority value you query might	1095	fine, as long as you do not mind that the priority value you query might
1078	or might not have been clamped to the valid range.	1096	or might not have been clamped to the valid range.
		1097
		1098	The default priority used by watchers when no priority has been set is
		1099	always C<0>, which is supposed to not be too high and not be too low :).
		1100
		1101	See L<WATCHER PRIORITIES>, below, for a more thorough treatment of
		1102	priorities.
1079		1103
1080	=item ev_invoke (loop, ev_TYPE *watcher, int revents)	1104	=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1081		1105
1082	Invoke the C<watcher> with the given C<loop> and C<revents>. Neither	1106	Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1083	C<loop> nor C<revents> need to be valid as long as the watcher callback	1107	C<loop> nor C<revents> need to be valid as long as the watcher callback
…		…
1158	t2_cb (EV_P_ ev_timer *w, int revents)	1182	t2_cb (EV_P_ ev_timer *w, int revents)
1159	{	1183	{
1160	struct my_biggy big = (struct my_biggy *	1184	struct my_biggy big = (struct my_biggy *
1161	(((char *)w) - offsetof (struct my_biggy, t2));	1185	(((char *)w) - offsetof (struct my_biggy, t2));
1162	}	1186	}
		1187
		1188	=head2 WATCHER PRIORITY MODELS
		1189
		1190	Many event loops support I<watcher priorities>, which are usually small
		1191	integers that influence the ordering of event callback invocation
		1192	between watchers in some way, all else being equal.
		1193
		1194	In libev, Watcher priorities can be set using C<ev_set_priority>. See its
		1195	description for the more technical details such as the actual priority
		1196	range.
		1197
		1198	There are two common ways how these these priorities are being interpreted
		1199	by event loops:
		1200
		1201	In the more common lock-out model, higher priorities "lock out" invocation
		1202	of lower priority watchers, which means as long as higher priority
		1203	watchers receive events, lower priority watchers are not being invoked.
		1204
		1205	The less common only-for-ordering model uses priorities solely to order
		1206	callback invocation within a single event loop iteration: Higher priority
		1207	watchers are invoked before lower priority ones, but they all get invoked
		1208	before polling for new events.
		1209
		1210	Libev uses the second (only-for-ordering) model for all its watchers
		1211	except for idle watchers (which use the lock-out model).
		1212
		1213	The rationale behind this is that implementing the lock-out model for
		1214	watchers is not well supported by most kernel interfaces, and most event
		1215	libraries will just poll for the same events again and again as long as
		1216	their callbacks have not been executed, which is very inefficient in the
		1217	common case of one high-priority watcher locking out a mass of lower
		1218	priority ones.
		1219
		1220	Static (ordering) priorities are most useful when you have two or more
		1221	watchers handling the same resource: a typical usage example is having an
		1222	C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
		1223	timeouts. Under load, data might be received while the program handles
		1224	other jobs, but since timers normally get invoked first, the timeout
		1225	handler will be executed before checking for data. In that case, giving
		1226	the timer a lower priority than the I/O watcher ensures that I/O will be
		1227	handled first even under adverse conditions (which is usually, but not
		1228	always, what you want).
		1229
		1230	Since idle watchers use the "lock-out" model, meaning that idle watchers
		1231	will only be executed when no same or higher priority watchers have
		1232	received events, they can be used to implement the "lock-out" model when
		1233	required.
		1234
		1235	For example, to emulate how many other event libraries handle priorities,
		1236	you can associate an C<ev_idle> watcher to each such watcher, and in
		1237	the normal watcher callback, you just start the idle watcher. The real
		1238	processing is done in the idle watcher callback. This causes libev to
		1239	continously poll and process kernel event data for the watcher, but when
		1240	the lock-out case is known to be rare (which in turn is rare :), this is
		1241	workable.
		1242
		1243	Usually, however, the lock-out model implemented that way will perform
		1244	miserably under the type of load it was designed to handle. In that case,
		1245	it might be preferable to stop the real watcher before starting the
		1246	idle watcher, so the kernel will not have to process the event in case
		1247	the actual processing will be delayed for considerable time.
		1248
		1249	Here is an example of an I/O watcher that should run at a strictly lower
		1250	priority than the default, and which should only process data when no
		1251	other events are pending:
		1252
		1253	ev_idle idle; // actual processing watcher
		1254	ev_io io; // actual event watcher
		1255
		1256	static void
		1257	io_cb (EV_P_ ev_io *w, int revents)
		1258	{
		1259	// stop the I/O watcher, we received the event, but
		1260	// are not yet ready to handle it.
		1261	ev_io_stop (EV_A_ w);
		1262
		1263	// start the idle watcher to ahndle the actual event.
		1264	// it will not be executed as long as other watchers
		1265	// with the default priority are receiving events.
		1266	ev_idle_start (EV_A_ &idle);
		1267	}
		1268
		1269	static void
		1270	idle-cb (EV_P_ ev_idle *w, int revents)
		1271	{
		1272	// actual processing
		1273	read (STDIN_FILENO, ...);
		1274
		1275	// have to start the I/O watcher again, as
		1276	// we have handled the event
		1277	ev_io_start (EV_P_ &io);
		1278	}
		1279
		1280	// initialisation
		1281	ev_idle_init (&idle, idle_cb);
		1282	ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
		1283	ev_io_start (EV_DEFAULT_ &io);
		1284
		1285	In the "real" world, it might also be beneficial to start a timer, so that
		1286	low-priority connections can not be locked out forever under load. This
		1287	enables your program to keep a lower latency for important connections
		1288	during short periods of high load, while not completely locking out less
		1289	important ones.
1163		1290
1164		1291
1165	=head1 WATCHER TYPES	1292	=head1 WATCHER TYPES
1166		1293
1167	This section describes each watcher in detail, but will not repeat	1294	This section describes each watcher in detail, but will not repeat
…		…
1324	year, it will still time out after (roughly) one hour. "Roughly" because	1451	year, it will still time out after (roughly) one hour. "Roughly" because
1325	detecting time jumps is hard, and some inaccuracies are unavoidable (the	1452	detecting time jumps is hard, and some inaccuracies are unavoidable (the
1326	monotonic clock option helps a lot here).	1453	monotonic clock option helps a lot here).
1327		1454
1328	The callback is guaranteed to be invoked only I<after> its timeout has	1455	The callback is guaranteed to be invoked only I<after> its timeout has
1329	passed, but if multiple timers become ready during the same loop iteration	1456	passed. If multiple timers become ready during the same loop iteration
1330	then order of execution is undefined.	1457	then the ones with earlier time-out values are invoked before ones with
		1458	later time-out values (but this is no longer true when a callback calls
		1459	C<ev_loop> recursively).
1331		1460
1332	=head3 Be smart about timeouts	1461	=head3 Be smart about timeouts
1333		1462
1334	Many real-world problems involve some kind of timeout, usually for error	1463	Many real-world problems involve some kind of timeout, usually for error
1335	recovery. A typical example is an HTTP request - if the other side hangs,	1464	recovery. A typical example is an HTTP request - if the other side hangs,
…		…
1554	If the timer is started but non-repeating, stop it (as if it timed out).	1683	If the timer is started but non-repeating, stop it (as if it timed out).
1555		1684
1556	If the timer is repeating, either start it if necessary (with the	1685	If the timer is repeating, either start it if necessary (with the
1557	C<repeat> value), or reset the running timer to the C<repeat> value.	1686	C<repeat> value), or reset the running timer to the C<repeat> value.
1558		1687
1559	This sounds a bit complicated, see "Be smart about timeouts", above, for a	1688	This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1560	usage example.	1689	usage example.
1561		1690
1562	=item ev_tstamp repeat [read-write]	1691	=item ev_tstamp repeat [read-write]
1563		1692
1564	The current C<repeat> value. Will be used each time the watcher times out	1693	The current C<repeat> value. Will be used each time the watcher times out
…		…
1624	timers, such as triggering an event on each "midnight, local time", or	1753	timers, such as triggering an event on each "midnight, local time", or
1625	other complicated rules. This cannot be done with C<ev_timer> watchers, as	1754	other complicated rules. This cannot be done with C<ev_timer> watchers, as
1626	those cannot react to time jumps.	1755	those cannot react to time jumps.
1627		1756
1628	As with timers, the callback is guaranteed to be invoked only when the	1757	As with timers, the callback is guaranteed to be invoked only when the
1629	point in time where it is supposed to trigger has passed, but if multiple	1758	point in time where it is supposed to trigger has passed. If multiple
1630	periodic timers become ready during the same loop iteration, then order of	1759	timers become ready during the same loop iteration then the ones with
1631	execution is undefined.	1760	earlier time-out values are invoked before ones with later time-out values
		1761	(but this is no longer true when a callback calls C<ev_loop> recursively).
1632		1762
1633	=head3 Watcher-Specific Functions and Data Members	1763	=head3 Watcher-Specific Functions and Data Members
1634		1764
1635	=over 4	1765	=over 4
1636		1766
…		…
3964	involves iterating over all running async watchers or all signal numbers.	4094	involves iterating over all running async watchers or all signal numbers.
3965		4095
3966	=back	4096	=back
3967		4097
3968		4098
		4099	=head1 GLOSSARY
		4100
		4101	=over 4
		4102
		4103	=item active
		4104
		4105	A watcher is active as long as it has been started (has been attached to
		4106	an event loop) but not yet stopped (disassociated from the event loop).
		4107
		4108	=item application
		4109
		4110	In this document, an application is whatever is using libev.
		4111
		4112	=item callback
		4113
		4114	The address of a function that is called when some event has been
		4115	detected. Callbacks are being passed the event loop, the watcher that
		4116	received the event, and the actual event bitset.
		4117
		4118	=item callback invocation
		4119
		4120	The act of calling the callback associated with a watcher.
		4121
		4122	=item event
		4123
		4124	A change of state of some external event, such as data now being available
		4125	for reading on a file descriptor, time having passed or simply not having
		4126	any other events happening anymore.
		4127
		4128	In libev, events are represented as single bits (such as C<EV_READ> or
		4129	C<EV_TIMEOUT>).
		4130
		4131	=item event library
		4132
		4133	A software package implementing an event model and loop.
		4134
		4135	=item event loop
		4136
		4137	An entity that handles and processes external events and converts them
		4138	into callback invocations.
		4139
		4140	=item event model
		4141
		4142	The model used to describe how an event loop handles and processes
		4143	watchers and events.
		4144
		4145	=item pending
		4146
		4147	A watcher is pending as soon as the corresponding event has been detected,
		4148	and stops being pending as soon as the watcher will be invoked or its
		4149	pending status is explicitly cleared by the application.
		4150
		4151	A watcher can be pending, but not active. Stopping a watcher also clears
		4152	its pending status.
		4153
		4154	=item real time
		4155
		4156	The physical time that is observed. It is apparently strictly monotonic :)
		4157
		4158	=item wall-clock time
		4159
		4160	The time and date as shown on clocks. Unlike real time, it can actually
		4161	be wrong and jump forwards and backwards, e.g. when the you adjust your
		4162	clock.
		4163
		4164	=item watcher
		4165
		4166	A data structure that describes interest in certain events. Watchers need
		4167	to be started (attached to an event loop) before they can receive events.
		4168
		4169	=item watcher invocation
		4170
		4171	The act of calling the callback associated with a watcher.
		4172
		4173	=back
		4174
3969	=head1 AUTHOR	4175	=head1 AUTHOR
3970		4176
3971	Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.	4177	Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3972		4178

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.229 by root, Wed Apr 15 17:49:27 2009 UTC vs. Revision 1.234 by root, Thu Apr 16 07:49:23 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.229 by root, Wed Apr 15 17:49:27 2009 UTC vs.
Revision 1.234 by root, Thu Apr 16 07:49:23 2009 UTC