[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.14 by root, Mon Dec 26 18:31:12 2005 UTC

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