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

Comparing libev/ev.pod (file contents):
Revision 1.302 by root, Thu Oct 14 04:23:19 2010 UTC vs.
Revision 1.307 by root, Thu Oct 21 02:33:08 2010 UTC

Diff Legend

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

…		…
439	of course I<doesn't>, and epoll just loves to report events for totally	439	of course I<doesn't>, and epoll just loves to report events for totally
440	I<different> file descriptors (even already closed ones, so one cannot	440	I<different> file descriptors (even already closed ones, so one cannot
441	even remove them from the set) than registered in the set (especially	441	even remove them from the set) than registered in the set (especially
442	on SMP systems). Libev tries to counter these spurious notifications by	442	on SMP systems). Libev tries to counter these spurious notifications by
443	employing an additional generation counter and comparing that against the	443	employing an additional generation counter and comparing that against the
444	events to filter out spurious ones, recreating the set when required.	444	events to filter out spurious ones, recreating the set when required. Last
		445	not least, it also refuses to work with some file descriptors which work
		446	perfectly fine with C<select> (files, many character devices...).
445		447
446	While stopping, setting and starting an I/O watcher in the same iteration	448	While stopping, setting and starting an I/O watcher in the same iteration
447	will result in some caching, there is still a system call per such	449	will result in some caching, there is still a system call per such
448	incident (because the same I<file descriptor> could point to a different	450	incident (because the same I<file descriptor> could point to a different
449	I<file description> now), so its best to avoid that. Also, C<dup ()>'ed	451	I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
…		…
3389	Associates a different C<struct ev_loop> with this watcher. You can only	3391	Associates a different C<struct ev_loop> with this watcher. You can only
3390	do this when the watcher is inactive (and not pending either).	3392	do this when the watcher is inactive (and not pending either).
3391		3393
3392	=item w->set ([arguments])	3394	=item w->set ([arguments])
3393		3395
3394	Basically the same as C<ev_TYPE_set>, with the same arguments. Must be	3396	Basically the same as C<ev_TYPE_set>, with the same arguments. Either this
3395	called at least once. Unlike the C counterpart, an active watcher gets	3397	method or a suitable start method must be called at least once. Unlike the
3396	automatically stopped and restarted when reconfiguring it with this	3398	C counterpart, an active watcher gets automatically stopped and restarted
3397	method.	3399	when reconfiguring it with this method.
3398		3400
3399	=item w->start ()	3401	=item w->start ()
3400		3402
3401	Starts the watcher. Note that there is no C<loop> argument, as the	3403	Starts the watcher. Note that there is no C<loop> argument, as the
3402	constructor already stores the event loop.	3404	constructor already stores the event loop.
3403		3405
		3406	=item w->start ([arguments])
		3407
		3408	Instead of calling C<set> and C<start> methods separately, it is often
		3409	convenient to wrap them in one call. Uses the same type of arguments as
		3410	the configure C<set> method of the watcher.
		3411
3404	=item w->stop ()	3412	=item w->stop ()
3405		3413
3406	Stops the watcher if it is active. Again, no C<loop> argument.	3414	Stops the watcher if it is active. Again, no C<loop> argument.
3407		3415
3408	=item w->again () (C<ev::timer>, C<ev::periodic> only)	3416	=item w->again () (C<ev::timer>, C<ev::periodic> only)
…		…
3420		3428
3421	=back	3429	=back
3422		3430
3423	=back	3431	=back
3424		3432
3425	Example: Define a class with an IO and idle watcher, start one of them in	3433	Example: Define a class with two I/O and idle watchers, start the I/O
3426	the constructor.	3434	watchers in the constructor.
3427		3435
3428	class myclass	3436	class myclass
3429	{	3437	{
3430	ev::io io ; void io_cb (ev::io &w, int revents);	3438	ev::io io ; void io_cb (ev::io &w, int revents);
		3439	ev::io2 io2 ; void io2_cb (ev::io &w, int revents);
3431	ev::idle idle; void idle_cb (ev::idle &w, int revents);	3440	ev::idle idle; void idle_cb (ev::idle &w, int revents);
3432		3441
3433	myclass (int fd)	3442	myclass (int fd)
3434	{	3443	{
3435	io .set <myclass, &myclass::io_cb > (this);	3444	io .set <myclass, &myclass::io_cb > (this);
		3445	io2 .set <myclass, &myclass::io2_cb > (this);
3436	idle.set <myclass, &myclass::idle_cb> (this);	3446	idle.set <myclass, &myclass::idle_cb> (this);
3437		3447
3438	io.start (fd, ev::READ);	3448	io.set (fd, ev::WRITE); // configure the watcher
		3449	io.start (); // start it whenever convenient
		3450
		3451	io2.start (fd, ev::READ); // set + start in one call
3439	}	3452	}
3440	};	3453	};
3441		3454
3442		3455
3443	=head1 OTHER LANGUAGE BINDINGS	3456	=head1 OTHER LANGUAGE BINDINGS
…		…
4399	=head1 PORTABILITY NOTES	4412	=head1 PORTABILITY NOTES
4400		4413
4401	=head2 GNU/LINUX 32 BIT LIMITATIONS	4414	=head2 GNU/LINUX 32 BIT LIMITATIONS
4402		4415
4403	GNU/Linux is the only common platform that supports 64 bit file/large file	4416	GNU/Linux is the only common platform that supports 64 bit file/large file
4404	interfaces but disables them by default.	4417	interfaces but I<disables> them by default.
4405		4418
4406	That means that libev compiled in the default environment doesn't support	4419	That means that libev compiled in the default environment doesn't support
4407	files larger than 2GiB, which mainly affects C<ev_stat> watchers.	4420	files larger than 2GiB or so, which mainly affects C<ev_stat> watchers.
4408		4421
4409	Unfortunately, many programs try to work around this GNU/Linux issue	4422	Unfortunately, many programs try to work around this GNU/Linux issue
4410	by enabling the large file API, which makes them incompatible with the	4423	by enabling the large file API, which makes them incompatible with the
4411	standard libev compiled for their system.	4424	standard libev compiled for their system.
4412		4425
…		…
4415	i.e. all programs not using special compile switches.	4428	i.e. all programs not using special compile switches.
4416		4429
4417	=head2 OS/X AND DARWIN BUGS	4430	=head2 OS/X AND DARWIN BUGS
4418		4431
4419	The whole thing is a bug if you ask me - basically any system interface	4432	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	4433	you touch is broken, whether it is locales, poll, kqueue or even the
4421	OpenGL drivers.	4434	OpenGL drivers.
4422		4435
4423	=over 4	4436	=head3 C<kqueue> is buggy
4424
4425	=item KQUEUE IS BUGGY
4426		4437
4427	The kqueue syscall is broken in all known versions - most versions support	4438	The kqueue syscall is broken in all known versions - most versions support
4428	only sockets, many support pipes.	4439	only sockets, many support pipes.
4429		4440
4430	=item POLL IS BUGGY	4441	Libev tries to work around this by not using C<kqueue> by default on
		4442	this rotten platform, but of course you can still ask for it when creating
		4443	a loop.
		4444
		4445	=head3 C<poll> is buggy
4431		4446
4432	Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>	4447	Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
4433	implementation by something calling C<kqueue> internally around the 10.5.6	4448	implementation by something calling C<kqueue> internally around the 10.5.6
4434	release, so now C<kqueue> I<and> C<poll> are broken.	4449	release, so now C<kqueue> I<and> C<poll> are broken.
4435		4450
4436	Libev tries to work around this by neither using C<kqueue> nor C<poll> by	4451	Libev tries to work around this by not using C<poll> by default on
4437	default on this rotten platform, but of course you cna still ask for them	4452	this rotten platform, but of course you can still ask for it when creating
4438	when creating a loop.	4453	a loop.
4439		4454
4440	=item SELECT IS BUGGY	4455	=head3 C<select> is buggy
4441		4456
4442	All that's left is C<select>, and of course Apple found a way to fuck this	4457	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	4458	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	4459	descriptors you can pass in to 1024 - your program suddenly crashes when
4445	you use more.	4460	you use more.
4446		4461
4447	There is an undocumented "workaround" for this - defining	4462	There is an undocumented "workaround" for this - defining
4448	C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>	4463	C<_DARWIN_UNLIMITED_SELECT>, which libev tries to use, so select I<should>
4449	work on OS/X.	4464	work on OS/X.
4450		4465
4451	=back
4452
4453	=head2 SOLARIS PROBLEMS AND WORKAROUNDS	4466	=head2 SOLARIS PROBLEMS AND WORKAROUNDS
4454		4467
4455	=over 4
4456
4457	=item C<errno> reentrancy	4468	=head3 C<errno> reentrancy
4458		4469
4459	The default compile environment on Solaris is unfortunately so	4470	The default compile environment on Solaris is unfortunately so
4460	thread-unsafe that you can't even use components/libraries compiled	4471	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,	4472	without C<-D_REENTRANT> (as long as they use C<errno>), which, of course,
4462	isn't defined by default.	4473	isn't defined by default.
4463		4474
4464	If you want to use libev in threaded environments you have to make sure	4475	If you want to use libev in threaded environments you have to make sure
4465	it's compiled with C<_REENTRANT> defined.	4476	it's compiled with C<_REENTRANT> defined.
4466		4477
4467	=item Event Port Backend	4478	=head3 Event port backend
4468		4479
4469	The scalable event interface for Solaris is called "event ports". Unfortunately,	4480	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	4481	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	4482	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	4483	all the relevant and latest kernel patches applied. No, I don't know which
4473	ones, but there are multiple ones.	4484	ones, but there are multiple ones.
4474		4485
4475	If you can't get it to work, you can try running the program with	4486	If you can't get it to work, you can try running the program by setting
4476	C<LIBEV_FLAGS=3> to only allow C<poll> and C<select> backends.	4487	the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and
4477		4488	C<select> backends.
4478	=back
4479		4489
4480	=head2 AIX POLL BUG	4490	=head2 AIX POLL BUG
4481		4491
4482	AIX unfortunately has a broken C<poll.h> header. Libev works around	4492	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	4493	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	4494	compiled in), which normally isn't a big problem as C<select> works fine
4485	with large bitsets, and AIX is dead anyway.	4495	with large bitsets, and AIX is dead anyway.
4486		4496
4487	=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS	4497	=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
		4498
		4499	=head3 General issues
