Last modified: February 7,1999

• The MemMap methods

Clear()
Close()
Flush()
FlushMapView()
GetDataSize()
GetGranularitySize()
GetMapInfo()
GetMaxSeek()
GetPageSize()
GetSize()
Lock()
MapView()
OpenFile()
OpenMem()
Read()
Write()
Unlock()
UnmapView()


Bonus

InitTimer()
StartTimer()
StopTimer()

• The MemMap inteface

my $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; # For debugging purpose

#################################################################### Return to the Index

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

Read() does read 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";

#################################################################### Return to the Index

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

Write() does write 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..

#################################################################### Return to the Index

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

OpenFile() does open and/or map the $file to virtual address space of the calling process, $name is the shared memory name,

Mapping is one of the follwing 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).

Important note:

DISABLE_MAPPING will be used in a situation were 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, the return values 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(DISABLE_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;

#################################################################### Return to the Index

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

MapView() does create 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(DISABLE_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;

#################################################################### Return to the Index

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

GetMapInfo() return 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 through 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};}

Warning!

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 full shared memory size.

#################################################################### Return to the 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,the $Rest is the number of bytes that remain in the $MaxSeek+1 (page) .

#################################################################### Return to the Index

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

Lock() lock the specified $position+$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.

Important note:

This function is very powerfull,but becarefull to not misuse it or you will end up disturbing the paging mechanism of your OS and degrading the performance.

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

##################################################################### Return to the Index

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

Unlock() does unlock a previously locked region.

#################################################################### Return to the Index

$PageSize = $obj->GetPageSize()

GetPageSize() does return the size of the virtual memory page in your computer .

#################################################################### Return to the Index

$bound = GetGranularitySize()

GetGranularitySize() returns the size with wich virtual memory is allocated .

#################################################################### Return to the Index

$Size = $obj->GetSize()

GetSize() returns the size of a shared memory object

Note:

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

Warning!

GetSize() 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 full shared memory size. Please use the {Size} hash key to get the size with file mapping objects

#################################################################### Return to the Index

$Size = $obj->GetDataSize()

GetSize() returns the actual data size on a shared memory object

Note:

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

Warning!

GetDataSize() 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 full shared memory size. Please use the {File} hash key with file mapping objects.

#################################################################### Return to the 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;

#################################################################### Return to the 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;

#################################################################### Return to the Index

$obj->UnmapView()

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

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

.#################################################################### Return to the Index

MapViewProtect() will be implemented soon.

#################################################################### Return to the Index

$obj->Close()

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

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

#################################################################### Return to the Index

$obj->Clear()

Clear() does clear a shared memory..

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

#################################################################### Return to the Index

 

QueryPageInfo will be implemented soon.

#################################################################### Return to the Index

 

InitTimer() initialize your timer (to get a more accurate measure)
StartTimer() start your timer
StopTimer() stop 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;

Sincerely,
Amine Moulay Ramdane