/ 
Sys-Mmap-Simple-0.03_4
/ Sys::Mmap::Simple

NAME

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

VERSION

Version 0.03

SYNOPSIS

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

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

DESCRIPTION

This module maps files to Perl variables. There are a few differences between this module and Sys::Mmap.

  • It offers a more simple interface targeted at common usage patterns: It always maps the whole file, and always does shared mapping. This seems to be what people want in almost all cases.

  • It is portable, supporting not only unix but also windows.

  • This module is safe yet fast. Sys::Mmap offers two interfaces, one is fast, but can cause segfault or loose the mapping if not used correctly. The other is safe, but reportedly 10 times slower. Sys::Mmap::Simple is fast (as long as it is used properly) and safe.

  • It will automatically unmap the file when the scalar gets destroyed.

  • 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 synced when unmapped, so this is usually not necessary.

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.

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.