--- IO-AIO/README 2006/10/31 00:45:41 1.20 +++ IO-AIO/README 2008/10/02 11:35:03 1.32 @@ -5,7 +5,8 @@ use IO::AIO; aio_open "/etc/passwd", O_RDONLY, 0, sub { - my ($fh) = @_; + my $fh = shift + or die "/etc/passwd: $!"; ... }; @@ -25,9 +26,11 @@ my $grp = aio_group sub { print "all stats done\n" }; add $grp aio_stat "..." for ...; - # AnyEvent integration - open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!"; - my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb }); + # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...) + use AnyEvent::AIO; + + # EV integration + my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; # Event integration Event->io (fd => IO::AIO::poll_fileno, @@ -62,10 +65,9 @@ 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 - or might not work (aio_read fails on sockets/pipes/fifos). Use an event - loop for that (such as the Event module): IO::AIO will naturally fit - into such an event loop itself. + nonblocking operation (again, sockets, pipes etc.) is very inefficient. + Use an event loop for that (such as the Event module): IO::AIO will + naturally fit into such an event loop itself. In this version, a number of threads are started that execute your requests and signal their completion. You don't need thread support in @@ -77,10 +79,10 @@ aio_write, so the remaining functionality would have to be implemented using threads anyway. - Although the module will work with in the presence of other (Perl-) - threads, it is currently not reentrant in any way, so use appropriate - locking yourself, always call "poll_cb" from within the same thread, or - never call "poll_cb" (or other "aio_" functions) recursively. + Although the module will work in the presence of other (Perl-) threads, + it is currently not reentrant in any way, so use appropriate locking + yourself, always call "poll_cb" from within the same thread, or never + call "poll_cb" (or other "aio_" functions) recursively. EXAMPLE This is a simple example that uses the Event module and loads @@ -97,7 +99,7 @@ # queue the request to open /etc/passwd aio_open "/etc/passwd", O_RDONLY, 0, sub { - my $fh = $_[0] + my $fh = shift or die "error while opening: $!"; # stat'ing filehandles is generally non-blocking @@ -175,8 +177,8 @@ identical, and they all accept an additional (and optional) $callback argument which must be a code reference. This code reference will get called with the syscall return code (e.g. most syscalls return -1 on - error, unlike perl, which usually delivers "false") as it's sole - argument when the given syscall has been executed asynchronously. + error, unlike perl, which usually delivers "false") as its sole argument + after the given syscall has been executed asynchronously. All functions expecting a filehandle keep a copy of the filehandle internally until the request has finished. @@ -199,7 +201,7 @@ contents. This works, btw. independent of the internal UTF-8 bit, which IO::AIO - handles correctly wether it is set or not. + handles correctly whether it is set or not. $prev_pri = aioreq_pri [$pri] Returns the priority value that would be used for the next request @@ -243,7 +245,9 @@ Likewise, $mode specifies the mode of the newly created file, if it didn't exist and "O_CREAT" has been given, just like perl's "sysopen", except that it is mandatory (i.e. use 0 if you don't - create new files, and 0666 or 0777 if you do). + create new files, and 0666 or 0777 if you do). Note that the $mode + will be modified by the umask in effect then the request is being + executed, so better never change the umask. Example: @@ -258,24 +262,39 @@ aio_close $fh, $callback->($status) Asynchronously close a file and call the callback with the result - code. *WARNING:* although accepted, you should not pass in a perl - filehandle here, as perl will likely close the file descriptor - another time when the filehandle is destroyed. Normally, you can - safely call perls "close" or just let filehandles go out of scope. + code. + + Unfortunately, you can't do this to perl. Perl *insists* very + strongly on closing the file descriptor associated with the + filehandle itself. + + Therefore, "aio_close" will not close the filehandle - instead it + will use dup2 to overwrite the file descriptor with the write-end of + a pipe (the pipe fd will be created on demand and will be cached). - This is supposed to be a bug in the API, so that might change. It's - therefore best to avoid this function. + Or in other words: the file descriptor will be closed, but it will + not be free for reuse until the perl filehandle is closed. 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 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). + + If $offset is undefined, then the current file descriptor offset + will be used (and updated), otherwise the file descriptor offset + will not be changed by these calls. + + If $length is undefined in "aio_write", use the remaining length of + $data. + + If $dataoffset is less than zero, it will be counted from the end of + $data. The $data scalar *MUST NOT* be modified in any way while the request - is outstanding. Modifying it can result in segfaults or WW3 (if the - necessary/optional hardware is installed). + is outstanding. Modifying it can result in segfaults or World War + III (if the necessary/optional hardware is installed). Example: Read 15 bytes at offset 7 into scalar $buffer, starting at offset 0 within the scalar: @@ -343,6 +362,40 @@ print "size is ", -s _, "\n"; }; + aio_utime $fh_or_path, $atime, $mtime, $callback->($status) + Works like perl's "utime" function (including the special case of + $atime and $mtime being undef). Fractional times are supported if + the underlying syscalls support them. + + When called with a pathname, uses utimes(2) if available, otherwise + utime(2). If called on a file descriptor, uses futimes(2) if + available, otherwise returns ENOSYS, so this is not portable. + + Examples: + + # set atime and mtime to current time (basically touch(1)): + aio_utime "path", undef, undef; + # set atime to current time and mtime to beginning of the epoch: + aio_utime "path", time, undef; # undef==0 + + aio_chown $fh_or_path, $uid, $gid, $callback->($status) + Works like perl's "chown" function, except that "undef" for either + $uid or $gid is being interpreted as "do not change" (but -1 can + also be used). + + Examples: + + # same as "chown root path" in the shell: + aio_chown "path", 0, -1; + # same as above: + aio_chown "path", 0, undef; + + aio_truncate $fh_or_path, $offset, $callback->($status) + Works like truncate(2) or ftruncate(2). + + aio_chmod $fh_or_path, $mode, $callback->($status) + Works like perl's "chmod" function. + aio_unlink $pathname, $callback->($status) Asynchronously unlink (delete) a file and call the callback with the result code. @@ -374,6 +427,11 @@ Asynchronously rename the object at $srcpath to $dstpath, just as rename(2) and call the callback with the result code. + aio_mkdir $pathname, $mode, $callback->($status) + Asynchronously mkdir (create) a directory and call the callback with + the result code. $mode will be modified by the umask at the time the + request is executed, so do not change your umask. + aio_rmdir $pathname, $callback->($status) Asynchronously rmdir (delete) a directory and call the callback with the result code. @@ -386,15 +444,19 @@ The callback a single argument which is either "undef" or an array-ref with the filenames. + aio_load $path, $data, $callback->($status) + This is a composite request that tries to fully load the given file + into memory. Status is the same as with aio_read. + 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. - This is a composite request that it creates the destination file - with mode 0200 and copies the contents of the source file into it - using "aio_sendfile", followed by restoring atime, mtime, access - mode and uid/gid, in that order. + This is a composite request that creates the destination file with + mode 0200 and copies the contents of the source file into it using + "aio_sendfile", followed by restoring atime, mtime, access mode and + uid/gid, in that order. If an error occurs, the partial destination file will be unlinked, if possible, except when setting atime, mtime, access mode and @@ -462,6 +524,15 @@ efficiency as those tend to return 0 or 1 as link counts, which disables the directory counting heuristic. + aio_rmtree $path, $callback->($status) + Delete a directory tree starting (and including) $path, return the + status of the final "rmdir" only. This is a composite request that + uses "aio_scandir" to recurse into and rmdir directories, and unlink + everything else. + + aio_sync $callback->($status) + Asynchronously call sync and call the callback when finished. + aio_fsync $fh, $callback->($status) Asynchronously call fsync on the given filehandle and call the callback with the fsync result code. @@ -473,6 +544,16 @@ 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_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 + operations (E.g. rename). This might not work on all operating + systems or have any specific effect, but usually it makes sure that + directory changes get written to disc. It works for anything that + can be opened for read-only, not just directories. + + Passes 0 when everything went ok, and -1 on error. + 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 @@ -563,23 +644,27 @@ This makes it very easy to create composite requests (see the source of "aio_move" for an application) that work and feel like simple requests. - * The IO::AIO::GRP objects will be cleaned up during calls to - "IO::AIO::poll_cb", just like any other request. - * They can be canceled like any other request. Canceling will cancel not - only the request itself, but also all requests it contains. - * They can also can also be added to other IO::AIO::GRP objects. - * You must not add requests to a group from within the group callback - (or any later time). + * The IO::AIO::GRP objects will be cleaned up during calls to + "IO::AIO::poll_cb", just like any other request. + + * They can be canceled like any other request. Canceling will cancel + not only the request itself, but also all requests it contains. + + * They can also can also be added to other IO::AIO::GRP objects. + + * You must not add requests to a group from within the group callback + (or any later time). Their lifetime, simplified, looks like this: when they are empty, they will finish very quickly. If they contain only requests that are in the "done" state, they will also finish. Otherwise they will continue to exist. - That means after creating a group you have some time to add requests. - And in the callbacks of those requests, you can add further requests to - the group. And only when all those requests have finished will the the - group itself finish. + That means after creating a group you have some time to add requests + (precisely before the callback has been invoked, which is only done + within the "poll_cb"). And in the callbacks of those requests, you can + add further requests to the group. And only when all those requests have + finished will the the group itself finish. add $grp ... $grp->add (...) @@ -596,7 +681,7 @@ $grp->result (...) Set the result value(s) that will be passed to the group callback - when all subrequests have finished and set thre groups errno to the + when all subrequests have finished and set the groups errno to the current value of errno (just like calling "errno" without an error number). By default, no argument will be passed and errno is zero. @@ -665,13 +750,15 @@ IO::AIO::poll_cb Process some outstanding events on the result pipe. You have to call - this regularly. Returns the number of events processed. Returns - immediately when no events are outstanding. The amount of events - processed depends on the settings of "IO::AIO::max_poll_req" and + this regularly. Returns 0 if all events could be processed, or -1 if + it returned earlier for whatever reason. Returns immediately when no + events are outstanding. The amount of events processed depends on + the settings of "IO::AIO::max_poll_req" and "IO::AIO::max_poll_time". If not all requests were processed for whatever reason, the - filehandle will still be ready when "poll_cb" returns. + filehandle will still be ready when "poll_cb" returns, so normally + 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: @@ -713,19 +800,20 @@ cb => &IO::AIO::poll_cb); IO::AIO::poll_wait - Wait till the result filehandle becomes ready for reading (simply - does a "select" on the filehandle. This is useful if you want to - synchronously wait for some requests to finish). + If there are any outstanding requests and none of them in the result + phase, wait till the result filehandle becomes ready for reading + (simply does a "select" on the filehandle. This is useful if you + want to synchronously wait for some requests to finish). See "nreqs" for an example. IO::AIO::poll Waits until some requests have been handled. - Strictly equivalent to: + Returns the number of requests processed, but is otherwise strictly + equivalent to: IO::AIO::poll_wait, IO::AIO::poll_cb - if IO::AIO::nreqs; IO::AIO::flush Wait till all outstanding AIO requests have been handled. @@ -786,12 +874,12 @@ creation is fast. If thread creation is very slow on your system you might want to use larger values. - $oldmaxreqs = IO::AIO::max_outstanding $maxreqs + IO::AIO::max_outstanding $maxreqs This is a very bad function to use in interactive programs because it blocks, and a bad way to reduce concurrency because it is inexact: Better use an "aio_group" together with a feed callback. - Sets the maximum number of outstanding requests to $nreqs. If you to + Sets the maximum number of outstanding requests to $nreqs. If you do queue up more than this number of requests, the next call to the "poll_cb" (and "poll_some" and other functions calling "poll_cb") function will block until the limit is no longer exceeded. @@ -800,7 +888,7 @@ the number of outstanding requests. You can still queue as many requests as you want. Therefore, - "max_oustsanding" is mainly useful in simple scripts (with low + "max_outstanding" is mainly useful in simple scripts (with low values) or as a stop gap to shield against fatal memory overflow (with large values). @@ -847,7 +935,7 @@ scalars and other data passed into aio requests will also be locked and will consume memory till the request has entered the done state. - This is now awfully much, so queuing lots of requests is not usually a + This is not awfully much, so queuing lots of requests is not usually a problem. Per-thread usage: @@ -860,7 +948,8 @@ Known bugs will be fixed in the next release. SEE ALSO - Coro::AIO. + AnyEvent::AIO for easy integration into event loops, Coro::AIO for a + more natural syntax. AUTHOR Marc Lehmann