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