SUMMARY: CONSTR | METHOD DETAIL: CONSTR | METHOD

Class IPC::Mmap

Known Subclasses:
IPC::Mmap::POSIX
IPC::Mmap::Win32

Provides a minimal interface to POSIX mmap(), and its Win32 equivalent. Abstract base class that is used by the IPC::Mmap::POSIX and IPC::Mmap::Win32 implementations.

Permission is granted to use this software under the same terms as Perl itself. Refer to the Perl Artistic License for details.

Author:
D. Arnold
Version:
0.11
Since:
2006-05-01

Unless otherwise noted, $self is the object instance variable.

Exported Symbols
MAP_SHAREDpermit the mmap'd area to be shared with other processes
MAP_PRIVATEdo not permit the mmap'ed area to be shared with other processes
MAP_ANONdo not use a backing file
MAP_ANONYMOUSsame as MAP_ANON
MAP_FILEuse a backing file for the memory mapped area
PROT_READpermit read access to the mmap'ed area
PROT_WRITEpermit write access to the mmap'ed area

Constructor Summary
new($filename, $length, $protflags, $mmapflags)
          Maps the specified number of bytes of the specified file into the current process's address space

Method Summary
getAddress()
          Get the base address to which the mmap'ed region was mapped
getFileHandle()
          Get the filehandle for the mmap'ed file
getFilename()
          Get the filename (or namespace on Win32) for the mmap'ed file
getLength()
          Get the length of the mmap'ed region
lock()
          Locks the mmap'ed region
pack($offset, $packstr, @values)
          Packs a list of values according to the specified pack string, and writes the binary result to the mmap'ed region at specified offset
read($data, $offset, $length)
          Reads data from a specific area of the mmap()'ed file
unlock()
          Unlock the mmap'ed region
unpack($offset, $length, $packstr)
          Read the specified number of bytes starting at the specified offset and unpack into Perl scalars using the specified pack() string
write($data, $offset, $length)
          Write data to the mmap()'ed region

Constructor Details

new

new($filename, $length, $protflags, $mmapflags)

Maps the specified number of bytes of the specified file into the current process's address space. Read/write access protection (default is read-only), and mmap() control flags may be specified (default is MAP_SHARED). If no length is given, maps the file's current length.

The specified file will be created if needed, and openned in an access mode that is compatible with the specified access protection. If the size of the file is less than the specified length, and the access flags include write access, the file will be extended with NUL characters to the specified length.

Note that for Win32, the specified file is used as a "namespace", rather than physical file, if an "anonymous" mmap() is requested.

On POSIX platforms, an anonymous, private shared memory region can be created (to be inherited by any fork()'ed child processes) by using a zero-length filename, and "private" (MAP_PRIVATE) mmap() flags.

On Win32 platforms, the default behavior is to create a "namespace", and use the Windows swap file for the backing file. However, by including MAP_FILE in the mmap() flags parameter, the specified file will be opened and/or created, and used for the backing file, rather than the system swap file.

Parameters:
$filename - name of file (or namespace) to be mapped
$length - optional number of bytes to be mapped
$protflags - optional read/write access flags
$mmapflags - optional mmap() control flags
Returns:
the IPC::Mmap object on success; undef on failure

Method Details

getAddress

getAddress()

Get the base address to which the mmap'ed region was mapped.

Returns:
the address of the mmap()ed region.

getFileHandle

getFileHandle()

Get the filehandle for the mmap'ed file. If MAP_ANON was specified for POSIX platforms, or MAP_FILE was not specified on Win32 platforms, returns undef.

Returns:
the file handle used for the mmap'ed file.

getFilename

getFilename()

Get the filename (or namespace on Win32) for the mmap'ed file.

Returns:
the mmap'ed filename.

getLength

getLength()

Get the length of the mmap'ed region

Returns:
the length of the mmap()ed region.

lock

lock()

Locks the mmap'ed region. Pure virtual function to be implemented in the OS-specific implementation subclass.


pack

pack($offset, $packstr, @values)

Packs a list of values according to the specified pack string, and writes the binary result to the mmap'ed region at specified offset. If the offset plus the packed data length extends beyond the end of the region, only the available number of bytes will be written.

Parameters:
$offset - offset to write the packed data
$packstr - pack string to be applied to the data
@values - list of values to pack and write
Returns:
undef if $offset is beyond the end of the mmap'ed region; otherwise, the total number of bytes written

read

read($data, $offset, $length)

Reads data from a specific area of the mmap()'ed file.

Parameters:
$data - scalar to receive the data
$offset - optional offset into mmap'ed area; default is zero
$length - optional length to read; default is from the offset to the end of the file
Returns:
the number of bytes actually read on success; undef on failure

unlock

unlock()

Unlock the mmap'ed region. Pure virtual function to be implemented in the OS-specific implementation subclass.


unpack

unpack($offset, $length, $packstr)

Read the specified number of bytes starting at the specified offset and unpack into Perl scalars using the specified pack() string.

Parameters:
$offset - offset to start reading from
$length - number of bytes to read
$packstr - pack string to apply to the read data
Returns:
on success, the list of unpacked values; undef on failure

write

write($data, $offset, $length)

Write data to the mmap()'ed region. Writes the specified number of bytes of the specified scalar variable to the mmap'ed region starting at the specified offset. If not specified, offset defaults to zero, and length> defaults to the length of the scalar. If the specified length exceeds the available length of the mmap'ed region starting from the offset, only the available region length will be written.

Parameters:
$data - the data to be written
$offset - optional offset where the data should be written; default is zero
$length - optional length of the data to write; default is the length of the data
Returns:
on success, returns the actual number of bytes written; returns undef if the offset exceeds the length of the region

Generated by psichedoc on Wed May 3 07:40:42 2006