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

Comparing IO-AIO/README (file contents):
Revision 1.47 by root, Fri May 27 00:44:49 2011 UTC vs.
Revision 1.50 by root, Sun Oct 9 08:24:49 2011 UTC

…		…
150	QUICK OVERVIEW	150	QUICK OVERVIEW
151	This section simply lists the prototypes of the most important functions	151	This section simply lists the prototypes of the most important functions
152	for quick reference. See the following sections for function-by-function	152	for quick reference. See the following sections for function-by-function
153	documentation.	153	documentation.
154		154
		155	aio_wd $pathname, $callback->($wd)
155	aio_open $pathname, $flags, $mode, $callback->($fh)	156	aio_open $pathname, $flags, $mode, $callback->($fh)
156	aio_close $fh, $callback->($status)	157	aio_close $fh, $callback->($status)
157	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	158	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
158	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	159	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
159	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)	160	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
…		…
164	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	165	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
165	aio_chown $fh_or_path, $uid, $gid, $callback->($status)	166	aio_chown $fh_or_path, $uid, $gid, $callback->($status)
166	aio_truncate $fh_or_path, $offset, $callback->($status)	167	aio_truncate $fh_or_path, $offset, $callback->($status)
167	aio_chmod $fh_or_path, $mode, $callback->($status)	168	aio_chmod $fh_or_path, $mode, $callback->($status)
168	aio_unlink $pathname, $callback->($status)	169	aio_unlink $pathname, $callback->($status)
169	aio_mknod $path, $mode, $dev, $callback->($status)	170	aio_mknod $pathname, $mode, $dev, $callback->($status)
170	aio_link $srcpath, $dstpath, $callback->($status)	171	aio_link $srcpath, $dstpath, $callback->($status)
171	aio_symlink $srcpath, $dstpath, $callback->($status)	172	aio_symlink $srcpath, $dstpath, $callback->($status)
172	aio_readlink $path, $callback->($link)	173	aio_readlink $pathname, $callback->($link)
		174	aio_realpath $pathname, $callback->($link)
173	aio_rename $srcpath, $dstpath, $callback->($status)	175	aio_rename $srcpath, $dstpath, $callback->($status)
174	aio_mkdir $pathname, $mode, $callback->($status)	176	aio_mkdir $pathname, $mode, $callback->($status)
175	aio_rmdir $pathname, $callback->($status)	177	aio_rmdir $pathname, $callback->($status)
176	aio_readdir $pathname, $callback->($entries)	178	aio_readdir $pathname, $callback->($entries)
177	aio_readdirx $pathname, $flags, $callback->($entries, $flags)	179	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
178	IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST	180	IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
179	IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN	181	IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
		182	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
180	aio_load $path, $data, $callback->($status)	183	aio_load $pathname, $data, $callback->($status)
181	aio_copy $srcpath, $dstpath, $callback->($status)	184	aio_copy $srcpath, $dstpath, $callback->($status)
182	aio_move $srcpath, $dstpath, $callback->($status)	185	aio_move $srcpath, $dstpath, $callback->($status)
183	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
184	aio_rmtree $path, $callback->($status)	186	aio_rmtree $pathname, $callback->($status)
185	aio_sync $callback->($status)	187	aio_sync $callback->($status)
		188	aio_syncfs $fh, $callback->($status)
186	aio_fsync $fh, $callback->($status)	189	aio_fsync $fh, $callback->($status)
187	aio_fdatasync $fh, $callback->($status)	190	aio_fdatasync $fh, $callback->($status)
188	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)	191	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
189	aio_pathsync $path, $callback->($status)	192	aio_pathsync $pathname, $callback->($status)
190	aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)	193	aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
191	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)	194	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
192	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)	195	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
193	aio_mlockall $flags, $callback->($status)	196	aio_mlockall $flags, $callback->($status)
194	aio_group $callback->(...)	197	aio_group $callback->(...)
…		…
221		224
222	AIO REQUEST FUNCTIONS	225	AIO REQUEST FUNCTIONS
223	All the "aio_*" calls are more or less thin wrappers around the syscall	226	All the "aio_*" calls are more or less thin wrappers around the syscall
224	with the same name (sans "aio_"). The arguments are similar or	227	with the same name (sans "aio_"). The arguments are similar or
225	identical, and they all accept an additional (and optional) $callback	228	identical, and they all accept an additional (and optional) $callback
226	argument which must be a code reference. This code reference will get	229	argument which must be a code reference. This code reference will be
227	called with the syscall return code (e.g. most syscalls return -1 on
228	error, unlike perl, which usually delivers "false") as its sole argument
229	after the given syscall has been executed asynchronously.	230	called after the syscall has been executed in an asynchronous fashion.
		231	The results of the request will be passed as arguments to the callback
		232	(and, if an error occured, in $!) - for most requests the syscall return
		233	code (e.g. most syscalls return -1 on error, unlike perl, which usually
		234	delivers "false").
		235
		236	Some requests (such as "aio_readdir") pass the actual results and
		237	communicate failures by passing "undef".
