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

Comparing IO-AIO/README (file contents):
Revision 1.4 by root, Sun Jul 10 21:04:46 2005 UTC vs.
Revision 1.32 by root, Thu Oct 2 11:35:03 2008 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 = shift
		9	or die "/etc/passwd: $!";
		10	...
		11	};
		12
		13	aio_unlink "/tmp/file", sub { };
		14
		15	aio_read $fh, 30000, 1024, $buffer, 0, sub {
		16	$_[0] > 0 or die "read error: $!";
		17	};
		18
		19	# version 2+ has request and group objects
		20	use IO::AIO 2;
		21
		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
		36	Event->io (fd => IO::AIO::poll_fileno,
		37	poll => 'r',
		38	cb => \&IO::AIO::poll_cb);
		39
		40	# Glib/Gtk2 integration
		41	add_watch Glib::IO IO::AIO::poll_fileno,
		42	in => sub { IO::AIO::poll_cb; 1 };
		43
		44	# Tk integration
		45	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
		46	readable => \&IO::AIO::poll_cb);
		47
		48	# Danga::Socket integration
		49	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
		50	\&IO::AIO::poll_cb);
6		51
7	DESCRIPTION	52	DESCRIPTION
8	This module implements asynchronous I/O using whatever means your	53	This module implements asynchronous I/O using whatever means your
9	operating system supports.	54	operating system supports.
10		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
11	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
12	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
13	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
14	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
15	native aio functions available on many operating systems. However, they	76	functions available on many operating systems. However, they are often
16	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
17	currently, for example), and they would only support aio_read and	78	files currently, for example), and they would only support aio_read and
18	aio_write, so the remaining functionality would have to be implemented	79	aio_write, so the remaining functionality would have to be implemented
19	using threads anyway.	80	using threads anyway.
20		81
21	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,
22	is currently not reentrant, so use appropriate locking yourself.	83	it is currently not reentrant in any way, so use appropriate locking
		84	yourself, always call "poll_cb" from within the same thread, or never
		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).
23		172
24	FUNCTIONS	173	FUNCTIONS
25	AIO FUNCTIONS	174	AIO REQUEST FUNCTIONS
26	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
27	with the same name (sans "aio_"). The arguments are similar or	176	with the same name (sans "aio_"). The arguments are similar or
28	identical, and they all accept an additional $callback argument which	177	identical, and they all accept an additional (and optional) $callback
29	must be a code reference. This code reference will get called with the	178	argument which must be a code reference. This code reference will get
30	syscall return code (e.g. most syscalls return -1 on error, unlike perl,	179	called with the syscall return code (e.g. most syscalls return -1 on
31	which usually delivers "false") as it's sole argument when the given	180	error, unlike perl, which usually delivers "false") as its sole argument
32	syscall has been executed asynchronously.	181	after the given syscall has been executed asynchronously.
33		182
34	All functions that expect a filehandle will also accept a file	183	All functions expecting a filehandle keep a copy of the filehandle
35	descriptor.	184	internally until the request has finished.
36		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
37	The filenames you pass to these routines must be absolute. The reason	189	The pathnames you pass to these routines must be absolute and encoded
38	is that at the time the request is being executed, the current working	190	as octets. The reason for the former is that at the time the request is
39	directory could have changed. Alternatively, you can make sure that you	191	being executed, the current working directory could have changed.
40	never change the current working directory.	192	Alternatively, you can make sure that you never change the current
		193	working directory anywhere in the program and then use relative paths.
41		194
		195	To encode pathnames as octets, either make sure you either: a) always
		196	pass in filenames you got from outside (command line, readdir etc.)
		197	without tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module
		198	and encode your pathnames to the locale (or other) encoding in effect in
		199	the user environment, d) use Glib::filename_from_unicode on unicode
		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.
		234
