SharedMemoryParcel
in package
implements
Parcel
uses
ForbidCloning, ForbidSerialization
A container object for sharing a value across contexts.
A shared object is a container that stores an object inside shared memory. The object can be accessed and mutated by any thread or process. Create a new parcel using self::create() within the owner process.
The shared object itself is not serializable and therefore cannot be sent to another process or thread. Send the integer returned from self::getKey() to the other process and open the parcel using self::use().
Because each shared object uses its own shared memory segment, it is much more efficient to store a larger object containing many values inside a single shared container than to use many small shared containers. The Serializer interface provided to this object provides a variety of strategies for storing data in shared memory and can be used to serialize data for consumption by programs written in languages other than PHP.
Tags
Table of Contents
Interfaces
Constants
- MAX_ID = 0x7fffffff
- MEM_DATA_OFFSET = 7
- STATE_ALLOCATED = 1
- STATE_MOVED = 2
- STATE_UNALLOCATED = 0
Properties
- $handle : Shmop
- $initializer : int
- $key : int
- $mutex : Mutex
- $nextId : int
- $serializer : Serializer
Methods
- __destruct() : mixed
- Frees the shared object from memory.
- __serialize() : never
- __unserialize() : never
- create() : self
- getKey() : int
- synchronized() : R
- Invokes a callback while maintaining a lock on the parcel. The current value of the parcel is provided as the first argument to the callback function. The return value of the callback is stored as the new value of the parcel.
- unwrap() : T
- use() : self
- __clone() : mixed
- __construct() : mixed
- createSegment() : Shmop}
- Opens a shared memory handle.
- deleteSegment() : void
- Requests the shared memory segment to be deleted.
- generateHeader() : string
- getValue() : mixed
- init() : void
- isFreed() : bool
- Checks if the object has been freed.
- open() : void
- readHeader() : array{state: int, size: int, permissions: int}
- Reads and returns the data header at the current memory segment. If the memory has been moved, this method updates the current memory segment handle, handling any moves made on the data.
- readSegment() : string
- Reads binary data from shared memory.
- wrap() : void
- If the value requires more memory to store than currently allocated, a new shared memory segment will be allocated with a larger size to store the value in. The previous memory segment will be cleaned up and marked for deletion. Other processes and threads will be notified of the new memory segment on the next read attempt. Once all running processes and threads disconnect from the old segment, it will be freed by the OS.
- writeSegment() : void
- Writes binary data to shared memory.
Constants
MAX_ID
private
mixed
MAX_ID
= 0x7fffffff
MEM_DATA_OFFSET
private
int
MEM_DATA_OFFSET
= 7
The byte offset to the start of the object data in memory.
STATE_ALLOCATED
private
mixed
STATE_ALLOCATED
= 1
STATE_MOVED
private
mixed
STATE_MOVED
= 2
STATE_UNALLOCATED
private
mixed
STATE_UNALLOCATED
= 0
Properties
$handle
private
Shmop
$handle
= null
An open handle to the shared memory segment.
$initializer
private
int
$initializer
= 0
$key
private
int
$key
$mutex read-only
private
Mutex
$mutex
$nextId
private
static int
$nextId
= 0
$serializer read-only
private
Serializer
$serializer
Methods
__destruct()
Frees the shared object from memory.
public
__destruct() : mixed
The memory containing the shared value will be invalidated. When all process disconnect from the object, the shared memory block will be destroyed by the OS.
__serialize()
public
final __serialize() : never
Return values
never__unserialize()
public
final __unserialize(array<string|int, mixed> $data) : never
Parameters
- $data : array<string|int, mixed>
Return values
nevercreate()
public
static create(Mutex $mutex, mixed $value[, int $size = 8192 ][, int $permissions = 0600 ][, Serializer|null $serializer = null ]) : self
Parameters
- $mutex : Mutex
-
Mutex to control access to the shared memory. Recommended: Single lock PosixSemaphore wrapped in an instance of SemaphoreMutex.
- $value : mixed
- $size : int = 8192
-
The initial size in bytes of the shared memory segment. It will automatically be expanded as necessary.
- $permissions : int = 0600
-
Permissions to access the semaphore. Use file permission format specified as 0xxx.
- $serializer : Serializer|null = null
Tags
Return values
selfgetKey()
public
getKey() : int
Return values
intsynchronized()
Invokes a callback while maintaining a lock on the parcel. The current value of the parcel is provided as the first argument to the callback function. The return value of the callback is stored as the new value of the parcel.
public
synchronized(Closure $closure) : R
Parameters
- $closure : Closure
-
The closure to invoke when a lock is obtained on the parcel. The parcel value is given as the single argument to the closure. The return value is stored as the new parcel value.
Return values
R —The value of the parcel after the closure was invoked.
unwrap()
public
unwrap() : T
Return values
T —The value inside the parcel.
use()
public
static use(Mutex $mutex, int $key[, Serializer|null $serializer = null ]) : self
Parameters
- $mutex : Mutex
- $key : int
-
Use getKey() on the creating process and send this key to another process.
- $serializer : Serializer|null = null
Tags
Return values
self__clone()
protected
final __clone() : mixed
__construct()
private
__construct(int $key, Mutex $mutex[, Serializer|null $serializer = null ]) : mixed
Parameters
- $key : int
-
The shared memory segment key.
- $mutex : Mutex
-
A mutex for synchronizing on the parcel.
- $serializer : Serializer|null = null
createSegment()
Opens a shared memory handle.
private
static createSegment(int $permissions, int $size) : Shmop}
Parameters
- $permissions : int
-
Process permissions on the shared memory.
- $size : int
-
The size to crate the shared memory in bytes.
Tags
Return values
Shmop}deleteSegment()
Requests the shared memory segment to be deleted.
private
deleteSegment() : void
Tags
generateHeader()
private
static generateHeader(int $state, int $size, int $permissions) : string
Parameters
- $state : int
-
An object state.
- $size : int
-
The size of the stored data, or other value.
- $permissions : int
-
The permissions mask on the memory segment.
Return values
stringgetValue()
private
getValue() : mixed
Tags
init()
private
init(mixed $value[, int $size = 8192 ][, int $permissions = 0600 ]) : void
Parameters
- $value : mixed
- $size : int = 8192
- $permissions : int = 0600
Tags
isFreed()
Checks if the object has been freed.
private
isFreed() : bool
Note that this does not check if the object has been destroyed; it only checks if this handle has freed its reference to the object.
Return values
bool —True if the object is freed, otherwise false.
open()
private
open() : void
readHeader()
Reads and returns the data header at the current memory segment. If the memory has been moved, this method updates the current memory segment handle, handling any moves made on the data.
private
readHeader() : array{state: int, size: int, permissions: int}
Tags
Return values
array{state: int, size: int, permissions: int} —An associative array of header data.
readSegment()
Reads binary data from shared memory.
private
readSegment(int $offset, int $size) : string
Parameters
- $offset : int
-
The offset to read from.
- $size : int
-
The number of bytes to read.
Tags
Return values
string —The binary data at the given offset.
wrap()
If the value requires more memory to store than currently allocated, a new shared memory segment will be allocated with a larger size to store the value in. The previous memory segment will be cleaned up and marked for deletion. Other processes and threads will be notified of the new memory segment on the next read attempt. Once all running processes and threads disconnect from the old segment, it will be freed by the OS.
private
wrap(mixed $value) : void
Parameters
- $value : mixed
writeSegment()
Writes binary data to shared memory.
private
writeSegment(string $data) : void
Parameters
- $data : string
-
The binary data to write.