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

Comparing IO-AIO/README (file contents):
Revision 1.14 by root, Mon Dec 26 18:31:12 2005 UTC vs.
Revision 1.34 by root, Thu Nov 20 09:01:40 2008 UTC

…		…
3		3
4	SYNOPSIS	4	SYNOPSIS
5	use IO::AIO;	5	use IO::AIO;
6		6
7	aio_open "/etc/passwd", O_RDONLY, 0, sub {	7	aio_open "/etc/passwd", O_RDONLY, 0, sub {
8	my ($fh) = @_;	8	my $fh = shift
		9	or die "/etc/passwd: $!";
9	...	10	...
10	};	11	};
11		12
12	aio_unlink "/tmp/file", sub { };	13	aio_unlink "/tmp/file", sub { };
13		14
14	aio_read $fh, 30000, 1024, $buffer, 0, sub {	15	aio_read $fh, 30000, 1024, $buffer, 0, sub {
15	$_[0] > 0 or die "read error: $!";	16	$_[0] > 0 or die "read error: $!";
16	};	17	};
17		18
18	# AnyEvent	19	# version 2+ has request and group objects
19	open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";	20	use IO::AIO 2;
20	my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
21		21
22	# Event	22	aioreq_pri 4; # give next request a very high priority
		23	my $req = aio_unlink "/tmp/file", sub { };
		24	$req->cancel; # cancel request if still in queue
		25
		26	my $grp = aio_group sub { print "all stats done\n" };
		27	add $grp aio_stat "..." for ...;
		28
		29	# AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
		30	use AnyEvent::AIO;
		31
		32	# EV integration
		33	my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
		34
		35	# Event integration
23	Event->io (fd => IO::AIO::poll_fileno,	36	Event->io (fd => IO::AIO::poll_fileno,
24	poll => 'r',	37	poll => 'r',
25	cb => \&IO::AIO::poll_cb);	38	cb => \&IO::AIO::poll_cb);
26		39
27	# Glib/Gtk2	40	# Glib/Gtk2 integration
28	add_watch Glib::IO IO::AIO::poll_fileno,	41	add_watch Glib::IO IO::AIO::poll_fileno,
29	in => sub { IO::AIO::poll_cb; 1 };	42	in => sub { IO::AIO::poll_cb; 1 };
30		43
31	# Tk	44	# Tk integration
32	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",	45	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
33	readable => \&IO::AIO::poll_cb);	46	readable => \&IO::AIO::poll_cb);
34		47
35	# Danga::Socket	48	# Danga::Socket integration
36	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>	49	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
37	\&IO::AIO::poll_cb);	50	\&IO::AIO::poll_cb);
38		51
39	DESCRIPTION	52	DESCRIPTION
40	This module implements asynchronous I/O using whatever means your	53	This module implements asynchronous I/O using whatever means your
41	operating system supports.	54	operating system supports.
42		55
		56	Asynchronous means that operations that can normally block your program
		57	(e.g. reading from disk) will be done asynchronously: the operation will
		58	still block, but you can do something else in the meantime. This is
		59	extremely useful for programs that need to stay interactive even when
		60	doing heavy I/O (GUI programs, high performance network servers etc.),
		61	but can also be used to easily do operations in parallel that are
		62	normally done sequentially, e.g. stat'ing many files, which is much
		63	faster on a RAID volume or over NFS when you do a number of stat
		64	operations concurrently.
		65
		66	While most of this works on all types of file descriptors (for example
		67	sockets), using these functions on file descriptors that support
		68	nonblocking operation (again, sockets, pipes etc.) is very inefficient.
		69	Use an event loop for that (such as the Event module): IO::AIO will
		70	naturally fit into such an event loop itself.
		71
