Last modified: February 28, 2001

Description

Shared memory is very important for client-server application developers and is also the fastest mechanism by wich server developers can etablish (local) interprocess communication between the cooperating tasks of an application program, often server applications are designed as a set of processes and threads, these tasks must use some .. kind .. of .. interprocess- communication mechanisms to communicate data and coordinate processing between each other, for example: .. TCP/IP, Pipes,Shared memory etc., but shared memory is the fastest one. This object oriented Perl module will allow you to map both memory and files into virtual address space, processes or threads can gain access to . mapped memory .. via .. naming mechanism. If for example one process writes a data into a particular region of shared memory the other processes see it immediatly hence shared memory does avoid system space buffering and slow I/O operations, also shared memory will take benefit of the underlying VM paging mechanism and it will improve the memory access time ( pages hits, locked memory regions). Any data structure you want can be embeded in a shared memory area and thus made accessible to .. multiple processes. This gives you the flexibility to create any communication structure you desire, both text and binary data are supported by this module.

The MemMap interface

Clear
Close
Flush
FlushMapView
GetDataSize
GetGranularitySize
GetMapInfo
GetMaxSeek
GetPageSize
GetSize
Lock
MapView
OpenFile
OpenMem
Read
Write
Unlock
UnmapView
LastError
-------------
InitTimer
StartTimer
StopTimer

The MemMap methods

$obj=$mapobj->OpenMem($name,$size)

OpenMem Creates a shared memory, $name is the name of the shared memory to be created $size is the size of the memory in bytes.If the $size is 0 you will get an error and $obj will be undefined.

If OpenMem() fails, the return value will be undef .To get extended error information call the LastError.

Example:

use Win32::MemMap;

my $size=100000; # size in bytes
my $obj=new Win32::MemMap;
my $mem=$obj->OpenMem("//MemMap/Perl",$size);
$obj->LastError;

---

Index

$ret = $obj->Read(\$retval,$pos,$size)

Read Reads data from the shared memory, $size in bytes requested will be returned in $retval from the $pos in the shared memory, but if the value of $pos plus the $size is greater than the number of bytes in the shared memory you will get an error. On error the value of $ret will be undefined..

Example:

use Win32::MemMap;
my $mmap=new Win32::MemMap;

my $str="Perl is great!";
my $mem=$mmap->OpenMem("//MemMap/Perl",$size);
$mem->Write(\$str,0);
$mem->Read(\$str,0,$mem->GetDataSize);
print "The data is: ".$str."\n";

---

Index

$ret = $obj->Write(\$str,$pos)

Write Writes data from $pos to a shared memory, if the value of $pos plus the size of $str is greater than the size of the shared memory you will get an error. On error the value of $ret will be undefined..

---

Index

$fmapobj = $obj->OpenFile($file,$name,Mapping)

OpenFile Opens and/or maps the $file to virtual address space of the calling process, $name is the shared memory name,

Mapping is one of the following constants:

ENABLE_MAPPING will map the file to the virtual address space
DISABLE_MAPPING will open the file but will not map it to the virtual address space

The file size is returned in $FileObj->{Size} (hash key).

Remarks:

DISABLE_MAPPING will be used in a situation where the file is huge (ea: Giga files), so you have to open the file first and map/unmap small chunks at a time with MapView and UnmapView.

If the OpenFile() fails, $fmapobj will be undef.To get extended error information call LastError.

Example1: ( with ENABLE_MAPPING)

use Win32::MemMap qw(ENABLE_MAPPING DISABLE_MAPPING);

my $str;my $obj = new Win32::MemMap;
my $FileMap = $obj->OpenFile("Perlwin32.txt","//MemMap/Perl",ENABLE_MAPPING);
print "File size is: ".$FileMap->{Size}."\n";
$FileMap->Read(\$str,0,$FileMap->{Size});
print "Data is: ".$str;
undef $str; # free the local buffer
$FileMap->Close;# don't forget to close!

Example2: ( with DISABLE_MAPPING)

use Win32::MemMap qw(ENABLE_MAPPING DISABLE_MAPPING);

my $str;my $obj = new Win32::MemMap;
my $File = $obj->OpenFile("Perlwin32.txt","//MemMap/Perl",DISABLE_MAPPING);
print "File size is: ".$File->{Size}."\n";
my $FileMap = $File->MapView("//MemMap/Perl",$File->{Size},0);
$FileMap->Read(\$str,0,$FileMap->GetPageSize); # slurp one file chunk
print "Data is: ".$str;
undef $str; # free the local buffer
$FileMap->UnmapView; # mandatory!
$File->Close;

---

Index

$mapobj = $obj->MapView($name,$size,$offset)

MapView Creates a mapview of an existing shared memory or file mapping object in the virtual address space of the calling process, $name is the name of a previously created shared memory or file mapping object, $size is the size in bytes to map, $offset is the offset in number of pages. You can find the size of the virtual memory page allocation granularity by calling the GetGranularitySize.

If MapView() fails $mapobj will be undef.To get extended error information call the LastError method.

Example:

use Win32::MemMap qw(ENABLE_MAPPING DISABLE_MAPPING);

my $str;my $obj = new Win32::MemMap;
my $File = $obj->OpenFile("Perlwin32.txt","//MemMap/Perl",DISABLE_MAPPING);
print "File size is: ".$File->{Size}."\n";
my $FileMap = $File->MapView("//MemMap/Perl",$File->{Size},0);
$FileMap->Read(\$str,0,$FileMap->GetGranularitySize); # slurp one file chunk
print "Data is: ".$str;
undef $str; # free the local buffer
$FileMap->UnmapView; # mandatory!
$File->Close;