42	aio_open $pathname, $flags, $mode, $callback	235	aio_open $pathname, $flags, $mode, $callback->($fh)
43	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
44	newly created filehandle for the file.	237	newly created filehandle for the file.
45		238
46	The pathname passed to "aio_open" must be absolute. See API NOTES,	239	The pathname passed to "aio_open" must be absolute. See API NOTES,
47	above, for an explanation.	240	above, for an explanation.
48		241
49	The $mode argument is a bitmask. See the "Fcntl" module for a list.	242	The $flags argument is a bitmask. See the "Fcntl" module for a list.
50	They are the same as used in "sysopen".	243	They are the same as used by "sysopen".
		244
		245	Likewise, $mode specifies the mode of the newly created file, if it
		246	didn't exist and "O_CREAT" has been given, just like perl's
		247	"sysopen", except that it is mandatory (i.e. use 0 if you don't
		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.
51		251
52	Example:	252	Example:
53		253
54	aio_open "/etc/passwd", O_RDONLY, 0, sub {	254	aio_open "/etc/passwd", O_RDONLY, 0, sub {
55	if ($_[0]) {	255	if ($_[0]) {
58	} else {	258	} else {
59	die "open failed: $!\n";	259	die "open failed: $!\n";
60	}	260	}
61	};	261	};
62		262
63	aio_close $fh, $callback	263	aio_close $fh, $callback->($status)
64	Asynchronously close a file and call the callback with the result	264	Asynchronously close a file and call the callback with the result
65	code. WARNING: although accepted, you should not pass in a perl	265	code.
66	filehandle here, as perl will likely close the file descriptor
67	itself when the filehandle is destroyed. Normally, you can safely
68	call perls "close" or just let filehandles go out of scope.
69		266
		267	Unfortunately, you can't do this to perl. Perl insists very
		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.
		277
70	aio_read $fh,$offset,$length, $data,$dataoffset,$callback	278	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
71	aio_write $fh,$offset,$length, $data,$dataoffset,$callback	279	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
72	Reads or writes "length" bytes from the specified "fh" and "offset"	280	Reads or writes $length bytes from the specified $fh and $offset
73	into the scalar given by "data" and offset "dataoffset" and calls	281	into the scalar given by $data and offset $dataoffset and calls the
74	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,
75	error, just like the syscall).	283	just like the syscall).
76		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.
		294
		295	The $data scalar MUST NOT be modified in any way while the request
		296	is outstanding. Modifying it can result in segfaults or World War
		297	III (if the necessary/optional hardware is installed).
		298
77	Example: Read 15 bytes at offset 7 into scalar $buffer, strating at	299	Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
78	offset 0 within the scalar:	300	offset 0 within the scalar:
79		301
80	aio_read $fh, 7, 15, $buffer, 0, sub {	302	aio_read $fh, 7, 15, $buffer, 0, sub {
81	$_[0] >= 0 or die "read error: $!";	303	$_[0] > 0 or die "read error: $!";
82	print "read <$buffer>\n";	304	print "read $_[0] bytes: <$buffer>\n";
83	};	305	};
84		306
		307	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
		308	Tries to copy $length bytes from $in_fh to $out_fh. It starts
		309	reading at byte offset $in_offset, and starts writing at the current
		310	file offset of $out_fh. Because of that, it is not safe to issue
		311	more than one "aio_sendfile" per $out_fh, as they will interfere
		312	with each other.
		313
		314	This call tries to make use of a native "sendfile" syscall to
		315	provide zero-copy operation. For this to work, $out_fh should refer
		316	to a socket, and $in_fh should refer to mmap'able file.
		317
		318	If the native sendfile call fails or is not implemented, it will be
		319	emulated, so you can call "aio_sendfile" on any type of filehandle
		320	regardless of the limitations of the operating system.
		321
		322	Please note, however, that "aio_sendfile" can read more bytes from
		323	$in_fh than are written, and there is no way to find out how many
		324	bytes have been read from "aio_sendfile" alone, as "aio_sendfile"
		325	only provides the number of bytes written to $out_fh. Only if the
		326	result value equals $length one can assume that $length bytes have
		327	been read.
		328
