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.175 by root, Sun Jan 10 20:37:33 2010 UTC vs.
Revision 1.187 by root, Fri Feb 11 00:05:17 2011 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use IO::AIO; 7 use IO::AIO;
8 8
9 aio_open "/etc/passwd", O_RDONLY, 0, sub { 9 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
10 my $fh = shift 10 my $fh = shift
11 or die "/etc/passwd: $!"; 11 or die "/etc/passwd: $!";
12 ... 12 ...
13 }; 13 };
14 14
… …
76 76
77 # register the IO::AIO callback with EV 77 # register the IO::AIO callback with EV
78 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; 78 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
79 79
80 # queue the request to open /etc/passwd 80 # queue the request to open /etc/passwd
81 aio_open "/etc/passwd", O_RDONLY, 0, sub { 81 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
82 my $fh = shift 82 my $fh = shift
83 or die "error while opening: $!"; 83 or die "error while opening: $!";
84 84
85 # stat'ing filehandles is generally non-blocking 85 # stat'ing filehandles is generally non-blocking
86 my $size = -s $fh; 86 my $size = -s $fh;
… …
168use common::sense; 168use common::sense;
169 169
170use base 'Exporter'; 170use base 'Exporter';
171 171
172BEGIN { 172BEGIN {
173 our $VERSION = '3.5'; 173 our $VERSION = '3.72';
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
… …
352by the umask in effect then the request is being executed, so better never 358by the umask in effect then the request is being executed, so better never
353change the umask. 359change the umask.
354 360
355Example: 361Example:
356 362
357 aio_open "/etc/passwd", O_RDONLY, 0, sub { 363 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
358 if ($_[0]) { 364 if ($_[0]) {
359 print "open successful, fh is $_[0]\n"; 365 print "open successful, fh is $_[0]\n";
360 ... 366 ...
361 } else { 367 } else {
362 die "open failed: $!\n"; 368 die "open failed: $!\n";
… …
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 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
… …
468for an explanation. 483for an explanation.
469 484
470Currently, the stats are always 64-bit-stats, i.e. instead of returning an 485Currently, the stats are always 64-bit-stats, i.e. instead of returning an
471error when stat'ing a large file, the results will be silently truncated 486error when stat'ing a large file, the results will be silently truncated
472unless perl itself is compiled with large file support. 487unless perl itself is compiled with large file support.
488
489To help interpret the mode and dev/rdev stat values, IO::AIO offers the
490following constants and functions (if not implemented, the constants will
491be C<0> and the functions will either C<croak> or fall back on traditional
492behaviour).
493
494C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
495C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
496C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
473 497
474Example: Print the length of F</etc/passwd>: 498Example: Print the length of F</etc/passwd>:
475 499
476 aio_stat "/etc/passwd", sub { 500 aio_stat "/etc/passwd", sub {
477 $_[0] and die "stat failed: $!"; 501 $_[0] and die "stat failed: $!";
… …
579 603
580The only (POSIX-) portable way of calling this function is: 604The only (POSIX-) portable way of calling this function is:
581 605
582 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 606 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
583 607
608See C<aio_stat> for info about some potentially helpful extra constants
609and functions.
584 610
585=item aio_link $srcpath, $dstpath, $callback->($status) 611=item aio_link $srcpath, $dstpath, $callback->($status)
586 612
587Asynchronously create a new link to the existing object at C<$srcpath> at 613Asynchronously create a new link to the existing object at C<$srcpath> at
588the path C<$dstpath> and call the callback with the result code. 614the path C<$dstpath> and call the callback with the result code.
… …
1084} 1110}
1085 1111
1086=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1112=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1087 1113
1088This is a rather advanced IO::AIO call, which only works on mmap(2)ed 1114This is a rather advanced IO::AIO call, which only works on mmap(2)ed
1089scalars (see the L<Sys::Mmap> or L<Mmap> modules for details on this, note 1115scalars (see the C<IO::AIO::mmap> function, although it also works on data
1116scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the
1090that the scalar must only be modified in-place while an aio operation is 1117scalar must only be modified in-place while an aio operation is pending on
1091pending on it). 1118it).
1092 1119
1093It calls the C<msync> function of your OS, if available, with the memory 1120It calls the C<msync> function of your OS, if available, with the memory
1094area starting at C<$offset> in the string and ending C<$length> bytes 1121area starting at C<$offset> in the string and ending C<$length> bytes
1095later. If C<$length> is negative, counts from the end, and if C<$length> 1122later. If C<$length> is negative, counts from the end, and if C<$length>
1096is C<undef>, then it goes till the end of the string. The flags can be 1123is C<undef>, then it goes till the end of the string. The flags can be
… …
1107as for C<aio_msync>, above, except for flags, which must be either 1134as for C<aio_msync>, above, except for flags, which must be either
1108C<0> (which reads all pages and ensures they are instantiated) or 1135C<0> (which reads all pages and ensures they are instantiated) or
1109C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and 1136C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and
1110writing an octet from it, which dirties the page). 1137writing an octet from it, which dirties the page).
1111 1138
1139=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1140
1141This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1142scalars.
1143
1144It reads in all the pages of the underlying storage into memory (if any)
1145and locks them, so they are not getting swapped/paged out or removed.
1146
1147If C<$length> is undefined, then the scalar will be locked till the end.
1148
1149On systems that do not implement C<mlock>, this function returns C<-1>
1150and sets errno to C<ENOSYS>.
1151
1152Note that the corresponding C<munlock> is synchronous and is
1153documented under L<MISCELLANEOUS FUNCTIONS>.
1154
1155Example: open a file, mmap and mlock it - both will be undone when
1156C<$data> gets destroyed.
1157
1158 open my $fh, "<", $path or die "$path: $!";
1159 my $data;
1160 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1161 aio_mlock $data; # mlock in background
1162
1163=item aio_mlockall $flags, $callback->($status)
1164
1165Calls the C<mlockall> function with the given C<$flags> (a combination of
1166C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
1167
1168On systems that do not implement C<mlockall>, this function returns C<-1>
1169and sets errno to C<ENOSYS>.
1170
1171Note that the corresponding C<munlockall> is synchronous and is
1172documented under L<MISCELLANEOUS FUNCTIONS>.
1173
1174Example: asynchronously lock all current and future pages into memory.
1175
1176 aio_mlockall IO::AIO::MCL_FUTURE;
1177
1112=item aio_group $callback->(...) 1178=item aio_group $callback->(...)
1113 1179
1114This is a very special aio request: Instead of doing something, it is a 1180This is a very special aio request: Instead of doing something, it is a
1115container for other aio requests, which is useful if you want to bundle 1181container for other aio requests, which is useful if you want to bundle
1116many requests into a single, composite, request with a definite callback 1182many requests into a single, composite, request with a definite callback
… …
1536 1602
1537Returns the number of bytes copied, or C<-1> on error. 1603Returns the number of bytes copied, or C<-1> on error.
1538 1604
1539=item IO::AIO::fadvise $fh, $offset, $len, $advice 1605=item IO::AIO::fadvise $fh, $offset, $len, $advice
1540 1606
1541Simply calls the C<posix_fadvise> function (see it's 1607Simply calls the C<posix_fadvise> function (see its
1542manpage for details). The following advice constants are 1608manpage for details). The following advice constants are
1543avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>, 1609avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
1544C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>, 1610C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
1545C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. 1611C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1546 1612
1547On systems that do not implement C<posix_fadvise>, this function returns 1613On systems that do not implement C<posix_fadvise>, this function returns
1548ENOSYS, otherwise the return value of C<posix_fadvise>. 1614ENOSYS, otherwise the return value of C<posix_fadvise>.
1549 1615
1550=item IO::AIO::mlockall $flags 1616=item IO::AIO::madvise $scalar, $offset, $len, $advice
1551 1617
1552Calls the C<mlockall> function with the given C<$flags> (a combination of 1618Simply calls the C<posix_madvise> function (see its
1553C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>). 1619manpage for details). The following advice constants are
1620avaiable: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
1621C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>.
1554 1622
1623On systems that do not implement C<posix_madvise>, this function returns
1624ENOSYS, otherwise the return value of C<posix_madvise>.
1625
1626=item IO::AIO::mprotect $scalar, $offset, $len, $protect
1627
1628Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
1629$scalar (see its manpage for details). The following protect
1630constants are avaiable: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
1631C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
1632
1555On systems that do not implement C<mlockall>, this function returns 1633On systems that do not implement C<mprotect>, this function returns
1556ENOSYS, otherwise the return value of C<mlockall>. 1634ENOSYS, otherwise the return value of C<mprotect>.
1635
1636=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1637
1638Memory-maps a file (or anonymous memory range) and attaches it to the
1639given C<$scalar>, which will act like a string scalar.
1640
1641The only operations allowed on the scalar are C<substr>/C<vec> that don't
1642change the string length, and most read-only operations such as copying it
1643or searching it with regexes and so on.
1644
1645Anything else is unsafe and will, at best, result in memory leaks.
1646
1647The memory map associated with the C<$scalar> is automatically removed
1648when the C<$scalar> is destroyed, or when the C<IO::AIO::mmap> or
1649C<IO::AIO::munmap> functions are called.
1650
1651This calls the C<mmap>(2) function internally. See your system's manual
1652page for details on the C<$length>, C<$prot> and C<$flags> parameters.
1653
1654The C<$length> must be larger than zero and smaller than the actual
1655filesize.
1656
1657C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>,
1658C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>,
1659
1660C<$flags> can be a combination of C<IO::AIO::MAP_SHARED> or
1661C<IO::AIO::MAP_PRIVATE>, or a number of system-specific flags (when
1662not available, the are defined as 0): C<IO::AIO::MAP_ANONYMOUS>
1663(which is set to C<MAP_ANON> if your system only provides this
1664constant), C<IO::AIO::MAP_HUGETLB>, C<IO::AIO::MAP_LOCKED>,
1665C<IO::AIO::MAP_NORESERVE>, C<IO::AIO::MAP_POPULATE> or
1666C<IO::AIO::MAP_NONBLOCK>
1667
1668If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
1669
1670C<$offset> is the offset from the start of the file - it generally must be
1671a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
1672
1673Example:
1674
1675 use Digest::MD5;
1676 use IO::AIO;
1677
1678 open my $fh, "<verybigfile"
1679 or die "$!";
1680
1681 IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
1682 or die "verybigfile: $!";
1683
1684 my $fast_md5 = md5 $data;
1685
1686=item IO::AIO::munmap $scalar
1687
1688Removes a previous mmap and undefines the C<$scalar>.
1689
1690=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
1691
1692Calls the C<munlock> function, undoing the effects of a previous
1693C<aio_mlock> call (see its description for details).
1557 1694
1558=item IO::AIO::munlockall 1695=item IO::AIO::munlockall
1559 1696
1560Calls the C<munlockall> function. 1697Calls the C<munlockall> function.
1561 1698

Diff Legend

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