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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.27 by root, Tue Aug 16 22:22:18 2005 UTC vs.
Revision 1.38 by root, Sun Aug 28 10:51:33 2005 UTC

… …
63use base 'Exporter'; 63use base 'Exporter';
64 64
65use Fcntl (); 65use Fcntl ();
66 66
67BEGIN { 67BEGIN {
68 $VERSION = 1.1; 68 $VERSION = 1.6;
69 69
70 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink 70 @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close stat
71 aio_aio_lstat aio_unlink aio_rmdir aio_readdir aio_symlink
71 aio_rmdir aio_symlink aio_fsync aio_fdatasync aio_readahead); 72 aio_fsync aio_fdatasync aio_readahead);
72 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 73 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel
74 max_outstanding nreqs);
73 75
74 require XSLoader; 76 require XSLoader;
75 XSLoader::load IO::AIO, $VERSION; 77 XSLoader::load IO::AIO, $VERSION;
76} 78}
77 79
… …
88syscall has been executed asynchronously. 90syscall has been executed asynchronously.
89 91
90All functions expecting a filehandle keep a copy of the filehandle 92All functions expecting a filehandle keep a copy of the filehandle
91internally until the request has finished. 93internally until the request has finished.
92 94
93The filenames you pass to these routines I<must> be absolute. The reason 95The pathnames you pass to these routines I<must> be absolute and
94for this is that at the time the request is being executed, the current 96encoded in byte form. The reason for the former is that at the time the
95working directory could have changed. Alternatively, you can make sure 97request is being executed, the current working directory could have
96that you never change the current working directory. 98changed. Alternatively, you can make sure that you never change the
99current working directory.
100
101To encode pathnames to byte form, either make sure you either: a)
102always pass in filenames you got from outside (command line, readdir
103etc.), b) are ASCII or ISO 8859-1, c) use the Encode module and encode
104your pathnames to the locale (or other) encoding in effect in the user
105environment, d) use Glib::filename_from_unicode on unicode filenames or e)
106use something else.
97 107
98=over 4 108=over 4
99 109
100=item aio_open $pathname, $flags, $mode, $callback 110=item aio_open $pathname, $flags, $mode, $callback
101 111
… …
142Reads or writes C<length> bytes from the specified C<fh> and C<offset> 152Reads or writes C<length> bytes from the specified C<fh> and C<offset>
143into the scalar given by C<data> and offset C<dataoffset> and calls the 153into the scalar given by C<data> and offset C<dataoffset> and calls the
144callback without the actual number of bytes read (or -1 on error, just 154callback without the actual number of bytes read (or -1 on error, just
145like the syscall). 155like the syscall).
146 156
157The C<$data> scalar I<MUST NOT> be modified in any way while the request
158is outstanding. Modifying it can result in segfaults or WW3 (if the
159necessary/optional hardware is installed).
160
147Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at 161Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at
148offset C<0> within the scalar: 162offset C<0> within the scalar:
149 163
150 aio_read $fh, 7, 15, $buffer, 0, sub { 164 aio_read $fh, 7, 15, $buffer, 0, sub {
151 $_[0] > 0 or die "read error: $!"; 165 $_[0] > 0 or die "read error: $!";
152 print "read $_[0] bytes: <$buffer>\n"; 166 print "read $_[0] bytes: <$buffer>\n";
153 }; 167 };
168
169=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback
170
171Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
172reading at byte offset C<$in_offset>, and starts writing at the current
173file offset of C<$out_fh>. Because of that, it is not safe to issue more
174than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
175other.
176
177This call tries to make use of a native C<sendfile> syscall to provide
178zero-copy operation. For this to work, C<$out_fh> should refer to a
179socket, and C<$in_fh> should refer to mmap'able file.
180
181If the native sendfile call fails or is not implemented, it will be
182emulated, so you can call C<aio_sendfile> on any type of filehandle
183regardless of the limitations of the operating system.
184
185Please note, however, that C<aio_sendfile> can read more bytes from
186C<$in_fh> than are written, and there is no way to find out how many
187bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
188provides the number of bytes written to C<$out_fh>. Only if the result
189value equals C<$length> one can assume that C<$length> bytes have been
190read.
154 191
155=item aio_readahead $fh,$offset,$length, $callback 192=item aio_readahead $fh,$offset,$length, $callback
156 193
157C<aio_readahead> populates the page cache with data from a file so that 194C<aio_readahead> populates the page cache with data from a file so that
158subsequent reads from that file will not block on disk I/O. The C<$offset> 195subsequent reads from that file will not block on disk I/O. The C<$offset>
… …
196=item aio_rmdir $pathname, $callback 233=item aio_rmdir $pathname, $callback
197 234
198Asynchronously rmdir (delete) a directory and call the callback with the 235Asynchronously rmdir (delete) a directory and call the callback with the
199result code. 236result code.
200 237
238=item aio_readdir $pathname $callback
239
240Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
241directory (i.e. opendir + readdir + closedir). The entries will not be
242sorted, and will B<NOT> include the C<.> and C<..> entries.
243
244The callback a single argument which is either C<undef> or an array-ref
245with the filenames.
246
201=item aio_fsync $fh, $callback 247=item aio_fsync $fh, $callback
202 248
203Asynchronously call fsync on the given filehandle and call the callback 249Asynchronously call fsync on the given filehandle and call the callback
204with the fsync result code. 250with the fsync result code.
205 251
… …
275 IO::AIO::poll_wait, IO::AIO::poll_cb 321 IO::AIO::poll_wait, IO::AIO::poll_cb
276 if IO::AIO::nreqs; 322 if IO::AIO::nreqs;
277 323
278=item IO::AIO::min_parallel $nthreads 324=item IO::AIO::min_parallel $nthreads
279 325
280Set the minimum number of AIO threads to C<$nthreads>. The default is 326Set the minimum number of AIO threads to C<$nthreads>. The current default
281C<1>, which means a single asynchronous operation can be done at one time 327is C<4>, which means four asynchronous operations can be done at one time
282(the number of outstanding operations, however, is unlimited). 328(the number of outstanding operations, however, is unlimited).
329
330IO::AIO starts threads only on demand, when an AIO request is queued and
331no free thread exists.
283 332
284It is recommended to keep the number of threads low, as some Linux 333It is recommended to keep the number of threads low, as some Linux
285kernel versions will scale negatively with the number of threads (higher 334kernel versions will scale negatively with the number of threads (higher
286parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 335parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
287threads should be fine. 336threads should be fine.
288 337
289Under normal circumstances you don't need to call this function, as this 338Under most circumstances you don't need to call this function, as the
290module automatically starts some threads (the exact number might change, 339module selects a default that is suitable for low to moderate load.
291and is currently 4).
292 340
293=item IO::AIO::max_parallel $nthreads 341=item IO::AIO::max_parallel $nthreads
294 342
295Sets the maximum number of AIO threads to C<$nthreads>. If more than 343Sets the maximum number of AIO threads to C<$nthreads>. If more than the
296the specified number of threads are currently running, kill them. This 344specified number of threads are currently running, this function kills
297function blocks until the limit is reached. 345them. This function blocks until the limit is reached.
346
347While C<$nthreads> are zero, aio requests get queued but not executed
348until the number of threads has been increased again.
298 349
299This module automatically runs C<max_parallel 0> at program end, to ensure 350This module automatically runs C<max_parallel 0> at program end, to ensure
300that all threads are killed and that there are no outstanding requests. 351that all threads are killed and that there are no outstanding requests.
301 352
302Under normal circumstances you don't need to call this function. 353Under normal circumstances you don't need to call this function.
… …
306Sets the maximum number of outstanding requests to C<$nreqs>. If you 357Sets the maximum number of outstanding requests to C<$nreqs>. If you
307try to queue up more than this number of requests, the caller will block until 358try to queue up more than this number of requests, the caller will block until
308some requests have been handled. 359some requests have been handled.
309 360
310The default is very large, so normally there is no practical limit. If you 361The default is very large, so normally there is no practical limit. If you
311queue up many requests in a loop it it often improves speed if you set 362queue up many requests in a loop it often improves speed if you set
312this to a relatively low number, such as C<100>. 363this to a relatively low number, such as C<100>.
313 364
314Under normal circumstances you don't need to call this function. 365Under normal circumstances you don't need to call this function.
315 366
316=back 367=back
… …
341 392
3421; 3931;
343 394
344=head2 FORK BEHAVIOUR 395=head2 FORK BEHAVIOUR
345 396
346IO::AIO handles all outstanding AIO requests before the fork, destroys all 397Before the fork, IO::AIO enters a quiescent state where no requests
347AIO threads, and recreates them in both the parent and the child after the 398can be added in other threads and no results will be processed. After
348fork. 399the fork the parent simply leaves the quiescent state and continues
349 400request/result processing, while the child clears the request/result
401queue (so the requests started before the fork will only be handled in
402the parent). Threats will be started on demand until the limit ste in the
403parent process has been reached again.
350 404
351=head1 SEE ALSO 405=head1 SEE ALSO
352 406
353L<Coro>, L<Linux::AIO>. 407L<Coro>, L<Linux::AIO>.
354 408

Diff Legend

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