85	aio_readahead $fh,$offset,$length, $callback	329	aio_readahead $fh,$offset,$length, $callback->($retval)
86	Asynchronously reads the specified byte range into the page cache,
87	using the "readahead" syscall. If that syscall doesn't exist the
88	status will be -1 and $! is set to ENOSYS.
89
90	readahead() populates the page cache with data from a file so that	330	"aio_readahead" populates the page cache with data from a file so
91	subsequent reads from that file will not block on disk I/O. The	331	that subsequent reads from that file will not block on disk I/O. The
92	$offset argument specifies the starting point from which data is to	332	$offset argument specifies the starting point from which data is to
93	be read and $length specifies the number of bytes to be read. I/O is	333	be read and $length specifies the number of bytes to be read. I/O is
94	performed in whole pages, so that offset is effectively rounded down	334	performed in whole pages, so that offset is effectively rounded down
95	to a page boundary and bytes are read up to the next page boundary	335	to a page boundary and bytes are read up to the next page boundary
96	greater than or equal to (off-set+length). aio_readahead() does not	336	greater than or equal to (off-set+length). "aio_readahead" does not
97	read beyond the end of the file. The current file offset of the file	337	read beyond the end of the file. The current file offset of the file
98	is left unchanged.	338	is left unchanged.
99		339
		340	If that syscall doesn't exist (likely if your OS isn't Linux) it
		341	will be emulated by simply reading the data, which would have a
		342	similar effect.
		343