43	Currently, a number of threads are started that execute your read/writes	72	In this version, a number of threads are started that execute your
44	and signal their completion. You don't need thread support in your libc	73	requests and signal their completion. You don't need thread support in
45	or perl, and the threads created by this module will not be visible to	74	perl, and the threads created by this module will not be visible to
46	the pthreads library. In the future, this module might make use of the	75	perl. In the future, this module might make use of the native aio
47	native aio functions available on many operating systems. However, they	76	functions available on many operating systems. However, they are often
48	are often not well-supported (Linux doesn't allow them on normal files	77	not well-supported or restricted (GNU/Linux doesn't allow them on normal
49	currently, for example), and they would only support aio_read and	78	files currently, for example), and they would only support aio_read and
50	aio_write, so the remaining functionality would have to be implemented	79	aio_write, so the remaining functionality would have to be implemented
51	using threads anyway.	80	using threads anyway.
52		81
53	Although the module will work with in the presence of other threads, it	82	Although the module will work in the presence of other (Perl-) threads,
54	is currently not reentrant, so use appropriate locking yourself, always	83	it is currently not reentrant in any way, so use appropriate locking
55	call "poll_cb" from within the same thread, or never call "poll_cb" (or	84	yourself, always call "poll_cb" from within the same thread, or never
56	other "aio_" functions) recursively.	85	call "poll_cb" (or other "aio_" functions) recursively.
		86
		87	EXAMPLE
		88	This is a simple example that uses the Event module and loads
		89	/etc/passwd asynchronously:
		90
		91	use Fcntl;
		92	use Event;
		93	use IO::AIO;
		94
		95	# register the IO::AIO callback with Event
		96	Event->io (fd => IO::AIO::poll_fileno,
		97	poll => 'r',
		98	cb => \&IO::AIO::poll_cb);
		99
		100	# queue the request to open /etc/passwd
		101	aio_open "/etc/passwd", O_RDONLY, 0, sub {
		102	my $fh = shift
		103	or die "error while opening: $!";
		104
		105	# stat'ing filehandles is generally non-blocking
		106	my $size = -s $fh;
		107
		108	# queue a request to read the file
		109	my $contents;
		110	aio_read $fh, 0, $size, $contents, 0, sub {
		111	$_[0] == $size
		112	or die "short read: $!";
		113
		114	close $fh;
		115
		116	# file contents now in $contents
		117	print $contents;
		118
		119	# exit event loop and program
		120	Event::unloop;
		121	};
		122	};
		123
		124	# possibly queue up other requests, or open GUI windows,
		125	# check for sockets etc. etc.
		126
		127	# process events as long as there are some:
		128	Event::loop;
		129
		130	REQUEST ANATOMY AND LIFETIME
		131	Every "aio_*" function creates a request. which is a C data structure
		132	not directly visible to Perl.
		133
		134	If called in non-void context, every request function returns a Perl
		135	object representing the request. In void context, nothing is returned,
		136	which saves a bit of memory.
		137
		138	The perl object is a fairly standard ref-to-hash object. The hash
		139	contents are not used by IO::AIO so you are free to store anything you
		140	like in it.
		141
		142	During their existance, aio requests travel through the following
		143	states, in order:
		144
		145	ready
		146	Immediately after a request is created it is put into the ready
		147	state, waiting for a thread to execute it.
		148
		149	execute
		150	A thread has accepted the request for processing and is currently
		151	executing it (e.g. blocking in read).
		152
		153	pending
		154	The request has been executed and is waiting for result processing.
		155
		156	While request submission and execution is fully asynchronous, result
		157	processing is not and relies on the perl interpreter calling
		158	"poll_cb" (or another function with the same effect).
		159
		160	result
		161	The request results are processed synchronously by "poll_cb".
		162
		163	The "poll_cb" function will process all outstanding aio requests by
		164	calling their callbacks, freeing memory associated with them and
		165	managing any groups they are contained in.
		166
		167	done
		168	Request has reached the end of its lifetime and holds no resources
		169	anymore (except possibly for the Perl object, but its connection to
		170	the actual aio request is severed and calling its methods will
		171	either do nothing or result in a runtime error).
57		172
58	FUNCTIONS	173	FUNCTIONS
59	AIO FUNCTIONS	174	AIO REQUEST FUNCTIONS
60	All the "aio_*" calls are more or less thin wrappers around the syscall	175	All the "aio_*" calls are more or less thin wrappers around the syscall
61	with the same name (sans "aio_"). The arguments are similar or	176	with the same name (sans "aio_"). The arguments are similar or
62	identical, and they all accept an additional (and optional) $callback	177	identical, and they all accept an additional (and optional) $callback
63	argument which must be a code reference. This code reference will get	178	argument which must be a code reference. This code reference will get
64	called with the syscall return code (e.g. most syscalls return -1 on	179	called with the syscall return code (e.g. most syscalls return -1 on
65	error, unlike perl, which usually delivers "false") as it's sole	180	error, unlike perl, which usually delivers "false") as its sole argument
66	argument when the given syscall has been executed asynchronously.	181	after the given syscall has been executed asynchronously.
67		182
68	All functions expecting a filehandle keep a copy of the filehandle	183	All functions expecting a filehandle keep a copy of the filehandle
69	internally until the request has finished.	184	internally until the request has finished.
70		185
		186	All functions return request objects of type IO::AIO::REQ that allow
		187	further manipulation of those requests while they are in-flight.
		188
71	The pathnames you pass to these routines must be absolute and encoded	189	The pathnames you pass to these routines must be absolute and encoded
72	in byte form. The reason for the former is that at the time the request	190	as octets. The reason for the former is that at the time the request is
73	is being executed, the current working directory could have changed.	191	being executed, the current working directory could have changed.
74	Alternatively, you can make sure that you never change the current	192	Alternatively, you can make sure that you never change the current
75	working directory.	193	working directory anywhere in the program and then use relative paths.
76		194
77	To encode pathnames to byte form, either make sure you either: a) always	195	To encode pathnames as octets, either make sure you either: a) always
78	pass in filenames you got from outside (command line, readdir etc.), b)	196	pass in filenames you got from outside (command line, readdir etc.)
79	are ASCII or ISO 8859-1, c) use the Encode module and encode your	197	without tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module
80	pathnames to the locale (or other) encoding in effect in the user	198	and encode your pathnames to the locale (or other) encoding in effect in
81	environment, d) use Glib::filename_from_unicode on unicode filenames or	199	the user environment, d) use Glib::filename_from_unicode on unicode
82	e) use something else.	200	filenames or e) use something else to ensure your scalar has the correct
		201	contents.
		202
		203	This works, btw. independent of the internal UTF-8 bit, which IO::AIO
		204	handles correctly whether it is set or not.
		205
		206	$prev_pri = aioreq_pri [$pri]
		207	Returns the priority value that would be used for the next request
		208	and, if $pri is given, sets the priority for the next aio request.
		209
		210	The default priority is 0, the minimum and maximum priorities are -4
		211	and 4, respectively. Requests with higher priority will be serviced
		212	first.
		213
		214	The priority will be reset to 0 after each call to one of the
		215	"aio_*" functions.
		216
		217	Example: open a file with low priority, then read something from it
		218	with higher priority so the read request is serviced before other
		219	low priority open requests (potentially spamming the cache):
		220
		221	aioreq_pri -3;
		222	aio_open ..., sub {
		223	return unless $_[0];
		224
		225	aioreq_pri -2;
		226	aio_read $_[0], ..., sub {
		227	...
		228	};
		229	};
		230
		231	aioreq_nice $pri_adjust
		232	Similar to "aioreq_pri", but subtracts the given value from the
		233	current priority, so the effect is cumulative.
