IPC::Mmap

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_SHARED` | permit the mmap'd area to be shared with other processes
`MAP_PRIVATE` | do not permit the mmap'ed area to be shared with other processes
`MAP_ANON` | do not use a backing file
`MAP_ANONYMOUS` | same as MAP_ANON
`MAP_FILE` | use a backing file for the memory mapped area
`PROT_READ` | permit read access to the mmap'ed area
`PROT_WRITE` | permit 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