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

Comparing libev/ev.pod (file contents):
Revision 1.227 by root, Wed Mar 4 14:33:10 2009 UTC vs.
Revision 1.236 by root, Thu Apr 16 07:56:05 2009 UTC

…		…
62		62
63	// unloop was called, so exit	63	// unloop was called, so exit
64	return 0;	64	return 0;
65	}	65	}
66		66
67	=head1 DESCRIPTION	67	=head1 ABOUT THIS DOCUMENT
		68
		69	This document documents the libev software package.
68		70
69	The newest version of this document is also available as an html-formatted	71	The newest version of this document is also available as an html-formatted
70	web page you might find easier to navigate when reading it for the first	72	web page you might find easier to navigate when reading it for the first
71	time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.	73	time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
		74
		75	While this document tries to be as complete as possible in documenting
		76	libev, its usage and the rationale behind its design, it is not a tutorial
		77	on event-based programming, nor will it introduce event-based programming
		78	with libev.
		79
		80	Familarity with event based programming techniques in general is assumed
		81	throughout this document.
		82
		83	=head1 ABOUT LIBEV
72		84
73	Libev is an event loop: you register interest in certain events (such as a	85	Libev is an event loop: you register interest in certain events (such as a
74	file descriptor being readable or a timeout occurring), and it will manage	86	file descriptor being readable or a timeout occurring), and it will manage
75	these event sources and provide your program with events.	87	these event sources and provide your program with events.
76		88
…		…
633	This function is rarely useful, but when some event callback runs for a	645	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	646	very long time without entering the event loop, updating libev's idea of
635	the current time is a good idea.	647	the current time is a good idea.
636		648
637	See also "The special problem of time updates" in the C<ev_timer> section.	649	See also "The special problem of time updates" in the C<ev_timer> section.
		650
		651	=item ev_suspend (loop)
		652
		653	=item ev_resume (loop)
		654
		655	These two functions suspend and resume a loop, for use when the loop is
		656	not used for a while and timeouts should not be processed.
		657
		658	A typical use case would be an interactive program such as a game: When
		659	the user presses C<^Z> to suspend the game and resumes it an hour later it
		660	would be best to handle timeouts as if no time had actually passed while
		661	the program was suspended. This can be achieved by calling C<ev_suspend>
		662	in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
		663	C<ev_resume> directly afterwards to resume timer processing.
		664
		665	Effectively, all C<ev_timer> watchers will be delayed by the time spend
		666	between C<ev_suspend> and C<ev_resume>, and all C<ev_periodic> watchers
		667	will be rescheduled (that is, they will lose any events that would have
		668	occured while suspended).
		669
		670	After calling C<ev_suspend> you B<must not> call I<any> function on the
		671	given loop other than C<ev_resume>, and you B<must not> call C<ev_resume>
		672	without a previous call to C<ev_suspend>.
		673
		674	Calling C<ev_suspend>/C<ev_resume> has the side effect of updating the
		675	event loop time (see C<ev_now_update>).
638		676
639	=item ev_loop (loop, int flags)	677	=item ev_loop (loop, int flags)
640		678
641	Finally, this is it, the event handler. This function usually is called	679	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	680	after you initialised all your watchers and you want to start handling
…		…
726		764
727	If you have a watcher you never unregister that should not keep C<ev_loop>	765	If you have a watcher you never unregister that should not keep C<ev_loop>
728	from returning, call ev_unref() after starting, and ev_ref() before	766	from returning, call ev_unref() after starting, and ev_ref() before
729	stopping it.	767	stopping it.
730		768
731	As an example, libev itself uses this for its internal signal pipe: It is	769	As an example, libev itself uses this for its internal signal pipe: It
732	not visible to the libev user and should not keep C<ev_loop> from exiting	770	is not visible to the libev user and should not keep C<ev_loop> from
733	if no event watchers registered by it are active. It is also an excellent	771	exiting if no event watchers registered by it are active. It is also an
734	way to do this for generic recurring timers or from within third-party	772	excellent way to do this for generic recurring timers or from within
735	libraries. Just remember to I<unref after start> and I<ref before stop>	773	third-party libraries. Just remember to I<unref after start> and I<ref
736	(but only if the watcher wasn't active before, or was active before,	774	before stop> (but only if the watcher wasn't active before, or was active
737	respectively).	775	before, respectively. Note also that libev might stop watchers itself
		776	(e.g. non-repeating timers) in which case you have to C<ev_ref>
		777	in the callback).
