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.23 by root, Fri Jul 22 08:25:22 2005 UTC vs.
Revision 1.34 by root, Thu Aug 18 16:32:10 2005 UTC

… …
63use base 'Exporter'; 63use base 'Exporter';
64 64
65use Fcntl (); 65use Fcntl ();
66 66
67BEGIN { 67BEGIN {
68 $VERSION = '1.0'; 68 $VERSION = 1.5;
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_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 };
154 166
155=item aio_readahead $fh,$offset,$length, $callback 167=item aio_readahead $fh,$offset,$length, $callback
156
157Asynchronously reads the specified byte range into the page cache, using
158the C<readahead> syscall. If that syscall doesn't exist (likely if your OS
159isn't Linux) the status will be C<-1> and C<$!> is set to C<ENOSYS>.
160 168
161C<aio_readahead> populates the page cache with data from a file so that 169C<aio_readahead> populates the page cache with data from a file so that
162subsequent reads from that file will not block on disk I/O. The C<$offset> 170subsequent reads from that file will not block on disk I/O. The C<$offset>
163argument specifies the starting point from which data is to be read and 171argument specifies the starting point from which data is to be read and
164C<$length> specifies the number of bytes to be read. I/O is performed in 172C<$length> specifies the number of bytes to be read. I/O is performed in
165whole pages, so that offset is effectively rounded down to a page boundary 173whole pages, so that offset is effectively rounded down to a page boundary
166and bytes are read up to the next page boundary greater than or equal to 174and bytes are read up to the next page boundary greater than or equal to
167(off-set+length). C<aio_readahead> does not read beyond the end of the 175(off-set+length). C<aio_readahead> does not read beyond the end of the
168file. The current file offset of the file is left unchanged. 176file. The current file offset of the file is left unchanged.
169 177
178If that syscall doesn't exist (likely if your OS isn't Linux) it will be
179emulated by simply reading the data, which would have a similar effect.
180
170=item aio_stat $fh_or_path, $callback 181=item aio_stat $fh_or_path, $callback
171 182
172=item aio_lstat $fh, $callback 183=item aio_lstat $fh, $callback
173 184
174Works like perl's C<stat> or C<lstat> in void context. The callback will 185Works like perl's C<stat> or C<lstat> in void context. The callback will
… …
192=item aio_unlink $pathname, $callback 203=item aio_unlink $pathname, $callback
193 204
194Asynchronously unlink (delete) a file and call the callback with the 205Asynchronously unlink (delete) a file and call the callback with the
195result code. 206result code.
196 207
208=item aio_rmdir $pathname, $callback
209
210Asynchronously rmdir (delete) a directory and call the callback with the
211result code.
212
197=item aio_fsync $fh, $callback 213=item aio_fsync $fh, $callback
198 214
199Asynchronously call fsync on the given filehandle and call the callback 215Asynchronously call fsync on the given filehandle and call the callback
200with the fsync result code. 216with the fsync result code.
201 217
202=item aio_fdatasync $fh, $callback 218=item aio_fdatasync $fh, $callback
203 219
204Asynchronously call fdatasync on the given filehandle and call the 220Asynchronously call fdatasync on the given filehandle and call the
205callback with the fdatasync result code. Might set C<$!> to C<ENOSYS> if 221callback with the fdatasync result code.
206C<fdatasync> is not available. 222
223If this call isn't available because your OS lacks it or it couldn't be
224detected, it will be emulated by calling C<fsync> instead.
207 225
208=back 226=back
209 227
210=head2 SUPPORT FUNCTIONS 228=head2 SUPPORT FUNCTIONS
211 229
… …
269 IO::AIO::poll_wait, IO::AIO::poll_cb 287 IO::AIO::poll_wait, IO::AIO::poll_cb
270 if IO::AIO::nreqs; 288 if IO::AIO::nreqs;
271 289
272=item IO::AIO::min_parallel $nthreads 290=item IO::AIO::min_parallel $nthreads
273 291
274Set the minimum number of AIO threads to C<$nthreads>. The default is 292Set the minimum number of AIO threads to C<$nthreads>. The current default
275C<1>, which means a single asynchronous operation can be done at one time 293is C<4>, which means four asynchronous operations can be done at one time
276(the number of outstanding operations, however, is unlimited). 294(the number of outstanding operations, however, is unlimited).
295
296IO::AIO starts threads only on demand, when an AIO request is queued and
297no free thread exists.
277 298
278It is recommended to keep the number of threads low, as some Linux 299It is recommended to keep the number of threads low, as some Linux
279kernel versions will scale negatively with the number of threads (higher 300kernel versions will scale negatively with the number of threads (higher
280parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 301parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
281threads should be fine. 302threads should be fine.
282 303
283Under normal circumstances you don't need to call this function, as this 304Under most circumstances you don't need to call this function, as the
284module automatically starts some threads (the exact number might change, 305module selects a default that is suitable for low to moderate load.
285and is currently 4).
286 306
287=item IO::AIO::max_parallel $nthreads 307=item IO::AIO::max_parallel $nthreads
288 308
289Sets the maximum number of AIO threads to C<$nthreads>. If more than 309Sets the maximum number of AIO threads to C<$nthreads>. If more than the
290the specified number of threads are currently running, kill them. This 310specified number of threads are currently running, this function kills
291function blocks until the limit is reached. 311them. This function blocks until the limit is reached.
312
313While C<$nthreads> are zero, aio requests get queued but not executed
314until the number of threads has been increased again.
292 315
293This module automatically runs C<max_parallel 0> at program end, to ensure 316This module automatically runs C<max_parallel 0> at program end, to ensure
294that all threads are killed and that there are no outstanding requests. 317that all threads are killed and that there are no outstanding requests.
295 318
296Under normal circumstances you don't need to call this function. 319Under normal circumstances you don't need to call this function.
… …
300Sets the maximum number of outstanding requests to C<$nreqs>. If you 323Sets the maximum number of outstanding requests to C<$nreqs>. If you
301try to queue up more than this number of requests, the caller will block until 324try to queue up more than this number of requests, the caller will block until
302some requests have been handled. 325some requests have been handled.
303 326
304The default is very large, so normally there is no practical limit. If you 327The default is very large, so normally there is no practical limit. If you
305queue up many requests in a loop it it often improves speed if you set 328queue up many requests in a loop it often improves speed if you set
306this to a relatively low number, such as C<100>. 329this to a relatively low number, such as C<100>.
307 330
308Under normal circumstances you don't need to call this function. 331Under normal circumstances you don't need to call this function.
309 332
310=back 333=back
… …
316 return undef if $_[0] < 0; 339 return undef if $_[0] < 0;
317 340
318 # try to generate nice filehandles 341 # try to generate nice filehandles
319 my $sym = "IO::AIO::fd#$_[0]"; 342 my $sym = "IO::AIO::fd#$_[0]";
320 local *$sym; 343 local *$sym;
321 open *$sym, "+<&=$_[0]" 344
345 open *$sym, "+<&=$_[0]" # usually works under any unix
346 or open *$sym, "<&=$_[0]" # cygwin needs this
347 or open *$sym, ">&=$_[0]" # or this
322 or return undef; 348 or return undef;
323 349
324 *$sym 350 *$sym
325} 351}
326 352
… …
330 max_parallel 0; 356 max_parallel 0;
331} 357}
332 358
3331; 3591;
334 360
361=head2 FORK BEHAVIOUR
362
363Before the fork, IO::AIO enters a quiescent state where no requests
364can be added in other threads and no results will be processed. After
365the fork the parent simply leaves the quiescent state and continues
366request/result processing, while the child clears the request/result
367queue (so the requests started before the fork will only be handled in
368the parent). Threats will be started on demand until the limit ste in the
369parent process has been reached again.
370
335=head1 SEE ALSO 371=head1 SEE ALSO
336 372
337L<Coro>, L<Linux::AIO>. 373L<Coro>, L<Linux::AIO>.
338 374
339=head1 AUTHOR 375=head1 AUTHOR

Diff Legend

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