83		234
84	aio_open $pathname, $flags, $mode, $callback->($fh)	235	aio_open $pathname, $flags, $mode, $callback->($fh)
85	Asynchronously open or create a file and call the callback with a	236	Asynchronously open or create a file and call the callback with a
86	newly created filehandle for the file.	237	newly created filehandle for the file.
87		238
…		…
92	They are the same as used by "sysopen".	243	They are the same as used by "sysopen".
93		244
94	Likewise, $mode specifies the mode of the newly created file, if it	245	Likewise, $mode specifies the mode of the newly created file, if it
95	didn't exist and "O_CREAT" has been given, just like perl's	246	didn't exist and "O_CREAT" has been given, just like perl's
96	"sysopen", except that it is mandatory (i.e. use 0 if you don't	247	"sysopen", except that it is mandatory (i.e. use 0 if you don't
97	create new files, and 0666 or 0777 if you do).	248	create new files, and 0666 or 0777 if you do). Note that the $mode
		249	will be modified by the umask in effect then the request is being
		250	executed, so better never change the umask.
98		251
99	Example:	252	Example:
100		253
101	aio_open "/etc/passwd", O_RDONLY, 0, sub {	254	aio_open "/etc/passwd", O_RDONLY, 0, sub {
102	if ($_[0]) {	255	if ($_[0]) {
…		…
107	}	260	}
108	};	261	};
109		262
110	aio_close $fh, $callback->($status)	263	aio_close $fh, $callback->($status)
111	Asynchronously close a file and call the callback with the result	264	Asynchronously close a file and call the callback with the result
112	code. WARNING: although accepted, you should not pass in a perl	265	code.
113	filehandle here, as perl will likely close the file descriptor
114	another time when the filehandle is destroyed. Normally, you can
115	safely call perls "close" or just let filehandles go out of scope.
116		266
117	This is supposed to be a bug in the API, so that might change. It's	267	Unfortunately, you can't do this to perl. Perl insists very
118	therefore best to avoid this function.	268	strongly on closing the file descriptor associated with the
		269	filehandle itself.
		270
		271	Therefore, "aio_close" will not close the filehandle - instead it
		272	will use dup2 to overwrite the file descriptor with the write-end of
		273	a pipe (the pipe fd will be created on demand and will be cached).
		274
		275	Or in other words: the file descriptor will be closed, but it will
		276	not be free for reuse until the perl filehandle is closed.
119		277
120	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	278	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
121	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	279	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
122	Reads or writes "length" bytes from the specified "fh" and "offset"	280	Reads or writes $length bytes from the specified $fh and $offset
123	into the scalar given by "data" and offset "dataoffset" and calls	281	into the scalar given by $data and offset $dataoffset and calls the
124	the callback without the actual number of bytes read (or -1 on	282	callback without the actual number of bytes read (or -1 on error,
125	error, just like the syscall).	283	just like the syscall).
		284
		285	If $offset is undefined, then the current file descriptor offset
		286	will be used (and updated), otherwise the file descriptor offset
		287	will not be changed by these calls.
		288
		289	If $length is undefined in "aio_write", use the remaining length of
		290	$data.
		291
		292	If $dataoffset is less than zero, it will be counted from the end of
		293	$data.
