| File::Map - Memory mapping made simple and safe. |
File::Map - Memory mapping made simple and safe.
Version 0.25
use File::Map 'map_file'; map_file my $map, $filename; if ($map ne "foobar") { $map =~ s/bar/quz/g; substr $map, 1024, 11, "Hello world"; }
File::Map maps files or anonymous memory into perl variables.
This module is safe yet fast. Alternatives are either fast but can cause segfaults or loose the mapping when not used correctly, or are safe but rather slow. File::Map is as fast as a normal string yet safe.
It offers a simple interface targeted at common usage patterns
substr.
File::Map supports Unix, Windows and VMS.
It has built-in support for thread synchronization.
The following functions for mapping a variable are available for exportation.
Use a filehandle to map into an lvalue. $filehandle should be a scalar filehandle. $mode uses the same format as open does (it currently accepts <, +<, > and +>). $offset and $length are byte positions in the file, and default to mapping the whole file.
Open a file and map it into an lvalue. Other than $filename, all arguments work as in map_handle.
Map an anonymous piece of memory.
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.
Unmap a variable. Note that normally this is not necessary as variables are unmapped automatically at destruction, but it is included for completeness.
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 not supported on other systems.
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.
Disable paging for this map, thus locking it in physical memory. Depending on your operating system there may be limits on pinning.
Unlock the map from physical memory.
Advise a certain memory usage pattern. This is not implemented on all operating systems, and may be a no-op. The following values for $advice are always accepted:.
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.
Specifies that the application expects to access the mapped variable in a random order.
Specifies that the application expects to access the mapped variable sequentially from start to end.
Specifies that the application expects to access the mapped variable in the near future.
Specifies that the application expects that it will not access the mapped variable in the near future.
On some systems there may be more values available, but this can not be relied on. Unknown values for $advice will cause a warning but are further ignored.
Change the memory protection of the mapping. $mode takes the same format as, but also accepts sys_map style constants.
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.
Lock $lvalue until the end of the scope. If your perl does not support threads, this will be a no-op.
Wait for block to become true. After every failed attempt, 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_handle, map_file, map_anonymous, sys_map, unmap
remap, sync, pin, unpin, advise, protect
lock_map, wait_until, notify, broadcast
PROT_NONE, PROT_READ, PROT_WRITE, PROT_EXEC, MAP_ANONYMOUS, MAP_SHARED, MAP_PRIVATE, MAP_ANON, MAP_FILE
All functions defined in this module.
In this overview %f is the name of the function that produced the error, and %e is some error from your OS.
An attempt was made to sync, remap, unmap, pin, unpin, advise or lock_map an unmapped variable.
Your OS didn't allow File::Map to do what you asked it to do for the reason specified in %e.
You tried to wait_until, notify or broadcast on an unlocked variable.
A zero length anonymous map is not possible (or in any way useful).
An attempts was made to remap a mapping that is shared among different threads, this is not possible.
You tried to to map a filehandle that has some encoding layer. This is not supported by File::Map.
Due to the way perl works internally, it's not possible to write a mapping implementation that allows direct assignment yet performs well. As a compromise, File::Map is capable of fixing up the mess if you do it nonetheless, but it will warn you that you're doing something you shouldn't. This warning is only given when use warnings 'substr' is in effect.
This warning is additional to the previous one, warning you that you're losing data. This warning is only given when use warnings 'substr' is in effect.
You gave advise an advice it didn't know. This is probably either a typo or a portability issue. This warning is only given when use warnings 'portable' is in effect.
sync flushes changes to the map to the filesystem. This obviously is of little use when you can't change the map. This warning is only given when use warnings 'io' is in effect.
Overwriting an empty map is rather nonsensical, hence a warning is given when this is tried. This warning is only given when use warnings 'substr' is in effect.
This module depends on perl 5.8 and Readonly.
On perl versions lower than 5.11.5 many string functions including substr are limited to 32bit logic, even on 64bit architectures. Effectively this means you can't use them on strings bigger than 2GB. If you are working with such large files, I strongly recommend upgrading to 5.12.
This module assumes the file is binary data and doesn't do any encoding or newline transformation for you. Most importantly this means that:
map_handle or sys_map. They will not accept a crlf filehandle as it would return a different value than reading it normally would. This can be done using open modes or binmode, see PerlIO for more information.
utf8 filehandles are not accepted, though a future version may deal wit them more gracefully.
You probably don't want to use > as a mode. This does not give you reading permissions on many architectures, resulting in segmentation faults when trying to read a variable (confusingly, it will work on some others like x86).
As any piece of software, bugs are likely to exist here. Bug reports are welcome.
Please report any bugs or feature requests to bug-file-map at rt.cpan.org, or through
the web interface at http://rt.cpan.org/NoAuth/ReportBug.html. I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.
Leon Timmermans, <leont at cpan.org>
You can find documentation for this module with the perldoc command.
perldoc File::Map
You can also look for information at:
Copyright 2008, 2009, 2010 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.
| File::Map - Memory mapping made simple and safe. |