Sys::Mmap::Simple - Memory mapping made simple and safe.
Version 0.14
use Sys::Mmap::Simple ':MAP'; map_file my $mmap, $filename; if ($mmap ne "foobar") { $mmap =~ s/bar/quz/g; }
This module is deprecated in favor of File::Map, its use is discouraged. It's nothing more than a thin compatibility layer.
The following functions for mapping a variable are available for exportation. They all take an lvalue as their first argument, except page_size.
map_handle $lvalue, *filehandle, $mode = '<', $offset = 0, $length = -s(*handle) - $offset
Use a filehandle to mmap into an lvalue. *filehandle may be a bareword, constant, scalar expression, typeglob, or a reference to a typeglob. $mode uses the same format as open does. $offset and $length are byte positions in the file, and default to mapping the whole file.
open
map_file $lvalue, $filename, $mode = '<', $offset = 0, $length = -s($filename) - $offset
Open a file and mmap it into an lvalue. Other than $filename, all arguments work as in map_handle.
map_anonymous $lvalue, $length
Map an anonymous piece of memory.
sys_map $lvalue, $length, $protection, $flags, *filehandle, $offset = 0
Low level map operation. It accepts the same constants as mmap does (except its first argument obviously). If you don't know how mmap works you probably shouldn't be using this.
sync $lvalue, $synchronous = 1
Flush changes made to the memory map back to disk. Mappings are always flushed when unmapped, so this is usually not necessary. If $synchronous is true and your operating system supports it, the flushing will be done synchronously.
remap $lvalue, $new_size
Try to remap $lvalue to a new size. It may fail if there is not sufficient space to expand a mapping at its current location. This call is linux specific and currently not supported on other systems.
unmap $lvalue
Unmap a variable. Note that normally this is not necessary, but it is included for completeness.
pin $lvalue
Disable paging for this map, thus locking it in physical memory. Depending on your operating system there may be limits on pinning.
unpin $lvalue
Unlock the map from physical memory.
advise $lvalue, $advice
Advise a certain memory usage pattern. This is not implemented on all operating systems, and may be a no-op. $advice is a string with one of the following values.
normal
Specifies that the application has no advice to give on its behavior with respect to the mapped variable. It is the default characteristic if no advice is given.
random
Specifies that the application expects to access the mapped variable in a random order.
sequential
Specifies that the application expects to access the mapped variable sequentially from start to end.
willneed
Specifies that the application expects to access the mapped variable in the near future.
dontneed
Specifies that the application expects that it will not access the mapped variable in the near future.
These locking functions provide locking for threads for the mapped region. The mapped region has an internal lock and condition variable. The condition variable functions(wait_until, notify, broadcast) can only be used inside a locked block. If your perl has been compiled without thread support the condition functions will not be available, and locked will execute its block without locking.
wait_until
notify
broadcast
locked
locked { block } $lvalue
Perform an action while keeping a thread lock on the map. The map is accessible as $_. It will return whatever its block returns.
$_
wait_until { block }
Wait for block to become true. After every failed try, wait for a signal. It returns the value returned by the block.
This will signal to one listener that the map is available.
This will signal to all listeners that the map is available.
These constants are used for sys_map. If you think you need them your mmap manpage will explain them, but in most cases you can skip sys_map altogether.
All previously mentioned functions are available for exportation, but none are exported by default. Some functions may not be available on your OS or your version of perl as specified above. A number of tags are defined to make importation easier.
map
map_handle, map_file, map_anonymous, sys_map, unmap
extra
remap, sync, pin, unpin, advise
lock
locked, wait_until, notify, broadcast
constants
PROT_NONE, PROT_READ, PROT_WRITE, PROT_EXEC, MAP_ANONYMOUS, MAP_SHARED, MAP_PRIVATE, MAP_ANON, MAP_FILE
If you use warnings, this module will give warnings if the variable is improperly used (anything that changes its size). This can be turned off lexically by using no warnings 'substr'.
use warnings
no warnings 'substr'
If an error occurs in any of these functions, an exception will be thrown. In particular; trying to sync, remap, unmap, pin, unpin, advise or do locked a variable that hasn't been mapped will cause an exception to be thrown.
sync
remap
unmap
pin
unpin
advise
This module does not have any dependencies on non-standard modules.
You probably don't want to use > as a mode. This does not give you reading permissions on many architectures, resulting in segmentation faults (more confusingly, it will work on some others).
>
As any piece of software, bugs are likely to exist here. Bug reports are welcome.
Please report any bugs or feature requests to bug-sys-mmap-simple at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sys-Mmap-Simple. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-sys-mmap-simple at rt.cpan.org
File::Map, the successor of this module
Sys::Mmap, the original Perl mmap module
IPC::Mmap, another mmap module
mmap(2). your mmap man page
CreateFileMapping at MSDN: http://msdn.microsoft.com/en-us/library/aa366537(VS.85).aspx
Leon Timmermans, <leont at cpan.org>
<leont at cpan.org>
You can find documentation for this module with the perldoc command.
perldoc Sys::Mmap::Simple
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-Mmap-Simple
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Sys-Mmap-Simple
CPAN Ratings
http://cpanratings.perl.org/d/Sys-Mmap-Simple
Search CPAN
http://search.cpan.org/dist/Sys-Mmap-Simple
Copyright 2008, 2009 Leon Timmermans, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as perl itself.
To install Sys::Mmap::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sys::Mmap::Simple
CPAN shell
perl -MCPAN -e shell install Sys::Mmap::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.