--- IO-AIO/AIO.pm 2005/07/11 03:29:22 1.17 +++ IO-AIO/AIO.pm 2005/07/31 21:21:12 1.25 @@ -24,7 +24,7 @@ # Glib/Gtk2 add_watch Glib::IO IO::AIO::poll_fileno, - in => sub { IO::AIO::poll_cb, 1 }; + in => sub { IO::AIO::poll_cb; 1 }; # Tk Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "", @@ -50,18 +50,22 @@ remaining functionality would have to be implemented using threads anyway. Although the module will work with in the presence of other threads, it is -currently not reentrant, so use appropriate locking yourself. +currently not reentrant, so use appropriate locking yourself, always call +C from within the same thread, or never call C (or other +C functions) recursively. =cut package IO::AIO; +no warnings; + use base 'Exporter'; use Fcntl (); BEGIN { - $VERSION = 0.3; + $VERSION = 1.1; @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink aio_fsync aio_fdatasync aio_readahead); @@ -83,12 +87,13 @@ perl, which usually delivers "false") as it's sole argument when the given syscall has been executed asynchronously. -All functions that expect a filehandle will also accept a file descriptor. +All functions expecting a filehandle keep a copy of the filehandle +internally until the request has finished. The filenames you pass to these routines I be absolute. The reason -is that at the time the request is being executed, the current working -directory could have changed. Alternatively, you can make sure that you -never change the current working directory. +for this is that at the time the request is being executed, the current +working directory could have changed. Alternatively, you can make sure +that you never change the current working directory. =over 4 @@ -100,8 +105,13 @@ The pathname passed to C must be absolute. See API NOTES, above, for an explanation. -The C<$mode> argument is a bitmask. See the C module for a -list. They are the same as used in C. +The C<$flags> argument is a bitmask. See the C module for a +list. They are the same as used by C. + +Likewise, C<$mode> specifies the mode of the newly created file, if it +didn't exist and C has been given, just like perl's C, +except that it is mandatory (i.e. use C<0> if you don't create new files, +and C<0666> or C<0777> if you do). Example: @@ -118,9 +128,12 @@ Asynchronously close a file and call the callback with the result code. I although accepted, you should not pass in a perl -filehandle here, as perl will likely close the file descriptor itself when -the filehandle is destroyed. Normally, you can safely call perls C -or just let filehandles go out of scope. +filehandle here, as perl will likely close the file descriptor another +time when the filehandle is destroyed. Normally, you can safely call perls +C or just let filehandles go out of scope. + +This is supposed to be a bug in the API, so that might change. It's +therefore best to avoid this function. =item aio_read $fh,$offset,$length, $data,$dataoffset,$callback @@ -143,15 +156,15 @@ Asynchronously reads the specified byte range into the page cache, using the C syscall. If that syscall doesn't exist (likely if your OS -isn't Linux) the status will be C<-1> and C<$!> is set to ENOSYS. +isn't Linux) the status will be C<-1> and C<$!> is set to C. -readahead() populates the page cache with data from a file so that +C populates the page cache with data from a file so that subsequent reads from that file will not block on disk I/O. The C<$offset> argument specifies the starting point from which data is to be read and C<$length> specifies the number of bytes to be read. I/O is performed in whole pages, so that offset is effectively rounded down to a page boundary and bytes are read up to the next page boundary greater than or equal to -(off-set+length). aio_readahead() does not read beyond the end of the +(off-set+length). C does not read beyond the end of the file. The current file offset of the file is left unchanged. =item aio_stat $fh_or_path, $callback @@ -189,7 +202,8 @@ =item aio_fdatasync $fh, $callback Asynchronously call fdatasync on the given filehandle and call the -callback with the fdatasync result code. +callback with the fdatasync result code. Might set C<$!> to C if +C is not available. =back @@ -199,10 +213,10 @@ =item $fileno = IO::AIO::poll_fileno -Return the I. This filehandle must be -polled for reading by some mechanism outside this module (e.g. Event -or select, see below). If the pipe becomes readable you have to call -C to check the results. +Return the I. This filehandle must be +polled for reading by some mechanism outside this module (e.g. Event or +select, see below or the SYNOPSIS). If the pipe becomes readable you have +to call C to check the results. See C for an example. @@ -212,7 +226,8 @@ regularly. Returns the number of events processed. Returns immediately when no events are outstanding. -You can use Event to multiplex, e.g.: +Example: Install an Event watcher that automatically calls +IO::AIO::poll_cb with high priority: Event->io (fd => IO::AIO::poll_fileno, poll => 'r', async => 1, @@ -221,14 +236,15 @@ =item IO::AIO::poll_wait Wait till the result filehandle becomes ready for reading (simply does a -select on the filehandle. This is useful if you want to synchronously wait +C