/ 
File-Map-0.20
River stage three • 11 direct dependents • 124 total dependents
/ File::Map

NAME

File::Map - Memory mapping made simple and safe.

VERSION

Version 0.20

SYNOPSIS

use File::Map 'map_file';

map_file my $map, $filename;
if ($map ne "foobar") {
    $map =~ s/bar/quz/g;
}

DESCRIPTION

File::Map maps files or anonymous memory into perl variables.

Advantages of memory mapping

  • Unlike normal perl variables, mapped memory is shared between threads or forked processes.

  • It is an efficient way to slurp an entire file. Unlike for example File::Slurp, this module returns almost immediately, loading the pages lazily on access. This means you only 'pay' for the parts of the file you actually use.

  • Perl usually doesn't return memory to the system while running, mapped memory can be returned.

Advantages of this module over other similar modules

  • Safety and Speed

    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.

  • Simplicity

    It offers a simple interface targeted at common usage patterns

    • Files are mapped into a variable that can be read just like any other variable, and it can be written to using standard Perl techniques such as regexps and substr.

    • Files can be mapped using a set of simple functions. There is no need to know weird constants or the order of 6 arguments.

    • It will automatically unmap the file when the scalar gets destroyed. This works correctly even in multi-threaded programs.

  • Portability

    File::Map supports Unix, VMS and Windows.

  • Thread synchronization

    It has built-in support for thread synchronization.

FUNCTIONS

Mapping

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 map 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.

  • map_file $lvalue, $filename, $mode = '<', $offset = 0, $length = -s($filename) - $offset

    Open a file and map 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 map does (except its first argument obviously). If you don't know how mmap works you probably shouldn't be using this.

  • unmap $lvalue

    Unmap a variable. Note that normally this is not necessary, but it is included for completeness.

  • 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.

Auxiliary

  • 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.

  • 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. The following values for $advice are always accepted:.

    • 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.

    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.

Locking

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_map $lvalue

    Lock $lvalue until the end of the scope. If your perl does not support threads, this will be a no-op.

  • wait_until { block } $lvalue

    Wait for block to become true. After every failed attempt, wait for a signal. It returns the value returned by the block.

  • notify $lvalue

    This will signal to one listener that the map is available.

  • broadcast $lvalue

    This will signal to all listeners that the map is available.

CONSTANTS

PROT_NONE, PROT_READ, PROT_WRITE, PROT_EXEC, MAP_ANONYMOUS, MAP_SHARED, MAP_PRIVATE, MAP_ANON, MAP_FILE

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.

EXPORTS

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

    lock_map, wait_until, notify, broadcast

  • :constants

    PROT_NONE, PROT_READ, PROT_WRITE, PROT_EXEC, MAP_ANONYMOUS, MAP_SHARED, MAP_PRIVATE, MAP_ANON, MAP_FILE

DIAGNOSTICS

In this overview %f is the name of the function that produced the error, and %e is some error from your OS.

Exceptions

  • Could not %f: this variable is not memory mapped

    An attempt was made to sync, remap, unmap, pin, unpin, advise or lock_map an unmapped variable.

  • Could not %f: %e

    Your OS didn't allow File::Map to do what you asked it to do for the reason specefied in %e

  • Trying to %f on an unlocked map

    You tried to wait_until, notify or broadcast on an unlocked variable.

  • Zero length not allowed for anonymous map

    A zero length anonymous map is not possible (or in any way useful).

  • Can't map empty file writably

    Empty files can't be mapped writably, because that wouldn't make any sense whatsoever.

Warnings

  • Writing directly to a to a memory mapped file is not recommended

    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.

  • Truncating new value to size of the memory map

    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.

  • Unknown advice '%s'

    You gave advise ani 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.

  • Syncing a readonly map makes no sense

    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.

DEPENDENCIES

This module does not have any dependencies on non-standard modules.

PITFALLS

You probably don't want to use > as a mode. This does not give you reading permissions on many architectures, resulting in segmentation faults (confusingly, it will work on some others like x86).

BUGS AND LIMITATIONS

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?Queue=File-Map. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO

AUTHOR

Leon Timmermans, <leont at cpan.org>

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc File::Map

You can also look for information at:

COPYRIGHT AND LICENSE

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.