warn( "Warning only: could not remove the semaphore id \"$semid\" with IPC::SysV::IPC_RMID value '", &IPC::SysV::IPC_RMID, "': $!") if( $self->_warnings_is_enabled );
return( $self->error( "No IPC::SharedMem object set. Have you opened the shared memory?") );
my$size= int( $self->size() ) || SHM_BUFSIZ;
my$packing= $self->_packing_method;
my$encoded;
if( $packingeq 'json')
{
# try-catch
local$@;
eval
{
$encoded= $self->_encode_json( $data);
};
if( $@ )
{
return( $self->error( "An error occured encoding data provided using $packing with base64 set to '", ( $self->{base64} // '' ), ": $@. Data was: '$data'" ) );
return( $self->error( "An error occured encoding data provided using $packing with base64 set to '", ( $self->{base64} // '' ), ": $@. Data was: '$data'" ) );
}
return( $self->error( "Unable to serialise ", CORE::length( $data), " bytes of data using CBOR::XS with base64 set to '", ( $self->{base64} // '' ), ": ", $self->error ) ) if( !defined( $encoded) );
return( $self->error( "An error occured encoding data provided using $packing with base64 set to '", ( $self->{base64} // '' ), ": $@. Data was: '$data'" ) );
}
return( $self->error( "Unable to serialise ", CORE::length( $data), " bytes of data using Sereal with base64 set to '", ( $self->{base64} // '' ), ": ", $self->error ) ) if( !defined( $encoded) );
return( $self->error( "An error occured encoding data provided using $packing with base64 set to '", ( $self->{base64} // '' ), ": $@. Data was: '$data'" ) );
}
return( $self->error( "Unable to serialise ", CORE::length( $data), " bytes of data using Storable with base64 set to '", ( $self->{base64} // '' ), ": ", $self->error ) ) if( !defined( $encoded) );
return( $self->error( "An error occurred while trying to decode JSON data: $@") );
}
return( $result);
}
# Purpose of this method is to recursively check the given data and change scalar reference if they are anything else than 1 or 0, otherwise JSON would complain
sub_encode_json
{
my$self= shift( @_);
my$data= shift( @_);
my$seen= {};
my$crawl;
$crawl= sub
{
my$this= shift( @_);
my$type= Scalar::Util::reftype( $this);
# Skip this reference if it is either hash or array and we have already seen it in order to avoid looping.
# I initially thought about using __FILE__, but during testing this would be in ./blib/lib and beside one user might use a version of this module somewhere while the one used under Apache/mod_perl2 could be somewhere else and this would render the generation of the IPC key unreliable and unrepeatable
# my $val = &IPC::SysV::ftok( File::Spec->rootdir(), $id );
my$val= &IPC::SysV::ftok( $path, $id);
return( $val);
}
}
subDESTROY
{
my$self= shift( @_);
returnunless( $self->{_ipc_shared} );
my$shm= $self->{_ipc_shared};
returnif( $shm->id );
$self->unlock;
$self->detach;
my$rv= $self->remove_semaphore;
if( $self->destroy )
{
my$stat= $self->shmstat();
# number of processes attached to the associated shared memory segment.
# NOTE: CBOR will call the THAW method with the stored classname as first argument, the constant string CBOR as second argument, and all values returned by FREEZE as remaining arguments.
# NOTE: Storable calls it with a blessed object it created followed with $cloning and any other arguments initially provided by STORABLE_freeze
# Data is automatically transcoded using Storable::Improved::freeze
$s->write( $data ) || die( $s->error );
=head1 VERSION
v0.2.4
=head1 DESCRIPTION
L<Module::Generic::SharedMemXS> provides an easy to use api to manipulate shared memory block. See L<perlipc> for more information. This module relies on the XS module L<IPC::SharedMem> part of the L<IPC::SysV> distribution.
This module is similar to L<Module::Generic::SharedMem>, except this one relies on L<IPC::SharedMem> whereas L<Module::Generic::SharedMem> uses perl core functions to access and manipulate shared memory.
As stipulated in L<perlport>, this is not supported on the following platforms: android, dos, MSWin32, OS2, VMS and Risc OS.
You can check if the system is supported with L</supported>
if( Module::Generic::SharedMemXS->supported )
{
# do something
}
This module only works with reference data, such as array, hash or reference to scalar. Anything that L<CBOR::XS>, L<Sereal>. or L<Storable::Improved> knows how to L<Storable::Improved/freeze> and L<Storable::Improved/thaw>
=head1 DEBUGGING
To list all used shared memory, at least on Unix type systems such as Linux or FreeBSD (including MacOSX), use:
ipcs -m
=head1 METHODS
=head2 new
This instantiates a shared memory object. It takes the following parameters:
=over 4
=item I<cbor>
Provided with a value (true or false does not matter), and this will set L<CBOR::XS> as the data serialisation mechanism when storing data to memory or reading data from memory.
=item I<debug>
A debug value will enable debugging output (equal or above 3 actually)
=item I<create>
A boolean value to indicate whether the shared memory block should be created if it does not exist. Default to false.
=item I<destroy>
A boolean value to indicate if the shared memory block should be removed when the object is destroyed upon end of the script process.
See L<perlmod> for more about object destruction.
=item I<destroy_semaphore>
A boolean value to indicate if the semaphore should be removed when the object is destroyed upon end of the script process.
See L<perlmod> for more about object destruction.
I<destroy_semaphore> is automatically enabled if I<destroy> is set to true.
Thus, one can deactive auto removal of the shared memory block, but enable auto removal of the semaphore. This is useful when there are two processes accessing the same shared memory block and one wants to give the first process the authority to create and remove the shared memory block, while the second only access and write to the shared memory block, but does not remove it. Still to avoid having semaphores surviving the process, by enabling this option and disabling I<destroy>, it will remove the semaphore and leave the shared memory.
=item I<exclusive>
A boolean value to set the shared memory as exclusive. This will affect the flags set by L</flags> which are used by L</open>.
=item I<json>
Provided with a value (true or false does not matter), and this will set L<JSON> as the data serialisation mechanism when storing data to memory or reading data from memory.
=item I<key>
The shared memory key identifier to use. It defaults to C<IPC::SysV::IPC_PRIVATE>
If you provide an empty value, it will revert to C<IPC::SysV::IPC_PRIVATE>.
If you provide a number, it will be used to call L<IPC::SysV/ftok>.
Otherwise, if you provide a key as string, the characters in the string will be converted to their numeric value and added up. The resulting id, called C<project id> by L<IPC::SysV>, will be used to call L<IPC::SysV/ftok> and will produce an hopefully unique and repeatable value.
Either way, the resulting value is used to create a shared memory segment and a semaphore by L</open>.
=item I<mode>
The octal mode value to use when opening the shared memory block.
Shared memory are owned by system users and access to shared memory segment is ruled by the initial permissions set to it.
If you do not want to share it with any other user than yourself, setting mode to C<0600> is fine.
=item I<sereal>
Provided with a value (true or false does not matter), and this will set L<Sereal> as the data serialisation mechanism when storing data to memory or reading data from memory.
=item I<serialiser>
You can provide the serialiser with this option. Possible values are: C<cbor>, C<json>, C<sereal>, C<storable>
=item I<size>
The size in byte of the shared memory.
This is set once it is created. You can create again the shared memory segment with a smaller size, but not a bigger one. If you want to increase the size, you would need to remove it first.
=item I<storable>
Provided with a value (true or false does not matter), and this will set L<Storable::Improved> as the data serialisation mechanism when storing data to memory or reading data from memory.
=back
An object will be returned if it successfully initiated, or undef() upon error, which can then be retrieved with C< Module::Generic::SharedMemXS->error >. You should always check the return value of the methods used here for their definedness.
my $shmem = Module::Generic::SharedMemXS->new(
create => 1,
destroy => 0,
key => 'my_memory',
# 64K
size => 65536,
) || die( Module::Generic::SharedMemXS->error );
=head2 addr
Returns the address of the shared memory segment once it has been attached to this address space.
=head2 attach
Attach the shared memory segment to this address space and returns its address.
Upon error, it returns C<undef> and sets an error that can be retrieved with the error method:
my $addr = $shem->attach || die( $shem->error );
A shared memory segment object must be first created with the L</open> method, because L</attach> calls L<IPC::SysV/shmat> with the shared memory id and this id is returned upon using the L</open> method.
=head2 cbor
When called, this will set L<CBOR::XS> as the data serialisation mechanism when storing data to memory or reading data from memory.
=head2 close
This is an alias for L</remove>
=head2 create
Set or get the boolean value to true to indicate you want to create the shared memory block if it does not exist already. Default to false.
=head2 delete
This is an alias for L</remove>
=head2 destroy
Set or get the boolean value to indicate that the shared memory should be automatically destroyed when the module object is destroyed. See L<perlmod> for more information about module object destruction.
=head2 detach
Quoting the IPC documentation, this detaches the shared memory segment located at the address specified by L</attach> from this address space.
It returns C<undef> if it is not attached anymore, but without setting an error.
=head2 exclusive
Set or get the boolean value to affect the open flags in exclusive mode.
=head2 exists
Checks if the shared memory identified with I<key> exists.
It takes the same arguments as L</open> and returns 1 if the shared memory exists or 0 otherwise.
It does this by performing a L<perlfunc/shmget> such as:
shmget( $shared_mem_key, $size, 0444 );
This will typically return the shared memory id if it exists or C<undef()> with an error set in C<$!> by perl otherwise.
=head2 flags
Provided with an optional hash or hash reference and this return a bitwise value of flags used by L</open>.
my $flags = $shmem->flags({
create => 1,
exclusive => 0,
mode => 0600,
}) || die( $shmem->error );
=head2 id
Returns the id of the shared memory once it has been opened with L</open>
my $s = $shmem->open || die( $shmem->error );
my $id = $s->id;
=head2 json
When called, this will set L<JSON> as the data serialisation mechanism when storing data to memory or reading data from memory.
=head2 key
Sets or gets the shared memory key identifier.
$shem->key( 'some_identifier' );
=head2 lock
It takes an optional bitwise lock value, and defaults to C<LOCK_SH> if none is provided and issues a lock on the shared memory.
use Module::Generic::SharedMemXS qw( :all );
my $s = $shem->open || die( $shmem->error );
$s->lock( LOCK_EX );
# Do something
$s->unlock;
=head2 locked
Returns a positive value when a lock is active or 0 when there is no active lock.
The value is the bitwise value of the lock used.
=head2 mode
Sets or gets the mode for the shared memory as used by L</open>
Create an access to the shared memory and return a new L<Module::Generic::SharedMemXS> object.
my $shmem = Module::Generic::SharedMemXS->new(
create => 1,
destroy => 0,
# If not provided, will use the one provided during object instantiation
key => 'my_memory',
# 64K
size => 65536,
) || die( Module::Generic::SharedMemXS->error );
# Overriding some default value set during previous object instantiation
my $s = $shmem->open({
mode => 0600,
size => 1024,
}) || die( $shmem->error );
If the L</create> option is set to true, but the shared memory already exists, L</open> will detect it and attempt to open access to the shared memory without the L</create> bit on, which is C<IPC::SysV::IPC_CREAT>
=head2 owner
Sets or gets the shared memory owner, which is by default actually the process id (C<$$>)
Get a random key to be used as identifier to create a shared memory.
=head2 read
Read the content of the shared memory and decode the data read using L<JSON>, L<CBOR|CBOR::XS>, L<Sereal> or L<Storable::Improved/thaw> depending on your choice upon either object instantiation or upon using the methods L</json>, L</cbor>, L</sereal> or L</storable>. For example:
my $s = Module::Generic::SharedMemXS->new( cbor => 1 ) ||
die( Module::Generic::SharedMemXS->error );
# or
$s->cbor(1);
# or
my $s = Module::Generic::SharedMemXS->new( serialiser => 'cbor' ) ||
die( Module::Generic::SharedMemXS->error );
By default, if no serialiser is specified, it will default to C<storable>.
You can optionally provide a buffer, and a maximum length and it will read that much length and put the shared memory content decoded in that buffer, if it were provided.
It then return the length read, or C<0E0> if no data was retrieved. C<0E0> still is treated as 0, but as a positive value, so you can do:
my $len = $s->read( $buffer ) || die( $s->error );
But you really should more thoroughly do instead:
my( $len, $buffer );
if( !defined( $len = $s->read( $buffer ) ) )
{
die( $s->error );
}
If you do not provide any buffer, you can call L</read> like this and it will return you the shared memory decoded content:
my $buffer;
if( !defined( $buffer = $s->read ) )
{
die( $s->error );
}
=head2 remove
Remove entire the shared memory identified with L</key>
=head2 remove_semaphore
Remove the semaphore associated with the shared memory.
=head2 removed
Returns true if the shared memory was removed, false otherwise.
=head2 removed_semaphore
Returns true if the semaphore has been removed, false otherwise.
=head2 reset
Reset the shared memory value. If a value is provided, it will be used as the new reset value, othewise an empty string will be used.
=head2 semid
Return the L<semaphore|https://en.wikipedia.org/wiki/Semaphore_(programming)> id once the shared memory has been opened. See L<perlipc> for more information about semaphore and L<perlfunc>.
=head2 sereal
When called, this will set L<Sereal> as the data serialisation mechanism when storing data to memory or reading data from memory.
=head2 serial
Returns the serial number used to create or access the shared memory segment.
This serial is created based on the I<key> parameter provided either upon object instantiation or upon using the L</open> method.
The serial is created by calling L<IPC::SysV/ftok> to provide a reliable and repeatable numeric identifier.
=head2 serialiser
Sets or gets the serialiser. Possible values are: C<cbor>, C<json>, C<sereal>, C<storable>
=head2 shmstat
Returns an C<Module::Generic::SharedStat> object representing the current shared memory properties.
=head2 size
Sets or gets the shared memory block size.
This should be an integer representing bytes, so typically a multiple of 1024.
If one parameter only is provided, it returns its corresponding value set.
It performs:
# Get the semaphore id
my $id = $s->semid;
my $value = semctl( $id, $sem, IPC::SysV::GETVAL, 0 );
When 2 parameters are provided, this is treated as a key-value pair and sets the value for the corresponding key.
It performs:
my $id = $s->semid;
semctl( $id, $sem, IPC::SysV::SETVAL, $val )
If no parameter is provided it returns a L<Module::Generic::SemStat> object in scalar context or an array of value in list context.
=head2 storable
When called, this will set L<Storable::Improved> as the data serialisation mechanism when storing data to memory or reading data from memory.
=head2 supported
Returns true if IPC shared memory segments are supported by the system, and false otherwise.
=head2 unlock
Remove the lock, if any. The shared memory must first be opened.
$s->unlock || die( $s->error );
=head2 write
Write the data provided to the shared memory, after having encoded it using L<JSON>, L<CBOR|CBOR::XS>, L<Sereal> or L<Storable::Improved/freeze> depending on your choice of serialiser. See L</json>, L</cbor>, L</sereal> and L</storable>
By default, if no serialiser is specified, it will default to C<storable>.
You can only store in shared memory reference, such as scalar reference, array or hash reference. You could also store module objects, but note that if you choose L<JSON> as a serialiser for your shared data, L<JSON> only supports encoding objects that are based on array or hash. As the L<JSON> documentation states "other blessed references will be converted into null". Thus if you use other reference types, you might want to use L<CBOR|CBOR::XS>, L<Sereal> or L<Storable> instead.
It returns the current object for chaining, or C<undef> if there was an error, which can then be retrieved with L<Module::Generic/error>
=head1 SERIALISATION
=for Pod::Coverage FREEZE
=for Pod::Coverage STORABLE_freeze
=for Pod::Coverage STORABLE_thaw
=for Pod::Coverage THAW
=for Pod::Coverage TO_JSON
Serialisation by L<CBOR|CBOR::XS>, L<Sereal> and L<Storable::Improved> (or the legacy L<Storable>) is supported by this package. To that effect, the following subroutines are implemented: C<FREEZE>, C<THAW>, C<STORABLE_freeze> and C<STORABLE_thaw>