/ 
Sys-Mmap-Simple-0.06
/ Sys::Mmap::Simple

NAME

Sys::Mmap::Simple - Memory mapping made simple and safe.

VERSION

Version 0.06

SYNOPSIS

use Sys::Mmap::Simple 'map_file';

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

DESCRIPTION

Sys::Mmap::Simple 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 normally never returns 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 (due to ties). Sys::Mmap::Simple is as fast as a normal string yet safe.

Simplicity

It offers a more 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. No weird constants or 6 argument functions.
It will automatically unmap the file when the scalar gets destroyed. This works correctly even in multithreaded programs.

Portability

Sys::Mmap::Simple supports both Unix 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.

map_handle $variable, *handle, $writable = 0

Use a filehandle to mmap into a variable. *handle may be filehandle or a reference to a filehandle.

map_file $variable, $filename, $writable = 0

Open a file and mmap it into a variable.

map_anonymous $variable, $length

Map an anonymous piece of memory.

sync $variable

Flush changes made to the memory map back to disk. Mappings are always flushed when unmapped, so this is usually not necessary. If your operating system supports it, the flushing will be done synchronously.

remap $variable, $new_size

Try to remap $variable 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 or even defined on other systems.

unmap $variable

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

Locking

These locking functions provide thread based locking for the mapped region. The mapped region has an internal lock and condition variable. The condional functions can only be used in a locked block. If your perl has been compiled without thread support the condition functions will not be availible, and locked will execute its block without locking.

locked { block } $variable

Perform an action while keeping a thread lock on the map. The map is accessible as $_. It will return whatever its block returns.

condition_wait { block }

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

condition_signal

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

condition_broadcast

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

DIAGNOSTICS

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

Trying to sync, remap, unmap or lock a variable that hasn't been mapped will cause an exception to be thrown.

DEPENDENCIES

This module does not have any dependencies on other modules.

BUGS AND LIMITATIONS

This is an early release. Bugs are likely. 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.

SEE ALSO

Sys::Mmap, the original Perl mmap module.
IPC::Mmap, Another mmap module.

AUTHOR

Leon Timmermans, <leont at cpan.org>

SUPPORT

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

perldoc Sys::Mmap::Simple

You can also look for information at:

COPYRIGHT AND LICENSE

Copyright 2008 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.