230		238
231	All functions expecting a filehandle keep a copy of the filehandle	239	All functions expecting a filehandle keep a copy of the filehandle
232	internally until the request has finished.	240	internally until the request has finished.
233		241
234	All functions return request objects of type IO::AIO::REQ that allow	242	All functions return request objects of type IO::AIO::REQ that allow
235	further manipulation of those requests while they are in-flight.	243	further manipulation of those requests while they are in-flight.
236		244
237	The pathnames you pass to these routines must be absolute and encoded	245	The pathnames you pass to these routines should be absolute. The
238	as octets. The reason for the former is that at the time the request is	246	reason for this is that at the time the request is being executed, the
239	being executed, the current working directory could have changed.	247	current working directory could have changed. Alternatively, you can
240	Alternatively, you can make sure that you never change the current	248	make sure that you never change the current working directory anywhere
241	working directory anywhere in the program and then use relative paths.	249	in the program and then use relative paths. You can also take advantage
		250	of IO::AIOs working directory abstraction, that lets you specify paths
		251	relative to some previously-opened "working directory object" - see the
		252	description of the "IO::AIO::WD" class later in this document.
242		253
243	To encode pathnames as octets, either make sure you either: a) always	254	To encode pathnames as octets, either make sure you either: a) always
244	pass in filenames you got from outside (command line, readdir etc.)	255	pass in filenames you got from outside (command line, readdir etc.)
245	without tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module	256	without tinkering, b) are in your native filesystem encoding, c) use the
246	and encode your pathnames to the locale (or other) encoding in effect in	257	Encode module and encode your pathnames to the locale (or other)
247	the user environment, d) use Glib::filename_from_unicode on unicode	258	encoding in effect in the user environment, d) use
248	filenames or e) use something else to ensure your scalar has the correct	259	Glib::filename_from_unicode on unicode filenames or e) use something
249	contents.	260	else to ensure your scalar has the correct contents.
250		261
251	This works, btw. independent of the internal UTF-8 bit, which IO::AIO	262	This works, btw. independent of the internal UTF-8 bit, which IO::AIO
252	handles correctly whether it is set or not.	263	handles correctly whether it is set or not.
253		264
254	$prev_pri = aioreq_pri [$pri]	265	$prev_pri = aioreq_pri [$pri]
…		…
367	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)	378	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
368	Tries to copy $length bytes from $in_fh to $out_fh. It starts	379	Tries to copy $length bytes from $in_fh to $out_fh. It starts
369	reading at byte offset $in_offset, and starts writing at the current	380	reading at byte offset $in_offset, and starts writing at the current
370	file offset of $out_fh. Because of that, it is not safe to issue	381	file offset of $out_fh. Because of that, it is not safe to issue
371	more than one "aio_sendfile" per $out_fh, as they will interfere	382	more than one "aio_sendfile" per $out_fh, as they will interfere
372	with each other.	383	with each other. The same $in_fh works fine though, as this function
		384	does not move or use the file offset of $in_fh.
373		385
374	Please note that "aio_sendfile" can read more bytes from $in_fh than	386	Please note that "aio_sendfile" can read more bytes from $in_fh than
375	are written, and there is no way to find out how many bytes have	387	are written, and there is no way to find out how many more bytes
376	been read from "aio_sendfile" alone, as "aio_sendfile" only provides	388	have been read from "aio_sendfile" alone, as "aio_sendfile" only
377	the number of bytes written to $out_fh. Only if the result value	389	provides the number of bytes written to $out_fh. Only if the result
378	equals $length one can assume that $length bytes have been read.	390	value equals $length one can assume that $length bytes have been
		391	read.
