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.12 by root, Tue Aug 23 00:05:00 2005 UTC

… …
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 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).
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 {
127 $_[0] > 0 or die "read error: $!"; 131 $_[0] > 0 or die "read error: $!";
128 print "read $_[0] bytes: <$buffer>\n"; 132 print "read $_[0] bytes: <$buffer>\n";
129 }; 133 };
134
135 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback
136 Tries to copy $length bytes from $in_fh to $out_fh. It starts
137 reading at byte offset $in_offset, and starts writing at the current
138 file offset of $out_fh. Because of that, it is not safe to issue
139 more than one "aio_sendfile" per $out_fh, as they will interfere
140 with each other.
141
142 This call tries to make use of a native "sendfile" syscall to
143 provide zero-copy operation. For this to work, $out_fh should refer
144 to a socket, and $in_fh should refer to mmap'able file.
145
146 If the native sendfile call fails or is not implemented, it will be
147 emulated, so you can call "aio_sendfile" on any type of filehandle
148 regardless of the limitations of the operating system.
149
150 Please note, however, that "aio_sendfile" can read more bytes from
151 $in_fh than are written, and there is no way to find out how many
152 bytes have been read from "aio_sendfile" alone, as "aio_sendfile"
153 only provides the number of bytes written to $out_fh. Only if the
154 result value equals $length one can assume that $length bytes have
155 been read.
130 156
131 aio_readahead $fh,$offset,$length, $callback 157 aio_readahead $fh,$offset,$length, $callback
132 "aio_readahead" populates the page cache with data from a file so 158 "aio_readahead" populates the page cache with data from a file so
133 that subsequent reads from that file will not block on disk I/O. The 159 that subsequent reads from that file will not block on disk I/O. The
134 $offset argument specifies the starting point from which data is to 160 $offset argument specifies the starting point from which data is to
… …
235 261
236 IO::AIO::poll_wait, IO::AIO::poll_cb 262 IO::AIO::poll_wait, IO::AIO::poll_cb
237 if IO::AIO::nreqs; 263 if IO::AIO::nreqs;
238 264
239 IO::AIO::min_parallel $nthreads 265 IO::AIO::min_parallel $nthreads
240 Set the minimum number of AIO threads to $nthreads. The default is 266 Set the minimum number of AIO threads to $nthreads. The current
241 1, which means a single asynchronous operation can be done at one 267 default is 4, which means four asynchronous operations can be done
242 time (the number of outstanding operations, however, is unlimited). 268 at one time (the number of outstanding operations, however, is
269 unlimited).
270
271 IO::AIO starts threads only on demand, when an AIO request is queued
272 and no free thread exists.
243 273
244 It is recommended to keep the number of threads low, as some Linux 274 It is recommended to keep the number of threads low, as some Linux
245 kernel versions will scale negatively with the number of threads 275 kernel versions will scale negatively with the number of threads
246 (higher parallelity => MUCH higher latency). With current Linux 2.6 276 (higher parallelity => MUCH higher latency). With current Linux 2.6
247 versions, 4-32 threads should be fine. 277 versions, 4-32 threads should be fine.
248 278
249 Under normal circumstances you don't need to call this function, as 279 Under most circumstances you don't need to call this function, as
250 this module automatically starts some threads (the exact number 280 the module selects a default that is suitable for low to moderate
251 might change, and is currently 4). 281 load.
252 282
253 IO::AIO::max_parallel $nthreads 283 IO::AIO::max_parallel $nthreads
254 Sets the maximum number of AIO threads to $nthreads. If more than 284 Sets the maximum number of AIO threads to $nthreads. If more than
255 the specified number of threads are currently running, kill them. 285 the specified number of threads are currently running, this function
256 This function blocks until the limit is reached. 286 kills them. This function blocks until the limit is reached.
287
288 While $nthreads are zero, aio requests get queued but not executed
289 until the number of threads has been increased again.
257 290
258 This module automatically runs "max_parallel 0" at program end, to 291 This module automatically runs "max_parallel 0" at program end, to
259 ensure that all threads are killed and that there are no outstanding 292 ensure that all threads are killed and that there are no outstanding
260 requests. 293 requests.
261 294
… …
265 Sets the maximum number of outstanding requests to $nreqs. If you 298 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 299 try to queue up more than this number of requests, the caller will
267 block until some requests have been handled. 300 block until some requests have been handled.
268 301
269 The default is very large, so normally there is no practical limit. 302 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 303 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. 304 you set this to a relatively low number, such as 100.
272 305
273 Under normal circumstances you don't need to call this function. 306 Under normal circumstances you don't need to call this function.
274 307
275 FORK BEHAVIOUR 308 FORK BEHAVIOUR
276 IO::AIO handles all outstanding AIO requests before the fork, destroys 309 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 310 be added in other threads and no results will be processed. After the
278 after the fork. 311 fork the parent simply leaves the quiescent state and continues
312 request/result processing, while the child clears the request/result
313 queue (so the requests started before the fork will only be handled in
314 the parent). Threats will be started on demand until the limit ste in
315 the parent process has been reached again.
279 316
280SEE ALSO 317SEE ALSO
281 Coro, Linux::AIO. 318 Coro, Linux::AIO.
282 319
283AUTHOR 320AUTHOR

Diff Legend

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