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

Comparing IO-AIO/README (file contents):
Revision 1.8 by root, Sun Jul 31 17:24:05 2005 UTC vs.
Revision 1.13 by root, Tue Aug 30 15:45:10 2005 UTC

…		…
62	argument when the given syscall has been executed asynchronously.	62	argument when the given syscall has been executed asynchronously.
63		63
64	All functions expecting a filehandle keep a copy of the filehandle	64	All functions expecting a filehandle keep a copy of the filehandle
65	internally until the request has finished.	65	internally until the request has finished.
66		66
67	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
68	for this is that at the time the request is being executed, the current	68	in byte form. The reason for the former is that at the time the request
69	working directory could have changed. Alternatively, you can make sure	69	is being executed, the current working directory could have changed.
70	that you never change the current working directory.	70	Alternatively, you can make sure that you never change the current
		71	working directory.
71		72
		73	To encode pathnames to byte form, either make sure you either: a) always
		74	pass in filenames you got from outside (command line, readdir etc.), b)
		75	are ASCII or ISO 8859-1, c) use the Encode module and encode your
		76	pathnames to the locale (or other) encoding in effect in the user
		77	environment, d) use Glib::filename_from_unicode on unicode filenames or
		78	e) use something else.
		79
72	aio_open $pathname, $flags, $mode, $callback	80	aio_open $pathname, $flags, $mode, $callback->($fh)
73	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
74	newly created filehandle for the file.	82	newly created filehandle for the file.
75		83
76	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,
77	above, for an explanation.	85	above, for an explanation.
…		…
93	} else {	101	} else {
94	die "open failed: $!\n";	102	die "open failed: $!\n";
95	}	103	}
96	};	104	};
97		105
98	aio_close $fh, $callback	106	aio_close $fh, $callback->($status)
99	Asynchronously close a file and call the callback with the result	107	Asynchronously close a file and call the callback with the result
100	code. WARNING: although accepted, you should not pass in a perl	108	code. WARNING: although accepted, you should not pass in a perl
101	filehandle here, as perl will likely close the file descriptor	109	filehandle here, as perl will likely close the file descriptor
102	another time when the filehandle is destroyed. Normally, you can	110	another time when the filehandle is destroyed. Normally, you can
103	safely call perls "close" or just let filehandles go out of scope.	111	safely call perls "close" or just let filehandles go out of scope.
104		112
105	This is supposed to be a bug in the API, so that might change. It's	113	This is supposed to be a bug in the API, so that might change. It's
106	therefore best to avoid this function.	114	therefore best to avoid this function.
107		115
108	aio_read $fh,$offset,$length, $data,$dataoffset,$callback	116	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
109	aio_write $fh,$offset,$length, $data,$dataoffset,$callback	117	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
110	Reads or writes "length" bytes from the specified "fh" and "offset"	118	Reads or writes "length" bytes from the specified "fh" and "offset"
111	into the scalar given by "data" and offset "dataoffset" and calls	119	into the scalar given by "data" and offset "dataoffset" and calls
112	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
113	error, just like the syscall).	121	error, just like the syscall).
114		122
		123	The $data scalar MUST NOT be modified in any way while the request
		124	is outstanding. Modifying it can result in segfaults or WW3 (if the
		125	necessary/optional hardware is installed).
		126
115	Example: Read 15 bytes at offset 7 into scalar $buffer, starting at	127	Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
116	offset 0 within the scalar:	128	offset 0 within the scalar:
117		129
118	aio_read $fh, 7, 15, $buffer, 0, sub {	130	aio_read $fh, 7, 15, $buffer, 0, sub {
119	$_[0] > 0 or die "read error: $!";	131	$_[0] > 0 or die "read error: $!";
120	print "read $_[0] bytes: <$buffer>\n";	132	print "read $_[0] bytes: <$buffer>\n";
121	};	133	};
122		134
		135	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
		136	Tries to copy $length bytes from $in_fh to $out_fh. It starts
		137	reading at byte offset $in_offset, and starts writing at the current
		138	file offset of $out_fh. Because of that, it is not safe to issue
		139	more than one "aio_sendfile" per $out_fh, as they will interfere
		140	with each other.
		141
		142	This call tries to make use of a native "sendfile" syscall to
		143	provide zero-copy operation. For this to work, $out_fh should refer
		144	to a socket, and $in_fh should refer to mmap'able file.
		145
		146	If the native sendfile call fails or is not implemented, it will be
		147	emulated, so you can call "aio_sendfile" on any type of filehandle
		148	regardless of the limitations of the operating system.
		149
		150	Please note, however, that "aio_sendfile" can read more bytes from
		151	$in_fh than are written, and there is no way to find out how many
		152	bytes have been read from "aio_sendfile" alone, as "aio_sendfile"
		153	only provides the number of bytes written to $out_fh. Only if the
		154	result value equals $length one can assume that $length bytes have
		155	been read.
		156
123	aio_readahead $fh,$offset,$length, $callback	157	aio_readahead $fh,$offset,$length, $callback->($retval)
124	Asynchronously reads the specified byte range into the page cache,
125	using the "readahead" syscall. If that syscall doesn't exist (likely
126	if your OS isn't Linux) the status will be -1 and $! is set to
127	"ENOSYS".
128
129	"aio_readahead" populates the page cache with data from a file so	158	"aio_readahead" populates the page cache with data from a file so
130	that subsequent reads from that file will not block on disk I/O. The	159	that subsequent reads from that file will not block on disk I/O. The
131	$offset argument specifies the starting point from which data is to	160	$offset argument specifies the starting point from which data is to
132	be read and $length specifies the number of bytes to be read. I/O is	161	be read and $length specifies the number of bytes to be read. I/O is
133	performed in whole pages, so that offset is effectively rounded down	162	performed in whole pages, so that offset is effectively rounded down
134	to a page boundary and bytes are read up to the next page boundary	163	to a page boundary and bytes are read up to the next page boundary
135	greater than or equal to (off-set+length). "aio_readahead" does not	164	greater than or equal to (off-set+length). "aio_readahead" does not
136	read beyond the end of the file. The current file offset of the file	165	read beyond the end of the file. The current file offset of the file
137	is left unchanged.	166	is left unchanged.
138		167
		168	If that syscall doesn't exist (likely if your OS isn't Linux) it
		169	will be emulated by simply reading the data, which would have a
		170	similar effect.
		171
139	aio_stat $fh_or_path, $callback	172	aio_stat $fh_or_path, $callback->($status)
140	aio_lstat $fh, $callback	173	aio_lstat $fh, $callback->($status)
141	Works like perl's "stat" or "lstat" in void context. The callback	174	Works like perl's "stat" or "lstat" in void context. The callback
142	will be called after the stat and the results will be available	175	will be called after the stat and the results will be available
143	using "stat _" or "-s _" etc...	176	using "stat _" or "-s _" etc...
144		177
145	The pathname passed to "aio_stat" must be absolute. See API NOTES,	178	The pathname passed to "aio_stat" must be absolute. See API NOTES,
…		…
155	aio_stat "/etc/passwd", sub {	188	aio_stat "/etc/passwd", sub {
156	$_[0] and die "stat failed: $!";	189	$_[0] and die "stat failed: $!";
157	print "size is ", -s _, "\n";	190	print "size is ", -s _, "\n";
158	};	191	};
159		192
160	aio_unlink $pathname, $callback	193	aio_unlink $pathname, $callback->($status)
161	Asynchronously unlink (delete) a file and call the callback with the	194	Asynchronously unlink (delete) a file and call the callback with the
162	result code.	195	result code.
163		196
		197	aio_rmdir $pathname, $callback->($status)
		198	Asynchronously rmdir (delete) a directory and call the callback with
		199	the result code.
		200
		201	aio_readdir $pathname $callback->($entries)
		202	Unlike the POSIX call of the same name, "aio_readdir" reads an
		203	entire directory (i.e. opendir + readdir + closedir). The entries
		204	will not be sorted, and will NOT include the "." and ".." entries.
		205
		206	The callback a single argument which is either "undef" or an
		207	array-ref with the filenames.
		208
		209	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
		210	Scans a directory (similar to "aio_readdir") and tries to separate
		211	the entries of directory $path into two sets of names, ones you can
		212	recurse into (directories), and ones you cannot recurse into
		213	(everything else).
		214
		215	"aio_scandir" is a composite request that consists of many
		216	aio-primitives. $maxreq specifies the maximum number of outstanding
		217	aio requests that this function generates. If it is "<= 0", then a
		218	suitable default will be chosen (currently 8).
		219
		220	On error, the callback is called without arguments, otherwise it
		221	receives two array-refs with path-relative entry names.
		222
		223	Example:
		224
		225	aio_scandir $dir, 0, sub {
		226	my ($dirs, $nondirs) = @_;
		227	print "real directories: @$dirs\n";
		228	print "everything else: @$nondirs\n";
		229	};
		230
		231	Implementation notes.
		232
		233	The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
		234	can.
		235
		236	After reading the directory, the modification time, size etc. of the
		237	directory before and after the readdir is checked, and if they
		238	match, the link count will be used to decide how many entries are
		239	directories (if >= 2). Otherwise, no knowledge of the number of
		240	subdirectories will be assumed.
		241
		242	Then entires will be sorted into likely directories (everything
		243	without a non-initial dot) and likely non-directories (everything
		244	else). Then every entry + "/." will be "stat"'ed, likely directories
		245	first. This is often faster because filesystems might detect the
		246	type of the entry without reading the inode data (e.g. ext2s
		247	filetype feature). If that succeeds, it assumes that the entry is a
		248	directory or a symlink to directory (which will be checked
		249	seperately).
		250
		251	If the known number of directories has been reached, the rest of the
		252	entries is assumed to be non-directories.
		253