126		294
127	The $data scalar MUST NOT be modified in any way while the request	295	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	296	is outstanding. Modifying it can result in segfaults or World War
129	necessary/optional hardware is installed).	297	III (if the necessary/optional hardware is installed).
130		298
131	Example: Read 15 bytes at offset 7 into scalar $buffer, starting at	299	Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
132	offset 0 within the scalar:	300	offset 0 within the scalar:
133		301
134	aio_read $fh, 7, 15, $buffer, 0, sub {	302	aio_read $fh, 7, 15, $buffer, 0, sub {
…		…
192	aio_stat "/etc/passwd", sub {	360	aio_stat "/etc/passwd", sub {
193	$_[0] and die "stat failed: $!";	361	$_[0] and die "stat failed: $!";
194	print "size is ", -s _, "\n";	362	print "size is ", -s _, "\n";
195	};	363	};
196		364
		365	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
		366	Works like perl's "utime" function (including the special case of
		367	$atime and $mtime being undef). Fractional times are supported if
		368	the underlying syscalls support them.
		369
		370	When called with a pathname, uses utimes(2) if available, otherwise
		371	utime(2). If called on a file descriptor, uses futimes(2) if
		372	available, otherwise returns ENOSYS, so this is not portable.
		373
		374	Examples:
		375
		376	# set atime and mtime to current time (basically touch(1)):
		377	aio_utime "path", undef, undef;
		378	# set atime to current time and mtime to beginning of the epoch:
		379	aio_utime "path", time, undef; # undef==0
		380
		381	aio_chown $fh_or_path, $uid, $gid, $callback->($status)
		382	Works like perl's "chown" function, except that "undef" for either
		383	$uid or $gid is being interpreted as "do not change" (but -1 can
		384	also be used).
		385
		386	Examples:
		387
		388	# same as "chown root path" in the shell:
		389	aio_chown "path", 0, -1;
		390	# same as above:
		391	aio_chown "path", 0, undef;
		392
		393	aio_truncate $fh_or_path, $offset, $callback->($status)
		394	Works like truncate(2) or ftruncate(2).
		395
		396	aio_chmod $fh_or_path, $mode, $callback->($status)
		397	Works like perl's "chmod" function.
		398
197	aio_unlink $pathname, $callback->($status)	399	aio_unlink $pathname, $callback->($status)
198	Asynchronously unlink (delete) a file and call the callback with the	400	Asynchronously unlink (delete) a file and call the callback with the
199	result code.	401	result code.
200		402
		403	aio_mknod $path, $mode, $dev, $callback->($status)
		404	[EXPERIMENTAL]
		405
		406	Asynchronously create a device node (or fifo). See mknod(2).
		407
		408	The only (POSIX-) portable way of calling this function is:
		409
		410	aio_mknod $path, IO::AIO::S_IFIFO \| $mode, 0, sub { ...
		411
		412	aio_link $srcpath, $dstpath, $callback->($status)
		413	Asynchronously create a new link to the existing object at $srcpath
		414	at the path $dstpath and call the callback with the result code.
		415
		416	aio_symlink $srcpath, $dstpath, $callback->($status)
		417	Asynchronously create a new symbolic link to the existing object at
		418	$srcpath at the path $dstpath and call the callback with the result
		419	code.
		420
		421	aio_readlink $path, $callback->($link)
		422	Asynchronously read the symlink specified by $path and pass it to
		423	the callback. If an error occurs, nothing or undef gets passed to
		424	the callback.
		425
		426	aio_rename $srcpath, $dstpath, $callback->($status)
		427	Asynchronously rename the object at $srcpath to $dstpath, just as
		428	rename(2) and call the callback with the result code.
		429
		430	aio_mkdir $pathname, $mode, $callback->($status)
		431	Asynchronously mkdir (create) a directory and call the callback with
		432	the result code. $mode will be modified by the umask at the time the
		433	request is executed, so do not change your umask.
		434
201	aio_rmdir $pathname, $callback->($status)	435	aio_rmdir $pathname, $callback->($status)
202	Asynchronously rmdir (delete) a directory and call the callback with	436	Asynchronously rmdir (delete) a directory and call the callback with
203	the result code.	437	the result code.
204		438
205	aio_readdir $pathname $callback->($entries)	439	aio_readdir $pathname, $callback->($entries)
206	Unlike the POSIX call of the same name, "aio_readdir" reads an	440	Unlike the POSIX call of the same name, "aio_readdir" reads an
207	entire directory (i.e. opendir + readdir + closedir). The entries	441	entire directory (i.e. opendir + readdir + closedir). The entries
208	will not be sorted, and will NOT include the "." and ".." entries.	442	will not be sorted, and will NOT include the "." and ".." entries.
209		443
210	The callback a single argument which is either "undef" or an	444	The callback a single argument which is either "undef" or an
211	array-ref with the filenames.	445	array-ref with the filenames.
212		446
		447	aio_load $path, $data, $callback->($status)
		448	This is a composite request that tries to fully load the given file
		449	into memory. Status is the same as with aio_read.
		450
		451	aio_copy $srcpath, $dstpath, $callback->($status)
		452	Try to copy the file (directories not supported as either source
		453	or destination) from $srcpath to $dstpath and call the callback with
		454	the 0 (error) or -1 ok.
		455
		456	This is a composite request that creates the destination file with
		457	mode 0200 and copies the contents of the source file into it using
		458	"aio_sendfile", followed by restoring atime, mtime, access mode and
		459	uid/gid, in that order.
		460
		461	If an error occurs, the partial destination file will be unlinked,
		462	if possible, except when setting atime, mtime, access mode and
		463	uid/gid, where errors are being ignored.
		464
		465	aio_move $srcpath, $dstpath, $callback->($status)
		466	Try to move the file (directories not supported as either source
		467	or destination) from $srcpath to $dstpath and call the callback with
		468	the 0 (error) or -1 ok.
		469
		470	This is a composite request that tries to rename(2) the file first;
		471	if rename fails with "EXDEV", it copies the file with "aio_copy"
		472	and, if that is successful, unlinks the $srcpath.
		473
213	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)	474	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
214	Scans a directory (similar to "aio_readdir") and tries to separate	475	Scans a directory (similar to "aio_readdir") but additionally tries
215	the entries of directory $path into two sets of names, ones you can	476	to efficiently separate the entries of directory $path into two sets
216	recurse into (directories), and ones you cannot recurse into	477	of names, directories you can recurse into (directories), and ones
217	(everything else).	478	you cannot recurse into (everything else, including symlinks to
		479	directories).
218		480
219	"aio_scandir" is a composite request that consists of many	481	"aio_scandir" is a composite request that creates of many sub
220	aio-primitives. $maxreq specifies the maximum number of outstanding	482	requests_ $maxreq specifies the maximum number of outstanding aio
221	aio requests that this function generates. If it is "<= 0", then a	483	requests that this function generates. If it is "<= 0", then a
222	suitable default will be chosen (currently 8).	484	suitable default will be chosen (currently 4).
223		485
224	On error, the callback is called without arguments, otherwise it	486	On error, the callback is called without arguments, otherwise it
225	receives two array-refs with path-relative entry names.	487	receives two array-refs with path-relative entry names.
226		488
227	Example:	489	Example:
…		…
236		498
237	The "aio_readdir" cannot be avoided, but "stat()"'ing every entry	499	The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
238	can.	500	can.
239		501
240	After reading the directory, the modification time, size etc. of the	502	After reading the directory, the modification time, size etc. of the
241	directory before and after the readdir is checked, and if they	503	directory before and after the readdir is checked, and if they match
242	match, the link count will be used to decide how many entries are	504	(and isn't the current time), the link count will be used to decide
243	directories (if >= 2). Otherwise, no knowledge of the number of	505	how many entries are directories (if >= 2). Otherwise, no knowledge
244	subdirectories will be assumed.	506	of the number of subdirectories will be assumed.
245		507
246	Then entires will be sorted into likely directories (everything	508	Then entries will be sorted into likely directories (everything
247	without a non-initial dot) and likely non-directories (everything	509	without a non-initial dot currently) and likely non-directories
248	else). Then every entry + "/." will be "stat"'ed, likely directories	510	(everything else). Then every entry plus an appended "/." will be
249	first. This is often faster because filesystems might detect the	511	"stat"'ed, likely directories first. If that succeeds, it assumes
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	512	that the entry is a directory or a symlink to directory (which will
253	seperately).	513	be checked seperately). This is often faster than stat'ing the entry
		514	itself because filesystems might detect the type of the entry
		515	without reading the inode data (e.g. ext2fs filetype feature).
254		516
255	If the known number of directories has been reached, the rest of the	517	If the known number of directories (link count - 2) has been
256	entries is assumed to be non-directories.	518	reached, the rest of the entries is assumed to be non-directories.
		519
		520	This only works with certainty on POSIX (= UNIX) filesystems, which
		521	fortunately are the vast majority of filesystems around.
		522
		523	It will also likely work on non-POSIX filesystems with reduced
		524	efficiency as those tend to return 0 or 1 as link counts, which
		525	disables the directory counting heuristic.
		526
		527	aio_rmtree $path, $callback->($status)
		528	Delete a directory tree starting (and including) $path, return the
		529	status of the final "rmdir" only. This is a composite request that
		530	uses "aio_scandir" to recurse into and rmdir directories, and unlink
		531	everything else.
		532
		533	aio_sync $callback->($status)
		534	Asynchronously call sync and call the callback when finished.
257		535
258	aio_fsync $fh, $callback->($status)	536	aio_fsync $fh, $callback->($status)
259	Asynchronously call fsync on the given filehandle and call the	537	Asynchronously call fsync on the given filehandle and call the
260	callback with the fsync result code.	538	callback with the fsync result code.
261		539
…		…
264	callback with the fdatasync result code.	542	callback with the fdatasync result code.
265		543
266	If this call isn't available because your OS lacks it or it couldn't	544	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.	545	be detected, it will be emulated by calling "fsync" instead.
268		546
		547	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
		548	Sync the data portion of the file specified by $offset and $length
		549	to disk (but NOT the metadata), by calling the Linux-specific
		550	sync_file_range call. If sync_file_range is not available or it
		551	returns ENOSYS, then fdatasync or fsync is being substituted.
		552
		553	$flags can be a combination of
		554	"IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
		555	"IO::AIO::SYNC_FILE_RANGE_WRITE" and
		556	"IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
		557	manpage for details.
		558
		559	aio_pathsync $path, $callback->($status)
		560	This request tries to open, fsync and close the given path. This is
		561	a composite request intended to sync directories after directory
		562	operations (E.g. rename). This might not work on all operating
		563	systems or have any specific effect, but usually it makes sure that
		564	directory changes get written to disc. It works for anything that
		565	can be opened for read-only, not just directories.
		566
		567	Passes 0 when everything went ok, and -1 on error.
		568
		569	aio_group $callback->(...)
		570	This is a very special aio request: Instead of doing something, it
		571	is a container for other aio requests, which is useful if you want
		572	to bundle many requests into a single, composite, request with a
		573	definite callback and the ability to cancel the whole request with
		574	its subrequests.
		575
		576	Returns an object of class IO::AIO::GRP. See its documentation below
		577	for more info.
		578
		579	Example:
		580
		581	my $grp = aio_group sub {
		582	print "all stats done\n";
		583	};
		584
		585	add $grp
		586	(aio_stat ...),
		587	(aio_stat ...),
		588	...;
		589
		590	aio_nop $callback->()
		591	This is a special request - it does nothing in itself and is only
		592	used for side effects, such as when you want to add a dummy request
		593	to a group so that finishing the requests in the group depends on
		594	executing the given code.
		595
		596	While this request does nothing, it still goes through the execution
		597	phase and still requires a worker thread. Thus, the callback will
		598	not be executed immediately but only after other requests in the
		599	queue have entered their execution phase. This can be used to
		600	measure request latency.
		601
		602	IO::AIO::aio_busy $fractional_seconds, $callback->() NOT EXPORTED
		603	Mainly used for debugging and benchmarking, this aio request puts
		604	one of the request workers to sleep for the given time.
		605
		606	While it is theoretically handy to have simple I/O scheduling
		607	requests like sleep and file handle readable/writable, the overhead
		608	this creates is immense (it blocks a thread for a long time) so do
		609	not use this function except to put your application under
		610	artificial I/O pressure.
		611
		612	IO::AIO::REQ CLASS
		613	All non-aggregate "aio_*" functions return an object of this class when
		614	called in non-void context.
		615
		616	cancel $req
		617	Cancels the request, if possible. Has the effect of skipping
		618	execution when entering the execute state and skipping calling the
		619	callback when entering the the result state, but will leave the
		620	request otherwise untouched. That means that requests that currently
		621	execute will not be stopped and resources held by the request will
		622	not be freed prematurely.
		623
		624	cb $req $callback->(...)
		625	Replace (or simply set) the callback registered to the request.
		626
		627	IO::AIO::GRP CLASS
		628	This class is a subclass of IO::AIO::REQ, so all its methods apply to
		629	objects of this class, too.
		630
		631	A IO::AIO::GRP object is a special request that can contain multiple
		632	other aio requests.
		633
		634	You create one by calling the "aio_group" constructing function with a
		635	callback that will be called when all contained requests have entered
		636	the "done" state:
		637
		638	my $grp = aio_group sub {
		639	print "all requests are done\n";
		640	};
		641
		642	You add requests by calling the "add" method with one or more
		643	"IO::AIO::REQ" objects:
		644
		645	$grp->add (aio_unlink "...");
		646
		647	add $grp aio_stat "...", sub {
		648	$_[0] or return $grp->result ("error");
		649
		650	# add another request dynamically, if first succeeded
		651	add $grp aio_open "...", sub {
		652	$grp->result ("ok");
		653	};
		654	};
		655
		656	This makes it very easy to create composite requests (see the source of
		657	"aio_move" for an application) that work and feel like simple requests.
		658
		659	* The IO::AIO::GRP objects will be cleaned up during calls to
		660	"IO::AIO::poll_cb", just like any other request.
		661
		662	* They can be canceled like any other request. Canceling will cancel
		663	not only the request itself, but also all requests it contains.
		664
		665	* They can also can also be added to other IO::AIO::GRP objects.
		666
		667	* You must not add requests to a group from within the group callback
		668	(or any later time).
		669
		670	Their lifetime, simplified, looks like this: when they are empty, they
		671	will finish very quickly. If they contain only requests that are in the
		672	"done" state, they will also finish. Otherwise they will continue to
		673	exist.
		674
		675	That means after creating a group you have some time to add requests
		676	(precisely before the callback has been invoked, which is only done
		677	within the "poll_cb"). And in the callbacks of those requests, you can
		678	add further requests to the group. And only when all those requests have
		679	finished will the the group itself finish.
		680
		681	add $grp ...
		682	$grp->add (...)
		683	Add one or more requests to the group. Any type of IO::AIO::REQ can
		684	be added, including other groups, as long as you do not create
		685	circular dependencies.
		686
		687	Returns all its arguments.
		688
		689	$grp->cancel_subs
		690	Cancel all subrequests and clears any feeder, but not the group
		691	request itself. Useful when you queued a lot of events but got a
		692	result early.
		693
		694	$grp->result (...)
		695	Set the result value(s) that will be passed to the group callback
		696	when all subrequests have finished and set the groups errno to the
		697	current value of errno (just like calling "errno" without an error
		698	number). By default, no argument will be passed and errno is zero.
		699
		700	$grp->errno ([$errno])
		701	Sets the group errno value to $errno, or the current value of errno
		702	when the argument is missing.
		703
		704	Every aio request has an associated errno value that is restored
		705	when the callback is invoked. This method lets you change this value
		706	from its default (0).
		707
		708	Calling "result" will also set errno, so make sure you either set $!
		709	before the call to "result", or call c<errno> after it.
		710
		711	feed $grp $callback->($grp)
		712	Sets a feeder/generator on this group: every group can have an
		713	attached generator that generates requests if idle. The idea behind
		714	this is that, although you could just queue as many requests as you
		715	want in a group, this might starve other requests for a potentially
		716	long time. For example, "aio_scandir" might generate hundreds of
		717	thousands "aio_stat" requests, delaying any later requests for a
		718	long time.
		719
		720	To avoid this, and allow incremental generation of requests, you can
		721	instead a group and set a feeder on it that generates those
		722	requests. The feed callback will be called whenever there are few
		723	enough (see "limit", below) requests active in the group itself and
		724	is expected to queue more requests.
		725
		726	The feed callback can queue as many requests as it likes (i.e. "add"
		727	does not impose any limits).
		728
		729	If the feed does not queue more requests when called, it will be
		730	automatically removed from the group.
		731
		732	If the feed limit is 0 when this method is called, it will be set to
		733	2 automatically.
		734
		735	Example:
		736
		737	# stat all files in @files, but only ever use four aio requests concurrently:
		738
		739	my $grp = aio_group sub { print "finished\n" };
		740	limit $grp 4;
		741	feed $grp sub {
		742	my $file = pop @files
		743	or return;
		744
		745	add $grp aio_stat $file, sub { ... };
		746	};
		747
		748	limit $grp $num
		749	Sets the feeder limit for the group: The feeder will be called
		750	whenever the group contains less than this many requests.
		751
		752	Setting the limit to 0 will pause the feeding process.
		753
		754	The default value for the limit is 0, but note that setting a feeder
		755	automatically bumps it up to 2.
		756
269	SUPPORT FUNCTIONS	757	SUPPORT FUNCTIONS
		758	EVENT PROCESSING AND EVENT LOOP INTEGRATION
270	$fileno = IO::AIO::poll_fileno	759	$fileno = IO::AIO::poll_fileno
271	Return the request result pipe file descriptor. This filehandle	760	Return the request result pipe file descriptor. This filehandle
272	must be polled for reading by some mechanism outside this module	761	must be polled for reading by some mechanism outside this module
273	(e.g. Event or select, see below or the SYNOPSIS). If the pipe	762	(e.g. Event or select, see below or the SYNOPSIS). If the pipe
274	becomes readable you have to call "poll_cb" to check the results.	763	becomes readable you have to call "poll_cb" to check the results.
275		764
276	See "poll_cb" for an example.	765	See "poll_cb" for an example.
277		766
278	IO::AIO::poll_cb	767	IO::AIO::poll_cb
279	Process all outstanding events on the result pipe. You have to call	768	Process some outstanding events on the result pipe. You have to call
280	this regularly. Returns the number of events processed. Returns	769	this regularly. Returns 0 if all events could be processed, or -1 if
281	immediately when no events are outstanding.	770	it returned earlier for whatever reason. Returns immediately when no
		771	events are outstanding. The amount of events processed depends on
		772	the settings of "IO::AIO::max_poll_req" and
		773	"IO::AIO::max_poll_time".
		774
		775	If not all requests were processed for whatever reason, the
		776	filehandle will still be ready when "poll_cb" returns, so normally
		777	you don't have to do anything special to have it called later.
282		778
283	Example: Install an Event watcher that automatically calls	779	Example: Install an Event watcher that automatically calls
284	IO::AIO::poll_cb with high priority:	780	IO::AIO::poll_cb with high priority:
285		781
286	Event->io (fd => IO::AIO::poll_fileno,	782	Event->io (fd => IO::AIO::poll_fileno,
287	poll => 'r', async => 1,	783	poll => 'r', async => 1,
288	cb => \&IO::AIO::poll_cb);	784	cb => \&IO::AIO::poll_cb);
289		785
		786	IO::AIO::max_poll_reqs $nreqs
		787	IO::AIO::max_poll_time $seconds
		788	These set the maximum number of requests (default 0, meaning
		789	infinity) that are being processed by "IO::AIO::poll_cb" in one
		790	call, respectively the maximum amount of time (default 0, meaning
		791	infinity) spent in "IO::AIO::poll_cb" to process requests (more
		792	correctly the mininum amount of time "poll_cb" is allowed to use).
		793
		794	Setting "max_poll_time" to a non-zero value creates an overhead of
		795	one syscall per request processed, which is not normally a problem
		796	unless your callbacks are really really fast or your OS is really
		797	really slow (I am not mentioning Solaris here). Using
		798	"max_poll_reqs" incurs no overhead.
		799
		800	Setting these is useful if you want to ensure some level of
		801	interactiveness when perl is not fast enough to process all requests
		802	in time.
		803
		804	For interactive programs, values such as 0.01 to 0.1 should be fine.
		805
		806	Example: Install an Event watcher that automatically calls
		807	IO::AIO::poll_cb with low priority, to ensure that other parts of
		808	the program get the CPU sometimes even under high AIO load.
		809
		810	# try not to spend much more than 0.1s in poll_cb
		811	IO::AIO::max_poll_time 0.1;
		812
		813	# use a low priority so other tasks have priority
		814	Event->io (fd => IO::AIO::poll_fileno,
		815	poll => 'r', nice => 1,
		816	cb => &IO::AIO::poll_cb);
		817
290	IO::AIO::poll_wait	818	IO::AIO::poll_wait
		819	If there are any outstanding requests and none of them in the result
291	Wait till the result filehandle becomes ready for reading (simply	820	phase, wait till the result filehandle becomes ready for reading
292	does a "select" on the filehandle. This is useful if you want to	821	(simply does a "select" on the filehandle. This is useful if you
293	synchronously wait for some requests to finish).	822	want to synchronously wait for some requests to finish).
294		823
295	See "nreqs" for an example.	824	See "nreqs" for an example.
296		825
		826	IO::AIO::poll
		827	Waits until some requests have been handled.
		828
		829	Returns the number of requests processed, but is otherwise strictly
		830	equivalent to:
		831
		832	IO::AIO::poll_wait, IO::AIO::poll_cb
		833
297	IO::AIO::nreqs	834	IO::AIO::flush
298	Returns the number of requests currently outstanding (i.e. for which	835	Wait till all outstanding AIO requests have been handled.
299	their callback has not been invoked yet).
300		836
301	Example: wait till there are no outstanding requests anymore:	837	Strictly equivalent to:
302		838
303	IO::AIO::poll_wait, IO::AIO::poll_cb	839	IO::AIO::poll_wait, IO::AIO::poll_cb
304	while IO::AIO::nreqs;	840	while IO::AIO::nreqs;
305		841
306	IO::AIO::flush	842	CONTROLLING THE NUMBER OF THREADS
307	Wait till all outstanding AIO requests have been handled.
308
309	Strictly equivalent to:
310
311	IO::AIO::poll_wait, IO::AIO::poll_cb
312	while IO::AIO::nreqs;
313
314	IO::AIO::poll
315	Waits until some requests have been handled.
316
317	Strictly equivalent to:
318
319	IO::AIO::poll_wait, IO::AIO::poll_cb
320	if IO::AIO::nreqs;
321
322	IO::AIO::min_parallel $nthreads	843	IO::AIO::min_parallel $nthreads
323	Set the minimum number of AIO threads to $nthreads. The current	844	Set the minimum number of AIO threads to $nthreads. The current
324	default is 4, which means four asynchronous operations can be done	845	default is 8, which means eight asynchronous operations can execute
325	at one time (the number of outstanding operations, however, is	846	concurrently at any one time (the number of outstanding requests,
326	unlimited).	847	however, is unlimited).
327		848
328	IO::AIO starts threads only on demand, when an AIO request is queued	849	IO::AIO starts threads only on demand, when an AIO request is queued
329	and no free thread exists.	850	and no free thread exists. Please note that queueing up a hundred
		851	requests can create demand for a hundred threads, even if it turns
		852	out that everything is in the cache and could have been processed
		853	faster by a single thread.
330		854
331	It is recommended to keep the number of threads low, as some Linux	855	It is recommended to keep the number of threads relatively low, as
332	kernel versions will scale negatively with the number of threads	856	some Linux kernel versions will scale negatively with the number of
333	(higher parallelity => MUCH higher latency). With current Linux 2.6	857	threads (higher parallelity => MUCH higher latency). With current
334	versions, 4-32 threads should be fine.	858	Linux 2.6 versions, 4-32 threads should be fine.
335		859
336	Under most circumstances you don't need to call this function, as	860	Under most circumstances you don't need to call this function, as
337	the module selects a default that is suitable for low to moderate	861	the module selects a default that is suitable for low to moderate
338	load.	862	load.
339		863
…		…
349	ensure that all threads are killed and that there are no outstanding	873	ensure that all threads are killed and that there are no outstanding
350	requests.	874	requests.
351		875
352	Under normal circumstances you don't need to call this function.	876	Under normal circumstances you don't need to call this function.
353		877
		878	IO::AIO::max_idle $nthreads
		879	Limit the number of threads (default: 4) that are allowed to idle
		880	(i.e., threads that did not get a request to process within 10
		881	seconds). That means if a thread becomes idle while $nthreads other
		882	threads are also idle, it will free its resources and exit.
		883
		884	This is useful when you allow a large number of threads (e.g. 100 or
		885	1000) to allow for extremely high load situations, but want to free
		886	resources under normal circumstances (1000 threads can easily
		887	consume 30MB of RAM).
		888
		889	The default is probably ok in most situations, especially if thread
		890	creation is fast. If thread creation is very slow on your system you
		891	might want to use larger values.
		892
354	$oldnreqs = IO::AIO::max_outstanding $nreqs	893	IO::AIO::max_outstanding $maxreqs
		894	This is a very bad function to use in interactive programs because
		895	it blocks, and a bad way to reduce concurrency because it is
		896	inexact: Better use an "aio_group" together with a feed callback.
		897
355	Sets the maximum number of outstanding requests to $nreqs. If you	898	Sets the maximum number of outstanding requests to $nreqs. If you do
356	try to queue up more than this number of requests, the caller will	899	queue up more than this number of requests, the next call to the
357	block until some requests have been handled.	900	"poll_cb" (and "poll_some" and other functions calling "poll_cb")
		901	function will block until the limit is no longer exceeded.
358		902
359	The default is very large, so normally there is no practical limit.	903	The default value is very large, so there is no practical limit on
360	If you queue up many requests in a loop it often improves speed if	904	the number of outstanding requests.
361	you set this to a relatively low number, such as 100.
362		905
363	Under normal circumstances you don't need to call this function.	906	You can still queue as many requests as you want. Therefore,
		907	"max_outstanding" is mainly useful in simple scripts (with low
		908	values) or as a stop gap to shield against fatal memory overflow
		909	(with large values).
		910
		911	STATISTICAL INFORMATION
		912	IO::AIO::nreqs
		913	Returns the number of requests currently in the ready, execute or
		914	pending states (i.e. for which their callback has not been invoked
		915	yet).
		916
		917	Example: wait till there are no outstanding requests anymore:
		918
		919	IO::AIO::poll_wait, IO::AIO::poll_cb
		920	while IO::AIO::nreqs;
		921
		922	IO::AIO::nready
		923	Returns the number of requests currently in the ready state (not yet
		924	executed).
		925
		926	IO::AIO::npending
		927	Returns the number of requests currently in the pending state
		928	(executed, but not yet processed by poll_cb).
364		929
365	FORK BEHAVIOUR	930	FORK BEHAVIOUR
		931	This module should do "the right thing" when the process using it forks:
		932
366	Before the fork, IO::AIO enters a quiescent state where no requests can	933	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	934	be added in other threads and no results will be processed. After the
368	fork the parent simply leaves the quiescent state and continues	935	fork the parent simply leaves the quiescent state and continues
369	request/result processing, while the child clears the request/result	936	request/result processing, while the child frees the request/result
370	queue (so the requests started before the fork will only be handled in	937	queue (so that the requests started before the fork will only be handled
371	the parent). Threats will be started on demand until the limit ste in	938	in the parent). Threads will be started on demand until the limit set in
372	the parent process has been reached again.	939	the parent process has been reached again.
373		940
		941	In short: the parent will, after a short pause, continue as if fork had
		942	not been called, while the child will act as if IO::AIO has not been
		943	used yet.
		944
		945	MEMORY USAGE
		946	Per-request usage:
		947
		948	Each aio request uses - depending on your architecture - around 100-200
		949	bytes of memory. In addition, stat requests need a stat buffer (possibly
		950	a few hundred bytes), readdir requires a result buffer and so on. Perl
		951	scalars and other data passed into aio requests will also be locked and
		952	will consume memory till the request has entered the done state.
		953
		954	This is not awfully much, so queuing lots of requests is not usually a
		955	problem.
		956
		957	Per-thread usage:
		958
		959	In the execution phase, some aio requests require more memory for
		960	temporary buffers, and each thread requires a stack and other data
		961	structures (usually around 16k-128k, depending on the OS).
		962
		963	KNOWN BUGS
		964	Known bugs will be fixed in the next release.
		965
374	SEE ALSO	966	SEE ALSO
375	Coro, Linux::AIO.	967	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
		968	more natural syntax.
376		969
377	AUTHOR	970	AUTHOR
378	Marc Lehmann <schmorp@schmorp.de>	971	Marc Lehmann <schmorp@schmorp.de>
379	http://home.schmorp.de/	972	http://home.schmorp.de/
380		973

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.14 by root, Mon Dec 26 18:31:12 2005 UTC vs. Revision 1.34 by root, Thu Nov 20 09:01:40 2008 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.14 by root, Mon Dec 26 18:31:12 2005 UTC vs.
Revision 1.34 by root, Thu Nov 20 09:01:40 2008 UTC