view release on metacpan or  search on metacpan

Mmap.pm  view on Meta::CPAN

Sys::Mmap - uses mmap to map in a file as a Perl variable

=head1 SYNOPSIS

    use Sys::Mmap;

    Sys::Mmap->new( my $str, 8192, 'structtest2.pl' ) or die $!;
    Sys::Mmap->new( $var, 8192 ) or die $!;

    mmap( $foo, 0, PROT_READ, MAP_SHARED, FILEHANDLE ) or die "mmap: $!";
    @tags = $foo =~ /<(.*?)>/g;
    munmap($foo) or die "munmap: $!";

    mmap( $bar, 8192, PROT_READ | PROT_WRITE, MAP_SHARED, FILEHANDLE );
    substr( $bar, 1024, 11 ) = "Hello world";

    mmap( $baz, 8192, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANON, STDOUT );

    $addr = mmap( $baz, 8192, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANON, STDOUT );
    Sys::Mmap::hardwire( $qux, $addr, 8192 );

=head1 DESCRIPTION

The Sys::Mmap module uses the POSIX L<mmap|https://en.wikipedia.org/wiki/Mmap> call
to map in a file as a Perl variable.  Memory access by mmap may be shared
between threads or forked processes, and may be a disc file that has been
mapped into memory.  L<Sys::Mmap> depends on your operating system supporting
UNIX or POSIX.1b mmap, of course.

B<Note> that L<PerlIO> now defines a C<:mmap> tag and presents mmap'd files as
regular files, if that is your cup of joe.

Several processes may share one copy of the file or string, saving memory, and
concurrently making changes to portions of the file or string. When not used
with a file, it is an alternative to SysV shared memory. Unlike SysV shared
memory, there are no arbitrary size limits on the shared memory area, and
sparse memory usage is handled optimally on most modern UNIX implementations.

Using the C<new()> method provides a C<tie()>'d interface to C<mmap()> that
allows you to use the variable as a normal variable. If a filename is provided,
the file is opened and mapped in. If the file is smaller than the length
provided, the file is grown to that length.  If no filename is provided,
anonymous shared inheritable memory is used. Assigning to the variable will
replace a section in the file corresponding to the length of the variable,
leaving the remainder of the file intact and unmodified. Using C<substr()>
allows you to access the file at an offset, and does not place any requirements
on the length argument to C<substr()> or the length of the variable being
inserted, provided it does not exceed the length of the memory region. This
protects you from the pathological cases involved in using C<mmap()> directly,
documented below.

When calling C<mmap()> or C<hardwire()> directly, you need to be careful how
you use the variable. Some programming constructs may create copies of a string
which, while unimportant for smallish strings, are far less welcome if you're
mapping in a file which is a few gigabytes big. If you use C<PROT_WRITE> and
attempt to write to the file via the variable you need to be even more careful.
One of the few ways in which you can safely write to the string in-place is by
using C<substr()> as an lvalue and ensuring that the part of the string that
you replace is exactly the same length.  Other functions will allocate other
storage for the variable, and it will no longer overlay the mapped in file.

=over 4

=item Sys::Mmap->new( C<VARIABLE>, C<LENGTH>, C<OPTIONALFILENAME> )

Maps C<LENGTH> bytes of (the contents of) C<OPTIONALFILENAME> if
C<OPTIONALFILENAME> is provided, otherwise uses anonymous, shared inheritable
memory. This memory region is inherited by any C<fork()>ed children.
C<VARIABLE> will now refer to the contents of that file.  Any change to
C<VARIABLE> will make an identical change to the file.  If C<LENGTH> is zero
and a file is specified, the current length of the file will be used.  (Note:
the tied interface does not support C<OFFSET>, so this always maps the full
file.)  If
C<LENGTH> is larger then the file, and C<OPTIONALFILENAME> is provided, the
file is grown to that length before being mapped.  This is the preferred
interface, as it requires much less caution in handling the variable.
C<VARIABLE> will be tied into the "Sys::Mmap" package, and C<mmap()> will be
called for you.

Assigning to C<VARIABLE> will overwrite the beginning of the file for a length
of the value being assigned in. The rest of the file or memory region after
that point will be left intact.  You may use C<substr()> to assign at a given
position:

    substr(VARIABLE, POSITION, LENGTH) = NEWVALUE

=item mmap(VARIABLE, LENGTH, PROTECTION, FLAGS, FILEHANDLE, OFFSET)

Maps C<LENGTH> bytes of (the underlying contents of) C<FILEHANDLE> into your
address space, starting at offset C<OFFSET> and makes C<VARIABLE> refer to that
memory. The C<OFFSET> argument can be omitted in which case it defaults to
zero. The C<LENGTH> argument can be zero in which case a stat is done on
C<FILEHANDLE> and the file size is used to infer the mapping length.  If
C<OFFSET> is also specified, the inferred length is C<file_size - OFFSET>
(i.e. the remainder of the file from C<OFFSET> onward).  An exception is
thrown if C<OFFSET> is at or beyond the end of the file.

B<Caveat>: the underlying C<mmap()> system call requires the offset to be a
multiple of the system page size (typically 4096 bytes).  Sys::Mmap handles
non-page-aligned offsets internally by adjusting the mapping, but very large
non-aligned offsets may map slightly more memory than the requested region.

The C<PROTECTION> argument should be some ORed combination of the constants
C<PROT_READ>, C<PROT_WRITE> and C<PROT_EXEC>, or else C<PROT_NONE>. The
constants C<PROT_EXEC> and C<PROT_NONE> are unlikely to be useful here but are
included for completeness.

The C<FLAGS> argument must include either C<MAP_SHARED> or C<MAP_PRIVATE> (the
latter is unlikely to be useful here).  If your platform supports it, you may
also use C<MAP_ANON> or C<MAP_ANONYMOUS>.  If your platform supplies
C<MAP_FILE> as a non-zero constant (necessarily non-POSIX) then you should also
include that in C<FLAGS>.  POSIX.1b does not specify C<MAP_FILE> as a C<FLAG>
argument and most if not all versions of Unix have C<MAP_FILE> as zero.

mmap returns C<undef> on failure, and the address in memory where the variable
was mapped to on success.

=item munmap(VARIABLE)

Unmaps the part of your address space which was previously mapped in with a