NAME

Win32::MMF - Win32 Memory Mapped File (MMF) Support for Perl

SYNOPSIS

use Win32::MMF;

# --- in process 1 ---
my $ns1 = Win32::MMF->new ( -namespace => "MyData1" );

$ns1->lock();
$ns1->write($data);
$ns1->unlock();

# --- in process 2 ---
my $ns2 = Win32::MMF->new ( -namespace => "MyData1",
                            -nocreate  => 1 )
        or die "namespace not exist";

$data = $ns2->read();

ABSTRACT

This module provides Windows' native Memory Mapped File Service for shared memory support under Windows. The core of the module is written in XS and is currently supported only under Windows NT/2000/XP.

The current version 0.03 of Win32::IPC is available on CPAN at:

http://search.cpan.org/search?query=Win32::MMF

DESCRIPTION

PROGRAMMING STYLE

This module provides two types of interfaces - an object-oriented and a functional interface. The default access method is via objects. The functional interface is not exported by default because it requires a detailed knowledge of the Windows operating system internals to use properly.

There are many advantages of using the object oriented interface. For example, the following is the amount of code required in function-oriented style to create a namespace (a named block of shared memory). It involves openning or creating a swap file, creating a memory mapping and finally creating a view:

use Win32::MMF qw/ ClaimNamespace UseNamespace MapViewOfFile /;

my ($swap, $ns, $view) = (0, 0, 0);
$ns = UseNamespace("MyData1");
if (!ns) {
    ($swap, $ns) = ClaimNamespace("data.swp", "MyData1", 1000);
    die "Can not create swap file" if !$swap;
    die "Can not create namespace" if !$ns;
}

$view = MapViewOfFile($ns, 0, 1000);

...

UnmapViewOfFile($view);
ReleaseNamespace($swap, $ns);

The following is the amount of code required to achieve the same result in object-oriented style:

use Win32::MMF;

my $ns = Win32::MMF->new( -swapfile=>"data.swp",
                          -namespace=>"MyData1",
                          -size=>1000 )
    or die "Can not create shared namespace";

Note that there is no need to explicitly unmap the view and close the swap file in object-oriented mode, the view, namespace and swap file handles are automatically closed-off and disposed of when the object falls out of scope.

CREATING A NEW NAMESPACE

The parameter names are case insensitive. For example, -swapfile,
-Swapfile and -SwapFile are equivalent. 0 or undef is returned if
the constructor fails.

# named parameters
$ns = Win32::MMF->new(
           -swapfile => $swapfilename,
           -namespace => $namespace_id,
           -size => 1024,
           -nocreate => 0,
           -autolock => 1,
           -timeout => 10,
      );

# hashref of parameters
$ns = Win32::MMF->new(
         { swapfile => $swapfilename,
           namespace => $namespace_id,
           size => 1024,
           nocreate => 0 }
      );

# list of parameters
$ns = Win32::MMF->new($namespace_id, 1024, $swapfile, 0);

-swapfile

Specify the name of the swap file. if it is omitted or undef
then the system swap file will be used.

-namespace

A unique string value that identifies a namespace in the
memory mapped file. This option is mandatory.

-size

Specify the size of the namespace in bytes.

-nocreate

Do not create a new swap file if the swap file does not
exist, return undef instead. Check if the namespace has
already been declared by another process, and use the
existing namespace instead.

-autolock

Automatic read/write locking, turned on by default.

-timeout

Specify the number of seconds to wait before timing out
the lock. This value is set to 10 seconds by default. Set
timeout to 0 to wait forever.

LOCKING A NAMESPACE EXPLICITLY

$ns->lock($timeout);

$timeout

Number of seconds before the lock attempt fails.

UNLOCKING A NAMESPACE EXPLICITLY

$ns->unlock();

WRITING TO A NAMESPACE

$ns->write($data);
$ns->write_iv(1000);

READING FROM A NAMESPACE

$data = $ns->read();
$i    = $ns->read_iv();

EXAMPLE

use strict;
use warnings;
use Win32::MMF;
use Data::Dumper;
use CGI;   # for testing of inter-process object transportation

# fork a process
defined(my $pid = fork()) or die "Can not fork a child process!";

if ($pid) {
    my $ns1 = Win32::MMF->new ( -namespace => "My.data1" );
    my $ns2 = Win32::MMF->new ( -namespace => "My.data2" );

    my $cgi = new CGI;
    my $data = {a=>[1,2,3], b=>4, c=>"A\0B\0C\0"};

    $ns1->write($data);
    $ns2->write($cgi);

    print "--- Sent ---\n";
    print Dumper($data), "\n";
    print Dumper($cgi), "\n";

    sleep(1);

} else {

    # in child
    sleep(1);
    my $ns1 = Win32::MMF->new ( -namespace => "My.data1",
                                -nocreate => 1 )
            or die "Namespace does not exist!";

    my $ns2 = Win32::MMF->new ( -namespace => "My.data2",
                                -nocreate => 1 )
            or die "Namespace does not exist!";

    my $data = $ns1->read();
    my $cgi = $ns2->read();

    print "--- Received ---\n";
    print Dumper($data), "\n";
    print Dumper($cgi), "\n";

    print "--- Use Received Object ---\n";
    # use the object from another process :-)
    print $cgi->header(),
          $cgi->start_html(), "\n",
          $cgi->end_html(), "\n";
}

CREDITS

All the credits go to my wife Jenny and son Albert, and I love them forever.

AUTHOR

Roger Lee <roger@cpan.org>

cpanm Win32::MMF

perl -MCPAN -e shell
install Win32::MMF