738		778
739	Example: Create a signal watcher, but keep it from keeping C<ev_loop>	779	Example: Create a signal watcher, but keep it from keeping C<ev_loop>
740	running when nothing else is active.	780	running when nothing else is active.
741		781
742	ev_signal exitsig;	782	ev_signal exitsig;
…		…
926		966
927	=item C<EV_ASYNC>	967	=item C<EV_ASYNC>
928		968
929	The given async watcher has been asynchronously notified (see C<ev_async>).	969	The given async watcher has been asynchronously notified (see C<ev_async>).
930		970
		971	=item C<EV_CUSTOM>
		972
		973	Not ever sent (or otherwise used) by libev itself, but can be freely used
		974	by libev users to signal watchers (e.g. via C<ev_feed_event>).
		975
931	=item C<EV_ERROR>	976	=item C<EV_ERROR>
932		977
933	An unspecified error has occurred, the watcher has been stopped. This might	978	An unspecified error has occurred, the watcher has been stopped. This might
934	happen because the watcher could not be properly started because libev	979	happen because the watcher could not be properly started because libev
935	ran out of memory, a file descriptor was found to be closed or any other	980	ran out of memory, a file descriptor was found to be closed or any other
…		…
1050	integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>	1095	integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1051	(default: C<-2>). Pending watchers with higher priority will be invoked	1096	(default: C<-2>). Pending watchers with higher priority will be invoked
1052	before watchers with lower priority, but priority will not keep watchers	1097	before watchers with lower priority, but priority will not keep watchers
1053	from being executed (except for C<ev_idle> watchers).	1098	from being executed (except for C<ev_idle> watchers).
1054		1099
1055	This means that priorities are I<only> used for ordering callback
1056	invocation after new events have been received. This is useful, for
1057	example, to reduce latency after idling, or more often, to bind two
1058	watchers on the same event and make sure one is called first.
1059
1060	If you need to suppress invocation when higher priority events are pending	1100	If you need to suppress invocation when higher priority events are pending
1061	you need to look at C<ev_idle> watchers, which provide this functionality.	1101	you need to look at C<ev_idle> watchers, which provide this functionality.
1062		1102
1063	You I<must not> change the priority of a watcher as long as it is active or	1103	You I<must not> change the priority of a watcher as long as it is active or
1064	pending.	1104	pending.
1065
1066	The default priority used by watchers when no priority has been set is
1067	always C<0>, which is supposed to not be too high and not be too low :).
1068		1105
1069	Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is	1106	Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1070	fine, as long as you do not mind that the priority value you query might	1107	fine, as long as you do not mind that the priority value you query might
1071	or might not have been clamped to the valid range.	1108	or might not have been clamped to the valid range.
		1109
		1110	The default priority used by watchers when no priority has been set is
		1111	always C<0>, which is supposed to not be too high and not be too low :).
		1112
		1113	See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
		1114	priorities.
