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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.2 by root, Sun Jul 10 18:16:49 2005 UTC vs.
Revision 1.13 by root, Mon Jul 11 01:49:14 2005 UTC

…		…
3	IO::AIO - Asynchronous Input/Output	3	IO::AIO - Asynchronous Input/Output
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use IO::AIO;	7	use IO::AIO;
		8
		9	aio_open "/etc/passwd", O_RDONLY, 0, sub {
		10	my ($fh) = @_;
		11	...
		12	};
		13
		14	aio_unlink "/tmp/file", sub { };
		15
		16	aio_read $fh, 30000, 1024, $buffer, 0, sub {
		17	$_[0] > 0 or die "read error: $!";
		18	};
		19
		20	# Event
		21	Event->io (fd => IO::AIO::poll_fileno,
		22	poll => 'r',
		23	cb => \&IO::AIO::poll_cb);
		24
		25	# Glib/Gtk2
		26	add_watch Glib::IO IO::AIO::poll_fileno,
		27	\&IO::AIO::poll_cb;
		28
		29	# Tk
		30	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
		31	readable => \&IO::AIO::poll_cb);
		32
		33	# Danga::Socket
		34	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
		35	\&IO::AIO::poll_cb);
		36
8		37
9	=head1 DESCRIPTION	38	=head1 DESCRIPTION
10		39
11	This module implements asynchronous I/O using whatever means your	40	This module implements asynchronous I/O using whatever means your
12	operating system supports.	41	operating system supports.
…		…
21	remaining functionality would have to be implemented using threads anyway.	50	remaining functionality would have to be implemented using threads anyway.
22		51
23	Although the module will work with in the presence of other threads, it is	52	Although the module will work with in the presence of other threads, it is
24	currently not reentrant, so use appropriate locking yourself.	53	currently not reentrant, so use appropriate locking yourself.
25		54
26	=head2 API NOTES	55	=cut
		56
		57	package IO::AIO;
		58
		59	use base 'Exporter';
		60
		61	use Fcntl ();
		62
		63	BEGIN {
		64	$VERSION = 0.3;
		65
		66	@EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
		67	aio_fsync aio_fdatasync aio_readahead);
		68	@EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
		69
		70	require XSLoader;
		71	XSLoader::load IO::AIO, $VERSION;
		72	}
		73
		74	=head1 FUNCTIONS
		75
		76	=head2 AIO FUNCTIONS
