/ 
Sys-Mmap-Simple-0.01
/ Sys::Mmap::Simple

NAME

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

VERSION

Version 0.01

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. It always maps the whole file, and always does shared mapping. This seems to be what people want in 95% of all cases.

  • This module is safe yet fast. Sys::Mmap offers two interfaces, one is fast, but can segfault 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.

FUNCTIONS

The following functions are defined and availible for exportation. All of them take an lvalue as first argument.

* map_handle($scalar, *handle, $writable)

Use a filehandle to mmap into a variable. *handle may be filehandle or a reference to a filehandle. $writable is optional and defaults to 0.

* map_file($scalar, $filename, $writable)

Open a file and mmap it into a variable. $writable is optional and defaults to 0.

* map_anonymous($scalar, $length)

Map an anonymous piece of memory.

* sync($scalar)

Flush changes made to the memory map back to disk.

* unmap($scalar)

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

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 of lexically by using no warnings 'substr'.

Trying to sync or unmap a variable that hasn't been mapped will result in an exception.

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.