[ViewVC] Diff of: cvs/Linux-AIO/AIO.pm

Comparing Linux-AIO/AIO.pm (file contents):
Revision 1.1 by root, Tue Aug 14 03:18:53 2001 UTC vs.
Revision 1.28 by root, Sat Jul 9 04:11:30 2005 UTC

…		…
6		6
7	use Linux::AIO;	7	use Linux::AIO;
8		8
9	=head1 DESCRIPTION	9	=head1 DESCRIPTION
10		10
		11	This module implements asynchronous I/O using the means available to Linux
		12	- clone. It does not hook into the POSIX aio_* functions because Linux
		13	does not yet support these in the kernel (even as of 2.6.12, only O_DIRECT
		14	files are supported) and even if, it would only allow aio_read and write,
		15	not open, stat and so on.
		16
		17	Instead, in this module a number of (non-posix) threads are started that
		18	execute your read/writes and signal their completion. You don't need
		19	thread support in your libc or perl, and the threads created by this
		20	module will not be visible to the pthreads library.
		21
		22	NOTICE: the threads created by this module will automatically be killed
		23	when the thread calling min_parallel exits. Make sure you only ever call
		24	min_parallel from the same thread that loaded this module.
		25
		26	Although the module will work with in the presence of other threads, it is
		27	not reentrant, so use appropriate locking yourself.
		28
11	=over 4	29	=over 4
12		30
13	=cut	31	=cut
14		32
15	package Linux::AIO;	33	package Linux::AIO;
16		34
		35	use base 'Exporter';
		36
17	BEGIN {	37	BEGIN {
18	$VERSION = 0.001;	38	$VERSION = 1.61;
		39
		40	@EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink);
		41	@EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs);
19		42
20	require XSLoader;	43	require XSLoader;
21	XSLoader::load Linux::AIO, $VERSION;	44	XSLoader::load Linux::AIO, $VERSION;
22	}	45	}
23		46
24	use base 'Exporter';	47	=item Linux::AIO::min_parallel $nthreads
25		48
26	=item Linux::AIO::min_parallel($nthreads)	49	Set the minimum number of AIO threads to C<$nthreads>. The default is
		50	C<1>, which means a single asynchronous operation can be done at one time
		51	(the number of outstanding operations, however, is unlimited).
27		52
		53	It is recommended to keep the number of threads low, as some linux
		54	kernel versions will scale negatively with the number of threads (higher
		55	parallelity => MUCH higher latency).
		56
		57	=item Linux::AIO::max_parallel $nthreads
		58
28	Set the minimum number of AIO threads to $nthreads.	59	Sets the maximum number of AIO threads to C<$nthreads>. If more than
		60	the specified number of threads are currently running, kill them. This
		61	function blocks until the limit is reached.
		62
		63	This module automatically runs C<max_parallel 0> at program end, to ensure
		64	that all threads are killed and that there are no outstanding requests.
		65
		66	=item $fileno = Linux::AIO::poll_fileno
		67
		68	Return the I<request result pipe filehandle>. This filehandle must be
		69	polled for reading by some mechanism outside this module (e.g. Event
		70	or select, see below). If the pipe becomes readable you have to call
		71	C<poll_cb> to check the results.
		72
		73	=item Linux::AIO::poll_cb
		74
		75	Process all outstanding events on the result pipe. You have to call this
		76	regularly. Returns the number of events processed. Returns immediately
		77	when no events are outstanding.
		78
		79	You can use Event to multiplex, e.g.:
		80
		81	Event->io (fd => Linux::AIO::poll_fileno,
		82	poll => 'r', async => 1,
		83	cb => \&Linux::AIO::poll_cb );
		84
		85	=item Linux::AIO::poll_wait
		86
		87	Wait till the result filehandle becomes ready for reading (simply does a
		88	select on the filehandle. This is useful if you want to synchronously wait
		89	for some requests to finish).
		90
		91	=item Linux::AIO::nreqs
		92
		93	Returns the number of requests currently outstanding.
		94
		95	=item aio_open $pathname, $flags, $mode, $callback
		96
		97	Asynchronously open or create a file and call the callback with the
		98	filedescriptor (NOT a perl filehandle, sorry for that, but watch out, this
		99	might change in the future).
		100
		101	=item aio_close $fh, $callback
		102
		103	Asynchronously close a file and call the callback with the result code.
		104
		105	=item aio_read $fh,$offset,$length, $data,$dataoffset,$callback
		106
		107	=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback
		108
		109	Reads or writes C<length> bytes from the specified C<fh> and C<offset>
		110	into the scalar given by C<data> and offset C<dataoffset> and calls the
		111	callback without the actual number of bytes read (or C<undef> on error).
		112
		113	=item aio_stat $fh_or_path, $callback
		114
		115	=item aio_lstat $fh, $callback
		116
		117	Works like perl's C<stat> or C<lstat> in void context. The callback will
		118	be called after the stat and the results will be available using C<stat _>
		119	or C<-s _> etc...
		120
		121	Currently, the stats are always 64-bit-stats, i.e. instead of returning an
		122	error when stat'ing a large file, the results will be silently truncated
		123	unless perl itself is compiled with large file support.
		124
		125	=item aio_unlink $pathname, $callback
		126
		127	Asynchronously unlink a file.
29		128
30	=cut	129	=cut
31		130
32	=item Linux::AIO::read($fh,$offset,$length, $data,$dataoffset,$callback)	131	min_parallel 1;
33	Linux::AIO::write($fh,$offset,$length, $data,$dataoffset,$callback)
34		132
35	Reads or writes C<length> bytes from the specified C<fh> and C<offset>	133	END {
36	into the scalar given by C<data> and offset C<dataoffset> and calls the	134	max_parallel 0;
37	callback without the actual number of bytes read (or undef on error).	135	}
38
39	=cut
40		136
41	1;	137	1;
42		138
43	=back	139	=back
44		140
45	=head1 BUGS	141	=head1 BUGS
46		142
47	This module has not yet been extensively tested. Watch out!	143	This module has been extensively tested in a large and very busy webserver
		144	for many years now.
48		145
49	This module does not use the aio_* posix functions because a) linux does	146	- aio_open gives a fd, but all other functions expect a perl filehandle.
50	not have aio, b) the existing aio_* functions use pthreads, which are too
51	buggy for my usage.
52		147
53	=head1 SEE ALSO	148	=head1 SEE ALSO
54		149
55	L<Coro>.	150	L<Coro>.
56		151
57	=head1 AUTHOR	152	=head1 AUTHOR
58		153
59	Marc Lehmann <pcg@goof.com>	154	Marc Lehmann <schmorp@schmorp.de>
60	http://www.goof.com/pcg/marc/	155	http://home.schmorp.de/
61		156
62	=cut	157	=cut
63		158

Diff Legend

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

Comparing Linux-AIO/AIO.pm (file contents): Revision 1.1 by root, Tue Aug 14 03:18:53 2001 UTC vs. Revision 1.28 by root, Sat Jul 9 04:11:30 2005 UTC

Diff Legend

Comparing Linux-AIO/AIO.pm (file contents):
Revision 1.1 by root, Tue Aug 14 03:18:53 2001 UTC vs.
Revision 1.28 by root, Sat Jul 9 04:11:30 2005 UTC