=pod

=head1 NAME

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

=head1 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();

=head1 DESCRIPTION

Provides an object-oriented interface to either the POSIX C<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 L<tie>'d variables or
locking enforced in other modules (e.g., L<Sys::Mmap>, L<Win32::MMF>);
hence, the application is responsible for performing C<read()>'s
and C<write()>'s on the IPC::Mmap object, and calling any needed
C<lock()> and C<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 C<mmap()>'ing process's virtual
memory space, thereby permitting each process to essentially share
the same physical memory. I<Refer to the excellent "Advanced Programming
in the UNIX Environment", Stevens et al., Addison-Wesley Publisher
for a detailed reference on the POSIX implementation.>
L<IPC::Mmap> provides OS-agnostic wrappers for both the POSIX and Win32
memory mapped file capabilities.

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

=head1 METHODS

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

=head1 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.

=head1 ACKNOWLEDGEMENTS

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

=head1 SEE ALSO

L<Sys::Mmap>

L<Win32::MMF>

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

=head1 AUTHOR, COPYRIGHT, AND LICENSE

Dean Arnold L<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 L<Perl Artistic License|perlartistic> for details.

=cut