NAME

IPC::Mmap - provides a minimal mmap() interface for both POSIX and Win32

SYNOPSIS

    use IPC::Mmap;
        #
        #       create from opened filehandle
        #
    $mmap_by_handle = IPC::Mmap->new(FILEHANDLE, 8192, PROT_READ|PROT_WRITE, MAP_SHARED)
        or die $!;
        #
        #       create from filename
        #
    $mmap_by_name = IPC::Mmap->new('somefile.dat', 8192, PROT_READ|PROT_WRITE, MAP_SHARED)
        or die $!;
        #
        #       write some data to a specific position
        #
        my $writelen = $mmap_by_name->write($value, $offset, $len);
        #
        #       read it back somewhere else
        #
        my $data;
        my $readlen = $mmap_by_handle->read($data, $offset, $len);
        #
        #       lock for before reading
        #
        $mmap_by_handle->lock();

        my $len = $mmap_by_handle->read($data, $offset, $len);

        $mmap_by_handle->unlock();
        #
        #       convenient binary pack/unpack
        #
        my $len = $mmap_by_name->pack($offset, 'lldV', $this, $this, $float, $other);

        ($this, $this, $float, $other) = $mmap_by_name->unpack($offset, 24, 'lldV');
        #
        #       when done, unmap
        #
        $mmap_from_name->unmap();

DESCRIPTION

Provides an object-oriented interface to either the POSIX mmap() or Win32 equivalent APIs to memory map a file into a process's address space for general memory access. IPC::Mmap provides only a minimal interface without the additional overhead of tie'd variables or locking enforced in other modules (e.g., Sys::Mmap, Win32::MMF); hence, the application is responsible for performing read()'s and write()'s on the IPC::Mmap object, and calling any needed lock() and unlock() methods, as required by concurrent processes.

Memory mapped files provide an alternate shared memory mechanism for multiple processes. The technique maps the OS's file system buffers for a given file into each mmap()'ing process's virtual memory space, thereby permitting each process to essentially share the same physical memory. Refer to the excellent "Advanced Programming in the UNIX Environment", Stevens et al., Addison-Wesley Publisher for a detailed reference on the POSIX implementation. IPC::Mmap provides OS-agnostic wrappers for both the POSIX and Win32 memory mapped file capabilities.

Note that PerlIO provides a :mmap layer to permit read-only access to mmap'd files as regular files.

METHODS

Refer to the included classdocs for summary and detailed method descriptions.

Constants

IPC::Mmap exports the following constants into your namespace:

    MAP_SHARED MAP_PRIVATE MAP_ANON MAP_ANONYMOUS MAP_FILE
    PROT_READ PROT_WRITE

Of the constants beginning with MAP_, only MAP_SHARED and MAP_PRIVATE are defined in POSIX.1b and only MAP_SHARED is likely to be useful.

Note that PROT_EXEC and PROT_NONE are not exported, nor supported.

These POSIX values are mapped into Win32 equivalents internally where appropriate.

ACKNOWLEDGEMENTS

Much of the POSIX XS code was borrowed from Sys::Mmap. Likewise, much of the Win32 implementation is borrowed from Win32::MMF.

SEE ALSO

Sys::Mmap

Win32::MMF

mmap(1) http://www.opengroup.org/onlinepubs/000095399/functions/mmap.html

AUTHOR, COPYRIGHT, AND LICENSE

Dean Arnold mailto:darnold@presicient.com

Copyright(C) 2006, Dean Arnold, Presicient Corp., USA. All rights reserved.

Permission is granted to use this software under the same terms as Perl itself. Refer to the Perl Artistic License for details.