[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.244 by root, Mon Jun 29 04:41:34 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
…		…
110	name C<loop> (which is always of type C<ev_loop *>) will not have	122	name C<loop> (which is always of type C<ev_loop *>) will not have
111	this argument.	123	this argument.
112		124
113	=head2 TIME REPRESENTATION	125	=head2 TIME REPRESENTATION
114		126
115	Libev represents time as a single floating point number, representing the	127	Libev represents time as a single floating point number, representing
116	(fractional) number of seconds since the (POSIX) epoch (somewhere near	128	the (fractional) number of seconds since the (POSIX) epoch (somewhere
117	the beginning of 1970, details are complicated, don't ask). This type is	129	near the beginning of 1970, details are complicated, don't ask). This
118	called C<ev_tstamp>, which is what you should use too. It usually aliases	130	type is called C<ev_tstamp>, which is what you should use too. It usually
119	to the C<double> type in C, and when you need to do any calculations on	131	aliases to the C<double> type in C. When you need to do any calculations
120	it, you should treat it as some floating point value. Unlike the name	132	on it, you should treat it as some floating point value. Unlike the name
121	component C<stamp> might indicate, it is also used for time differences	133	component C<stamp> might indicate, it is also used for time differences
122	throughout libev.	134	throughout libev.
123		135
124	=head1 ERROR HANDLING	136	=head1 ERROR HANDLING
125		137
…		…
632		644
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 L<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
…		…
1057	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>
1058	(default: C<-2>). Pending watchers with higher priority will be invoked	1096	(default: C<-2>). Pending watchers with higher priority will be invoked
1059	before watchers with lower priority, but priority will not keep watchers	1097	before watchers with lower priority, but priority will not keep watchers
1060	from being executed (except for C<ev_idle> watchers).	1098	from being executed (except for C<ev_idle> watchers).
1061		1099
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	1100	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.	1101	you need to look at C<ev_idle> watchers, which provide this functionality.
1069		1102
1070	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
1071	pending.	1104	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		1105
1076	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
1077	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
1078	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.
1079		1115
1080	=item ev_invoke (loop, ev_TYPE *watcher, int revents)	1116	=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1081		1117
1082	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
1083	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
…		…
1148	#include <stddef.h>	1184	#include <stddef.h>
1149		1185
1150	static void	1186	static void
1151	t1_cb (EV_P_ ev_timer *w, int revents)	1187	t1_cb (EV_P_ ev_timer *w, int revents)
1152	{	1188	{
1153	struct my_biggy big = (struct my_biggy *	1189	struct my_biggy big = (struct my_biggy *)
1154	(((char *)w) - offsetof (struct my_biggy, t1));	1190	(((char *)w) - offsetof (struct my_biggy, t1));
1155	}	1191	}
1156		1192
1157	static void	1193	static void
1158	t2_cb (EV_P_ ev_timer *w, int revents)	1194	t2_cb (EV_P_ ev_timer *w, int revents)
1159	{	1195	{
1160	struct my_biggy big = (struct my_biggy *	1196	struct my_biggy big = (struct my_biggy *)
1161	(((char *)w) - offsetof (struct my_biggy, t2));	1197	(((char *)w) - offsetof (struct my_biggy, t2));
1162	}	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.
1163		1302
1164		1303
1165	=head1 WATCHER TYPES	1304	=head1 WATCHER TYPES
1166		1305
1167	This section describes each watcher in detail, but will not repeat	1306	This section describes each watcher in detail, but will not repeat
…		…
1193	descriptors to non-blocking mode is also usually a good idea (but not	1332	descriptors to non-blocking mode is also usually a good idea (but not
1194	required if you know what you are doing).	1333	required if you know what you are doing).
1195		1334
1196	If you cannot use non-blocking mode, then force the use of a	1335	If you cannot use non-blocking mode, then force the use of a
1197	known-to-be-good backend (at the time of this writing, this includes only	1336	known-to-be-good backend (at the time of this writing, this includes only
1198	C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>).	1337	C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
		1338	descriptors for which non-blocking operation makes no sense (such as
		1339	files) - libev doesn't guarentee any specific behaviour in that case.
1199		1340
1200	Another thing you have to watch out for is that it is quite easy to	1341	Another thing you have to watch out for is that it is quite easy to
1201	receive "spurious" readiness notifications, that is your callback might	1342	receive "spurious" readiness notifications, that is your callback might
1202	be called with C<EV_READ> but a subsequent C<read>(2) will actually block	1343	be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1203	because there is no data. Not only are some backends known to create a	1344	because there is no data. Not only are some backends known to create a
…		…
1324	year, it will still time out after (roughly) one hour. "Roughly" because	1465	year, it will still time out after (roughly) one hour. "Roughly" because
1325	detecting time jumps is hard, and some inaccuracies are unavoidable (the	1466	detecting time jumps is hard, and some inaccuracies are unavoidable (the
1326	monotonic clock option helps a lot here).	1467	monotonic clock option helps a lot here).
1327		1468
1328	The callback is guaranteed to be invoked only I<after> its timeout has	1469	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	1470	passed (not I<at>, so on systems with very low-resolution clocks this
1330	then order of execution is undefined.	1471	might introduce a small delay). If multiple timers become ready during the
		1472	same loop iteration then the ones with earlier time-out values are invoked
		1473	before ones with later time-out values (but this is no longer true when a
		1474	callback calls C<ev_loop> recursively).
1331		1475
1332	=head3 Be smart about timeouts	1476	=head3 Be smart about timeouts
1333		1477
1334	Many real-world problems involve some kind of timeout, usually for error	1478	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,	1479	recovery. A typical example is an HTTP request - if the other side hangs,
…		…
1379	C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>	1523	C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1380	member and C<ev_timer_again>.	1524	member and C<ev_timer_again>.
1381		1525
1382	At start:	1526	At start:
1383		1527
1384	ev_timer_init (timer, callback);	1528	ev_init (timer, callback);
1385	timer->repeat = 60.;	1529	timer->repeat = 60.;
1386	ev_timer_again (loop, timer);	1530	ev_timer_again (loop, timer);
1387		1531
1388	Each time there is some activity:	1532	Each time there is some activity:
1389		1533
…		…
1451		1595
1452	To start the timer, simply initialise the watcher and set C<last_activity>	1596	To start the timer, simply initialise the watcher and set C<last_activity>
1453	to the current time (meaning we just have some activity :), then call the	1597	to the current time (meaning we just have some activity :), then call the
1454	callback, which will "do the right thing" and start the timer:	1598	callback, which will "do the right thing" and start the timer:
1455		1599
1456	ev_timer_init (timer, callback);	1600	ev_init (timer, callback);
1457	last_activity = ev_now (loop);	1601	last_activity = ev_now (loop);
1458	callback (loop, timer, EV_TIMEOUT);	1602	callback (loop, timer, EV_TIMEOUT);
1459		1603
1460	And when there is some activity, simply store the current time in	1604	And when there is some activity, simply store the current time in
1461	C<last_activity>, no libev calls at all:	1605	C<last_activity>, no libev calls at all:
…		…
1554	If the timer is started but non-repeating, stop it (as if it timed out).	1698	If the timer is started but non-repeating, stop it (as if it timed out).
1555		1699
1556	If the timer is repeating, either start it if necessary (with the	1700	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.	1701	C<repeat> value), or reset the running timer to the C<repeat> value.
1558		1702
1559	This sounds a bit complicated, see "Be smart about timeouts", above, for a	1703	This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1560	usage example.	1704	usage example.
1561		1705
1562	=item ev_tstamp repeat [read-write]	1706	=item ev_tstamp repeat [read-write]
1563		1707
1564	The current C<repeat> value. Will be used each time the watcher times out	1708	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	1768	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	1769	other complicated rules. This cannot be done with C<ev_timer> watchers, as
1626	those cannot react to time jumps.	1770	those cannot react to time jumps.
1627		1771
1628	As with timers, the callback is guaranteed to be invoked only when the	1772	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	1773	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	1774	timers become ready during the same loop iteration then the ones with
1631	execution is undefined.	1775	earlier time-out values are invoked before ones with later time-out values
		1776	(but this is no longer true when a callback calls C<ev_loop> recursively).
1632		1777
1633	=head3 Watcher-Specific Functions and Data Members	1778	=head3 Watcher-Specific Functions and Data Members
1634		1779
1635	=over 4	1780	=over 4
1636		1781
…		…
1857	some child status changes (most typically when a child of yours dies or	2002	some child status changes (most typically when a child of yours dies or
1858	exits). It is permissible to install a child watcher I<after> the child	2003	exits). It is permissible to install a child watcher I<after> the child
1859	has been forked (which implies it might have already exited), as long	2004	has been forked (which implies it might have already exited), as long
1860	as the event loop isn't entered (or is continued from a watcher), i.e.,	2005	as the event loop isn't entered (or is continued from a watcher), i.e.,
1861	forking and then immediately registering a watcher for the child is fine,	2006	forking and then immediately registering a watcher for the child is fine,
1862	but forking and registering a watcher a few event loop iterations later is	2007	but forking and registering a watcher a few event loop iterations later or
1863	not.	2008	in the next callback invocation is not.
1864		2009
1865	Only the default event loop is capable of handling signals, and therefore	2010	Only the default event loop is capable of handling signals, and therefore
1866	you can only register child watchers in the default event loop.	2011	you can only register child watchers in the default event loop.
1867		2012
1868	=head3 Process Interaction	2013	=head3 Process Interaction
…		…
2223	// no longer anything immediate to do.	2368	// no longer anything immediate to do.
2224	}	2369	}
2225		2370
2226	ev_idle *idle_watcher = malloc (sizeof (ev_idle));	2371	ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2227	ev_idle_init (idle_watcher, idle_cb);	2372	ev_idle_init (idle_watcher, idle_cb);
2228	ev_idle_start (loop, idle_cb);	2373	ev_idle_start (loop, idle_watcher);
2229		2374
2230		2375
2231	=head2 C<ev_prepare> and C<ev_check> - customise your event loop!	2376	=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2232		2377
2233	Prepare and check watchers are usually (but not always) used in pairs:	2378	Prepare and check watchers are usually (but not always) used in pairs:
…		…
2326	struct pollfd fds [nfd];	2471	struct pollfd fds [nfd];
2327	// actual code will need to loop here and realloc etc.	2472	// actual code will need to loop here and realloc etc.
2328	adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));	2473	adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2329		2474
2330	/* the callback is illegal, but won't be called as we stop during check */	2475	/* the callback is illegal, but won't be called as we stop during check */
2331	ev_timer_init (&tw, 0, timeout * 1e-3);	2476	ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
2332	ev_timer_start (loop, &tw);	2477	ev_timer_start (loop, &tw);
2333		2478
2334	// create one ev_io per pollfd	2479	// create one ev_io per pollfd
2335	for (int i = 0; i < nfd; ++i)	2480	for (int i = 0; i < nfd; ++i)
2336	{	2481	{
…		…
2566	event loop blocks next and before C<ev_check> watchers are being called,	2711	event loop blocks next and before C<ev_check> watchers are being called,
2567	and only in the child after the fork. If whoever good citizen calling	2712	and only in the child after the fork. If whoever good citizen calling
2568	C<ev_default_fork> cheats and calls it in the wrong process, the fork	2713	C<ev_default_fork> cheats and calls it in the wrong process, the fork
2569	handlers will be invoked, too, of course.	2714	handlers will be invoked, too, of course.
2570		2715
		2716	=head3 The special problem of life after fork - how is it possible?
		2717
		2718	Most uses of C<fork()> consist of forking, then some simple calls to ste
		2719	up/change the process environment, followed by a call to C<exec()>. This
		2720	sequence should be handled by libev without any problems.
		2721
		2722	This changes when the application actually wants to do event handling
		2723	in the child, or both parent in child, in effect "continuing" after the
		2724	fork.
		2725
		2726	The default mode of operation (for libev, with application help to detect
		2727	forks) is to duplicate all the state in the child, as would be expected
		2728	when I<either> the parent I<or> the child process continues.
		2729
		2730	When both processes want to continue using libev, then this is usually the
		2731	wrong result. In that case, usually one process (typically the parent) is
		2732	supposed to continue with all watchers in place as before, while the other
		2733	process typically wants to start fresh, i.e. without any active watchers.
		2734
		2735	The cleanest and most efficient way to achieve that with libev is to
		2736	simply create a new event loop, which of course will be "empty", and
		2737	use that for new watchers. This has the advantage of not touching more
		2738	memory than necessary, and thus avoiding the copy-on-write, and the
		2739	disadvantage of having to use multiple event loops (which do not support
		2740	signal watchers).
		2741
		2742	When this is not possible, or you want to use the default loop for
		2743	other reasons, then in the process that wants to start "fresh", call
		2744	C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
		2745	the default loop will "orphan" (not stop) all registered watchers, so you
		2746	have to be careful not to execute code that modifies those watchers. Note
		2747	also that in that case, you have to re-register any signal watchers.
		2748
2571	=head3 Watcher-Specific Functions and Data Members	2749	=head3 Watcher-Specific Functions and Data Members
2572		2750
2573	=over 4	2751	=over 4
2574		2752
2575	=item ev_fork_init (ev_signal *, callback)	2753	=item ev_fork_init (ev_signal *, callback)
…		…
3757	way (note also that glib is the slowest event library known to man).	3935	way (note also that glib is the slowest event library known to man).
3758		3936
3759	There is no supported compilation method available on windows except	3937	There is no supported compilation method available on windows except
3760	embedding it into other applications.	3938	embedding it into other applications.
3761		3939
		3940	Sensible signal handling is officially unsupported by Microsoft - libev
		3941	tries its best, but under most conditions, signals will simply not work.
		3942
3762	Not a libev limitation but worth mentioning: windows apparently doesn't	3943	Not a libev limitation but worth mentioning: windows apparently doesn't
3763	accept large writes: instead of resulting in a partial write, windows will	3944	accept large writes: instead of resulting in a partial write, windows will
3764	either accept everything or return C<ENOBUFS> if the buffer is too large,	3945	either accept everything or return C<ENOBUFS> if the buffer is too large,
3765	so make sure you only write small amounts into your sockets (less than a	3946	so make sure you only write small amounts into your sockets (less than a
3766	megabyte seems safe, but this apparently depends on the amount of memory	3947	megabyte seems safe, but this apparently depends on the amount of memory
…		…
3770	the abysmal performance of winsockets, using a large number of sockets	3951	the abysmal performance of winsockets, using a large number of sockets
3771	is not recommended (and not reasonable). If your program needs to use	3952	is not recommended (and not reasonable). If your program needs to use
3772	more than a hundred or so sockets, then likely it needs to use a totally	3953	more than a hundred or so sockets, then likely it needs to use a totally
3773	different implementation for windows, as libev offers the POSIX readiness	3954	different implementation for windows, as libev offers the POSIX readiness
3774	notification model, which cannot be implemented efficiently on windows	3955	notification model, which cannot be implemented efficiently on windows
3775	(Microsoft monopoly games).	3956	(due to Microsoft monopoly games).
3776		3957
3777	A typical way to use libev under windows is to embed it (see the embedding	3958	A typical way to use libev under windows is to embed it (see the embedding
3778	section for details) and use the following F<evwrap.h> header file instead	3959	section for details) and use the following F<evwrap.h> header file instead
3779	of F<ev.h>:	3960	of F<ev.h>:
3780		3961
…		…
3816		3997
3817	Early versions of winsocket's select only supported waiting for a maximum	3998	Early versions of winsocket's select only supported waiting for a maximum
3818	of C<64> handles (probably owning to the fact that all windows kernels	3999	of C<64> handles (probably owning to the fact that all windows kernels
3819	can only wait for C<64> things at the same time internally; Microsoft	4000	can only wait for C<64> things at the same time internally; Microsoft
3820	recommends spawning a chain of threads and wait for 63 handles and the	4001	recommends spawning a chain of threads and wait for 63 handles and the
3821	previous thread in each. Great).	4002	previous thread in each. Sounds great!).
3822		4003
3823	Newer versions support more handles, but you need to define C<FD_SETSIZE>	4004	Newer versions support more handles, but you need to define C<FD_SETSIZE>
3824	to some high number (e.g. C<2048>) before compiling the winsocket select	4005	to some high number (e.g. C<2048>) before compiling the winsocket select
3825	call (which might be in libev or elsewhere, for example, perl does its own	4006	call (which might be in libev or elsewhere, for example, perl and many
3826	select emulation on windows).	4007	other interpreters do their own select emulation on windows).
3827		4008
3828	Another limit is the number of file descriptors in the Microsoft runtime	4009	Another limit is the number of file descriptors in the Microsoft runtime
3829	libraries, which by default is C<64> (there must be a hidden I<64> fetish	4010	libraries, which by default is C<64> (there must be a hidden I<64>
3830	or something like this inside Microsoft). You can increase this by calling	4011	fetish or something like this inside Microsoft). You can increase this
3831	C<_setmaxstdio>, which can increase this limit to C<2048> (another	4012	by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3832	arbitrary limit), but is broken in many versions of the Microsoft runtime	4013	(another arbitrary limit), but is broken in many versions of the Microsoft
3833	libraries.
3834
3835	This might get you to about C<512> or C<2048> sockets (depending on	4014	runtime libraries. This might get you to about C<512> or C<2048> sockets
3836	windows version and/or the phase of the moon). To get more, you need to	4015	(depending on windows version and/or the phase of the moon). To get more,
3837	wrap all I/O functions and provide your own fd management, but the cost of	4016	you need to wrap all I/O functions and provide your own fd management, but
3838	calling select (O(n²)) will likely make this unworkable.	4017	the cost of calling select (O(n²)) will likely make this unworkable.
3839		4018
3840	=back	4019	=back
3841		4020
3842	=head2 PORTABILITY REQUIREMENTS	4021	=head2 PORTABILITY REQUIREMENTS
3843		4022
…		…
3964	involves iterating over all running async watchers or all signal numbers.	4143	involves iterating over all running async watchers or all signal numbers.
3965		4144
3966	=back	4145	=back
3967		4146
3968		4147
		4148	=head1 GLOSSARY
		4149
		4150	=over 4
		4151
		4152	=item active
		4153
		4154	A watcher is active as long as it has been started (has been attached to
		4155	an event loop) but not yet stopped (disassociated from the event loop).
		4156
		4157	=item application
		4158
		4159	In this document, an application is whatever is using libev.
		4160
		4161	=item callback
		4162
		4163	The address of a function that is called when some event has been
		4164	detected. Callbacks are being passed the event loop, the watcher that
		4165	received the event, and the actual event bitset.
		4166
		4167	=item callback invocation
		4168
		4169	The act of calling the callback associated with a watcher.
		4170
		4171	=item event
		4172
		4173	A change of state of some external event, such as data now being available
		4174	for reading on a file descriptor, time having passed or simply not having
		4175	any other events happening anymore.
		4176
		4177	In libev, events are represented as single bits (such as C<EV_READ> or
		4178	C<EV_TIMEOUT>).
		4179
		4180	=item event library
		4181
		4182	A software package implementing an event model and loop.
		4183
		4184	=item event loop
		4185
		4186	An entity that handles and processes external events and converts them
		4187	into callback invocations.
		4188
		4189	=item event model
		4190
		4191	The model used to describe how an event loop handles and processes
		4192	watchers and events.
		4193
		4194	=item pending
		4195
		4196	A watcher is pending as soon as the corresponding event has been detected,
		4197	and stops being pending as soon as the watcher will be invoked or its
		4198	pending status is explicitly cleared by the application.
		4199
		4200	A watcher can be pending, but not active. Stopping a watcher also clears
		4201	its pending status.
		4202
		4203	=item real time
		4204
		4205	The physical time that is observed. It is apparently strictly monotonic :)
		4206
		4207	=item wall-clock time
		4208
		4209	The time and date as shown on clocks. Unlike real time, it can actually
		4210	be wrong and jump forwards and backwards, e.g. when the you adjust your
		4211	clock.
		4212
		4213	=item watcher
		4214
		4215	A data structure that describes interest in certain events. Watchers need
		4216	to be started (attached to an event loop) before they can receive events.
		4217
		4218	=item watcher invocation
		4219
		4220	The act of calling the callback associated with a watcher.
		4221
		4222	=back
		4223
3969	=head1 AUTHOR	4224	=head1 AUTHOR
3970		4225
3971	Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.	4226	Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
3972		4227

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.244 by root, Mon Jun 29 04:41:34 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.244 by root, Mon Jun 29 04:41:34 2009 UTC