27		77
28	All the C<aio_*> calls are more or less thin wrappers around the syscall	78	All the C<aio_*> calls are more or less thin wrappers around the syscall
29	with the same name (sans C<aio_>). The arguments are similar or identical,	79	with the same name (sans C<aio_>). The arguments are similar or identical,
30	and they all accept an additional C<$callback> argument which must be	80	and they all accept an additional C<$callback> argument which must be
31	a code reference. This code reference will get called with the syscall	81	a code reference. This code reference will get called with the syscall
…		…
39	is that at the time the request is being executed, the current working	89	is that at the time the request is being executed, the current working
40	directory could have changed. Alternatively, you can make sure that you	90	directory could have changed. Alternatively, you can make sure that you
41	never change the current working directory.	91	never change the current working directory.
42		92
43	=over 4	93	=over 4
44
45	=cut
46
47	package IO::AIO;
48
49	use base 'Exporter';
50
51	use Fcntl ();
52
53	BEGIN {
54	$VERSION = 0.1;
55
56	@EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
57	aio_fsync aio_fdatasync aio_readahead);
58	@EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs);
59
60	require XSLoader;
61	XSLoader::load IO::AIO, $VERSION;
62	}
63
64	=item IO::AIO::min_parallel $nthreads
65
66	Set the minimum number of AIO threads to C<$nthreads>. The default is
67	C<1>, which means a single asynchronous operation can be done at one time
68	(the number of outstanding operations, however, is unlimited).
69
70	It is recommended to keep the number of threads low, as some linux
71	kernel versions will scale negatively with the number of threads (higher
72	parallelity => MUCH higher latency).
73
74	Under normal circumstances you don't need to call this function, as this
75	module automatically starts a single async thread.
76
77	=item IO::AIO::max_parallel $nthreads
78
79	Sets the maximum number of AIO threads to C<$nthreads>. If more than
80	the specified number of threads are currently running, kill them. This
81	function blocks until the limit is reached.
82
83	This module automatically runs C<max_parallel 0> at program end, to ensure
84	that all threads are killed and that there are no outstanding requests.
85
86	Under normal circumstances you don't need to call this function.
87
88	=item $fileno = IO::AIO::poll_fileno
89
90	Return the I<request result pipe filehandle>. This filehandle must be
91	polled for reading by some mechanism outside this module (e.g. Event
92	or select, see below). If the pipe becomes readable you have to call
93	C<poll_cb> to check the results.
94
95	See C<poll_cb> for an example.
96
97	=item IO::AIO::poll_cb
98
99	Process all outstanding events on the result pipe. You have to call this
100	regularly. Returns the number of events processed. Returns immediately
101	when no events are outstanding.
102
103	You can use Event to multiplex, e.g.:
104
105	Event->io (fd => IO::AIO::poll_fileno,
106	poll => 'r', async => 1,
107	cb => \&IO::AIO::poll_cb);
108
109	=item IO::AIO::poll_wait
110
111	Wait till the result filehandle becomes ready for reading (simply does a
112	select on the filehandle. This is useful if you want to synchronously wait
113	for some requests to finish).
114
115	See C<nreqs> for an example.
116
117	=item IO::AIO::nreqs
118
119	Returns the number of requests currently outstanding.
120
121	Example: wait till there are no outstanding requests anymore:
122
123	IO::AIO::poll_wait, IO::AIO::poll_cb
124	while IO::AIO::nreqs;
125		94
126	=item aio_open $pathname, $flags, $mode, $callback	95	=item aio_open $pathname, $flags, $mode, $callback
127		96
128	Asynchronously open or create a file and call the callback with a newly	97	Asynchronously open or create a file and call the callback with a newly
129	created filehandle for the file.	98	created filehandle for the file.
…		…
164		133
165	Example: Read 15 bytes at offset 7 into scalar C<$buffer>, strating at	134	Example: Read 15 bytes at offset 7 into scalar C<$buffer>, strating at
166	offset C<0> within the scalar:	135	offset C<0> within the scalar:
167		136
168	aio_read $fh, 7, 15, $buffer, 0, sub {	137	aio_read $fh, 7, 15, $buffer, 0, sub {
169	$_[0] >= 0 or die "read error: $!";	138	$_[0] > 0 or die "read error: $!";
170	print "read <$buffer>\n";	139	print "read $_[0] bytes: <$buffer>\n";
171	};	140	};
172		141
173	=item aio_readahead $fh,$offset,$length, $callback	142	=item aio_readahead $fh,$offset,$length, $callback
174		143
175	Asynchronously reads the specified byte range into the page cache, using	144	Asynchronously reads the specified byte range into the page cache, using
…		…
220	=item aio_fdatasync $fh, $callback	189	=item aio_fdatasync $fh, $callback
221		190
222	Asynchronously call fdatasync on the given filehandle and call the	191	Asynchronously call fdatasync on the given filehandle and call the
223	callback with the fdatasync result code.	192	callback with the fdatasync result code.
224		193
		194	=back
		195
		196	=head2 SUPPORT FUNCTIONS
		197
		198	=over 4
		199
		200	=item $fileno = IO::AIO::poll_fileno
		201
		202	Return the I<request result pipe filehandle>. This filehandle must be
		203	polled for reading by some mechanism outside this module (e.g. Event
		204	or select, see below). If the pipe becomes readable you have to call
		205	C<poll_cb> to check the results.
		206
		207	See C<poll_cb> for an example.
		208
		209	=item IO::AIO::poll_cb
		210
		211	Process all outstanding events on the result pipe. You have to call this
		212	regularly. Returns the number of events processed. Returns immediately
		213	when no events are outstanding.
		214
		215	You can use Event to multiplex, e.g.:
		216
		217	Event->io (fd => IO::AIO::poll_fileno,
		218	poll => 'r', async => 1,
		219	cb => \&IO::AIO::poll_cb);
		220
		221	=item IO::AIO::poll_wait
		222
		223	Wait till the result filehandle becomes ready for reading (simply does a
		224	select on the filehandle. This is useful if you want to synchronously wait
		225	for some requests to finish).
		226
		227	See C<nreqs> for an example.
		228
		229	=item IO::AIO::nreqs
		230
		231	Returns the number of requests currently outstanding.
		232
		233	Example: wait till there are no outstanding requests anymore:
		234
		235	IO::AIO::poll_wait, IO::AIO::poll_cb
		236	while IO::AIO::nreqs;
		237
		238	=item IO::AIO::flush
		239
		240	Wait till all outstanding AIO requests have been handled.
		241
		242	Strictly equivalent to:
		243
		244	IO::AIO::poll_wait, IO::AIO::poll_cb
		245	while IO::AIO::nreqs;
		246
		247	=item IO::AIO::poll
		248
		249	Waits until some requests have been handled.
		250
		251	Strictly equivalent to:
		252
		253	IO::AIO::poll_wait, IO::AIO::poll_cb
		254	if IO::AIO::nreqs;
		255
		256	=item IO::AIO::min_parallel $nthreads
		257
		258	Set the minimum number of AIO threads to C<$nthreads>. The default is
		259	C<1>, which means a single asynchronous operation can be done at one time
		260	(the number of outstanding operations, however, is unlimited).
		261
		262	It is recommended to keep the number of threads low, as some Linux
		263	kernel versions will scale negatively with the number of threads (higher
		264	parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
		265	threads should be fine.
		266
		267	Under normal circumstances you don't need to call this function, as this
		268	module automatically starts some threads (the exact number might change,
		269	and is currently 4).
		270
		271	=item IO::AIO::max_parallel $nthreads
		272
		273	Sets the maximum number of AIO threads to C<$nthreads>. If more than
		274	the specified number of threads are currently running, kill them. This
		275	function blocks until the limit is reached.
		276
		277	This module automatically runs C<max_parallel 0> at program end, to ensure
		278	that all threads are killed and that there are no outstanding requests.
		279
		280	Under normal circumstances you don't need to call this function.
		281
		282	=item $oldnreqs = IO::AIO::max_outstanding $nreqs
		283
		284	Sets the maximum number of outstanding requests to C<$nreqs>. If you
		285	try to queue up more than this number of requests, the caller will block until
		286	some requests have been handled.
		287
		288	The default is very large, so normally there is no practical limit. If you
		289	queue up many requests in a loop it it often improves speed if you set
		290	this to a relatively low number, such as C<100>.
		291
		292	Under normal circumstances you don't need to call this function.
		293
		294	=back
		295
225	=cut	296	=cut
226		297
227	# support function to convert a fd into a perl filehandle	298	# support function to convert a fd into a perl filehandle
228	sub _fd2fh {	299	sub _fd2fh {
229	return undef if $_[0] < 0;	300	return undef if $_[0] < 0;
…		…
242	max_parallel 0;	313	max_parallel 0;
243	}	314	}
244		315
245	1;	316	1;
246		317
247	=back
248
249	=head1 BUGS
250
251	- could be optimized to use more semaphores instead of filehandles.
252
253	=head1 SEE ALSO	318	=head1 SEE ALSO
254		319
255	L<Coro>, L<Linux::AIO>.	320	L<Coro>, L<Linux::AIO>.
256		321
257	=head1 AUTHOR	322	=head1 AUTHOR

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.2 by root, Sun Jul 10 18:16:49 2005 UTC vs. Revision 1.13 by root, Mon Jul 11 01:49:14 2005 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.2 by root, Sun Jul 10 18:16:49 2005 UTC vs.
Revision 1.13 by root, Mon Jul 11 01:49:14 2005 UTC