ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/README
(Generate patch)

Comparing IO-AIO/README (file contents):
Revision 1.9 by root, Tue Aug 16 23:33:38 2005 UTC vs.
Revision 1.11 by root, Sat Aug 20 00:32:42 2005 UTC

… …
117 aio_write $fh,$offset,$length, $data,$dataoffset,$callback 117 aio_write $fh,$offset,$length, $data,$dataoffset,$callback
118 Reads or writes "length" bytes from the specified "fh" and "offset" 118 Reads or writes "length" bytes from the specified "fh" and "offset"
119 into the scalar given by "data" and offset "dataoffset" and calls 119 into the scalar given by "data" and offset "dataoffset" and calls
120 the callback without the actual number of bytes read (or -1 on 120 the callback without the actual number of bytes read (or -1 on
121 error, just like the syscall). 121 error, just like the syscall).
122
123 The $data scalar *MUST NOT* be modified in any way while the request
124 is outstanding. Modifying it can result in segfaults or WW3 (if the
125 necessary/optional hardware is installed).
122 126
123 Example: Read 15 bytes at offset 7 into scalar $buffer, starting at 127 Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
124 offset 0 within the scalar: 128 offset 0 within the scalar:
125 129
126 aio_read $fh, 7, 15, $buffer, 0, sub { 130 aio_read $fh, 7, 15, $buffer, 0, sub {
… …
235 239
236 IO::AIO::poll_wait, IO::AIO::poll_cb 240 IO::AIO::poll_wait, IO::AIO::poll_cb
237 if IO::AIO::nreqs; 241 if IO::AIO::nreqs;
238 242
239 IO::AIO::min_parallel $nthreads 243 IO::AIO::min_parallel $nthreads
240 Set the minimum number of AIO threads to $nthreads. The default is 244 Set the minimum number of AIO threads to $nthreads. The current
241 1, which means a single asynchronous operation can be done at one 245 default is 4, which means four asynchronous operations can be done
242 time (the number of outstanding operations, however, is unlimited). 246 at one time (the number of outstanding operations, however, is
247 unlimited).
248
249 IO::AIO starts threads only on demand, when an AIO request is queued
250 and no free thread exists.
243 251
244 It is recommended to keep the number of threads low, as some Linux 252 It is recommended to keep the number of threads low, as some Linux
245 kernel versions will scale negatively with the number of threads 253 kernel versions will scale negatively with the number of threads
246 (higher parallelity => MUCH higher latency). With current Linux 2.6 254 (higher parallelity => MUCH higher latency). With current Linux 2.6
247 versions, 4-32 threads should be fine. 255 versions, 4-32 threads should be fine.
248 256
249 Under normal circumstances you don't need to call this function, as 257 Under most circumstances you don't need to call this function, as
250 this module automatically starts some threads (the exact number 258 the module selects a default that is suitable for low to moderate
251 might change, and is currently 4). 259 load.
252 260
253 IO::AIO::max_parallel $nthreads 261 IO::AIO::max_parallel $nthreads
254 Sets the maximum number of AIO threads to $nthreads. If more than 262 Sets the maximum number of AIO threads to $nthreads. If more than
255 the specified number of threads are currently running, kill them. 263 the specified number of threads are currently running, this function
256 This function blocks until the limit is reached. 264 kills them. This function blocks until the limit is reached.
265
266 While $nthreads are zero, aio requests get queued but not executed
267 until the number of threads has been increased again.
257 268
258 This module automatically runs "max_parallel 0" at program end, to 269 This module automatically runs "max_parallel 0" at program end, to
259 ensure that all threads are killed and that there are no outstanding 270 ensure that all threads are killed and that there are no outstanding
260 requests. 271 requests.
261 272
… …
265 Sets the maximum number of outstanding requests to $nreqs. If you 276 Sets the maximum number of outstanding requests to $nreqs. If you
266 try to queue up more than this number of requests, the caller will 277 try to queue up more than this number of requests, the caller will
267 block until some requests have been handled. 278 block until some requests have been handled.
268 279
269 The default is very large, so normally there is no practical limit. 280 The default is very large, so normally there is no practical limit.
270 If you queue up many requests in a loop it it often improves speed 281 If you queue up many requests in a loop it often improves speed if
271 if you set this to a relatively low number, such as 100. 282 you set this to a relatively low number, such as 100.
272 283
273 Under normal circumstances you don't need to call this function. 284 Under normal circumstances you don't need to call this function.
274 285
275 FORK BEHAVIOUR 286 FORK BEHAVIOUR
276 IO::AIO handles all outstanding AIO requests before the fork, destroys 287 Before the fork, IO::AIO enters a quiescent state where no requests can
277 all AIO threads, and recreates them in both the parent and the child 288 be added in other threads and no results will be processed. After the
278 after the fork. 289 fork the parent simply leaves the quiescent state and continues
290 request/result processing, while the child clears the request/result
291 queue (so the requests started before the fork will only be handled in
292 the parent). Threats will be started on demand until the limit ste in
293 the parent process has been reached again.
279 294
280SEE ALSO 295SEE ALSO
281 Coro, Linux::AIO. 296 Coro, Linux::AIO.
282 297
283AUTHOR 298AUTHOR

Diff Legend

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