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.193 by root, Thu May 26 04:15:37 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.8';
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 idle_timeout
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
… …
254 IO::AIO::max_poll_reqs $nreqs 258 IO::AIO::max_poll_reqs $nreqs
255 IO::AIO::max_poll_time $seconds 259 IO::AIO::max_poll_time $seconds
256 IO::AIO::min_parallel $nthreads 260 IO::AIO::min_parallel $nthreads
257 IO::AIO::max_parallel $nthreads 261 IO::AIO::max_parallel $nthreads
258 IO::AIO::max_idle $nthreads 262 IO::AIO::max_idle $nthreads
263 IO::AIO::idle_timeout $seconds
259 IO::AIO::max_outstanding $maxreqs 264 IO::AIO::max_outstanding $maxreqs
260 IO::AIO::nreqs 265 IO::AIO::nreqs
261 IO::AIO::nready 266 IO::AIO::nready
262 IO::AIO::npending 267 IO::AIO::npending
263 268
264 IO::AIO::sendfile $ofh, $ifh, $offset, $count 269 IO::AIO::sendfile $ofh, $ifh, $offset, $count
265 IO::AIO::fadvise $fh, $offset, $len, $advice 270 IO::AIO::fadvise $fh, $offset, $len, $advice
266 IO::AIO::mlockall $flags 271 IO::AIO::madvise $scalar, $offset, $length, $advice
272 IO::AIO::mprotect $scalar, $offset, $length, $protect
273 IO::AIO::munlock $scalar, $offset = 0, $length = undef
267 IO::AIO::munlockall 274 IO::AIO::munlockall
268 275
269=head2 AIO REQUEST FUNCTIONS 276=head2 AIO REQUEST FUNCTIONS
270 277
271All the C<aio_*> calls are more or less thin wrappers around the syscall 278All 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 359by the umask in effect then the request is being executed, so better never
353change the umask. 360change the umask.
354 361
355Example: 362Example:
356 363
357 aio_open "/etc/passwd", O_RDONLY, 0, sub { 364 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
358 if ($_[0]) { 365 if ($_[0]) {
359 print "open successful, fh is $_[0]\n"; 366 print "open successful, fh is $_[0]\n";
360 ... 367 ...
361 } else { 368 } else {
362 die "open failed: $!\n"; 369 die "open failed: $!\n";
… …
422reading at byte offset C<$in_offset>, and starts writing at the current 429reading 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 430file 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 431than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
425other. 432other.
426 433
434Please note that C<aio_sendfile> can read more bytes from C<$in_fh> than
435are written, and there is no way to find out how many bytes have been read
436from C<aio_sendfile> alone, as C<aio_sendfile> only provides the number of
437bytes written to C<$out_fh>. Only if the result value equals C<$length>
438one can assume that C<$length> bytes have been read.
439
440Unlike with other C<aio_> functions, it makes a lot of sense to use
441C<aio_sendfile> on non-blocking sockets, as long as one end (typically
442the C<$in_fh>) is a file - the file I/O will then be asynchronous, while
443the socket I/O will be non-blocking. Note, however, that you can run into
444a trap where C<aio_sendfile> reads some data with readahead, then fails
445to write all data, and when the socket is ready the next time, the data
446in the cache is already lost, forcing C<aio_sendfile> to again hit the
447disk. Explicit C<aio_read> + C<aio_write> let's you control resource usage
448much better.
449
427This call tries to make use of a native C<sendfile> syscall to provide 450This 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 451zero-copy operation. For this to work, C<$out_fh> should refer to a
429socket, and C<$in_fh> should refer to mmap'able file. 452socket, and C<$in_fh> should refer to an mmap'able file.
430 453
431If a native sendfile cannot be found or it fails with C<ENOSYS>, 454If a native sendfile cannot be found or it fails with C<ENOSYS>,
432C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>, 455C<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 456it will be emulated, so you can call C<aio_sendfile> on any type of
434filehandle regardless of the limitations of the operating system. 457filehandle 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 458
443 459
444=item aio_readahead $fh,$offset,$length, $callback->($retval) 460=item aio_readahead $fh,$offset,$length, $callback->($retval)
445 461
446C<aio_readahead> populates the page cache with data from a file so that 462C<aio_readahead> populates the page cache with data from a file so that
… …
468for an explanation. 484for an explanation.
469 485
470Currently, the stats are always 64-bit-stats, i.e. instead of returning an 486Currently, 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 487error when stat'ing a large file, the results will be silently truncated
472unless perl itself is compiled with large file support. 488unless perl itself is compiled with large file support.
489
490To help interpret the mode and dev/rdev stat values, IO::AIO offers the
491following constants and functions (if not implemented, the constants will
492be C<0> and the functions will either C<croak> or fall back on traditional
493behaviour).
494
495C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
496C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
497C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
473 498
474Example: Print the length of F</etc/passwd>: 499Example: Print the length of F</etc/passwd>:
475 500
476 aio_stat "/etc/passwd", sub { 501 aio_stat "/etc/passwd", sub {
477 $_[0] and die "stat failed: $!"; 502 $_[0] and die "stat failed: $!";
… …
579 604
580The only (POSIX-) portable way of calling this function is: 605The only (POSIX-) portable way of calling this function is:
581 606
582 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 607 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
583 608
609See C<aio_stat> for info about some potentially helpful extra constants
610and functions.
584 611
585=item aio_link $srcpath, $dstpath, $callback->($status) 612=item aio_link $srcpath, $dstpath, $callback->($status)
586 613
587Asynchronously create a new link to the existing object at C<$srcpath> at 614Asynchronously create a new link to the existing object at C<$srcpath> at
588the path C<$dstpath> and call the callback with the result code. 615the path C<$dstpath> and call the callback with the result code.
… …
641 668
642=over 4 669=over 4
643 670
644=item IO::AIO::READDIR_DENTS 671=item IO::AIO::READDIR_DENTS
645 672
646When this flag is off, then the callback gets an arrayref with of names 673When this flag is off, then the callback gets an arrayref consisting of
647only (as with C<aio_readdir>), otherwise it gets an arrayref with 674names only (as with C<aio_readdir>), otherwise it gets an arrayref with
648C<[$name, $type, $inode]> arrayrefs, each describing a single directory 675C<[$name, $type, $inode]> arrayrefs, each describing a single directory
649entry in more detail. 676entry in more detail.
650 677
651C<$name> is the name of the entry. 678C<$name> is the name of the entry.
652 679
… …
665systems that do not deliver the inode information. 692systems that do not deliver the inode information.
666 693
667=item IO::AIO::READDIR_DIRS_FIRST 694=item IO::AIO::READDIR_DIRS_FIRST
668 695
669When this flag is set, then the names will be returned in an order where 696When this flag is set, then the names will be returned in an order where
670likely directories come first. This is useful when you need to quickly 697likely directories come first, in optimal stat order. This is useful when
671find directories, or you want to find all directories while avoiding to 698you need to quickly find directories, or you want to find all directories
672stat() each entry. 699while avoiding to stat() each entry.
673 700
674If the system returns type information in readdir, then this is used 701If the system returns type information in readdir, then this is used
675to find directories directly. Otherwise, likely directories are files 702to find directories directly. Otherwise, likely directories are names
676beginning with ".", or otherwise files with no dots, of which files with 703beginning with ".", or otherwise names with no dots, of which names with
677short names are tried first. 704short names are tried first.
678 705
679=item IO::AIO::READDIR_STAT_ORDER 706=item IO::AIO::READDIR_STAT_ORDER
680 707
681When this flag is set, then the names will be returned in an order 708When this flag is set, then the names will be returned in an order
… …
1084} 1111}
1085 1112
1086=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1113=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1087 1114
1088This is a rather advanced IO::AIO call, which only works on mmap(2)ed 1115This 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 1116scalars (see the C<IO::AIO::mmap> function, although it also works on data
1117scalars 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 1118scalar must only be modified in-place while an aio operation is pending on
1091pending on it). 1119it).
1092 1120
1093It calls the C<msync> function of your OS, if available, with the memory 1121It 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 1122area 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> 1123later. 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 1124is 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 1135as for C<aio_msync>, above, except for flags, which must be either
1108C<0> (which reads all pages and ensures they are instantiated) or 1136C<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 1137C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and
1110writing an octet from it, which dirties the page). 1138writing an octet from it, which dirties the page).
1111 1139
1140=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1141
1142This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1143scalars.
1144
1145It reads in all the pages of the underlying storage into memory (if any)
1146and locks them, so they are not getting swapped/paged out or removed.
1147
1148If C<$length> is undefined, then the scalar will be locked till the end.
1149
1150On systems that do not implement C<mlock>, this function returns C<-1>
1151and sets errno to C<ENOSYS>.
1152
1153Note that the corresponding C<munlock> is synchronous and is
1154documented under L<MISCELLANEOUS FUNCTIONS>.
1155
1156Example: open a file, mmap and mlock it - both will be undone when
1157C<$data> gets destroyed.
1158
1159 open my $fh, "<", $path or die "$path: $!";
1160 my $data;
1161 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1162 aio_mlock $data; # mlock in background
1163
1164=item aio_mlockall $flags, $callback->($status)
1165
1166Calls the C<mlockall> function with the given C<$flags> (a combination of
1167C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
1168
1169On systems that do not implement C<mlockall>, this function returns C<-1>
1170and sets errno to C<ENOSYS>.
1171
1172Note that the corresponding C<munlockall> is synchronous and is
1173documented under L<MISCELLANEOUS FUNCTIONS>.
1174
1175Example: asynchronously lock all current and future pages into memory.
1176
1177 aio_mlockall IO::AIO::MCL_FUTURE;
1178
1112=item aio_group $callback->(...) 1179=item aio_group $callback->(...)
1113 1180
1114This is a very special aio request: Instead of doing something, it is a 1181This 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 1182container for other aio requests, which is useful if you want to bundle
1116many requests into a single, composite, request with a definite callback 1183many requests into a single, composite, request with a definite callback
… …
1339 1406
1340See C<poll_cb> for an example. 1407See C<poll_cb> for an example.
1341 1408
1342=item IO::AIO::poll_cb 1409=item IO::AIO::poll_cb
1343 1410
1344Process some outstanding events on the result pipe. You have to call this 1411Process some outstanding events on the result pipe. You have to call
1345regularly. Returns C<0> if all events could be processed, or C<-1> if it 1412this regularly. Returns C<0> if all events could be processed (or there
1346returned earlier for whatever reason. Returns immediately when no events 1413were no events to process), or C<-1> if it returned earlier for whatever
1347are outstanding. The amount of events processed depends on the settings of 1414reason. Returns immediately when no events are outstanding. The amount of
1348C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>. 1415events processed depends on the settings of C<IO::AIO::max_poll_req> and
1416C<IO::AIO::max_poll_time>.
1349 1417
1350If not all requests were processed for whatever reason, the filehandle 1418If not all requests were processed for whatever reason, the filehandle
1351will still be ready when C<poll_cb> returns, so normally you don't have to 1419will still be ready when C<poll_cb> returns, so normally you don't have to
1352do anything special to have it called later. 1420do anything special to have it called later.
1421
1422Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
1423ready, it can be beneficial to call this function from loops which submit
1424a lot of requests, to make sure the results get processed when they become
1425available and not just when the loop is finished and the event loop takes
1426over again. This function returns very fast when there are no outstanding
1427requests.
1353 1428
1354Example: Install an Event watcher that automatically calls 1429Example: Install an Event watcher that automatically calls
1355IO::AIO::poll_cb with high priority (more examples can be found in the 1430IO::AIO::poll_cb with high priority (more examples can be found in the
1356SYNOPSIS section, at the top of this document): 1431SYNOPSIS section, at the top of this document):
1357 1432
… …
1459 1534
1460Under normal circumstances you don't need to call this function. 1535Under normal circumstances you don't need to call this function.
1461 1536
1462=item IO::AIO::max_idle $nthreads 1537=item IO::AIO::max_idle $nthreads
1463 1538
1464Limit the number of threads (default: 4) that are allowed to idle (i.e., 1539Limit the number of threads (default: 4) that are allowed to idle
1465threads that did not get a request to process within 10 seconds). That 1540(i.e., threads that did not get a request to process within the idle
1466means if a thread becomes idle while C<$nthreads> other threads are also 1541timeout (default: 10 seconds). That means if a thread becomes idle while
1467idle, it will free its resources and exit. 1542C<$nthreads> other threads are also idle, it will free its resources and
1543exit.
1468 1544
1469This is useful when you allow a large number of threads (e.g. 100 or 1000) 1545This is useful when you allow a large number of threads (e.g. 100 or 1000)
1470to allow for extremely high load situations, but want to free resources 1546to allow for extremely high load situations, but want to free resources
1471under normal circumstances (1000 threads can easily consume 30MB of RAM). 1547under normal circumstances (1000 threads can easily consume 30MB of RAM).
1472 1548
1473The default is probably ok in most situations, especially if thread 1549The default is probably ok in most situations, especially if thread
1474creation is fast. If thread creation is very slow on your system you might 1550creation is fast. If thread creation is very slow on your system you might
1475want to use larger values. 1551want to use larger values.
1552
1553=item IO::AIO::idle_timeout $seconds
1554
1555Sets the minimum idle timeout (default 10) after which worker threads are
1556allowed to exit. SEe C<IO::AIO::max_idle>.
1476 1557
1477=item IO::AIO::max_outstanding $maxreqs 1558=item IO::AIO::max_outstanding $maxreqs
1478 1559
1479This is a very bad function to use in interactive programs because it 1560This is a very bad function to use in interactive programs because it
1480blocks, and a bad way to reduce concurrency because it is inexact: Better 1561blocks, and a bad way to reduce concurrency because it is inexact: Better
… …
1536 1617
1537Returns the number of bytes copied, or C<-1> on error. 1618Returns the number of bytes copied, or C<-1> on error.
1538 1619
1539=item IO::AIO::fadvise $fh, $offset, $len, $advice 1620=item IO::AIO::fadvise $fh, $offset, $len, $advice
1540 1621
1541Simply calls the C<posix_fadvise> function (see it's 1622Simply calls the C<posix_fadvise> function (see its
1542manpage for details). The following advice constants are 1623manpage for details). The following advice constants are
1543avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>, 1624avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
1544C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>, 1625C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
1545C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. 1626C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1546 1627
1547On systems that do not implement C<posix_fadvise>, this function returns 1628On systems that do not implement C<posix_fadvise>, this function returns
1548ENOSYS, otherwise the return value of C<posix_fadvise>. 1629ENOSYS, otherwise the return value of C<posix_fadvise>.
1549 1630
1550=item IO::AIO::mlockall $flags 1631=item IO::AIO::madvise $scalar, $offset, $len, $advice
1551 1632
1552Calls the C<mlockall> function with the given C<$flags> (a combination of 1633Simply calls the C<posix_madvise> function (see its
1553C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>). 1634manpage for details). The following advice constants are
1635avaiable: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
1636C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>.
1554 1637
1638On systems that do not implement C<posix_madvise>, this function returns
1639ENOSYS, otherwise the return value of C<posix_madvise>.
1640
1641=item IO::AIO::mprotect $scalar, $offset, $len, $protect
1642
1643Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
1644$scalar (see its manpage for details). The following protect
1645constants are avaiable: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
1646C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
1647
1555On systems that do not implement C<mlockall>, this function returns 1648On systems that do not implement C<mprotect>, this function returns
1556ENOSYS, otherwise the return value of C<mlockall>. 1649ENOSYS, otherwise the return value of C<mprotect>.
1650
1651=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1652
1653Memory-maps a file (or anonymous memory range) and attaches it to the
1654given C<$scalar>, which will act like a string scalar.
1655
1656The only operations allowed on the scalar are C<substr>/C<vec> that don't
1657change the string length, and most read-only operations such as copying it
1658or searching it with regexes and so on.
1659
1660Anything else is unsafe and will, at best, result in memory leaks.
1661
1662The memory map associated with the C<$scalar> is automatically removed
1663when the C<$scalar> is destroyed, or when the C<IO::AIO::mmap> or
1664C<IO::AIO::munmap> functions are called.
1665
1666This calls the C<mmap>(2) function internally. See your system's manual
1667page for details on the C<$length>, C<$prot> and C<$flags> parameters.
1668
1669The C<$length> must be larger than zero and smaller than the actual
1670filesize.
1671
1672C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>,
1673C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>,
1674
1675C<$flags> can be a combination of C<IO::AIO::MAP_SHARED> or
1676C<IO::AIO::MAP_PRIVATE>, or a number of system-specific flags (when
1677not available, the are defined as 0): C<IO::AIO::MAP_ANONYMOUS>
1678(which is set to C<MAP_ANON> if your system only provides this
1679constant), C<IO::AIO::MAP_HUGETLB>, C<IO::AIO::MAP_LOCKED>,
1680C<IO::AIO::MAP_NORESERVE>, C<IO::AIO::MAP_POPULATE> or
1681C<IO::AIO::MAP_NONBLOCK>
1682
1683If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
1684
1685C<$offset> is the offset from the start of the file - it generally must be
1686a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
1687
1688Example:
1689
1690 use Digest::MD5;
1691 use IO::AIO;
1692
1693 open my $fh, "<verybigfile"
1694 or die "$!";
1695
1696 IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
1697 or die "verybigfile: $!";
1698
1699 my $fast_md5 = md5 $data;
1700
1701=item IO::AIO::munmap $scalar
1702
1703Removes a previous mmap and undefines the C<$scalar>.
1704
1705=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
1706
1707Calls the C<munlock> function, undoing the effects of a previous
1708C<aio_mlock> call (see its description for details).
1557 1709
1558=item IO::AIO::munlockall 1710=item IO::AIO::munlockall
1559 1711
1560Calls the C<munlockall> function. 1712Calls the C<munlockall> function.
1561 1713

Diff Legend

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