[ViewVC] Diff of: cvs/IO-AIO/README

Comparing IO-AIO/README (file contents):
Revision 1.2 by root, Sun Jul 10 18:16:49 2005 UTC vs.
Revision 1.9 by root, Tue Aug 16 23:33:38 2005 UTC

…		…
1	NAME	1	NAME
2	IO::AIO - Asynchronous Input/Output	2	IO::AIO - Asynchronous Input/Output
3		3
4	SYNOPSIS	4	SYNOPSIS
5	use IO::AIO;	5	use IO::AIO;
		6
		7	aio_open "/etc/passwd", O_RDONLY, 0, sub {
		8	my ($fh) = @_;
		9	...
		10	};
		11
		12	aio_unlink "/tmp/file", sub { };
		13
		14	aio_read $fh, 30000, 1024, $buffer, 0, sub {
		15	$_[0] > 0 or die "read error: $!";
		16	};
		17
		18	# Event
		19	Event->io (fd => IO::AIO::poll_fileno,
		20	poll => 'r',
		21	cb => \&IO::AIO::poll_cb);
		22
		23	# Glib/Gtk2
		24	add_watch Glib::IO IO::AIO::poll_fileno,
		25	in => sub { IO::AIO::poll_cb; 1 };
		26
		27	# Tk
		28	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
		29	readable => \&IO::AIO::poll_cb);
		30
		31	# Danga::Socket
		32	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
		33	\&IO::AIO::poll_cb);
6		34
7	DESCRIPTION	35	DESCRIPTION
8	This module implements asynchronous I/O using whatever means your	36	This module implements asynchronous I/O using whatever means your
9	operating system supports.	37	operating system supports.
10		38
17	currently, for example), and they would only support aio_read and	45	currently, for example), and they would only support aio_read and
18	aio_write, so the remaining functionality would have to be implemented	46	aio_write, so the remaining functionality would have to be implemented
19	using threads anyway.	47	using threads anyway.
20		48
21	Although the module will work with in the presence of other threads, it	49	Although the module will work with in the presence of other threads, it
22	is currently not reentrant, so use appropriate locking yourself.	50	is currently not reentrant, so use appropriate locking yourself, always
		51	call "poll_cb" from within the same thread, or never call "poll_cb" (or
		52	other "aio_" functions) recursively.
23		53
24	API NOTES	54	FUNCTIONS
		55	AIO FUNCTIONS