379		392
380	Unlike with other "aio_" functions, it makes a lot of sense to use	393	Unlike with other "aio_" functions, it makes a lot of sense to use
381	"aio_sendfile" on non-blocking sockets, as long as one end	394	"aio_sendfile" on non-blocking sockets, as long as one end
382	(typically the $in_fh) is a file - the file I/O will then be	395	(typically the $in_fh) is a file - the file I/O will then be
383	asynchronous, while the socket I/O will be non-blocking. Note,	396	asynchronous, while the socket I/O will be non-blocking. Note,
384	however, that you can run into a trap where "aio_sendfile" reads	397	however, that you can run into a trap where "aio_sendfile" reads
385	some data with readahead, then fails to write all data, and when the	398	some data with readahead, then fails to write all data, and when the
386	socket is ready the next time, the data in the cache is already	399	socket is ready the next time, the data in the cache is already
387	lost, forcing "aio_sendfile" to again hit the disk. Explicit	400	lost, forcing "aio_sendfile" to again hit the disk. Explicit
388	"aio_read" + "aio_write" let's you control resource usage much	401	"aio_read" + "aio_write" let's you better control resource usage.
389	better.
390		402
391	This call tries to make use of a native "sendfile" syscall to	403	This call tries to make use of a native "sendfile"-like syscall to
392	provide zero-copy operation. For this to work, $out_fh should refer	404	provide zero-copy operation. For this to work, $out_fh should refer
393	to a socket, and $in_fh should refer to an mmap'able file.	405	to a socket, and $in_fh should refer to an mmap'able file.
394		406
395	If a native sendfile cannot be found or it fails with "ENOSYS",	407	If a native sendfile cannot be found or it fails with "ENOSYS",
396	"ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK",	408	"EINVAL", "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or
397	it will be emulated, so you can call "aio_sendfile" on any type of	409	"ENOTSOCK", it will be emulated, so you can call "aio_sendfile" on
398	filehandle regardless of the limitations of the operating system.	410	any type of filehandle regardless of the limitations of the
		411	operating system.
		412
		413	As native sendfile syscalls (as practically any non-POSIX interface
		414	hacked together in a hurry to improve benchmark numbers) tend to be
		415	rather buggy on many systems, this implementation tries to work
		416	around some known bugs in Linux and FreeBSD kernels (probably
		417	others, too), but that might fail, so you really really should check
		418	the return value of "aio_sendfile" - fewre bytes than expected might
		419	have been transferred.