164	aio_fsync $fh, $callback	254	aio_fsync $fh, $callback->($status)
165	Asynchronously call fsync on the given filehandle and call the	255	Asynchronously call fsync on the given filehandle and call the
166	callback with the fsync result code.	256	callback with the fsync result code.
167		257
168	aio_fdatasync $fh, $callback	258	aio_fdatasync $fh, $callback->($status)
169	Asynchronously call fdatasync on the given filehandle and call the	259	Asynchronously call fdatasync on the given filehandle and call the
170	callback with the fdatasync result code. Might set $! to "ENOSYS" if	260	callback with the fdatasync result code.
171	"fdatasync" is not available.	261
		262	If this call isn't available because your OS lacks it or it couldn't
		263	be detected, it will be emulated by calling "fsync" instead.
172		264
173	SUPPORT FUNCTIONS	265	SUPPORT FUNCTIONS
174	$fileno = IO::AIO::poll_fileno	266	$fileno = IO::AIO::poll_fileno
175	Return the request result pipe file descriptor. This filehandle	267	Return the request result pipe file descriptor. This filehandle
176	must be polled for reading by some mechanism outside this module	268	must be polled for reading by some mechanism outside this module
…		…
222		314
223	IO::AIO::poll_wait, IO::AIO::poll_cb	315	IO::AIO::poll_wait, IO::AIO::poll_cb
224	if IO::AIO::nreqs;	316	if IO::AIO::nreqs;
225		317
226	IO::AIO::min_parallel $nthreads	318	IO::AIO::min_parallel $nthreads
227	Set the minimum number of AIO threads to $nthreads. The default is	319	Set the minimum number of AIO threads to $nthreads. The current
228	1, which means a single asynchronous operation can be done at one	320	default is 4, which means four asynchronous operations can be done
229	time (the number of outstanding operations, however, is unlimited).	321	at one time (the number of outstanding operations, however, is
		322	unlimited).
		323
		324	IO::AIO starts threads only on demand, when an AIO request is queued
		325	and no free thread exists.
230		326
231	It is recommended to keep the number of threads low, as some Linux	327	It is recommended to keep the number of threads low, as some Linux
232	kernel versions will scale negatively with the number of threads	328	kernel versions will scale negatively with the number of threads
233	(higher parallelity => MUCH higher latency). With current Linux 2.6	329	(higher parallelity => MUCH higher latency). With current Linux 2.6
234	versions, 4-32 threads should be fine.	330	versions, 4-32 threads should be fine.
235		331
236	Under normal circumstances you don't need to call this function, as	332	Under most circumstances you don't need to call this function, as
237	this module automatically starts some threads (the exact number	333	the module selects a default that is suitable for low to moderate
238	might change, and is currently 4).	334	load.
239		335
240	IO::AIO::max_parallel $nthreads	336	IO::AIO::max_parallel $nthreads
241	Sets the maximum number of AIO threads to $nthreads. If more than	337	Sets the maximum number of AIO threads to $nthreads. If more than
242	the specified number of threads are currently running, kill them.	338	the specified number of threads are currently running, this function
243	This function blocks until the limit is reached.	339	kills them. This function blocks until the limit is reached.
		340
		341	While $nthreads are zero, aio requests get queued but not executed
		342	until the number of threads has been increased again.
244		343
245	This module automatically runs "max_parallel 0" at program end, to	344	This module automatically runs "max_parallel 0" at program end, to
246	ensure that all threads are killed and that there are no outstanding	345	ensure that all threads are killed and that there are no outstanding
247	requests.	346	requests.
248		347
…		…
252	Sets the maximum number of outstanding requests to $nreqs. If you	351	Sets the maximum number of outstanding requests to $nreqs. If you
253	try to queue up more than this number of requests, the caller will	352	try to queue up more than this number of requests, the caller will
254	block until some requests have been handled.	353	block until some requests have been handled.
255		354
256	The default is very large, so normally there is no practical limit.	355	The default is very large, so normally there is no practical limit.
257	If you queue up many requests in a loop it it often improves speed	356	If you queue up many requests in a loop it often improves speed if
258	if you set this to a relatively low number, such as 100.	357	you set this to a relatively low number, such as 100.
259		358
260	Under normal circumstances you don't need to call this function.	359	Under normal circumstances you don't need to call this function.
		360
		361	FORK BEHAVIOUR
		362	Before the fork, IO::AIO enters a quiescent state where no requests can
		363	be added in other threads and no results will be processed. After the
		364	fork the parent simply leaves the quiescent state and continues
		365	request/result processing, while the child clears the request/result
		366	queue (so the requests started before the fork will only be handled in
		367	the parent). Threats will be started on demand until the limit ste in
		368	the parent process has been reached again.
261		369
262	SEE ALSO	370	SEE ALSO
263	Coro, Linux::AIO.	371	Coro, Linux::AIO.
264		372
265	AUTHOR	373	AUTHOR

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.8 by root, Sun Jul 31 17:24:05 2005 UTC vs. Revision 1.13 by root, Tue Aug 30 15:45:10 2005 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.8 by root, Sun Jul 31 17:24:05 2005 UTC vs.
Revision 1.13 by root, Tue Aug 30 15:45:10 2005 UTC