25	All the "aio_*" calls are more or less thin wrappers around the syscall	56	All the "aio_*" calls are more or less thin wrappers around the syscall
26	with the same name (sans "aio_"). The arguments are similar or	57	with the same name (sans "aio_"). The arguments are similar or
27	identical, and they all accept an additional $callback argument which	58	identical, and they all accept an additional (and optional) $callback
28	must be a code reference. This code reference will get called with the	59	argument which must be a code reference. This code reference will get
29	syscall return code (e.g. most syscalls return -1 on error, unlike perl,	60	called with the syscall return code (e.g. most syscalls return -1 on
30	which usually delivers "false") as it's sole argument when the given	61	error, unlike perl, which usually delivers "false") as it's sole
31	syscall has been executed asynchronously.	62	argument when the given syscall has been executed asynchronously.
32		63
33	All functions that expect a filehandle will also accept a file	64	All functions expecting a filehandle keep a copy of the filehandle
34	descriptor.	65	internally until the request has finished.
35		66
36	The filenames you pass to these routines must be absolute. The reason	67	The pathnames you pass to these routines must be absolute and encoded
37	is that at the time the request is being executed, the current working	68	in byte form. The reason for the former is that at the time the request
38	directory could have changed. Alternatively, you can make sure that you	69	is being executed, the current working directory could have changed.
39	never change the current working directory.	70	Alternatively, you can make sure that you never change the current
		71	working directory.
40		72
41	IO::AIO::min_parallel $nthreads	73	To encode pathnames to byte form, either make sure you either: a) always
42	Set the minimum number of AIO threads to $nthreads. The default is	74	pass in filenames you got from outside (command line, readdir etc.), b)
43	1, which means a single asynchronous operation can be done at one	75	are ASCII or ISO 8859-1, c) use the Encode module and encode your
44	time (the number of outstanding operations, however, is unlimited).	76	pathnames to the locale (or other) encoding in effect in the user
45		77	environment, d) use Glib::filename_from_unicode on unicode filenames or
46	It is recommended to keep the number of threads low, as some linux	78	e) use something else.
47	kernel versions will scale negatively with the number of threads
48	(higher parallelity => MUCH higher latency).
49
50	Under normal circumstances you don't need to call this function, as
51	this module automatically starts a single async thread.
52
53	IO::AIO::max_parallel $nthreads
54	Sets the maximum number of AIO threads to $nthreads. If more than
55	the specified number of threads are currently running, kill them.
56	This function blocks until the limit is reached.
57
58	This module automatically runs "max_parallel 0" at program end, to
59	ensure that all threads are killed and that there are no outstanding
60	requests.
61
62	Under normal circumstances you don't need to call this function.
63
64	$fileno = IO::AIO::poll_fileno
65	Return the request result pipe filehandle. This filehandle must be
66	polled for reading by some mechanism outside this module (e.g. Event
67	or select, see below). If the pipe becomes readable you have to call
68	"poll_cb" to check the results.
69
70	See "poll_cb" for an example.
71
72	IO::AIO::poll_cb
73	Process all outstanding events on the result pipe. You have to call
74	this regularly. Returns the number of events processed. Returns
75	immediately when no events are outstanding.
76
77	You can use Event to multiplex, e.g.:
78
79	Event->io (fd => IO::AIO::poll_fileno,
80	poll => 'r', async => 1,
81	cb => \&IO::AIO::poll_cb);
82
83	IO::AIO::poll_wait
84	Wait till the result filehandle becomes ready for reading (simply
85	does a select on the filehandle. This is useful if you want to
86	synchronously wait for some requests to finish).
87
88	See "nreqs" for an example.
89
90	IO::AIO::nreqs
91	Returns the number of requests currently outstanding.
92
93	Example: wait till there are no outstanding requests anymore:
94
95	IO::AIO::poll_wait, IO::AIO::poll_cb
96	while IO::AIO::nreqs;
97		79
98	aio_open $pathname, $flags, $mode, $callback	80	aio_open $pathname, $flags, $mode, $callback
99	Asynchronously open or create a file and call the callback with a	81	Asynchronously open or create a file and call the callback with a
100	newly created filehandle for the file.	82	newly created filehandle for the file.
101		83
102	The pathname passed to "aio_open" must be absolute. See API NOTES,	84	The pathname passed to "aio_open" must be absolute. See API NOTES,
103	above, for an explanation.	85	above, for an explanation.
104		86
105	The $mode argument is a bitmask. See the "Fcntl" module for a list.	87	The $flags argument is a bitmask. See the "Fcntl" module for a list.
106	They are the same as used in "sysopen".	88	They are the same as used by "sysopen".
		89
		90	Likewise, $mode specifies the mode of the newly created file, if it
		91	didn't exist and "O_CREAT" has been given, just like perl's
		92	"sysopen", except that it is mandatory (i.e. use 0 if you don't
		93	create new files, and 0666 or 0777 if you do).