---

Index

$ret = $obj->GetMapInfo($mapname,\$Info)

GetMapInfo Returns information from a shared memory (mainly used accross process bounderies)

$mapname the name of an already existing shared memory

$Info hash reference that receive shared memory info, this information can be accessed with the following hash keys:

$Info->{Name} shared memory name
$Info->{Size} shared memory size
$Info->{DataSize} actual data size on the shared memory

If GetMapInfo() fails $ret will be undef.To get extended error information call LastError method.

Example:

use Win32::MemMap;

my $obj = new Win32::MemMap;
if($obj->GetMapInfo("//MemMap/perl",\$MapInfo)
{print "Name is: ".$MapInfo->{Name}."\n";
print "Full Size is: ".$MapInfo->{Size}."\n";
print "Actual data size is: ".$MapInfo->{DataSize};}

Remarks:

GetMapInfo() doesn't work with file mapping objects and memory mapped view size inferior to the full shared memory size, the mapped view size must be equal to the shared memory size.

---

Index

($MaxSeek,$Rest) = $obj->GetMaxSeek($size)

GetMaxSeek is passed $File->{Size} that is returned by OpenFile, the returned values are: $MaxSeek the number of pages to seek, $Rest is the number of bytes that remain in $MaxSeek+1 (page).

---

Index

$ret = $obj->Lock($position,$size)

Lock Locks the specified $size region in the process virtual address space,$position is the begining of the region and $size is the size of the region to lock,this function can be used to ensure that subsequent access to the region's pages will not incur page faults,if the function doesn't succeed $ret will be undefined.

If the Lock() fails, the return value will be undef.To get extended error information, call LastError.

Remarks:

Becarefull to not misuse this method or you will end up disturbing the paging mechanism of your OS and degrading the performance.

---

Index

$ret = $obj->Unlock($position,$size)

Unlock Unlocks a previously locked region.

---

Index

$pagesize = $obj->GetPageSize()

GetPageSize Returns the size of the virtual memory page in your computer.

---

Index

$size = GetGranularitySize()

GetGranularitySize Returns the size with wich virtual memory is allocated.

---

Index

$size = $obj->GetSize()

GetSize Returns the size of a shared memory object

Note:

GetSize() works both within the same process address space and accross processes&threads bounderies.

Remarks:

GetSize() doesn't work with file mapping objects and memory mapped view size inferior to the shared memory size, the mapped view size must be equal to the shared memory size. Please use the {Size} hash key to get the size with file mapping objects.

---

Index

$size = $obj->GetDataSize()

GetSize Returns the actual data size on a shared memory object

Note:

GetDataSize() works both within the same process address space and accross processes&threads bounderies.

Remarks:

GetDataSize() doesn't work with file mapping objects and memory mapped view size inferior to the shared memory size, the mapped view size must be equal to the shared memory size. Please use the {SIZE} hash key with file mapping objects.

---

Index

$ret = $obj->FlushMapView($offset,$size)

FlushMapView() writes to the disk a byte range within a mapped view of a file.

$offset the page offset at wich the $size bytes will be flushed to the physical disk.

$size in bytes.

If the FlushMapView() fails, the return value will be undef.To get extended error information, call LastError.

Example:

use Win32::MemMap qw(DISABLE_MAPPING DISABLE_MAPPING);

my $str="Perl is great!";
my $obj = new Win32::MemMap;
my $File = $obj->OpenFile("Perl.txt","//MemMap/Perl",DISABLE_MAPPING);
print "File size is: ".$File->{Size}."\n";
my $FileMap = $File->MapView("//MemMap/Perl",10000,0);
$FileMap->Write(\$str,0);
$FileMap->FlushMapView(0,10000);
$FileMap->UnmapView; # mandatory!
$File->Close;

---

Index

$ret = $obj->Flush()

Flush() writes to the disk all the byte range within a mapped view of a file.

If the Flush() fails, the return value will be undef.To get extended error information, call LastError.

Example:

use Win32::MemMap qw(DISABLE_MAPPING DISABLE_MAPPING);

my $str="Perl is great!";
my $obj = new Win32::MemMap;
my $FileMap = $obj->OpenFile("Perl.txt","//MemMap/Perl",ENABLE_MAPPING);
$FileMap->Write(\$str,0);
$FileMap->Flush; # Flush all the previous changes to the disk
$FileMap->Close;

---

Index

$obj->UnmapView()

UnmapView() unmaps a previously file/memory mapped view..

If the UnmapView() fails, the return value will be undef.To get extended error information call LastError.

---

Index

$obj->Close()

The Close() closes an open file or memory mapping object.

If Close() fails, the return value will be undef.To get extended error information, call LastError.

---

Index

$obj->Clear()

Clear() clears a shared memory..

If Clear() fails, the return value will be undef.To get extended error information, call LastError.

---

.Index

LastError()

LastError Prints the last error.

---

Index

InitTimer initialize your timer
StartTimer starts your timer
StopTimer Stops your timer

Those functions will be used to profile your code in high resolution (microseconds).

Example:

use Win32::MemMap;

my $obj = new Win32:MemMap;

$obj->InitTimer;
$obj->StartTimer;
select(undef,undef,undef,0.2); # time this 200ms
$obj->StopTimer;