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

Diff Legend

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