The WebAbility® Network Developers - Documentation
WebAbility Site
\core\WASHM shared memory wrapper library

I. Structure:


- namespace:
\core\

- Direct superclass:
\core\WADebug

- Direct known subclasses:
none

II. Description:


This is the class to manage the shared memory.

You can have more than one shared memory segment, each segment is pointed by a unique ID. To work with more than 1 segment, create an instance for each segment you need.

$SHM1 = new WASHM(1024, 1); // shared segment 1, 1K space
$SHM2 = new WASHM(2048, 5); // shared segment 2, 2K space
$SHM3 = new WASHM(2048, 6, 'c'); // on version 3: shared segment 3 for files cache, under project 'c', 2K space


In each segment you create, you can fix its unique ID and it maximum size.
If you pass only 2 parameters or less, the SHM library will create a variable mapper to keep track of all the data you set into the shared memory. You can keep local variables and the SHM tools will give you the size of variables and total shared memory used. In this case, the SHM is SLOW, due to the serialization/deserialization of the mapper for each access to the shared memory. So we recommend to use this mapped memory with a maximum of 20-30 variables.

As version 3, if you pass a third parameter (the "project" as described in ftok PHP function), the class will not create a variable mapper, and the SHM is used to cache filesystem files, the id's are the files path. In this case the shared memory manager is extremely fast (as fast as dealing with real files) but will prevent filesystem contention. You can use this type of shared memory for thousands of file without degradation.

To have an idea of time:

Mapped SHM with 1000 variables of 30K each one (approx 300Mb) on a monoprocesor:
write the 1000 variables into memory: 1 second.
read 10,000 times randomly the variables: 10 seconds.

File type (ftok) direct access of the same data (as of version 3):
write the 1000 variables into memory: 0.2 seconds
read 10,000 times randomly the variables: 0.2 seconds


If the shared memory segment does not exists, it will be automatically created when you create the WASHM instance.

You can write (add and modify), read and delete variables in each segment.
You also have access to control methods, like flush to clean up the memory, size to know how much free space is left and content to make scan of every variables into the shared memory.

If any error happen, a SHMError error is thrown.

You can access your variables with write, read and delete methods, but also with direct class assignation:

$SHM = new WASHM();
$SHM->a = 'value'; // will call write
print $SHM->a; // will call read
unset($SHM->a); // will call delete


The WASHM class keeps track of last read/access and write/access time of each variable into the shared memory segment.
The last read/access time is usefull to know how much a variable is used into the segment, thus can be deleted if obsolete.
The last write/access time is used to know if the memory variable is desynchronized from its source.


III. Reference:


3.1. Contructor:


\core\WASHM($size, $id, $project)
Creates the instance. It will create or connect to the specified shared memory segment pointed by $id.
  • $size: integer, the size in bytes of the shared memory to reserve when created.
  • $id: integer, the unique ID of the shared memory segment.
  • $project: string, (as of Version 3) the project to create the unique ID of the filename variable using ftok.
Caution: if you create 2 instances of the WASHM, you should use two different ids, or you will point the same segment.

3.2. Constants:

There is no constant into this class.

3.3. Attributes:

There is no attribute into this class.

3.4. Methods:


public void write($id, $val)
This method is used to add a variable to the shared memory.
  • $id: string, the variable name.
  • $val: mixed, the variable value. The value must be serializable (to consider when you save an instance into the shared memory).

public mixed read($id)
This method is used to retrieve a variable from the shared memory.
  • $id: string, the variable name.

public void delete($id)
This method is used to delete a variable from the shared memory.
  • $id: string, the variable name.

public integer lastread($id)
This method is used to retrieve the last read access to the variable.
Note: The returned value is a unix timestamp that you can format to a human readable date with date().
  • $id: string, the variable name.

public integer lastwrite($id)
This method is used to retrieve the last write access to the variable.
Note: The returned value is a unix timestamp that you can format to a human readable date with date().
  • $id: string, the variable name.

public void flush()
This method is used to empty the shared memory segment. The segment will be create again with no variables into it.

public array content()
This method is used to retrieve the shared memory content index.
Will work only on mapped SHM on version 3.
The content is an array of 'variables name' => (integer) shared memory variable ID

public array size()
This method is used to retrieve the used size of the shared memory.
Will work only on mapped SHM on version 3.
The returned value is a 3 values array:

array(
'total' => integer: total amount of shared memory,
'used' => integer: amount of reserver shared memory by variables,
'free' => integer: free shared memory available in this segment
)