NAME

IPC::Shm::Simple - Simple data in SysV shared memory segments.

SYNOPSIS

Provides the ability to create a shared segment with or without first knowing what ipckey it will use. Caches shared memory reads in process memory, and defeatably verifies writes by reading the value back and comparing it stringwise.

Can only store string or numeric data.

OBJECT CACHING

This module caches the underlying C object, such that the process only has one attachment to the shared segment. However, the Perl objects are not cached, to facilitate timely destruction. There can be many distinct blessed references to the same shared segment. This is made transparent by storing all state information in package lexicals, not upon the object.

CONSTRUCTORS

$this->bind( ipckey, [size], [mode] );

Attach to the shared memory segment identified by ipckey, whether it exists already or not.

If a segment must be created, size and permissions may be specified as for the $this->create() call. Otherwise, the class defaults will apply.

Returns blessed reference on success, undef on failure.

Throws an exception on invalid parameters.

The segment will be unlocked even if it was just created.

$this->attach( ipckey );

Attach to the shared memory segment identified by ipckey if it exists.

Returns blessed reference on success, undef on failure.

Throws an exception on invalid parameters.

$self->ATTACH();

Called by $this-attach() > and $this-shmat() > when an uncached attachment occurs.

Must return true, otherwise the attachment is aborted.

Does nothing on its own; this is meant for subclasses to override.

$this->create( [ipckey], [segsize], [permissions] )

Create a new shared memory segment, with the given ipckey, unless it exists. Can be given IPC_PRIVATE as an ipckey to create an unkeyed segment, which is assumed if no argument is provided.

The optional parameters segsize and permissions default to $this->Size() and $this->Mode(), respectively.

Returns blessed reference on success, undef on failure.

The segment will automatically have a writelock in effect.

$this->shmat( shmid );

Attach to an existing shared memory segment by its shmid.

CLEANUP METHOD

$self->remove();

Uncaches the referenced instance, and causes the underlying shared memory segments to be removed from the operating system when DESTROYed.

Returns 1 on success, undef on failure.

DESTRUCTOR

$self->DETACH();

Called by $self-DESTROY() > on the last copy of the object.

Uncaches the referenced instance, and causes the underlying shared memory segments to be detached by the operating system.

If subclasees override this, they must call $self-SUPER::DESTROY() >.

ACCESSOR METHODS

$self->key();

Returns the ipckey assigned by the program at instantiation.

$self->shmid();

Returns the shmid assigned by the operating system at instantiation.

$self->flags();

Returns the permissions flags assigned at instantiation.

$self->length();

Returns the number of bytes currently stored in the share.

$self->serial();

Returns the serial number of the current shared memory value.

$self->top_seg_size();

Returns the total size of the top share segment, in bytes.

$self->chunk_seg_size();

Returns the size of data chunk segments, in bytes.

$self->chunk_seg_size( chunk_segment_size );

Changes the size of chunk data segments. The share must have only one allocated segment (the top segment) for this call to succeed.

$self->nconns();

Reports the number of processes connected to the share.

$self->nrefs();

Returns the current shared reference count.

$self->incref();

Increments the shared reference counter.

$self->decref();

Decrements the shared reference counter.

DATA METHODS

$self->scache();

Returns a scalar reference to the segment cache. Does not guarantee freshness, and the reference can become invalid after the next I/O operation.

$self->scache_clean();

Entirely removes the cache entry for the object.

$self->fetch();

Fetch a previously stored value.

If nothing has been stored yet, '' (the empty string) is returned.

$self->FRESH();

Invoked by fetch() when the data has been changed by another process.

$self->store( value );

Stores a string or numeric value in the shared memory segment.

INSTANCE ATTRIBUTES - I/O BEHAVIOR

$this->dwell( [seconds] );

Specifies the time-to-live of cached shared memory reads, in seconds. This only affects the case where the serial number has -not- changed.

Default: 0.

$this->verify( [boolean] );

Specifies whether to read-back and compare shared memory writes.

Expensive.

Default: 1.

PACKAGE ATTRIBUTES - SEGMENT PARAMETERS

These methods carry the default values used during instantiation.

$this->Mode( [value] );

Specifies or fetches the permissions for new segments. Default: 0660.

$this->Size( [value] );

Specifies or fetches the initial size of new shared memory segments. Default: 4096

CAVEATS

To do.

cpanm IPC::Shm::Simple

perl -MCPAN -e shell
install IPC::Shm::Simple