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

Comparing libev/ev.pod (file contents):
Revision 1.299 by sf-exg, Sat Aug 28 21:42:12 2010 UTC vs.
Revision 1.302 by root, Thu Oct 14 04:23:19 2010 UTC

…		…
2123	Example: Call a callback every hour, or, more precisely, whenever the	2123	Example: Call a callback every hour, or, more precisely, whenever the
2124	system time is divisible by 3600. The callback invocation times have	2124	system time is divisible by 3600. The callback invocation times have
2125	potentially a lot of jitter, but good long-term stability.	2125	potentially a lot of jitter, but good long-term stability.
2126		2126
2127	static void	2127	static void
2128	clock_cb (struct ev_loop loop, ev_io w, int revents)	2128	clock_cb (struct ev_loop loop, ev_periodic w, int revents)
2129	{	2129	{
2130	... its now a full hour (UTC, or TAI or whatever your clock follows)	2130	... its now a full hour (UTC, or TAI or whatever your clock follows)
2131	}	2131	}
2132		2132
2133	ev_periodic hourly_tick;	2133	ev_periodic hourly_tick;
…		…
2965	C<ev_default_fork> cheats and calls it in the wrong process, the fork	2965	C<ev_default_fork> cheats and calls it in the wrong process, the fork
2966	handlers will be invoked, too, of course.	2966	handlers will be invoked, too, of course.
2967		2967
2968	=head3 The special problem of life after fork - how is it possible?	2968	=head3 The special problem of life after fork - how is it possible?
2969		2969
2970	Most uses of C<fork()> consist of forking, then some simple calls to ste	2970	Most uses of C<fork()> consist of forking, then some simple calls to set
2971	up/change the process environment, followed by a call to C<exec()>. This	2971	up/change the process environment, followed by a call to C<exec()>. This
2972	sequence should be handled by libev without any problems.	2972	sequence should be handled by libev without any problems.
2973		2973
2974	This changes when the application actually wants to do event handling	2974	This changes when the application actually wants to do event handling
2975	in the child, or both parent in child, in effect "continuing" after the	2975	in the child, or both parent in child, in effect "continuing" after the
…		…
3009	believe me.	3009	believe me.
3010		3010
3011	=back	3011	=back
3012		3012
3013		3013
3014	=head2 C<ev_async> - how to wake up another event loop	3014	=head2 C<ev_async> - how to wake up an event loop
3015		3015
3016	In general, you cannot use an C<ev_loop> from multiple threads or other	3016	In general, you cannot use an C<ev_loop> from multiple threads or other
3017	asynchronous sources such as signal handlers (as opposed to multiple event	3017	asynchronous sources such as signal handlers (as opposed to multiple event
3018	loops - those are of course safe to use in different threads).	3018	loops - those are of course safe to use in different threads).
3019		3019
3020	Sometimes, however, you need to wake up another event loop you do not	3020	Sometimes, however, you need to wake up an event loop you do not control,
3021	control, for example because it belongs to another thread. This is what	3021	for example because it belongs to another thread. This is what C<ev_async>
3022	C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you	3022	watchers do: as long as the C<ev_async> watcher is active, you can signal
3023	can signal it by calling C<ev_async_send>, which is thread- and signal	3023	it by calling C<ev_async_send>, which is thread- and signal safe.
3024	safe.
3025		3024
3026	This functionality is very similar to C<ev_signal> watchers, as signals,	3025	This functionality is very similar to C<ev_signal> watchers, as signals,
3027	too, are asynchronous in nature, and signals, too, will be compressed	3026	too, are asynchronous in nature, and signals, too, will be compressed
3028	(i.e. the number of callback invocations may be less than the number of	3027	(i.e. the number of callback invocations may be less than the number of
3029	C<ev_async_sent> calls).	3028	C<ev_async_sent> calls).
…		…
4042	will be C<0>.	4041	will be C<0>.
4043		4042
4044	=item EV_COMMON	4043	=item EV_COMMON
4045		4044
4046	By default, all watchers have a C<void *data> member. By redefining	4045	By default, all watchers have a C<void *data> member. By redefining
4047	this macro to a something else you can include more and other types of	4046	this macro to something else you can include more and other types of
4048	members. You have to define it each time you include one of the files,	4047	members. You have to define it each time you include one of the files,
4049	though, and it must be identical each time.	4048	though, and it must be identical each time.
4050		4049
4051	For example, the perl EV module uses something like this:	4050	For example, the perl EV module uses something like this:
4052		4051
…		…
4351	maintainable.	4350	maintainable.
4352		4351
4353	And of course, some compiler warnings are just plain stupid, or simply	4352	And of course, some compiler warnings are just plain stupid, or simply
4354	wrong (because they don't actually warn about the condition their message	4353	wrong (because they don't actually warn about the condition their message
4355	seems to warn about). For example, certain older gcc versions had some	4354	seems to warn about). For example, certain older gcc versions had some
4356	warnings that resulted an extreme number of false positives. These have	4355	warnings that resulted in an extreme number of false positives. These have
4357	been fixed, but some people still insist on making code warn-free with	4356	been fixed, but some people still insist on making code warn-free with
4358	such buggy versions.	4357	such buggy versions.
4359		4358
4360	While libev is written to generate as few warnings as possible,	4359	While libev is written to generate as few warnings as possible,
4361	"warn-free" code is not a goal, and it is recommended not to build libev	4360	"warn-free" code is not a goal, and it is recommended not to build libev
…		…
4396	If you need, for some reason, empty reports from valgrind for your project	4395	If you need, for some reason, empty reports from valgrind for your project
4397	I suggest using suppression lists.	4396	I suggest using suppression lists.
4398		4397
4399		4398
4400	=head1 PORTABILITY NOTES	4399	=head1 PORTABILITY NOTES
		4400
		4401	=head2 GNU/LINUX 32 BIT LIMITATIONS
		4402
		4403	GNU/Linux is the only common platform that supports 64 bit file/large file
		4404	interfaces but disables them by default.
		4405
		4406	That means that libev compiled in the default environment doesn't support
		4407	files larger than 2GiB, which mainly affects C<ev_stat> watchers.
		4408
		4409	Unfortunately, many programs try to work around this GNU/Linux issue
		4410	by enabling the large file API, which makes them incompatible with the
		4411	standard libev compiled for their system.
		4412
		4413	Likewise, libev cannot enable the large file API itself as this would
		4414	suddenly make it incompatible to the default compile time environment,
		4415	i.e. all programs not using special compile switches.
		4416
		4417	=head2 OS/X AND DARWIN BUGS
		4418
		4419	The whole thing is a bug if you ask me - basically any system interface
		4420	you touch is broken, whether it is locales, poll, kqueue or even their
		4421	OpenGL drivers.
		4422
		4423	=over 4
		4424
		4425	=item KQUEUE IS BUGGY
		4426
		4427	The kqueue syscall is broken in all known versions - most versions support
		4428	only sockets, many support pipes.
		4429
		4430	=item POLL IS BUGGY
		4431
		4432	Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
		4433	implementation by something calling C<kqueue> internally around the 10.5.6
		4434	release, so now C<kqueue> I<and> C<poll> are broken.
		4435
		4436	Libev tries to work around this by neither using C<kqueue> nor C<poll> by
		4437	default on this rotten platform, but of course you cna still ask for them
		4438	when creating a loop.
		4439
		4440	=item SELECT IS BUGGY
		4441
		4442	All that's left is C<select>, and of course Apple found a way to fuck this
		4443	one up as well: On OS/X, C<select> actively limits the number of file
		4444	descriptors you can pass in to 1024 - your program suddenyl crashes when
		4445	you use more.
		4446
		4447	There is an undocumented "workaround" for this - defining
		4448	C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
		4449	work on OS/X.
		4450
		4451	=back
		4452
		4453	=head2 SOLARIS PROBLEMS AND WORKAROUNDS
		4454
		4455	=over 4
		4456
		4457	=item C<errno> reentrancy
		4458
		4459	The default compile environment on Solaris is unfortunately so
		4460	thread-unsafe that you can't even use components/libraries compiled
		4461	without C<-D_REENTRANT> (as long as they use C<errno>), which, of course,
		4462	isn't defined by default.
		4463
		4464	If you want to use libev in threaded environments you have to make sure
		4465	it's compiled with C<_REENTRANT> defined.
		4466
		4467	=item Event Port Backend
		4468
		4469	The scalable event interface for Solaris is called "event ports". Unfortunately,
		4470	this mechanism is very buggy. If you run into high CPU usage, your program
		4471	freezes or you get a large number of spurious wakeups, make sure you have
		4472	all the relevant and latest kernel patches applied. No, I don't know which
		4473	ones, but there are multiple ones.
		4474
		4475	If you can't get it to work, you can try running the program with
		4476	C<LIBEV_FLAGS=3> to only allow C<poll> and C<select> backends.
		4477
		4478	=back
		4479
		4480	=head2 AIX POLL BUG
		4481
		4482	AIX unfortunately has a broken C<poll.h> header. Libev works around
		4483	this by trying to avoid the poll backend altogether (i.e. it's not even
		4484	compiled in), which normally isn't a big problem as C<select> works fine
		4485	with large bitsets, and AIX is dead anyway.
4401		4486
4402	=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS	4487	=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
4403		4488
4404	Win32 doesn't support any of the standards (e.g. POSIX) that libev	4489	Win32 doesn't support any of the standards (e.g. POSIX) that libev
4405	requires, and its I/O model is fundamentally incompatible with the POSIX	4490	requires, and its I/O model is fundamentally incompatible with the POSIX

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.299 by sf-exg, Sat Aug 28 21:42:12 2010 UTC vs. Revision 1.302 by root, Thu Oct 14 04:23:19 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.299 by sf-exg, Sat Aug 28 21:42:12 2010 UTC vs.
Revision 1.302 by root, Thu Oct 14 04:23:19 2010 UTC