--- IO-AIO/README 2008/10/02 11:35:03 1.32 +++ IO-AIO/README 2010/01/02 14:24:32 1.41 @@ -30,7 +30,7 @@ use AnyEvent::AIO; # EV integration - my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; + my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; # Event integration Event->io (fd => IO::AIO::poll_fileno, @@ -51,7 +51,8 @@ DESCRIPTION This module implements asynchronous I/O using whatever means your - operating system supports. + operating system supports. It is implemented as an interface to "libeio" + (). Asynchronous means that operations that can normally block your program (e.g. reading from disk) will be done asynchronously: the operation will @@ -66,7 +67,7 @@ While most of this works on all types of file descriptors (for example sockets), using these functions on file descriptors that support nonblocking operation (again, sockets, pipes etc.) is very inefficient. - Use an event loop for that (such as the Event module): IO::AIO will + Use an event loop for that (such as the EV module): IO::AIO will naturally fit into such an event loop itself. In this version, a number of threads are started that execute your @@ -85,17 +86,15 @@ call "poll_cb" (or other "aio_" functions) recursively. EXAMPLE - This is a simple example that uses the Event module and loads - /etc/passwd asynchronously: + This is a simple example that uses the EV module and loads /etc/passwd + asynchronously: use Fcntl; - use Event; + use EV; use IO::AIO; - # register the IO::AIO callback with Event - Event->io (fd => IO::AIO::poll_fileno, - poll => 'r', - cb => \&IO::AIO::poll_cb); + # register the IO::AIO callback with EV + my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; # queue the request to open /etc/passwd aio_open "/etc/passwd", O_RDONLY, 0, sub { @@ -117,7 +116,7 @@ print $contents; # exit event loop and program - Event::unloop; + EV::unloop; }; }; @@ -125,7 +124,7 @@ # check for sockets etc. etc. # process events as long as there are some: - Event::loop; + EV::loop; REQUEST ANATOMY AND LIFETIME Every "aio_*" function creates a request. which is a C data structure @@ -277,10 +276,13 @@ aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) - Reads or writes $length bytes from the specified $fh and $offset - into the scalar given by $data and offset $dataoffset and calls the - callback without the actual number of bytes read (or -1 on error, - just like the syscall). + Reads or writes $length bytes from or to the specified $fh and + $offset into the scalar given by $data and offset $dataoffset and + calls the callback without the actual number of bytes read (or -1 on + error, just like the syscall). + + "aio_read" will, like "sysread", shrink or grow the $data scalar to + offset plus the actual number of bytes read. If $offset is undefined, then the current file descriptor offset will be used (and updated), otherwise the file descriptor offset @@ -315,9 +317,10 @@ provide zero-copy operation. For this to work, $out_fh should refer to a socket, and $in_fh should refer to mmap'able file. - If the native sendfile call fails or is not implemented, it will be - emulated, so you can call "aio_sendfile" on any type of filehandle - regardless of the limitations of the operating system. + If a native sendfile cannot be found or it fails with "ENOSYS", + "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK", + it will be emulated, so you can call "aio_sendfile" on any type of + filehandle regardless of the limitations of the operating system. Please note, however, that "aio_sendfile" can read more bytes from $in_fh than are written, and there is no way to find out how many @@ -441,8 +444,69 @@ entire directory (i.e. opendir + readdir + closedir). The entries will not be sorted, and will NOT include the "." and ".." entries. - The callback a single argument which is either "undef" or an - array-ref with the filenames. + The callback is passed a single argument which is either "undef" or + an array-ref with the filenames. + + aio_readdirx $pathname, $flags, $callback->($entries, $flags) + Quite similar to "aio_readdir", but the $flags argument allows to + tune behaviour and output format. In case of an error, $entries will + be "undef". + + The flags are a combination of the following constants, ORed + together (the flags will also be passed to the callback, possibly + modified): + + IO::AIO::READDIR_DENTS + When this flag is off, then the callback gets an arrayref with + of names only (as with "aio_readdir"), otherwise it gets an + arrayref with "[$name, $type, $inode]" arrayrefs, each + describing a single directory entry in more detail. + + $name is the name of the entry. + + $type is one of the "IO::AIO::DT_xxx" constants: + + "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR", + "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG", + "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT". + + "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If + you need to know, you have to run stat yourself. Also, for speed + reasons, the $type scalars are read-only: you can not modify + them. + + $inode is the inode number (which might not be exact on systems + with 64 bit inode numbers and 32 bit perls). This field has + unspecified content on systems that do not deliver the inode + information. + + IO::AIO::READDIR_DIRS_FIRST + When this flag is set, then the names will be returned in an + order where likely directories come first. This is useful when + you need to quickly find directories, or you want to find all + directories while avoiding to stat() each entry. + + If the system returns type information in readdir, then this is + used to find directories directly. Otherwise, likely directories + are files beginning with ".", or otherwise files with no dots, + of which files with short names are tried first. + + IO::AIO::READDIR_STAT_ORDER + When this flag is set, then the names will be returned in an + order suitable for stat()'ing each one. That is, when you plan + to stat() all files in the given directory, then the returned + order will likely be fastest. + + If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are + specified, then the likely dirs come first, resulting in a less + optimal stat order. + + IO::AIO::READDIR_FOUND_UNKNOWN + This flag should not be set when calling "aio_readdirx". + Instead, it is being set by "aio_readdirx", when any of the + $type's found were "IO::AIO::DT_UNKNOWN". The absense of this + flag therefore indicates that all $type's are known, which can + be used to speed up some algorithms. aio_load $path, $data, $callback->($status) This is a composite request that tries to fully load the given file @@ -451,7 +515,7 @@ aio_copy $srcpath, $dstpath, $callback->($status) Try to copy the *file* (directories not supported as either source or destination) from $srcpath to $dstpath and call the callback with - the 0 (error) or -1 ok. + a status of 0 (ok) or -1 (error, see $!). This is a composite request that creates the destination file with mode 0200 and copies the contents of the source file into it using @@ -465,11 +529,11 @@ aio_move $srcpath, $dstpath, $callback->($status) Try to move the *file* (directories not supported as either source or destination) from $srcpath to $dstpath and call the callback with - the 0 (error) or -1 ok. + a status of 0 (ok) or -1 (error, see $!). - This is a composite request that tries to rename(2) the file first. - If rename files with "EXDEV", it copies the file with "aio_copy" - and, if that is successful, unlinking the $srcpath. + This is a composite request that tries to rename(2) the file first; + if rename fails with "EXDEV", it copies the file with "aio_copy" + and, if that is successful, unlinks the $srcpath. aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) Scans a directory (similar to "aio_readdir") but additionally tries @@ -499,20 +563,26 @@ The "aio_readdir" cannot be avoided, but "stat()"'ing every entry can. - After reading the directory, the modification time, size etc. of the - directory before and after the readdir is checked, and if they match - (and isn't the current time), the link count will be used to decide - how many entries are directories (if >= 2). Otherwise, no knowledge - of the number of subdirectories will be assumed. - - Then entries will be sorted into likely directories (everything - without a non-initial dot currently) and likely non-directories - (everything else). Then every entry plus an appended "/." will be - "stat"'ed, likely directories first. If that succeeds, it assumes - that the entry is a directory or a symlink to directory (which will - be checked seperately). This is often faster than stat'ing the entry - itself because filesystems might detect the type of the entry - without reading the inode data (e.g. ext2fs filetype feature). + If readdir returns file type information, then this is used directly + to find directories. + + Otherwise, after reading the directory, the modification time, size + etc. of the directory before and after the readdir is checked, and + if they match (and isn't the current time), the link count will be + used to decide how many entries are directories (if >= 2). + Otherwise, no knowledge of the number of subdirectories will be + assumed. + + Then entries will be sorted into likely directories a non-initial + dot currently) and likely non-directories (see "aio_readdirx"). Then + every entry plus an appended "/." will be "stat"'ed, likely + directories first, in order of their inode numbers. If that + succeeds, it assumes that the entry is a directory or a symlink to + directory (which will be checked seperately). This is often faster + than stat'ing the entry itself because filesystems might detect the + type of the entry without reading the inode data (e.g. ext2fs + filetype feature), even on systems that cannot return the filetype + information on readdir. If the known number of directories (link count - 2) has been reached, the rest of the entries is assumed to be non-directories. @@ -544,6 +614,18 @@ If this call isn't available because your OS lacks it or it couldn't be detected, it will be emulated by calling "fsync" instead. + aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) + Sync the data portion of the file specified by $offset and $length + to disk (but NOT the metadata), by calling the Linux-specific + sync_file_range call. If sync_file_range is not available or it + returns ENOSYS, then fdatasync or fsync is being substituted. + + $flags can be a combination of + "IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE", + "IO::AIO::SYNC_FILE_RANGE_WRITE" and + "IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range + manpage for details. + aio_pathsync $path, $callback->($status) This request tries to open, fsync and close the given path. This is a composite request intended to sync directories after directory @@ -552,8 +634,37 @@ directory changes get written to disc. It works for anything that can be opened for read-only, not just directories. + Future versions of this function might fall back to other methods + when "fsync" on the directory fails (such as calling "sync"). + Passes 0 when everything went ok, and -1 on error. + aio_msync $scalar, $offset = 0, $length = undef, flags = 0, + $callback->($status) + This is a rather advanced IO::AIO call, which only works on + mmap(2)ed scalars (see the Sys::Mmap or Mmap modules for details on + this, note that the scalar must only be modified in-place while an + aio operation is pending on it). + + It calls the "msync" function of your OS, if available, with the + memory area starting at $offset in the string and ending $length + bytes later. If $length is negative, counts from the end, and if + $length is "undef", then it goes till the end of the string. The + flags can be a combination of "IO::AIO::MS_ASYNC", + "IO::AIO::MS_INVALIDATE" and "IO::AIO::MS_SYNC". + + aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, + $callback->($status) + This is a rather advanced IO::AIO call, which works best on + mmap(2)ed scalars. + + It touches (reads or writes) all memory pages in the specified range + inside the scalar. All caveats and parameters are the same as for + "aio_msync", above, except for flags, which must be either 0 (which + reads all pages and ensures they are instantiated) or + "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading + and writing an octet from it, which dirties the page). + aio_group $callback->(...) This is a very special aio request: Instead of doing something, it is a container for other aio requests, which is useful if you want @@ -605,9 +716,9 @@ Cancels the request, if possible. Has the effect of skipping execution when entering the execute state and skipping calling the callback when entering the the result state, but will leave the - request otherwise untouched. That means that requests that currently - execute will not be stopped and resources held by the request will - not be freed prematurely. + request otherwise untouched (with the exception of readdir). That + means that requests that currently execute will not be stopped and + resources held by the request will not be freed prematurely. cb $req $callback->(...) Replace (or simply set) the callback registered to the request. @@ -679,6 +790,9 @@ request itself. Useful when you queued a lot of events but got a result early. + The group request will finish normally (you cannot add requests to + the group). + $grp->result (...) Set the result value(s) that will be passed to the group callback when all subrequests have finished and set the groups errno to the @@ -717,7 +831,8 @@ If the feed does not queue more requests when called, it will be automatically removed from the group. - If the feed limit is 0, it will be set to 2 automatically. + If the feed limit is 0 when this method is called, it will be set to + 2 automatically. Example: @@ -738,13 +853,17 @@ Setting the limit to 0 will pause the feeding process. + The default value for the limit is 0, but note that setting a feeder + automatically bumps it up to 2. + SUPPORT FUNCTIONS EVENT PROCESSING AND EVENT LOOP INTEGRATION $fileno = IO::AIO::poll_fileno Return the *request result pipe file descriptor*. This filehandle must be polled for reading by some mechanism outside this module - (e.g. Event or select, see below or the SYNOPSIS). If the pipe - becomes readable you have to call "poll_cb" to check the results. + (e.g. EV, Glib, select and so on, see below or the SYNOPSIS). If the + pipe becomes readable you have to call "poll_cb" to check the + results. See "poll_cb" for an example. @@ -761,7 +880,8 @@ you don't have to do anything special to have it called later. Example: Install an Event watcher that automatically calls - IO::AIO::poll_cb with high priority: + IO::AIO::poll_cb with high priority (more examples can be found in + the SYNOPSIS section, at the top of this document): Event->io (fd => IO::AIO::poll_fileno, poll => 'r', async => 1, @@ -911,6 +1031,28 @@ Returns the number of requests currently in the pending state (executed, but not yet processed by poll_cb). + MISCELLANEOUS FUNCTIONS + IO::AIO implements some functions that might be useful, but are not + asynchronous. + + IO::AIO::sendfile $ofh, $ifh, $offset, $count + Calls the "eio_sendfile_sync" function, which is like + "aio_sendfile", but is blocking (this makes most sense if you know + the input data is likely cached already and the output filehandle is + set to non-blocking operations). + + Returns the number of bytes copied, or -1 on error. + + IO::AIO::fadvise $fh, $offset, $len, $advice + Simply calls the "posix_fadvise" function (see it's manpage for + details). The following advice constants are avaiable: + "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL", + "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE", + "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED". + + On systems that do not implement "posix_fadvise", this function + returns ENOSYS, otherwise the return value of "posix_fadvise". + FORK BEHAVIOUR This module should do "the right thing" when the process using it forks: