NAME

Win32::MMF::Shareable - tied variable interface to MMF

SYNOPSIS

use Win32::MMF::Shareable;

my $ns = tie my $s1, "Win32::MMF::Shareable", "varid";
tie my @a1, "Win32::MMF::Shareable", "array";
$s1 = 'Hello world';
@a1 = ( A => 1, B => 2, C => 3 );

tie my $s2, "Win32::MMF::Shareable", "varid";
tie my @a1, "Win32::MMF::Shareable", "array";
print "$s2\n";
print "@a1\n";

ABSTRACT

This module provides a tied variable interface to the Win32::MMF module. It is part of the Win32::MMF package.

The current version 0.09 of Win32::MMF is available on CPAN at:

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

DESCRIPTION

The Win32::MMF::Shareable module is modelled after IPC::Shareable. All options from IPC::Shareable can be used in Win32::MMF::Shareable, although they are mostly ignored except for the 'label' argument. Because memory and variable management are managed internally by the Win32::MMF module, you do not need to specify how much memory is required by the variable.

All access to tied variables are automatically and exclusively locked to preserve data integrity across multiple processes.

Win32::MMF::Shareable mimics the operation of IPC::Shareable, it allows you to tie a variable to a namespace (shared memory) making it easy to share its content with other Perl processes.

Note that if you try to tie a variable without specifying the namespace, the default namespace 'shareable' will be used. If you want to change how the default namespace is created, provide the namespace, swapfile and size options when you tie the first variable.

use Win32::MMF::Shareable;
tie $scalar, "Win32::MMF::Shareable", "var_1",
             { namespace = 'MyNamespace', size = 1024 * 1024,
               swapfile = 'C:\private.swp' };

The options are exactly the same as the Win32::MMF constructor options. For compatibility with IPC::Shareable, you can pass in IPC::Shareable options, although they mostly get ignored, except for the 'key' option.

An alternative is to provide these options when the Win32::MMF::Shareable module is imported:

use Win32::MMF::Shareable { namespace = 'MyNamespace',
                            size = 1024 * 1024,
                            swapfile = 'C:\private.swp' };
tie $scalar,"Win32::MMF::Shareable", "var_1";

Currently only scalars, arrays, and hashes can be tied, I am investigating on the possibilities with tied file handles at the moment.

To tie a variable to the default namespace:

tie $scalar, "Win32::MMF::Shareable", "var_1";
tie @array,  "Win32::MMF::Shareable", "var_2";
tie %hash,   "Win32::MMF::Shareable", "var_3";

And to use a tied variable:

$scalar = 'Hello Perl';

@array = qw/ A B C D E F G /;

%hash = @array;

REFERENCE

Initialization

There are two ways to initialize an MMF namespace to be used in tied mode.

# Method 1 - when importing the module
use Win32::MMF::Shareable { namespace = 'MyNamespace',
                            size = 1024 * 1024,
                            swapfile = 'C:\private.swp' };

# Method 2 - initialization upon first use
use Win32::MMF::Shareable;
tie $scalar, "Win32::MMF::Shareable", "var_1",
             { namespace = 'MyNamespace', size = 1024 * 1024,
               swapfile = 'C:\private.swp' };

The options are exactly the same as those for the Win32::MMF constructor, although you can pass in IPC::Shareable options as well, making it easy to port IPC::Shareable

Locking

All read and write accesses to a tied variable are locked by default. Additional level of locking can be performed to protect critical part of the code.

my $ns = tie $scalar, "Win32::MMF::Shareable", "var_1";
...

$ns->lock();
$scalar = 'some string';
$ns->unlock();

Debugging

There is a built-in method debug that will display as much information as possible for a given tied object.

my $ns = tie $scalar, "Win32::MMF::Shareable", "var_1";
...

$ns->debug();

Limitations

Currently only scalar, list and hash can be tied and modified correctly. You can tie a scalar reference too, but the elements that the scalar reference is pointing to can not be modified by a direct assignment. The way to get around it is to make a local copy of the tied reference, modify the local copy, and then assign the modified local copy back to the reference.

tie $ref, "Win32::MMF::Shareable", "var_1";
$ref = [ 'A', 'B', 'C' ];

push @$ref, 'D';       # this does not work

@list = @$ref;
push @list, 'D';
$ref = \@list;         # this works

SEE ALSO

Win32::MMF

CREDITS

Credits go to my wife Jenny and son Albert, and I love them forever.

AUTHOR

Roger Lee <roger@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2004 Roger Lee

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Win32::MMF

perl -MCPAN -e shell
install Win32::MMF