399		420
400	aio_readahead $fh,$offset,$length, $callback->($retval)	421	aio_readahead $fh,$offset,$length, $callback->($retval)
401	"aio_readahead" populates the page cache with data from a file so	422	"aio_readahead" populates the page cache with data from a file so
402	that subsequent reads from that file will not block on disk I/O. The	423	that subsequent reads from that file will not block on disk I/O. The
403	$offset argument specifies the starting point from which data is to	424	$offset argument specifies the starting point from which data is to
…		…
521		542
522	aio_unlink $pathname, $callback->($status)	543	aio_unlink $pathname, $callback->($status)
523	Asynchronously unlink (delete) a file and call the callback with the	544	Asynchronously unlink (delete) a file and call the callback with the
524	result code.	545	result code.
525		546
526	aio_mknod $path, $mode, $dev, $callback->($status)	547	aio_mknod $pathname, $mode, $dev, $callback->($status)
527	[EXPERIMENTAL]	548	[EXPERIMENTAL]
528		549
529	Asynchronously create a device node (or fifo). See mknod(2).	550	Asynchronously create a device node (or fifo). See mknod(2).
530		551
531	The only (POSIX-) portable way of calling this function is:	552	The only (POSIX-) portable way of calling this function is:
532		553
533	aio_mknod $path, IO::AIO::S_IFIFO \| $mode, 0, sub { ...	554	aio_mknod $pathname, IO::AIO::S_IFIFO \| $mode, 0, sub { ...
534		555
535	See "aio_stat" for info about some potentially helpful extra	556	See "aio_stat" for info about some potentially helpful extra
536	constants and functions.	557	constants and functions.
537		558
538	aio_link $srcpath, $dstpath, $callback->($status)	559	aio_link $srcpath, $dstpath, $callback->($status)
…		…
542	aio_symlink $srcpath, $dstpath, $callback->($status)	563	aio_symlink $srcpath, $dstpath, $callback->($status)
543	Asynchronously create a new symbolic link to the existing object at	564	Asynchronously create a new symbolic link to the existing object at
544	$srcpath at the path $dstpath and call the callback with the result	565	$srcpath at the path $dstpath and call the callback with the result
545	code.	566	code.
546		567
547	aio_readlink $path, $callback->($link)	568	aio_readlink $pathname, $callback->($link)
548	Asynchronously read the symlink specified by $path and pass it to	569	Asynchronously read the symlink specified by $path and pass it to
549	the callback. If an error occurs, nothing or undef gets passed to	570	the callback. If an error occurs, nothing or undef gets passed to
550	the callback.	571	the callback.
		572
		573	aio_realpath $pathname, $callback->($path)
		574	Asynchronously make the path absolute and resolve any symlinks in
		575	$path. The resulting path only consists of directories (Same as
		576	Cwd::realpath).
		577
		578	This request can be used to get the absolute path of the current
		579	working directory by passing it a path of . (a single dot).
551		580
552	aio_rename $srcpath, $dstpath, $callback->($status)	581	aio_rename $srcpath, $dstpath, $callback->($status)
553	Asynchronously rename the object at $srcpath to $dstpath, just as	582	Asynchronously rename the object at $srcpath to $dstpath, just as
554	rename(2) and call the callback with the result code.	583	rename(2) and call the callback with the result code.
555		584
…		…
569		598
570	The callback is passed a single argument which is either "undef" or	599	The callback is passed a single argument which is either "undef" or
571	an array-ref with the filenames.	600	an array-ref with the filenames.
572		601
573	aio_readdirx $pathname, $flags, $callback->($entries, $flags)	602	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
574	Quite similar to "aio_readdir", but the $flags argument allows to	603	Quite similar to "aio_readdir", but the $flags argument allows one
575	tune behaviour and output format. In case of an error, $entries will	604	to tune behaviour and output format. In case of an error, $entries
576	be "undef".	605	will be "undef".
577		606
578	The flags are a combination of the following constants, ORed	607	The flags are a combination of the following constants, ORed
579	together (the flags will also be passed to the callback, possibly	608	together (the flags will also be passed to the callback, possibly
580	modified):	609	modified):
581		610
…		…
626	optimal stat order.	655	optimal stat order.
627		656
628	IO::AIO::READDIR_FOUND_UNKNOWN	657	IO::AIO::READDIR_FOUND_UNKNOWN
629	This flag should not be set when calling "aio_readdirx".	658	This flag should not be set when calling "aio_readdirx".
630	Instead, it is being set by "aio_readdirx", when any of the	659	Instead, it is being set by "aio_readdirx", when any of the
631	$type's found were "IO::AIO::DT_UNKNOWN". The absense of this	660	$type's found were "IO::AIO::DT_UNKNOWN". The absence of this
632	flag therefore indicates that all $type's are known, which can	661	flag therefore indicates that all $type's are known, which can
633	be used to speed up some algorithms.	662	be used to speed up some algorithms.
634		663
635	aio_load $path, $data, $callback->($status)	664	aio_load $pathname, $data, $callback->($status)
636	This is a composite request that tries to fully load the given file	665	This is a composite request that tries to fully load the given file
637	into memory. Status is the same as with aio_read.	666	into memory. Status is the same as with aio_read.
638		667
639	aio_copy $srcpath, $dstpath, $callback->($status)	668	aio_copy $srcpath, $dstpath, $callback->($status)
640	Try to copy the file (directories not supported as either source	669	Try to copy the file (directories not supported as either source
…		…
657		686
658	This is a composite request that tries to rename(2) the file first;	687	This is a composite request that tries to rename(2) the file first;
659	if rename fails with "EXDEV", it copies the file with "aio_copy"	688	if rename fails with "EXDEV", it copies the file with "aio_copy"
660	and, if that is successful, unlinks the $srcpath.	689	and, if that is successful, unlinks the $srcpath.
661		690
662	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)	691	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
663	Scans a directory (similar to "aio_readdir") but additionally tries	692	Scans a directory (similar to "aio_readdir") but additionally tries
664	to efficiently separate the entries of directory $path into two sets	693	to efficiently separate the entries of directory $path into two sets
665	of names, directories you can recurse into (directories), and ones	694	of names, directories you can recurse into (directories), and ones
666	you cannot recurse into (everything else, including symlinks to	695	you cannot recurse into (everything else, including symlinks to
667	directories).	696	directories).
…		…
700	Then entries will be sorted into likely directories a non-initial	729	Then entries will be sorted into likely directories a non-initial
701	dot currently) and likely non-directories (see "aio_readdirx"). Then	730	dot currently) and likely non-directories (see "aio_readdirx"). Then
702	every entry plus an appended "/." will be "stat"'ed, likely	731	every entry plus an appended "/." will be "stat"'ed, likely
703	directories first, in order of their inode numbers. If that	732	directories first, in order of their inode numbers. If that
704	succeeds, it assumes that the entry is a directory or a symlink to	733	succeeds, it assumes that the entry is a directory or a symlink to
705	directory (which will be checked seperately). This is often faster	734	directory (which will be checked separately). This is often faster
706	than stat'ing the entry itself because filesystems might detect the	735	than stat'ing the entry itself because filesystems might detect the
707	type of the entry without reading the inode data (e.g. ext2fs	736	type of the entry without reading the inode data (e.g. ext2fs
708	filetype feature), even on systems that cannot return the filetype	737	filetype feature), even on systems that cannot return the filetype
709	information on readdir.	738	information on readdir.
710		739
…		…
716		745
717	It will also likely work on non-POSIX filesystems with reduced	746	It will also likely work on non-POSIX filesystems with reduced
718	efficiency as those tend to return 0 or 1 as link counts, which	747	efficiency as those tend to return 0 or 1 as link counts, which
719	disables the directory counting heuristic.	748	disables the directory counting heuristic.
720		749
721	aio_rmtree $path, $callback->($status)	750	aio_rmtree $pathname, $callback->($status)
722	Delete a directory tree starting (and including) $path, return the	751	Delete a directory tree starting (and including) $path, return the
723	status of the final "rmdir" only. This is a composite request that	752	status of the final "rmdir" only. This is a composite request that
724	uses "aio_scandir" to recurse into and rmdir directories, and unlink	753	uses "aio_scandir" to recurse into and rmdir directories, and unlink
725	everything else.	754	everything else.
726		755
…		…
735	Asynchronously call fdatasync on the given filehandle and call the	764	Asynchronously call fdatasync on the given filehandle and call the
736	callback with the fdatasync result code.	765	callback with the fdatasync result code.
737		766
738	If this call isn't available because your OS lacks it or it couldn't	767	If this call isn't available because your OS lacks it or it couldn't
739	be detected, it will be emulated by calling "fsync" instead.	768	be detected, it will be emulated by calling "fsync" instead.
		769
		770	aio_syncfs $fh, $callback->($status)
		771	Asynchronously call the syncfs syscall to sync the filesystem
		772	associated to the given filehandle and call the callback with the
		773	syncfs result code. If syncfs is not available, calls sync(), but
		774	returns -1 and sets errno to "ENOSYS" nevertheless.
740		775
741	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)	776	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
742	Sync the data portion of the file specified by $offset and $length	777	Sync the data portion of the file specified by $offset and $length
743	to disk (but NOT the metadata), by calling the Linux-specific	778	to disk (but NOT the metadata), by calling the Linux-specific
744	sync_file_range call. If sync_file_range is not available or it	779	sync_file_range call. If sync_file_range is not available or it
…		…
748	"IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",	783	"IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
749	"IO::AIO::SYNC_FILE_RANGE_WRITE" and	784	"IO::AIO::SYNC_FILE_RANGE_WRITE" and
750	"IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range	785	"IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
751	manpage for details.	786	manpage for details.
752		787
753	aio_pathsync $path, $callback->($status)	788	aio_pathsync $pathname, $callback->($status)
754	This request tries to open, fsync and close the given path. This is	789	This request tries to open, fsync and close the given path. This is
755	a composite request intended to sync directories after directory	790	a composite request intended to sync directories after directory
756	operations (E.g. rename). This might not work on all operating	791	operations (E.g. rename). This might not work on all operating
757	systems or have any specific effect, but usually it makes sure that	792	systems or have any specific effect, but usually it makes sure that
758	directory changes get written to disc. It works for anything that	793	directory changes get written to disc. It works for anything that
…		…
871	requests like sleep and file handle readable/writable, the overhead	906	requests like sleep and file handle readable/writable, the overhead
872	this creates is immense (it blocks a thread for a long time) so do	907	this creates is immense (it blocks a thread for a long time) so do
873	not use this function except to put your application under	908	not use this function except to put your application under
874	artificial I/O pressure.	909	artificial I/O pressure.
875		910
		911	IO::AIO::WD - multiple working directories
		912	Your process only has one current working directory, which is used by
		913	all threads. This makes it hard to use relative paths (some other
		914	component could call "chdir" at any time, and it is hard to control when
		915	the path will be used by IO::AIO).
		916
		917	One solution for this is to always use absolute paths. This usually
		918	works, but can be quite slow (the kernel has to walk the whole path on
		919	every access), and can also be a hassle to implement.
		920
		921	Newer POSIX systems have a number of functions (openat, fdopendir,
		922	futimensat and so on) that make it possible to specify working
		923	directories per operation.
		924
		925	For portability, and because the clowns who "designed", or shall I
		926	write, perpetrated this new interface were obviously half-drunk, this
		927	abstraction cannot be perfect, though.
		928
		929	IO::AIO allows you to convert directory paths into a so-called
		930	IO::AIO::WD object. This object stores the canonicalised, absolute
		931	version of the path, and on systems that allow it, also a directory file
		932	descriptor.
		933
		934	Everywhere where a pathname is accepted by IO::AIO (e.g. in "aio_stat"
		935	or "aio_unlink"), one can specify an array reference with an IO::AIO::WD
		936	object and a pathname instead (or the IO::AIO::WD object alone, which
		937	gets interpreted as "[$wd, "."]"). If the pathname is absolute, the
		938	IO::AIO::WD object is ignored, otherwise the pathname is resolved
		939	relative to that IO::AIO::WD object.
		940
		941	For example, to get a wd object for /etc and then stat passwd inside,
		942	you would write:
		943
		944	aio_wd "/etc", sub {
		945	my $etcdir = shift;
		946
		947	# although $etcdir can be undef on error, there is generally no reason
		948	# to check for errors here, as aio_stat will fail with ENOENT
		949	# when $etcdir is undef.
		950
		951	aio_stat [$etcdir, "passwd"], sub {
		952	# yay
		953	};
		954	};
		955
		956	That "aio_wd" is a request and not a normal function shows that creating
		957	an IO::AIO::WD object is itself a potentially blocking operation, which
		958	is why it is done asynchronously.
		959
		960	To stat the directory obtained with "aio_wd" above, one could write
		961	either of the following three request calls:
		962
		963	aio_lstat "/etc" , sub { ... # pathname as normal string
		964	aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
		965	aio_lstat $wd , sub { ... # shorthand for the previous
		966
		967	As with normal pathnames, IO::AIO keeps a copy of the working directory
		968	object and the pathname string, so you could write the following without
		969	causing any issues due to $path getting reused:
		970
		971	my $path = [$wd, undef];
		972
		973	for my $name (qw(abc def ghi)) {
		974	$path->[1] = $name;
		975	aio_stat $path, sub {
		976	# ...
		977	};
		978	}
		979
		980	There are some caveats: when directories get renamed (or deleted), the
		981	pathname string doesn't change, so will point to the new directory (or
		982	nowhere at all), while the directory fd, if available on the system,
		983	will still point to the original directory. Most functions accepting a
		984	pathname will use the directory fd on newer systems, and the string on
		985	older systems. Some functions (such as realpath) will always rely on the
		986	string form of the pathname.
		987
		988	So this fucntionality is mainly useful to get some protection against
		989	"chdir", to easily get an absolute path out of a relative path for
		990	future reference, and to speed up doing many operations in the same
		991	directory (e.g. when stat'ing all files in a directory).
		992
		993	The following functions implement this working directory abstraction:
		994
		995	aio_wd $pathname, $callback->($wd)
		996	Asynchonously canonicalise the given pathname and convert it to an
		997	IO::AIO::WD object representing it. If possible and supported on the
		998	system, also open a directory fd to speed up pathname resolution
		999	relative to this working directory.
		1000
		1001	If something goes wrong, then "undef" is passwd to the callback
		1002	instead of a working directory object and $! is set appropriately.
		1003	Since passing "undef" as working directory component of a pathname
		1004	fails the request with "ENOENT", there is often no need for error
		1005	checking in the "aio_wd" callback, as future requests using the
		1006	value will fail in the expected way.
		1007
		1008	If this call isn't available because your OS lacks it or it couldn't
		1009	be detected, it will be emulated by calling "fsync" instead.
		1010
		1011	IO::AIO::CWD
		1012	This is a compiletime constant (object) that represents the process
		1013	current working directory.
		1014
		1015	Specifying this object as working directory object for a pathname is
		1016	as if the pathname would be specified directly, without a directory
		1017	object, e.g., these calls are functionally identical:
		1018
		1019	aio_stat "somefile", sub { ... };
		1020	aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
		1021
876	IO::AIO::REQ CLASS	1022	IO::AIO::REQ CLASS
877	All non-aggregate "aio_*" functions return an object of this class when	1023	All non-aggregate "aio_*" functions return an object of this class when
878	called in non-void context.	1024	called in non-void context.
879		1025
880	cancel $req	1026	cancel $req
…		…
979	Sets a feeder/generator on this group: every group can have an	1125	Sets a feeder/generator on this group: every group can have an
980	attached generator that generates requests if idle. The idea behind	1126	attached generator that generates requests if idle. The idea behind
981	this is that, although you could just queue as many requests as you	1127	this is that, although you could just queue as many requests as you
982	want in a group, this might starve other requests for a potentially	1128	want in a group, this might starve other requests for a potentially
983	long time. For example, "aio_scandir" might generate hundreds of	1129	long time. For example, "aio_scandir" might generate hundreds of
984	thousands "aio_stat" requests, delaying any later requests for a	1130	thousands of "aio_stat" requests, delaying any later requests for a
985	long time.	1131	long time.
986		1132
987	To avoid this, and allow incremental generation of requests, you can	1133	To avoid this, and allow incremental generation of requests, you can
988	instead a group and set a feeder on it that generates those	1134	instead a group and set a feeder on it that generates those
989	requests. The feed callback will be called whenever there are few	1135	requests. The feed callback will be called whenever there are few
…		…
1170	IO::AIO::idle_timeout $seconds	1316	IO::AIO::idle_timeout $seconds
1171	Sets the minimum idle timeout (default 10) after which worker	1317	Sets the minimum idle timeout (default 10) after which worker
1172	threads are allowed to exit. SEe "IO::AIO::max_idle".	1318	threads are allowed to exit. SEe "IO::AIO::max_idle".
1173		1319
1174	IO::AIO::max_outstanding $maxreqs	1320	IO::AIO::max_outstanding $maxreqs
		1321	Sets the maximum number of outstanding requests to $nreqs. If you do
		1322	queue up more than this number of requests, the next call to
		1323	"IO::AIO::poll_cb" (and other functions calling "poll_cb", such as
		1324	"IO::AIO::flush" or "IO::AIO::poll") will block until the limit is
		1325	no longer exceeded.
		1326
		1327	In other words, this setting does not enforce a queue limit, but can
		1328	be used to make poll functions block if the limit is exceeded.
		1329
1175	This is a very bad function to use in interactive programs because	1330	This is a very bad function to use in interactive programs because
1176	it blocks, and a bad way to reduce concurrency because it is	1331	it blocks, and a bad way to reduce concurrency because it is
1177	inexact: Better use an "aio_group" together with a feed callback.	1332	inexact: Better use an "aio_group" together with a feed callback.
1178		1333
1179	Sets the maximum number of outstanding requests to $nreqs. If you do	1334	It's main use is in scripts without an event loop - when you want to
1180	queue up more than this number of requests, the next call to the	1335	stat a lot of files, you can write somehting like this:
1181	"poll_cb" (and "poll_some" and other functions calling "poll_cb")
1182	function will block until the limit is no longer exceeded.
1183		1336
1184	The default value is very large, so there is no practical limit on	1337	IO::AIO::max_outstanding 32;
		1338
		1339	for my $path (...) {
		1340	aio_stat $path , ...;
		1341	IO::AIO::poll_cb;
		1342	}
		1343
		1344	IO::AIO::flush;
		1345
		1346	The call to "poll_cb" inside the loop will normally return
		1347	instantly, but as soon as more thna 32 reqeusts are in-flight, it
		1348	will block until some requests have been handled. This keeps the
		1349	loop from pushing a large number of "aio_stat" requests onto the
		1350	queue.
		1351
		1352	The default value for "max_outstanding" is very large, so there is
1185	the number of outstanding requests.	1353	no practical limit on the number of outstanding requests.
1186
1187	You can still queue as many requests as you want. Therefore,
1188	"max_outstanding" is mainly useful in simple scripts (with low
1189	values) or as a stop gap to shield against fatal memory overflow
1190	(with large values).
1191		1354
1192	STATISTICAL INFORMATION	1355	STATISTICAL INFORMATION
1193	IO::AIO::nreqs	1356	IO::AIO::nreqs
1194	Returns the number of requests currently in the ready, execute or	1357	Returns the number of requests currently in the ready, execute or
1195	pending states (i.e. for which their callback has not been invoked	1358	pending states (i.e. for which their callback has not been invoked
…		…
1220		1383
1221	Returns the number of bytes copied, or -1 on error.	1384	Returns the number of bytes copied, or -1 on error.
1222		1385
1223	IO::AIO::fadvise $fh, $offset, $len, $advice	1386	IO::AIO::fadvise $fh, $offset, $len, $advice
1224	Simply calls the "posix_fadvise" function (see its manpage for	1387	Simply calls the "posix_fadvise" function (see its manpage for
1225	details). The following advice constants are avaiable:	1388	details). The following advice constants are available:
1226	"IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",	1389	"IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1227	"IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",	1390	"IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1228	"IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".	1391	"IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1229		1392
1230	On systems that do not implement "posix_fadvise", this function	1393	On systems that do not implement "posix_fadvise", this function
1231	returns ENOSYS, otherwise the return value of "posix_fadvise".	1394	returns ENOSYS, otherwise the return value of "posix_fadvise".
1232		1395
1233	IO::AIO::madvise $scalar, $offset, $len, $advice	1396	IO::AIO::madvise $scalar, $offset, $len, $advice
1234	Simply calls the "posix_madvise" function (see its manpage for	1397	Simply calls the "posix_madvise" function (see its manpage for
1235	details). The following advice constants are avaiable:	1398	details). The following advice constants are available:
1236	"IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",	1399	"IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
1237	"IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",	1400	"IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
1238	"IO::AIO::MADV_DONTNEED".	1401	"IO::AIO::MADV_DONTNEED".
1239		1402
1240	On systems that do not implement "posix_madvise", this function	1403	On systems that do not implement "posix_madvise", this function
1241	returns ENOSYS, otherwise the return value of "posix_madvise".	1404	returns ENOSYS, otherwise the return value of "posix_madvise".
1242		1405
1243	IO::AIO::mprotect $scalar, $offset, $len, $protect	1406	IO::AIO::mprotect $scalar, $offset, $len, $protect
1244	Simply calls the "mprotect" function on the preferably AIO::mmap'ed	1407	Simply calls the "mprotect" function on the preferably AIO::mmap'ed
1245	$scalar (see its manpage for details). The following protect	1408	$scalar (see its manpage for details). The following protect
1246	constants are avaiable: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",	1409	constants are available: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
1247	"IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".	1410	"IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
1248		1411
1249	On systems that do not implement "mprotect", this function returns	1412	On systems that do not implement "mprotect", this function returns
1250	ENOSYS, otherwise the return value of "mprotect".	1413	ENOSYS, otherwise the return value of "mprotect".
1251		1414
…		…
1341	# Danga::Socket integration	1504	# Danga::Socket integration
1342	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>	1505	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
1343	\&IO::AIO::poll_cb);	1506	\&IO::AIO::poll_cb);
1344		1507
1345	FORK BEHAVIOUR	1508	FORK BEHAVIOUR
1346	This module should do "the right thing" when the process using it forks:	1509	Usage of pthreads in a program changes the semantics of fork
		1510	considerably. Specifically, only async-safe functions can be called
		1511	after fork. Perl doesn't know about this, so in general, you cannot call
		1512	fork with defined behaviour in perl if pthreads are involved. IO::AIO
		1513	uses pthreads, so this applies, but many other extensions and (for
		1514	inexplicable reasons) perl itself often is linked against pthreads, so
		1515	this limitation applies to quite a lot of perls.
1347		1516
1348	Before the fork, IO::AIO enters a quiescent state where no requests can	1517	This module no longer tries to fight your OS, or POSIX. That means
1349	be added in other threads and no results will be processed. After the	1518	IO::AIO only works in the process that loaded it. Forking is fully
1350	fork the parent simply leaves the quiescent state and continues	1519	supported, but using IO::AIO in the child is not.
1351	request/result processing, while the child frees the request/result
1352	queue (so that the requests started before the fork will only be handled
1353	in the parent). Threads will be started on demand until the limit set in
1354	the parent process has been reached again.
1355		1520
1356	In short: the parent will, after a short pause, continue as if fork had	1521	You might get around by not using IO::AIO before (or after) forking.
1357	not been called, while the child will act as if IO::AIO has not been	1522	You could also try to call the IO::AIO::reinit function in the child:
1358	used yet.	1523
		1524	IO::AIO::reinit
		1525	Abandons all current requests and I/O threads and simply
		1526	reinitialises all data structures. This is not an operation
		1527	supported by any standards, but happens to work on GNU/Linux and
		1528	some newer BSD systems.
		1529
		1530	The only reasonable use for this function is to call it after
		1531	forking, if "IO::AIO" was used in the parent. Calling it while
		1532	IO::AIO is active in the process will result in undefined behaviour.
		1533	Calling it at any time will also result in any undefined (by POSIX)
		1534	behaviour.
1359		1535
1360	MEMORY USAGE	1536	MEMORY USAGE
1361	Per-request usage:	1537	Per-request usage:
1362		1538
1363	Each aio request uses - depending on your architecture - around 100-200	1539	Each aio request uses - depending on your architecture - around 100-200

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.47 by root, Fri May 27 00:44:49 2011 UTC vs. Revision 1.50 by root, Sun Oct 9 08:24:49 2011 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.47 by root, Fri May 27 00:44:49 2011 UTC vs.
Revision 1.50 by root, Sun Oct 9 08:24:49 2011 UTC