107		94
108	Example:	95	Example:
109		96
110	aio_open "/etc/passwd", O_RDONLY, 0, sub {	97	aio_open "/etc/passwd", O_RDONLY, 0, sub {
111	if ($_[0]) {	98	if ($_[0]) {
…		…
118		105
119	aio_close $fh, $callback	106	aio_close $fh, $callback
120	Asynchronously close a file and call the callback with the result	107	Asynchronously close a file and call the callback with the result
121	code. WARNING: although accepted, you should not pass in a perl	108	code. WARNING: although accepted, you should not pass in a perl
122	filehandle here, as perl will likely close the file descriptor	109	filehandle here, as perl will likely close the file descriptor
123	itself when the filehandle is destroyed. Normally, you can safely	110	another time when the filehandle is destroyed. Normally, you can
124	call perls "close" or just let filehandles go out of scope.	111	safely call perls "close" or just let filehandles go out of scope.
		112
		113	This is supposed to be a bug in the API, so that might change. It's
		114	therefore best to avoid this function.
125		115
126	aio_read $fh,$offset,$length, $data,$dataoffset,$callback	116	aio_read $fh,$offset,$length, $data,$dataoffset,$callback
127	aio_write $fh,$offset,$length, $data,$dataoffset,$callback	117	aio_write $fh,$offset,$length, $data,$dataoffset,$callback
128	Reads or writes "length" bytes from the specified "fh" and "offset"	118	Reads or writes "length" bytes from the specified "fh" and "offset"
129	into the scalar given by "data" and offset "dataoffset" and calls	119	into the scalar given by "data" and offset "dataoffset" and calls
130	the callback without the actual number of bytes read (or -1 on	120	the callback without the actual number of bytes read (or -1 on
131	error, just like the syscall).	121	error, just like the syscall).
132		122
133	Example: Read 15 bytes at offset 7 into scalar $buffer, strating at	123	Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
134	offset 0 within the scalar:	124	offset 0 within the scalar:
135		125
136	aio_read $fh, 7, 15, $buffer, 0, sub {	126	aio_read $fh, 7, 15, $buffer, 0, sub {
137	$_[0] >= 0 or die "read error: $!";	127	$_[0] > 0 or die "read error: $!";
138	print "read <$buffer>\n";	128	print "read $_[0] bytes: <$buffer>\n";
139	};	129	};
140		130
141	aio_readahead $fh,$offset,$length, $callback	131	aio_readahead $fh,$offset,$length, $callback
142	Asynchronously reads the specified byte range into the page cache,
143	using the "readahead" syscall. If that syscall doesn't exist the
144	status will be -1 and $! is set to ENOSYS.
145
146	readahead() populates the page cache with data from a file so that	132	"aio_readahead" populates the page cache with data from a file so
147	subsequent reads from that file will not block on disk I/O. The	133	that subsequent reads from that file will not block on disk I/O. The
148	$offset argument specifies the starting point from which data is to	134	$offset argument specifies the starting point from which data is to
149	be read and $length specifies the number of bytes to be read. I/O is	135	be read and $length specifies the number of bytes to be read. I/O is
150	performed in whole pages, so that offset is effectively rounded down	136	performed in whole pages, so that offset is effectively rounded down
151	to a page boundary and bytes are read up to the next page boundary	137	to a page boundary and bytes are read up to the next page boundary
152	greater than or equal to (off-set+length). aio_readahead() does not	138	greater than or equal to (off-set+length). "aio_readahead" does not
153	read beyond the end of the file. The current file offset of the file	139	read beyond the end of the file. The current file offset of the file
154	is left unchanged.	140	is left unchanged.
		141
		142	If that syscall doesn't exist (likely if your OS isn't Linux) it
		143	will be emulated by simply reading the data, which would have a
		144	similar effect.
155		145
156	aio_stat $fh_or_path, $callback	146	aio_stat $fh_or_path, $callback
157	aio_lstat $fh, $callback	147	aio_lstat $fh, $callback
158	Works like perl's "stat" or "lstat" in void context. The callback	148	Works like perl's "stat" or "lstat" in void context. The callback
159	will be called after the stat and the results will be available	149	will be called after the stat and the results will be available
…		…
176		166
177	aio_unlink $pathname, $callback	167	aio_unlink $pathname, $callback
178	Asynchronously unlink (delete) a file and call the callback with the	168	Asynchronously unlink (delete) a file and call the callback with the
179	result code.	169	result code.
180		170
		171	aio_rmdir $pathname, $callback
		172	Asynchronously rmdir (delete) a directory and call the callback with
		173	the result code.
		174
181	aio_fsync $fh, $callback	175	aio_fsync $fh, $callback
182	Asynchronously call fsync on the given filehandle and call the	176	Asynchronously call fsync on the given filehandle and call the
183	callback with the fsync result code.	177	callback with the fsync result code.
184		178
185	aio_fdatasync $fh, $callback	179	aio_fdatasync $fh, $callback
186	Asynchronously call fdatasync on the given filehandle and call the	180	Asynchronously call fdatasync on the given filehandle and call the
187	callback with the fdatasync result code.	181	callback with the fdatasync result code.
188		182
189	BUGS	183	If this call isn't available because your OS lacks it or it couldn't
190	- could be optimized to use more semaphores instead of filehandles.	184	be detected, it will be emulated by calling "fsync" instead.
		185
		186	SUPPORT FUNCTIONS
		187	$fileno = IO::AIO::poll_fileno
		188	Return the request result pipe file descriptor. This filehandle
		189	must be polled for reading by some mechanism outside this module
		190	(e.g. Event or select, see below or the SYNOPSIS). If the pipe
		191	becomes readable you have to call "poll_cb" to check the results.
		192
		193	See "poll_cb" for an example.
		194
		195	IO::AIO::poll_cb
		196	Process all outstanding events on the result pipe. You have to call
		197	this regularly. Returns the number of events processed. Returns
		198	immediately when no events are outstanding.
		199
		200	Example: Install an Event watcher that automatically calls
		201	IO::AIO::poll_cb with high priority:
		202
		203	Event->io (fd => IO::AIO::poll_fileno,
		204	poll => 'r', async => 1,
		205	cb => \&IO::AIO::poll_cb);
		206
		207	IO::AIO::poll_wait
		208	Wait till the result filehandle becomes ready for reading (simply
		209	does a "select" on the filehandle. This is useful if you want to
		210	synchronously wait for some requests to finish).
		211
		212	See "nreqs" for an example.
		213
		214	IO::AIO::nreqs
		215	Returns the number of requests currently outstanding (i.e. for which
		216	their callback has not been invoked yet).
		217
		218	Example: wait till there are no outstanding requests anymore:
		219
		220	IO::AIO::poll_wait, IO::AIO::poll_cb
		221	while IO::AIO::nreqs;
		222
		223	IO::AIO::flush
		224	Wait till all outstanding AIO requests have been handled.
		225
		226	Strictly equivalent to:
		227
		228	IO::AIO::poll_wait, IO::AIO::poll_cb
		229	while IO::AIO::nreqs;
		230
		231	IO::AIO::poll
		232	Waits until some requests have been handled.
		233
		234	Strictly equivalent to:
		235
		236	IO::AIO::poll_wait, IO::AIO::poll_cb
		237	if IO::AIO::nreqs;
		238
		239	IO::AIO::min_parallel $nthreads
		240	Set the minimum number of AIO threads to $nthreads. The default is
		241	1, which means a single asynchronous operation can be done at one
		242	time (the number of outstanding operations, however, is unlimited).
		243
		244	It is recommended to keep the number of threads low, as some Linux
		245	kernel versions will scale negatively with the number of threads
		246	(higher parallelity => MUCH higher latency). With current Linux 2.6
		247	versions, 4-32 threads should be fine.
		248
		249	Under normal circumstances you don't need to call this function, as
		250	this module automatically starts some threads (the exact number
		251	might change, and is currently 4).
		252
		253	IO::AIO::max_parallel $nthreads
		254	Sets the maximum number of AIO threads to $nthreads. If more than
		255	the specified number of threads are currently running, kill them.
		256	This function blocks until the limit is reached.
		257
		258	This module automatically runs "max_parallel 0" at program end, to
		259	ensure that all threads are killed and that there are no outstanding
		260	requests.
		261
		262	Under normal circumstances you don't need to call this function.
		263
		264	$oldnreqs = IO::AIO::max_outstanding $nreqs
		265	Sets the maximum number of outstanding requests to $nreqs. If you
		266	try to queue up more than this number of requests, the caller will
		267	block until some requests have been handled.
		268
		269	The default is very large, so normally there is no practical limit.
		270	If you queue up many requests in a loop it it often improves speed
		271	if you set this to a relatively low number, such as 100.
		272
		273	Under normal circumstances you don't need to call this function.
		274
		275	FORK BEHAVIOUR
		276	IO::AIO handles all outstanding AIO requests before the fork, destroys
		277	all AIO threads, and recreates them in both the parent and the child
		278	after the fork.
191		279
192	SEE ALSO	280	SEE ALSO
193	Coro, Linux::AIO.	281	Coro, Linux::AIO.
194		282
195	AUTHOR	283	AUTHOR

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.2 by root, Sun Jul 10 18:16:49 2005 UTC vs. Revision 1.9 by root, Tue Aug 16 23:33:38 2005 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.2 by root, Sun Jul 10 18:16:49 2005 UTC vs.
Revision 1.9 by root, Tue Aug 16 23:33:38 2005 UTC