4488		4500
4489	Win32 doesn't support any of the standards (e.g. POSIX) that libev	4501	Win32 doesn't support any of the standards (e.g. POSIX) that libev
4490	requires, and its I/O model is fundamentally incompatible with the POSIX	4502	requires, and its I/O model is fundamentally incompatible with the POSIX
4491	model. Libev still offers limited functionality on this platform in	4503	model. Libev still offers limited functionality on this platform in
4492	the form of the C<EVBACKEND_SELECT> backend, and only supports socket	4504	the form of the C<EVBACKEND_SELECT> backend, and only supports socket
4493	descriptors. This only applies when using Win32 natively, not when using	4505	descriptors. This only applies when using Win32 natively, not when using
4494	e.g. cygwin.	4506	e.g. cygwin. Actually, it only applies to the microsofts own compilers,
		4507	as every compielr comes with a slightly differently broken/incompatible
		4508	environment.
4495		4509
4496	Lifting these limitations would basically require the full	4510	Lifting these limitations would basically require the full
4497	re-implementation of the I/O system. If you are into these kinds of	4511	re-implementation of the I/O system. If you are into this kind of thing,
4498	things, then note that glib does exactly that for you in a very portable	4512	then note that glib does exactly that for you in a very portable way (note
4499	way (note also that glib is the slowest event library known to man).	4513	also that glib is the slowest event library known to man).
4500		4514
4501	There is no supported compilation method available on windows except	4515	There is no supported compilation method available on windows except
4502	embedding it into other applications.	4516	embedding it into other applications.
4503		4517
4504	Sensible signal handling is officially unsupported by Microsoft - libev	4518	Sensible signal handling is officially unsupported by Microsoft - libev
…		…
4532	you do I<not> compile the F<ev.c> or any other embedded source files!):	4546	you do I<not> compile the F<ev.c> or any other embedded source files!):
4533		4547
4534	#include "evwrap.h"	4548	#include "evwrap.h"
4535	#include "ev.c"	4549	#include "ev.c"
4536		4550
4537	=over 4
4538
4539	=item The winsocket select function	4551	=head3 The winsocket C<select> function
4540		4552
4541	The winsocket C<select> function doesn't follow POSIX in that it	4553	The winsocket C<select> function doesn't follow POSIX in that it
4542	requires socket I<handles> and not socket I<file descriptors> (it is	4554	requires socket I<handles> and not socket I<file descriptors> (it is
4543	also extremely buggy). This makes select very inefficient, and also	4555	also extremely buggy). This makes select very inefficient, and also
4544	requires a mapping from file descriptors to socket handles (the Microsoft	4556	requires a mapping from file descriptors to socket handles (the Microsoft
…		…
4553	#define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */	4565	#define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
4554		4566
4555	Note that winsockets handling of fd sets is O(n), so you can easily get a	4567	Note that winsockets handling of fd sets is O(n), so you can easily get a
4556	complexity in the O(n²) range when using win32.	4568	complexity in the O(n²) range when using win32.
4557		4569
4558	=item Limited number of file descriptors	4570	=head3 Limited number of file descriptors
4559		4571
4560	Windows has numerous arbitrary (and low) limits on things.	4572	Windows has numerous arbitrary (and low) limits on things.
4561		4573
4562	Early versions of winsocket's select only supported waiting for a maximum	4574	Early versions of winsocket's select only supported waiting for a maximum
4563	of C<64> handles (probably owning to the fact that all windows kernels	4575	of C<64> handles (probably owning to the fact that all windows kernels
…		…
4578	runtime libraries. This might get you to about C<512> or C<2048> sockets	4590	runtime libraries. This might get you to about C<512> or C<2048> sockets
4579	(depending on windows version and/or the phase of the moon). To get more,	4591	(depending on windows version and/or the phase of the moon). To get more,
4580	you need to wrap all I/O functions and provide your own fd management, but	4592	you need to wrap all I/O functions and provide your own fd management, but
4581	the cost of calling select (O(n²)) will likely make this unworkable.	4593	the cost of calling select (O(n²)) will likely make this unworkable.
4582		4594
4583	=back
4584
4585	=head2 PORTABILITY REQUIREMENTS	4595	=head2 PORTABILITY REQUIREMENTS
4586		4596
4587	In addition to a working ISO-C implementation and of course the	4597	In addition to a working ISO-C implementation and of course the
4588	backend-specific APIs, libev relies on a few additional extensions:	4598	backend-specific APIs, libev relies on a few additional extensions:
4589		4599

Comparing libev/ev.pod (file contents): Revision 1.302 by root, Thu Oct 14 04:23:19 2010 UTC vs. Revision 1.307 by root, Thu Oct 21 02:33:08 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.302 by root, Thu Oct 14 04:23:19 2010 UTC vs.
Revision 1.307 by root, Thu Oct 21 02:33:08 2010 UTC