--- IO-AIO/README 2005/07/10 20:57:36 1.3 +++ IO-AIO/README 2005/07/10 21:04:46 1.4 @@ -21,7 +21,8 @@ Although the module will work with in the presence of other threads, it is currently not reentrant, so use appropriate locking yourself. - API NOTES +FUNCTIONS + AIO FUNCTIONS All the "aio_*" calls are more or less thin wrappers around the syscall with the same name (sans "aio_"). The arguments are similar or identical, and they all accept an additional $callback argument which @@ -38,76 +39,6 @@ directory could have changed. Alternatively, you can make sure that you never change the current working directory. - 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). - - 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). - - 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. - - This module automatically runs "max_parallel 0" at program end, to - ensure that all threads are killed and that there are no outstanding - requests. - - Under normal circumstances you don't need to call this function. - - $oldnreqs = IO::AIO::max_outstanding $nreqs - Sets the maximum number of outstanding requests to $nreqs. If you - try to queue up more than this number of requests, the caller will - 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. - - Under normal circumstances you don't need to call this function. - - $fileno = IO::AIO::poll_fileno - Return the *request result pipe filehandle*. This filehandle must be - polled for reading by some mechanism outside this module (e.g. Event - or select, see below). If the pipe becomes readable you have to call - "poll_cb" to check the results. - - See "poll_cb" for an example. - - IO::AIO::poll_cb - Process all 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. - - You can use Event to multiplex, e.g.: - - Event->io (fd => IO::AIO::poll_fileno, - poll => 'r', async => 1, - 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). - - See "nreqs" for an example. - - IO::AIO::nreqs - Returns the number of requests currently outstanding. - - Example: wait till there are no outstanding requests anymore: - - IO::AIO::poll_wait, IO::AIO::poll_cb - while IO::AIO::nreqs; - aio_open $pathname, $flags, $mode, $callback Asynchronously open or create a file and call the callback with a newly created filehandle for the file. @@ -199,8 +130,76 @@ Asynchronously call fdatasync on the given filehandle and call the callback with the fdatasync result code. -BUGS - - could be optimized to use more semaphores instead of filehandles. + SUPPORT FUNCTIONS + $fileno = IO::AIO::poll_fileno + Return the *request result pipe filehandle*. This filehandle must be + polled for reading by some mechanism outside this module (e.g. Event + or select, see below). If the pipe becomes readable you have to call + "poll_cb" to check the results. + + See "poll_cb" for an example. + + IO::AIO::poll_cb + Process all 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. + + You can use Event to multiplex, e.g.: + + Event->io (fd => IO::AIO::poll_fileno, + poll => 'r', async => 1, + 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). + + See "nreqs" for an example. + + IO::AIO::nreqs + Returns the number of requests currently outstanding. + + Example: wait till there are no outstanding requests anymore: + + IO::AIO::poll_wait, IO::AIO::poll_cb + while 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). + + 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). + + 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. + + This module automatically runs "max_parallel 0" at program end, to + ensure that all threads are killed and that there are no outstanding + requests. + + Under normal circumstances you don't need to call this function. + + $oldnreqs = IO::AIO::max_outstanding $nreqs + Sets the maximum number of outstanding requests to $nreqs. If you + try to queue up more than this number of requests, the caller will + 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. + + Under normal circumstances you don't need to call this function. SEE ALSO Coro, Linux::AIO.