--- IO-AIO/README 2005/07/31 17:24:05 1.8 +++ IO-AIO/README 2005/08/20 00:32:42 1.11 @@ -64,10 +64,18 @@ All functions expecting a filehandle keep a copy of the filehandle internally until the request has finished. - The filenames you pass to these routines *must* be absolute. The reason - for this is that at the time the request is being executed, the current - working directory could have changed. Alternatively, you can make sure - that you never change the current working directory. + The pathnames you pass to these routines *must* be absolute and encoded + in byte form. The reason for the former is that at the time the request + is being executed, the current working directory could have changed. + Alternatively, you can make sure that you never change the current + working directory. + + To encode pathnames to byte form, either make sure you either: a) always + pass in filenames you got from outside (command line, readdir etc.), b) + are ASCII or ISO 8859-1, c) use the Encode module and encode your + pathnames to the locale (or other) encoding in effect in the user + environment, d) use Glib::filename_from_unicode on unicode filenames or + e) use something else. aio_open $pathname, $flags, $mode, $callback Asynchronously open or create a file and call the callback with a @@ -112,6 +120,10 @@ the callback without the actual number of bytes read (or -1 on error, just like the syscall). + 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). + Example: Read 15 bytes at offset 7 into scalar $buffer, starting at offset 0 within the scalar: @@ -121,11 +133,6 @@ }; aio_readahead $fh,$offset,$length, $callback - Asynchronously reads the specified byte range into the page cache, - using the "readahead" syscall. If that syscall doesn't exist (likely - if your OS isn't Linux) the status will be -1 and $! is set to - "ENOSYS". - "aio_readahead" populates the page cache with data from a file so that subsequent reads from that file will not block on disk I/O. The $offset argument specifies the starting point from which data is to @@ -136,6 +143,10 @@ read beyond the end of the file. The current file offset of the file is left unchanged. + If that syscall doesn't exist (likely if your OS isn't Linux) it + will be emulated by simply reading the data, which would have a + similar effect. + aio_stat $fh_or_path, $callback aio_lstat $fh, $callback Works like perl's "stat" or "lstat" in void context. The callback @@ -161,14 +172,20 @@ Asynchronously unlink (delete) a file and call the callback with the result code. + aio_rmdir $pathname, $callback + Asynchronously rmdir (delete) a directory and call the callback with + the result code. + aio_fsync $fh, $callback Asynchronously call fsync on the given filehandle and call the callback with the fsync result code. aio_fdatasync $fh, $callback Asynchronously call fdatasync on the given filehandle and call the - callback with the fdatasync result code. Might set $! to "ENOSYS" if - "fdatasync" is not available. + callback with the fdatasync result code. + + 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. SUPPORT FUNCTIONS $fileno = IO::AIO::poll_fileno @@ -224,23 +241,30 @@ if IO::AIO::nreqs; IO::AIO::min_parallel $nthreads - Set the minimum number of AIO threads to $nthreads. The default is - 1, which means a single asynchronous operation can be done at one - time (the number of outstanding operations, however, is unlimited). + Set the minimum number of AIO threads to $nthreads. The current + default is 4, which means four asynchronous operations can be done + at one time (the number of outstanding operations, however, is + unlimited). + + IO::AIO starts threads only on demand, when an AIO request is queued + and no free thread exists. It is recommended to keep the number of threads low, as some Linux kernel versions will scale negatively with the number of threads (higher parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 threads should be fine. - Under normal circumstances you don't need to call this function, as - this module automatically starts some threads (the exact number - might change, and is currently 4). + Under most circumstances you don't need to call this function, as + the module selects a default that is suitable for low to moderate + load. IO::AIO::max_parallel $nthreads Sets the maximum number of AIO threads to $nthreads. If more than - the specified number of threads are currently running, kill them. - This function blocks until the limit is reached. + the specified number of threads are currently running, this function + kills them. This function blocks until the limit is reached. + + While $nthreads are zero, aio requests get queued but not executed + until the number of threads has been increased again. This module automatically runs "max_parallel 0" at program end, to ensure that all threads are killed and that there are no outstanding @@ -254,11 +278,20 @@ block until some requests have been handled. The default is very large, so normally there is no practical limit. - If you queue up many requests in a loop it it often improves speed - if you set this to a relatively low number, such as 100. + If you queue up many requests in a loop it often improves speed if + you set this to a relatively low number, such as 100. Under normal circumstances you don't need to call this function. + FORK BEHAVIOUR + Before the fork, IO::AIO enters a quiescent state where no requests can + be added in other threads and no results will be processed. After the + fork the parent simply leaves the quiescent state and continues + request/result processing, while the child clears the request/result + queue (so the requests started before the fork will only be handled in + the parent). Threats will be started on demand until the limit ste in + the parent process has been reached again. + SEE ALSO Coro, Linux::AIO.