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. Optionally caches shared memory reads in process memory, and defeatably verifies writes by reading the value back and comparing it stringwise.
TODO
- 1. Document _init interface and _fresh interface
- 2. Trap thread creation and wipe ObjCache/ObjOwner
- 3. Complete API documentation
- 4. Add portability documentation
- 5. Change valid to is_valid
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.
$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.
$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.
$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.
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->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->fetch();
Fetch a previously stored value. If a subclass defines a _fresh method, it will be called only when the shared memory value is changed by another process. If nothing has been stored yet, undef is returned.
$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.