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.181 by root, Tue May 4 21:14:01 2010 UTC vs.
Revision 1.185 by root, Sat Dec 11 19:06:07 2010 UTC

… …
168use common::sense; 168use common::sense;
169 169
170use base 'Exporter'; 170use base 'Exporter';
171 171
172BEGIN { 172BEGIN {
173 our $VERSION = '3.65'; 173 our $VERSION = '3.7';
174 174
175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close 175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx 176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
177 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync 177 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync
178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead 178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead
179 aio_rename aio_link aio_move aio_copy aio_group 179 aio_rename aio_link aio_move aio_copy aio_group
180 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown 180 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
181 aio_chmod aio_utime aio_truncate 181 aio_chmod aio_utime aio_truncate
182 aio_msync aio_mtouch aio_statvfs); 182 aio_msync aio_mtouch aio_mlock aio_mlockall
183 aio_statvfs);
183 184
184 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 185 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
185 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 186 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
186 min_parallel max_parallel max_idle 187 min_parallel max_parallel max_idle
187 nreqs nready npending nthreads 188 nreqs nready npending nthreads
188 max_poll_time max_poll_reqs 189 max_poll_time max_poll_reqs
189 sendfile fadvise); 190 sendfile fadvise madvise
191 mmap munmap munlock munlockall);
190 192
191 push @AIO_REQ, qw(aio_busy); # not exported 193 push @AIO_REQ, qw(aio_busy); # not exported
192 194
193 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 195 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
194 196
… …
239 aio_fdatasync $fh, $callback->($status) 241 aio_fdatasync $fh, $callback->($status)
240 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 242 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
241 aio_pathsync $path, $callback->($status) 243 aio_pathsync $path, $callback->($status)
242 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 244 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
243 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 245 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
246 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
247 aio_mlockall $flags, $callback->($status)
244 aio_group $callback->(...) 248 aio_group $callback->(...)
245 aio_nop $callback->() 249 aio_nop $callback->()
246 250
247 $prev_pri = aioreq_pri [$pri] 251 $prev_pri = aioreq_pri [$pri]
248 aioreq_nice $pri_adjust 252 aioreq_nice $pri_adjust
… …
261 IO::AIO::nready 265 IO::AIO::nready
262 IO::AIO::npending 266 IO::AIO::npending
263 267
264 IO::AIO::sendfile $ofh, $ifh, $offset, $count 268 IO::AIO::sendfile $ofh, $ifh, $offset, $count
265 IO::AIO::fadvise $fh, $offset, $len, $advice 269 IO::AIO::fadvise $fh, $offset, $len, $advice
266 IO::AIO::mlockall $flags 270 IO::AIO::madvise $scalar, $offset, $length, $advice
271 IO::AIO::mprotect $scalar, $offset, $length, $protect
272 IO::AIO::munlock $scalar, $offset = 0, $length = undef
267 IO::AIO::munlockall 273 IO::AIO::munlockall
268 274
269=head2 AIO REQUEST FUNCTIONS 275=head2 AIO REQUEST FUNCTIONS
270 276
271All the C<aio_*> calls are more or less thin wrappers around the syscall 277All the C<aio_*> calls are more or less thin wrappers around the syscall
… …
422reading at byte offset C<$in_offset>, and starts writing at the current 428reading at byte offset C<$in_offset>, and starts writing at the current
423file offset of C<$out_fh>. Because of that, it is not safe to issue more 429file offset of C<$out_fh>. Because of that, it is not safe to issue more
424than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each 430than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
425other. 431other.
426 432
433Please note that C<aio_sendfile> can read more bytes from C<$in_fh> than
434are written, and there is no way to find out how many bytes have been read
435from C<aio_sendfile> alone, as C<aio_sendfile> only provides the number of
436bytes written to C<$out_fh>. Only if the result value equals C<$length>
437one can assume that C<$length> bytes have been read.
438
439Unlike with other C<aio_> functions, it makes a lot of sense to use
440C<aio_sendfile> on non-blocking sockets, as long as one end (typically
441the C<$in_fh>) is a file - the file I/O will then be asynchronous, while
442the socket I/O will be non-blocking. Note, however, that you can run into
443a trap where C<aio_sendfile> reads some data with readahead, then fails
444to write all data, and when the socket is ready the next time, the data
445in the cache is already lost, forcing C<aio_sendfile> to again hit the
446disk. Explicit C<aio_read> + C<aio_write> let's you control resource usage
447much better.
448
427This call tries to make use of a native C<sendfile> syscall to provide 449This call tries to make use of a native C<sendfile> syscall to provide
428zero-copy operation. For this to work, C<$out_fh> should refer to a 450zero-copy operation. For this to work, C<$out_fh> should refer to a
429socket, and C<$in_fh> should refer to an mmap'able file. 451socket, and C<$in_fh> should refer to an mmap'able file.
430 452
431If a native sendfile cannot be found or it fails with C<ENOSYS>, 453If a native sendfile cannot be found or it fails with C<ENOSYS>,
432C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>, 454C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>,
433it will be emulated, so you can call C<aio_sendfile> on any type of 455it will be emulated, so you can call C<aio_sendfile> on any type of
434filehandle regardless of the limitations of the operating system. 456filehandle regardless of the limitations of the operating system.
435
436Please note, however, that C<aio_sendfile> can read more bytes from
437C<$in_fh> than are written, and there is no way to find out how many
438bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
439provides the number of bytes written to C<$out_fh>. Only if the result
440value equals C<$length> one can assume that C<$length> bytes have been
441read.
442 457
443 458
444=item aio_readahead $fh,$offset,$length, $callback->($retval) 459=item aio_readahead $fh,$offset,$length, $callback->($retval)
445 460
446C<aio_readahead> populates the page cache with data from a file so that 461C<aio_readahead> populates the page cache with data from a file so that
… …
1108as for C<aio_msync>, above, except for flags, which must be either 1123as for C<aio_msync>, above, except for flags, which must be either
1109C<0> (which reads all pages and ensures they are instantiated) or 1124C<0> (which reads all pages and ensures they are instantiated) or
1110C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and 1125C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and
1111writing an octet from it, which dirties the page). 1126writing an octet from it, which dirties the page).
1112 1127
1128=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1129
1130This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1131scalars.
1132
1133It reads in all the pages of the underlying storage into memory (if any)
1134and locks them, so they are not getting swapped/paged out or removed.
1135
1136If C<$length> is undefined, then the scalar will be locked till the end.
1137
1138On systems that do not implement C<mlock>, this function returns C<-1>
1139and sets errno to C<ENOSYS>.
1140
1141Note that the corresponding C<munlock> is synchronous and is
1142documented under L<MISCELLANEOUS FUNCTIONS>.
1143
1144Example: open a file, mmap and mlock it - both will be undone when
1145C<$data> gets destroyed.
1146
1147 open my $fh, "<", $path or die "$path: $!";
1148 my $data;
1149 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1150 aio_mlock $data; # mlock in background
1151
1152=item aio_mlockall $flags, $callback->($status)
1153
1154Calls the C<mlockall> function with the given C<$flags> (a combination of
1155C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
1156
1157On systems that do not implement C<mlockall>, this function returns C<-1>
1158and sets errno to C<ENOSYS>.
1159
1160Note that the corresponding C<munlockall> is synchronous and is
1161documented under L<MISCELLANEOUS FUNCTIONS>.
1162
1163Example: asynchronously lock all current and future pages into memory.
1164
1165 aio_mlockall IO::AIO::MCL_FUTURE;
1166
1113=item aio_group $callback->(...) 1167=item aio_group $callback->(...)
1114 1168
1115This is a very special aio request: Instead of doing something, it is a 1169This is a very special aio request: Instead of doing something, it is a
1116container for other aio requests, which is useful if you want to bundle 1170container for other aio requests, which is useful if you want to bundle
1117many requests into a single, composite, request with a definite callback 1171many requests into a single, composite, request with a definite callback
… …
1537 1591
1538Returns the number of bytes copied, or C<-1> on error. 1592Returns the number of bytes copied, or C<-1> on error.
1539 1593
1540=item IO::AIO::fadvise $fh, $offset, $len, $advice 1594=item IO::AIO::fadvise $fh, $offset, $len, $advice
1541 1595
1542Simply calls the C<posix_fadvise> function (see it's 1596Simply calls the C<posix_fadvise> function (see its
1543manpage for details). The following advice constants are 1597manpage for details). The following advice constants are
1544avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>, 1598avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
1545C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>, 1599C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
1546C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. 1600C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1547 1601
1548On systems that do not implement C<posix_fadvise>, this function returns 1602On systems that do not implement C<posix_fadvise>, this function returns
1549ENOSYS, otherwise the return value of C<posix_fadvise>. 1603ENOSYS, otherwise the return value of C<posix_fadvise>.
1604
1605=item IO::AIO::madvise $scalar, $offset, $len, $advice
1606
1607Simply calls the C<posix_madvise> function (see its
1608manpage for details). The following advice constants are
1609avaiable: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
1610C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>.
1611
1612On systems that do not implement C<posix_madvise>, this function returns
1613ENOSYS, otherwise the return value of C<posix_madvise>.
1614
1615=item IO::AIO::mprotect $scalar, $offset, $len, $protect
1616
1617Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
1618$scalar (see its manpage for details). The following protect
1619constants are avaiable: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
1620C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
1621
1622On systems that do not implement C<mprotect>, this function returns
1623ENOSYS, otherwise the return value of C<mprotect>.
1550 1624
1551=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] 1625=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1552 1626
1553Memory-maps a file (or anonymous memory range) and attaches it to the 1627Memory-maps a file (or anonymous memory range) and attaches it to the
1554given C<$scalar>, which will act like a string scalar. 1628given C<$scalar>, which will act like a string scalar.
… …
1600 1674
1601=item IO::AIO::munmap $scalar 1675=item IO::AIO::munmap $scalar
1602 1676
1603Removes a previous mmap and undefines the C<$scalar>. 1677Removes a previous mmap and undefines the C<$scalar>.
1604 1678
1605=item IO::AIO::mlockall $flags 1679=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
1606 1680
1607Calls the C<mlockall> function with the given C<$flags> (a combination of 1681Calls the C<munlock> function, undoing the effects of a previous
1608C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>). 1682C<aio_mlock> call (see its description for details).
1609
1610On systems that do not implement C<mlockall>, this function returns
1611ENOSYS, otherwise the return value of C<mlockall>.
1612 1683
1613=item IO::AIO::munlockall 1684=item IO::AIO::munlockall
1614 1685
1615Calls the C<munlockall> function. 1686Calls the C<munlockall> function.
1616 1687

Diff Legend

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