100	aio_stat $fh_or_path, $callback	344	aio_stat $fh_or_path, $callback->($status)
101	aio_lstat $fh, $callback	345	aio_lstat $fh, $callback->($status)
102	Works like perl's "stat" or "lstat" in void context. The callback	346	Works like perl's "stat" or "lstat" in void context. The callback
103	will be called after the stat and the results will be available	347	will be called after the stat and the results will be available
104	using "stat _" or "-s _" etc...	348	using "stat _" or "-s _" etc...
105		349
106	The pathname passed to "aio_stat" must be absolute. See API NOTES,	350	The pathname passed to "aio_stat" must be absolute. See API NOTES,
…		…
116	aio_stat "/etc/passwd", sub {	360	aio_stat "/etc/passwd", sub {
117	$_[0] and die "stat failed: $!";	361	$_[0] and die "stat failed: $!";
118	print "size is ", -s _, "\n";	362	print "size is ", -s _, "\n";
119	};	363	};
120		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
121	aio_unlink $pathname, $callback	399	aio_unlink $pathname, $callback->($status)
122	Asynchronously unlink (delete) a file and call the callback with the	400	Asynchronously unlink (delete) a file and call the callback with the
123	result code.	401	result code.
124		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
		435	aio_rmdir $pathname, $callback->($status)
		436	Asynchronously rmdir (delete) a directory and call the callback with
		437	the result code.
		438
		439	aio_readdir $pathname, $callback->($entries)
		440	Unlike the POSIX call of the same name, "aio_readdir" reads an
		441	entire directory (i.e. opendir + readdir + closedir). The entries
		442	will not be sorted, and will NOT include the "." and ".." entries.
		443
		444	The callback a single argument which is either "undef" or an
		445	array-ref with the filenames.
		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 files with "EXDEV", it copies the file with "aio_copy"
		472	and, if that is successful, unlinking the $srcpath.
		473
		474	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
		475	Scans a directory (similar to "aio_readdir") but additionally tries
		476	to efficiently separate the entries of directory $path into two sets
		477	of names, directories you can recurse into (directories), and ones
		478	you cannot recurse into (everything else, including symlinks to
		479	directories).
		480
		481	"aio_scandir" is a composite request that creates of many sub
		482	requests_ $maxreq specifies the maximum number of outstanding aio
		483	requests that this function generates. If it is "<= 0", then a
		484	suitable default will be chosen (currently 4).
		485
		486	On error, the callback is called without arguments, otherwise it
		487	receives two array-refs with path-relative entry names.
		488
		489	Example:
		490
		491	aio_scandir $dir, 0, sub {
		492	my ($dirs, $nondirs) = @_;
		493	print "real directories: @$dirs\n";
		494	print "everything else: @$nondirs\n";
		495	};
		496
		497	Implementation notes.
		498
		499	The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
		500	can.
		501
		502	After reading the directory, the modification time, size etc. of the
		503	directory before and after the readdir is checked, and if they match
		504	(and isn't the current time), the link count will be used to decide
		505	how many entries are directories (if >= 2). Otherwise, no knowledge
		506	of the number of subdirectories will be assumed.
		507
		508	Then entries will be sorted into likely directories (everything
		509	without a non-initial dot currently) and likely non-directories
		510	(everything else). Then every entry plus an appended "/." will be
		511	"stat"'ed, likely directories first. If that succeeds, it assumes
		512	that the entry is a directory or a symlink to directory (which will
		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).
		516
		517	If the known number of directories (link count - 2) has been
		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.
		535
125	aio_fsync $fh, $callback	536	aio_fsync $fh, $callback->($status)
126	Asynchronously call fsync on the given filehandle and call the	537	Asynchronously call fsync on the given filehandle and call the
127	callback with the fsync result code.	538	callback with the fsync result code.
128		539
129	aio_fdatasync $fh, $callback	540	aio_fdatasync $fh, $callback->($status)
130	Asynchronously call fdatasync on the given filehandle and call the	541	Asynchronously call fdatasync on the given filehandle and call the
131	callback with the fdatasync result code.	542	callback with the fdatasync result code.
132		543
		544	If this call isn't available because your OS lacks it or it couldn't
		545	be detected, it will be emulated by calling "fsync" instead.
		546
		547	aio_pathsync $path, $callback->($status)
		548	This request tries to open, fsync and close the given path. This is
		549	a composite request intended to sync directories after directory
		550	operations (E.g. rename). This might not work on all operating
		551	systems or have any specific effect, but usually it makes sure that
		552	directory changes get written to disc. It works for anything that
		553	can be opened for read-only, not just directories.
		554
		555	Passes 0 when everything went ok, and -1 on error.
		556
		557	aio_group $callback->(...)
		558	This is a very special aio request: Instead of doing something, it
		559	is a container for other aio requests, which is useful if you want
		560	to bundle many requests into a single, composite, request with a
		561	definite callback and the ability to cancel the whole request with
		562	its subrequests.
		563
		564	Returns an object of class IO::AIO::GRP. See its documentation below
		565	for more info.
		566
		567	Example:
		568
		569	my $grp = aio_group sub {
		570	print "all stats done\n";
		571	};
		572
		573	add $grp
		574	(aio_stat ...),
		575	(aio_stat ...),
		576	...;
		577
		578	aio_nop $callback->()
		579	This is a special request - it does nothing in itself and is only
		580	used for side effects, such as when you want to add a dummy request
		581	to a group so that finishing the requests in the group depends on
		582	executing the given code.
		583
		584	While this request does nothing, it still goes through the execution
		585	phase and still requires a worker thread. Thus, the callback will
		586	not be executed immediately but only after other requests in the
		587	queue have entered their execution phase. This can be used to
		588	measure request latency.
		589
		590	IO::AIO::aio_busy $fractional_seconds, $callback->() NOT EXPORTED
		591	Mainly used for debugging and benchmarking, this aio request puts
		592	one of the request workers to sleep for the given time.
		593
		594	While it is theoretically handy to have simple I/O scheduling
		595	requests like sleep and file handle readable/writable, the overhead
		596	this creates is immense (it blocks a thread for a long time) so do
		597	not use this function except to put your application under
		598	artificial I/O pressure.
		599
		600	IO::AIO::REQ CLASS
		601	All non-aggregate "aio_*" functions return an object of this class when
		602	called in non-void context.
		603
		604	cancel $req
		605	Cancels the request, if possible. Has the effect of skipping
		606	execution when entering the execute state and skipping calling the
		607	callback when entering the the result state, but will leave the
		608	request otherwise untouched. That means that requests that currently
		609	execute will not be stopped and resources held by the request will
		610	not be freed prematurely.
		611
		612	cb $req $callback->(...)
		613	Replace (or simply set) the callback registered to the request.
		614
		615	IO::AIO::GRP CLASS
		616	This class is a subclass of IO::AIO::REQ, so all its methods apply to
		617	objects of this class, too.
		618
		619	A IO::AIO::GRP object is a special request that can contain multiple
		620	other aio requests.
		621
		622	You create one by calling the "aio_group" constructing function with a
		623	callback that will be called when all contained requests have entered
		624	the "done" state:
		625
		626	my $grp = aio_group sub {
		627	print "all requests are done\n";
		628	};
		629
		630	You add requests by calling the "add" method with one or more
		631	"IO::AIO::REQ" objects:
		632
		633	$grp->add (aio_unlink "...");
		634
		635	add $grp aio_stat "...", sub {
		636	$_[0] or return $grp->result ("error");
		637
		638	# add another request dynamically, if first succeeded
		639	add $grp aio_open "...", sub {
		640	$grp->result ("ok");
		641	};
		642	};
		643
		644	This makes it very easy to create composite requests (see the source of
		645	"aio_move" for an application) that work and feel like simple requests.
		646
		647	* The IO::AIO::GRP objects will be cleaned up during calls to
		648	"IO::AIO::poll_cb", just like any other request.
		649
		650	* They can be canceled like any other request. Canceling will cancel
		651	not only the request itself, but also all requests it contains.
		652
		653	* They can also can also be added to other IO::AIO::GRP objects.
		654
		655	* You must not add requests to a group from within the group callback
		656	(or any later time).
		657
		658	Their lifetime, simplified, looks like this: when they are empty, they
		659	will finish very quickly. If they contain only requests that are in the
		660	"done" state, they will also finish. Otherwise they will continue to
		661	exist.
		662
		663	That means after creating a group you have some time to add requests
		664	(precisely before the callback has been invoked, which is only done
		665	within the "poll_cb"). And in the callbacks of those requests, you can
		666	add further requests to the group. And only when all those requests have
		667	finished will the the group itself finish.
		668
		669	add $grp ...
		670	$grp->add (...)
		671	Add one or more requests to the group. Any type of IO::AIO::REQ can
		672	be added, including other groups, as long as you do not create
		673	circular dependencies.
		674
		675	Returns all its arguments.
		676
		677	$grp->cancel_subs
		678	Cancel all subrequests and clears any feeder, but not the group
		679	request itself. Useful when you queued a lot of events but got a
		680	result early.
		681
		682	$grp->result (...)
		683	Set the result value(s) that will be passed to the group callback
		684	when all subrequests have finished and set the groups errno to the
		685	current value of errno (just like calling "errno" without an error
		686	number). By default, no argument will be passed and errno is zero.
		687
		688	$grp->errno ([$errno])
		689	Sets the group errno value to $errno, or the current value of errno
		690	when the argument is missing.
		691
		692	Every aio request has an associated errno value that is restored
		693	when the callback is invoked. This method lets you change this value
		694	from its default (0).
		695
		696	Calling "result" will also set errno, so make sure you either set $!
		697	before the call to "result", or call c<errno> after it.
		698
		699	feed $grp $callback->($grp)
		700	Sets a feeder/generator on this group: every group can have an
		701	attached generator that generates requests if idle. The idea behind
		702	this is that, although you could just queue as many requests as you
		703	want in a group, this might starve other requests for a potentially
		704	long time. For example, "aio_scandir" might generate hundreds of
		705	thousands "aio_stat" requests, delaying any later requests for a
		706	long time.
		707
		708	To avoid this, and allow incremental generation of requests, you can
		709	instead a group and set a feeder on it that generates those
		710	requests. The feed callback will be called whenever there are few
		711	enough (see "limit", below) requests active in the group itself and
		712	is expected to queue more requests.
		713
		714	The feed callback can queue as many requests as it likes (i.e. "add"
		715	does not impose any limits).
		716
		717	If the feed does not queue more requests when called, it will be
		718	automatically removed from the group.
		719
		720	If the feed limit is 0, it will be set to 2 automatically.
		721
		722	Example:
		723
		724	# stat all files in @files, but only ever use four aio requests concurrently:
		725
		726	my $grp = aio_group sub { print "finished\n" };
		727	limit $grp 4;
		728	feed $grp sub {
		729	my $file = pop @files
		730	or return;
		731
		732	add $grp aio_stat $file, sub { ... };
		733	};
		734
		735	limit $grp $num
		736	Sets the feeder limit for the group: The feeder will be called
		737	whenever the group contains less than this many requests.
		738
		739	Setting the limit to 0 will pause the feeding process.
		740
133	SUPPORT FUNCTIONS	741	SUPPORT FUNCTIONS
		742	EVENT PROCESSING AND EVENT LOOP INTEGRATION
134	$fileno = IO::AIO::poll_fileno	743	$fileno = IO::AIO::poll_fileno
135	Return the request result pipe filehandle. This filehandle must be	744	Return the request result pipe file descriptor. This filehandle
136	polled for reading by some mechanism outside this module (e.g. Event	745	must be polled for reading by some mechanism outside this module
137	or select, see below). If the pipe becomes readable you have to call	746	(e.g. Event or select, see below or the SYNOPSIS). If the pipe
138	"poll_cb" to check the results.	747	becomes readable you have to call "poll_cb" to check the results.
139		748
140	See "poll_cb" for an example.	749	See "poll_cb" for an example.
141		750
142	IO::AIO::poll_cb	751	IO::AIO::poll_cb
143	Process all outstanding events on the result pipe. You have to call	752	Process some outstanding events on the result pipe. You have to call
144	this regularly. Returns the number of events processed. Returns	753	this regularly. Returns 0 if all events could be processed, or -1 if
145	immediately when no events are outstanding.	754	it returned earlier for whatever reason. Returns immediately when no
		755	events are outstanding. The amount of events processed depends on
		756	the settings of "IO::AIO::max_poll_req" and
		757	"IO::AIO::max_poll_time".
146		758
147	You can use Event to multiplex, e.g.:	759	If not all requests were processed for whatever reason, the
		760	filehandle will still be ready when "poll_cb" returns, so normally
		761	you don't have to do anything special to have it called later.
		762
		763	Example: Install an Event watcher that automatically calls
		764	IO::AIO::poll_cb with high priority:
148		765
149	Event->io (fd => IO::AIO::poll_fileno,	766	Event->io (fd => IO::AIO::poll_fileno,
150	poll => 'r', async => 1,	767	poll => 'r', async => 1,
151	cb => \&IO::AIO::poll_cb);	768	cb => \&IO::AIO::poll_cb);
152		769
		770	IO::AIO::max_poll_reqs $nreqs
		771	IO::AIO::max_poll_time $seconds
		772	These set the maximum number of requests (default 0, meaning
		773	infinity) that are being processed by "IO::AIO::poll_cb" in one
		774	call, respectively the maximum amount of time (default 0, meaning
		775	infinity) spent in "IO::AIO::poll_cb" to process requests (more
		776	correctly the mininum amount of time "poll_cb" is allowed to use).
		777
		778	Setting "max_poll_time" to a non-zero value creates an overhead of
		779	one syscall per request processed, which is not normally a problem
		780	unless your callbacks are really really fast or your OS is really
		781	really slow (I am not mentioning Solaris here). Using
		782	"max_poll_reqs" incurs no overhead.
		783
		784	Setting these is useful if you want to ensure some level of
		785	interactiveness when perl is not fast enough to process all requests
		786	in time.
		787
		788	For interactive programs, values such as 0.01 to 0.1 should be fine.
		789
		790	Example: Install an Event watcher that automatically calls
		791	IO::AIO::poll_cb with low priority, to ensure that other parts of
		792	the program get the CPU sometimes even under high AIO load.
		793
		794	# try not to spend much more than 0.1s in poll_cb
		795	IO::AIO::max_poll_time 0.1;
		796
		797	# use a low priority so other tasks have priority
		798	Event->io (fd => IO::AIO::poll_fileno,
		799	poll => 'r', nice => 1,
		800	cb => &IO::AIO::poll_cb);
		801
153	IO::AIO::poll_wait	802	IO::AIO::poll_wait
		803	If there are any outstanding requests and none of them in the result
154	Wait till the result filehandle becomes ready for reading (simply	804	phase, wait till the result filehandle becomes ready for reading
155	does a select on the filehandle. This is useful if you want to	805	(simply does a "select" on the filehandle. This is useful if you
156	synchronously wait for some requests to finish).	806	want to synchronously wait for some requests to finish).
157		807
158	See "nreqs" for an example.	808	See "nreqs" for an example.
159		809
		810	IO::AIO::poll
		811	Waits until some requests have been handled.
		812
		813	Returns the number of requests processed, but is otherwise strictly
		814	equivalent to:
		815
		816	IO::AIO::poll_wait, IO::AIO::poll_cb
		817
160	IO::AIO::nreqs	818	IO::AIO::flush
161	Returns the number of requests currently outstanding.	819	Wait till all outstanding AIO requests have been handled.
162		820
163	Example: wait till there are no outstanding requests anymore:	821	Strictly equivalent to:
164		822
165	IO::AIO::poll_wait, IO::AIO::poll_cb	823	IO::AIO::poll_wait, IO::AIO::poll_cb
166	while IO::AIO::nreqs;	824	while IO::AIO::nreqs;
167		825
		826	CONTROLLING THE NUMBER OF THREADS
168	IO::AIO::min_parallel $nthreads	827	IO::AIO::min_parallel $nthreads
169	Set the minimum number of AIO threads to $nthreads. The default is	828	Set the minimum number of AIO threads to $nthreads. The current
170	1, which means a single asynchronous operation can be done at one	829	default is 8, which means eight asynchronous operations can execute
171	time (the number of outstanding operations, however, is unlimited).	830	concurrently at any one time (the number of outstanding requests,
		831	however, is unlimited).
172		832
		833	IO::AIO starts threads only on demand, when an AIO request is queued
		834	and no free thread exists. Please note that queueing up a hundred
		835	requests can create demand for a hundred threads, even if it turns
		836	out that everything is in the cache and could have been processed
		837	faster by a single thread.
		838
173	It is recommended to keep the number of threads low, as some Linux	839	It is recommended to keep the number of threads relatively low, as
174	kernel versions will scale negatively with the number of threads	840	some Linux kernel versions will scale negatively with the number of
175	(higher parallelity => MUCH higher latency). With current Linux 2.6	841	threads (higher parallelity => MUCH higher latency). With current
176	versions, 4-32 threads should be fine.	842	Linux 2.6 versions, 4-32 threads should be fine.
177		843
178	Under normal circumstances you don't need to call this function, as	844	Under most circumstances you don't need to call this function, as
179	this module automatically starts some threads (the exact number	845	the module selects a default that is suitable for low to moderate
180	might change, and is currently 4).	846	load.
181		847
182	IO::AIO::max_parallel $nthreads	848	IO::AIO::max_parallel $nthreads
183	Sets the maximum number of AIO threads to $nthreads. If more than	849	Sets the maximum number of AIO threads to $nthreads. If more than
184	the specified number of threads are currently running, kill them.	850	the specified number of threads are currently running, this function
185	This function blocks until the limit is reached.	851	kills them. This function blocks until the limit is reached.
		852
		853	While $nthreads are zero, aio requests get queued but not executed
		854	until the number of threads has been increased again.
186		855
187	This module automatically runs "max_parallel 0" at program end, to	856	This module automatically runs "max_parallel 0" at program end, to
188	ensure that all threads are killed and that there are no outstanding	857	ensure that all threads are killed and that there are no outstanding
189	requests.	858	requests.
190		859
191	Under normal circumstances you don't need to call this function.	860	Under normal circumstances you don't need to call this function.
192		861
		862	IO::AIO::max_idle $nthreads
		863	Limit the number of threads (default: 4) that are allowed to idle
		864	(i.e., threads that did not get a request to process within 10
		865	seconds). That means if a thread becomes idle while $nthreads other
		866	threads are also idle, it will free its resources and exit.
		867
		868	This is useful when you allow a large number of threads (e.g. 100 or
		869	1000) to allow for extremely high load situations, but want to free
		870	resources under normal circumstances (1000 threads can easily
		871	consume 30MB of RAM).
		872
		873	The default is probably ok in most situations, especially if thread
		874	creation is fast. If thread creation is very slow on your system you
		875	might want to use larger values.
		876
193	$oldnreqs = IO::AIO::max_outstanding $nreqs	877	IO::AIO::max_outstanding $maxreqs
		878	This is a very bad function to use in interactive programs because
		879	it blocks, and a bad way to reduce concurrency because it is
		880	inexact: Better use an "aio_group" together with a feed callback.
		881
194	Sets the maximum number of outstanding requests to $nreqs. If you	882	Sets the maximum number of outstanding requests to $nreqs. If you do
195	try to queue up more than this number of requests, the caller will	883	queue up more than this number of requests, the next call to the
196	block until some requests have been handled.	884	"poll_cb" (and "poll_some" and other functions calling "poll_cb")
		885	function will block until the limit is no longer exceeded.
197		886
198	The default is very large, so normally there is no practical limit.	887	The default value is very large, so there is no practical limit on
199	If you queue up many requests in a loop it it often improves speed	888	the number of outstanding requests.
200	if you set this to a relatively low number, such as 100.
201		889
202	Under normal circumstances you don't need to call this function.	890	You can still queue as many requests as you want. Therefore,
		891	"max_outstanding" is mainly useful in simple scripts (with low
		892	values) or as a stop gap to shield against fatal memory overflow
		893	(with large values).
		894
		895	STATISTICAL INFORMATION
		896	IO::AIO::nreqs
		897	Returns the number of requests currently in the ready, execute or
		898	pending states (i.e. for which their callback has not been invoked
		899	yet).
		900
		901	Example: wait till there are no outstanding requests anymore:
		902
		903	IO::AIO::poll_wait, IO::AIO::poll_cb
		904	while IO::AIO::nreqs;
		905
		906	IO::AIO::nready
		907	Returns the number of requests currently in the ready state (not yet
		908	executed).
		909
		910	IO::AIO::npending
		911	Returns the number of requests currently in the pending state
		912	(executed, but not yet processed by poll_cb).
		913
		914	FORK BEHAVIOUR
		915	This module should do "the right thing" when the process using it forks:
		916
		917	Before the fork, IO::AIO enters a quiescent state where no requests can
		918	be added in other threads and no results will be processed. After the
		919	fork the parent simply leaves the quiescent state and continues
		920	request/result processing, while the child frees the request/result
		921	queue (so that the requests started before the fork will only be handled
		922	in the parent). Threads will be started on demand until the limit set in
		923	the parent process has been reached again.
		924
		925	In short: the parent will, after a short pause, continue as if fork had
		926	not been called, while the child will act as if IO::AIO has not been
		927	used yet.
		928
		929	MEMORY USAGE
		930	Per-request usage:
		931
		932	Each aio request uses - depending on your architecture - around 100-200
		933	bytes of memory. In addition, stat requests need a stat buffer (possibly
		934	a few hundred bytes), readdir requires a result buffer and so on. Perl
		935	scalars and other data passed into aio requests will also be locked and
		936	will consume memory till the request has entered the done state.
		937
		938	This is not awfully much, so queuing lots of requests is not usually a
		939	problem.
		940
		941	Per-thread usage:
		942
		943	In the execution phase, some aio requests require more memory for
		944	temporary buffers, and each thread requires a stack and other data
		945	structures (usually around 16k-128k, depending on the OS).
		946
		947	KNOWN BUGS
		948	Known bugs will be fixed in the next release.
203		949
204	SEE ALSO	950	SEE ALSO
205	Coro, Linux::AIO.	951	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
		952	more natural syntax.
206		953
207	AUTHOR	954	AUTHOR
208	Marc Lehmann <schmorp@schmorp.de>	955	Marc Lehmann <schmorp@schmorp.de>
209	http://home.schmorp.de/	956	http://home.schmorp.de/
210		957

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.4 by root, Sun Jul 10 21:04:46 2005 UTC vs. Revision 1.32 by root, Thu Oct 2 11:35:03 2008 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.4 by root, Sun Jul 10 21:04:46 2005 UTC vs.
Revision 1.32 by root, Thu Oct 2 11:35:03 2008 UTC