1072		1115
1073	=item ev_invoke (loop, ev_TYPE *watcher, int revents)	1116	=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1074		1117
1075	Invoke the C<watcher> with the given C<loop> and C<revents>. Neither	1118	Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1076	C<loop> nor C<revents> need to be valid as long as the watcher callback	1119	C<loop> nor C<revents> need to be valid as long as the watcher callback
…		…
1151	t2_cb (EV_P_ ev_timer *w, int revents)	1194	t2_cb (EV_P_ ev_timer *w, int revents)
1152	{	1195	{
1153	struct my_biggy big = (struct my_biggy *	1196	struct my_biggy big = (struct my_biggy *
1154	(((char *)w) - offsetof (struct my_biggy, t2));	1197	(((char *)w) - offsetof (struct my_biggy, t2));
1155	}	1198	}
		1199
		1200	=head2 WATCHER PRIORITY MODELS
		1201
		1202	Many event loops support I<watcher priorities>, which are usually small
		1203	integers that influence the ordering of event callback invocation
		1204	between watchers in some way, all else being equal.
		1205
		1206	In libev, Watcher priorities can be set using C<ev_set_priority>. See its
		1207	description for the more technical details such as the actual priority
		1208	range.
		1209
		1210	There are two common ways how these these priorities are being interpreted
		1211	by event loops:
		1212
		1213	In the more common lock-out model, higher priorities "lock out" invocation
		1214	of lower priority watchers, which means as long as higher priority
		1215	watchers receive events, lower priority watchers are not being invoked.
		1216
		1217	The less common only-for-ordering model uses priorities solely to order
		1218	callback invocation within a single event loop iteration: Higher priority
		1219	watchers are invoked before lower priority ones, but they all get invoked
		1220	before polling for new events.
		1221
		1222	Libev uses the second (only-for-ordering) model for all its watchers
		1223	except for idle watchers (which use the lock-out model).
		1224
		1225	The rationale behind this is that implementing the lock-out model for
		1226	watchers is not well supported by most kernel interfaces, and most event
		1227	libraries will just poll for the same events again and again as long as
		1228	their callbacks have not been executed, which is very inefficient in the
		1229	common case of one high-priority watcher locking out a mass of lower
		1230	priority ones.
		1231
		1232	Static (ordering) priorities are most useful when you have two or more
		1233	watchers handling the same resource: a typical usage example is having an
		1234	C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
		1235	timeouts. Under load, data might be received while the program handles
		1236	other jobs, but since timers normally get invoked first, the timeout
		1237	handler will be executed before checking for data. In that case, giving
		1238	the timer a lower priority than the I/O watcher ensures that I/O will be
		1239	handled first even under adverse conditions (which is usually, but not
		1240	always, what you want).
		1241
		1242	Since idle watchers use the "lock-out" model, meaning that idle watchers
		1243	will only be executed when no same or higher priority watchers have
		1244	received events, they can be used to implement the "lock-out" model when
		1245	required.
		1246
		1247	For example, to emulate how many other event libraries handle priorities,
		1248	you can associate an C<ev_idle> watcher to each such watcher, and in
		1249	the normal watcher callback, you just start the idle watcher. The real
		1250	processing is done in the idle watcher callback. This causes libev to
		1251	continously poll and process kernel event data for the watcher, but when
		1252	the lock-out case is known to be rare (which in turn is rare :), this is
		1253	workable.
		1254
		1255	Usually, however, the lock-out model implemented that way will perform
		1256	miserably under the type of load it was designed to handle. In that case,
		1257	it might be preferable to stop the real watcher before starting the
		1258	idle watcher, so the kernel will not have to process the event in case
		1259	the actual processing will be delayed for considerable time.
		1260
		1261	Here is an example of an I/O watcher that should run at a strictly lower
		1262	priority than the default, and which should only process data when no
		1263	other events are pending:
		1264
		1265	ev_idle idle; // actual processing watcher
		1266	ev_io io; // actual event watcher
		1267
		1268	static void
		1269	io_cb (EV_P_ ev_io *w, int revents)
		1270	{
		1271	// stop the I/O watcher, we received the event, but
		1272	// are not yet ready to handle it.
		1273	ev_io_stop (EV_A_ w);
		1274
		1275	// start the idle watcher to ahndle the actual event.
		1276	// it will not be executed as long as other watchers
		1277	// with the default priority are receiving events.
		1278	ev_idle_start (EV_A_ &idle);
		1279	}
		1280
		1281	static void
		1282	idle-cb (EV_P_ ev_idle *w, int revents)
		1283	{
		1284	// actual processing
		1285	read (STDIN_FILENO, ...);
		1286
		1287	// have to start the I/O watcher again, as
		1288	// we have handled the event
		1289	ev_io_start (EV_P_ &io);
		1290	}
		1291
		1292	// initialisation
		1293	ev_idle_init (&idle, idle_cb);
		1294	ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
		1295	ev_io_start (EV_DEFAULT_ &io);
		1296
		1297	In the "real" world, it might also be beneficial to start a timer, so that
		1298	low-priority connections can not be locked out forever under load. This
		1299	enables your program to keep a lower latency for important connections
		1300	during short periods of high load, while not completely locking out less
		1301	important ones.
1156		1302
1157		1303
1158	=head1 WATCHER TYPES	1304	=head1 WATCHER TYPES
1159		1305
1160	This section describes each watcher in detail, but will not repeat	1306	This section describes each watcher in detail, but will not repeat
…		…
1317	year, it will still time out after (roughly) one hour. "Roughly" because	1463	year, it will still time out after (roughly) one hour. "Roughly" because
1318	detecting time jumps is hard, and some inaccuracies are unavoidable (the	1464	detecting time jumps is hard, and some inaccuracies are unavoidable (the
1319	monotonic clock option helps a lot here).	1465	monotonic clock option helps a lot here).
1320		1466
1321	The callback is guaranteed to be invoked only I<after> its timeout has	1467	The callback is guaranteed to be invoked only I<after> its timeout has
1322	passed, but if multiple timers become ready during the same loop iteration	1468	passed. If multiple timers become ready during the same loop iteration
1323	then order of execution is undefined.	1469	then the ones with earlier time-out values are invoked before ones with
		1470	later time-out values (but this is no longer true when a callback calls
		1471	C<ev_loop> recursively).
1324		1472
1325	=head3 Be smart about timeouts	1473	=head3 Be smart about timeouts
1326		1474
1327	Many real-world problems involve some kind of timeout, usually for error	1475	Many real-world problems involve some kind of timeout, usually for error
1328	recovery. A typical example is an HTTP request - if the other side hangs,	1476	recovery. A typical example is an HTTP request - if the other side hangs,
…		…
1547	If the timer is started but non-repeating, stop it (as if it timed out).	1695	If the timer is started but non-repeating, stop it (as if it timed out).
1548		1696
1549	If the timer is repeating, either start it if necessary (with the	1697	If the timer is repeating, either start it if necessary (with the
1550	C<repeat> value), or reset the running timer to the C<repeat> value.	1698	C<repeat> value), or reset the running timer to the C<repeat> value.
1551		1699
1552	This sounds a bit complicated, see "Be smart about timeouts", above, for a	1700	This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1553	usage example.	1701	usage example.
1554		1702
1555	=item ev_tstamp repeat [read-write]	1703	=item ev_tstamp repeat [read-write]
1556		1704
1557	The current C<repeat> value. Will be used each time the watcher times out	1705	The current C<repeat> value. Will be used each time the watcher times out
…		…
1617	timers, such as triggering an event on each "midnight, local time", or	1765	timers, such as triggering an event on each "midnight, local time", or
1618	other complicated rules. This cannot be done with C<ev_timer> watchers, as	1766	other complicated rules. This cannot be done with C<ev_timer> watchers, as
1619	those cannot react to time jumps.	1767	those cannot react to time jumps.
1620		1768
1621	As with timers, the callback is guaranteed to be invoked only when the	1769	As with timers, the callback is guaranteed to be invoked only when the
1622	point in time where it is supposed to trigger has passed, but if multiple	1770	point in time where it is supposed to trigger has passed. If multiple
1623	periodic timers become ready during the same loop iteration, then order of	1771	timers become ready during the same loop iteration then the ones with
1624	execution is undefined.	1772	earlier time-out values are invoked before ones with later time-out values
		1773	(but this is no longer true when a callback calls C<ev_loop> recursively).
1625		1774
1626	=head3 Watcher-Specific Functions and Data Members	1775	=head3 Watcher-Specific Functions and Data Members
1627		1776
1628	=over 4	1777	=over 4
1629		1778
…		…
3033	L<http://software.schmorp.de/pkg/EV>.	3182	L<http://software.schmorp.de/pkg/EV>.
3034		3183
3035	=item Python	3184	=item Python
3036		3185
3037	Python bindings can be found at L<http://code.google.com/p/pyev/>. It	3186	Python bindings can be found at L<http://code.google.com/p/pyev/>. It
3038	seems to be quite complete and well-documented. Note, however, that the	3187	seems to be quite complete and well-documented.
3039	patch they require for libev is outright dangerous as it breaks the ABI
3040	for everybody else, and therefore, should never be applied in an installed
3041	libev (if python requires an incompatible ABI then it needs to embed
3042	libev).
3043		3188
3044	=item Ruby	3189	=item Ruby
3045		3190
3046	Tony Arcieri has written a ruby extension that offers access to a subset	3191	Tony Arcieri has written a ruby extension that offers access to a subset
3047	of the libev API and adds file handle abstractions, asynchronous DNS and	3192	of the libev API and adds file handle abstractions, asynchronous DNS and
3048	more on top of it. It can be found via gem servers. Its homepage is at	3193	more on top of it. It can be found via gem servers. Its homepage is at
3049	L<http://rev.rubyforge.org/>.	3194	L<http://rev.rubyforge.org/>.
3050		3195
3051	Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>	3196	Roger Pack reports that using the link order C<-lws2_32 -lmsvcrt-ruby-190>
3052	makes rev work even on mingw.	3197	makes rev work even on mingw.
		3198
		3199	=item Haskell
		3200
		3201	A haskell binding to libev is available at
		3202	L<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hlibev>.
3053		3203
3054	=item D	3204	=item D
3055		3205
3056	Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to	3206	Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
3057	be found at L<http://proj.llucax.com.ar/wiki/evd>.	3207	be found at L<http://proj.llucax.com.ar/wiki/evd>.
…		…
3956	involves iterating over all running async watchers or all signal numbers.	4106	involves iterating over all running async watchers or all signal numbers.
3957		4107
3958	=back	4108	=back
3959		4109
3960		4110
		4111	=head1 GLOSSARY
		4112
		4113	=over 4
		4114
		4115	=item active
		4116
		4117	A watcher is active as long as it has been started (has been attached to
		4118	an event loop) but not yet stopped (disassociated from the event loop).
		4119
		4120	=item application
		4121
		4122	In this document, an application is whatever is using libev.
		4123
		4124	=item callback
		4125
		4126	The address of a function that is called when some event has been
		4127	detected. Callbacks are being passed the event loop, the watcher that
		4128	received the event, and the actual event bitset.
		4129
		4130	=item callback invocation
		4131
		4132	The act of calling the callback associated with a watcher.
		4133
		4134	=item event
		4135
		4136	A change of state of some external event, such as data now being available
		4137	for reading on a file descriptor, time having passed or simply not having
		4138	any other events happening anymore.
		4139
		4140	In libev, events are represented as single bits (such as C<EV_READ> or
		4141	C<EV_TIMEOUT>).
		4142
		4143	=item event library
		4144
		4145	A software package implementing an event model and loop.
		4146
		4147	=item event loop
		4148
		4149	An entity that handles and processes external events and converts them
		4150	into callback invocations.
		4151
		4152	=item event model
		4153
		4154	The model used to describe how an event loop handles and processes
		4155	watchers and events.
		4156
		4157	=item pending
		4158
		4159	A watcher is pending as soon as the corresponding event has been detected,
		4160	and stops being pending as soon as the watcher will be invoked or its
		4161	pending status is explicitly cleared by the application.
		4162
		4163	A watcher can be pending, but not active. Stopping a watcher also clears
		4164	its pending status.
		4165
		4166	=item real time
		4167
		4168	The physical time that is observed. It is apparently strictly monotonic :)
		4169
		4170	=item wall-clock time
		4171
		4172	The time and date as shown on clocks. Unlike real time, it can actually
		4173	be wrong and jump forwards and backwards, e.g. when the you adjust your
		4174	clock.
		4175
		4176	=item watcher
		4177
		4178	A data structure that describes interest in certain events. Watchers need
		4179	to be started (attached to an event loop) before they can receive events.
		4180
		4181	=item watcher invocation
		4182
		4183	The act of calling the callback associated with a watcher.
		4184
		4185	=back
		4186
3961	=head1 AUTHOR	4187	=head1 AUTHOR
3962		4188
3963	Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.	4189	Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3964		4190

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.227 by root, Wed Mar 4 14:33:10 2009 UTC vs. Revision 1.236 by root, Thu Apr 16 07:56:05 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.227 by root, Wed Mar 4 14:33:10 2009 UTC vs.
Revision 1.236 by root, Thu Apr 16 07:56:05 2009 UTC