return( $self->error( "Mmap cache file found in our object is not a Module::Generic::File object.") ) if( !$self->_is_a( $file=> 'Module::Generic::File') );
return( $self->error( "An error occurred while trying to decode JSON data: $@") );
}
my$result= $crawl->( $decoded);
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;
nowarnings 'uninitialized';
$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.
# 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
L<Module::Generic::File::Mmap> implements a Mmap cache mechanism using L<Cache::FastMmap>, which is an XS module. The api is very similar to its counterpart with L<Module::Generic::File::Cache> and L<Module::Generic::SharedMem>, but has the advantage of sharing data over a file like L<Module::Generic::File::Cache>, but using Mmap and being very fast.
You must have installed separately L<Cache::FastMmap> for this module to work. If it is not installed, you could still instantiate an object, but you would not be able to get a new object after with L</open>.
This is particularly useful for system that lack support for shared memory cache. See L<perlport> for that.
=head1 METHODS
=head2 new
This instantiates a shared mmap cache object. It takes the following parameters:
=over 4
=item I<debug>
A debug value will enable debugging output (equal or above 3 actually)
=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 mmap file.
=item I<create>
A boolean value to indicate whether the shared mmap cache file should be created if it does not exist. Default to false.
=item I<destroy>
A boolean value to indicate if the shared mmap cache file should be removed when the object is destroyed upon end of the script process.
See L<perlmod> for more about object destruction.
=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 mmap file
Please note that if you want to store objects, you need to use I<storable> instead, because L<JSON> is not suitable to serialise objects.
=item I<key>
The shared mmap cache key identifier to use. It defaults to a random one created with L</rand>
If you provide an empty value, it will revert to one created with L</rand>.
If you provide a number, it will be used to call L</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 will be used to call L</ftok> and will produce a unique and repeatable value.
Either way, the resulting value is used to create a shared mmap cache file by L</open>.
=item I<mode>
The octal mode value to use when opening the shared mmap cache file.
Shared cache files are owned by system users and access to shared mmap cache files 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 mmap file
=item I<size>
The size in byte of the shared mmap cache.
This is set once it is created. You can create again the shared mmap cache file with a smaller size. No 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 mmap file
=back
An object will be returned if it successfully initiated, or C<undef()> upon error, which can then be retrieved with L<Module::Generic/error> inherited by L<Module::Generic::SharedMem>. You should always check the return value of the methods used here for their definedness.
my $shmem = Module::Generic::SharedMem->new(
create => 1,
destroy => 0,
key => 'my_memory',
# 64K
size => 65536,
storable => 1,
) || die( Module::Generic::SharedMem->error );
=head2 cache_file
Sets or gets the underlying cache file to use.
=head2 cbor
When called, this will set L<CBOR::XS> as the data serialisation mechanism when storing data to mmap cache or reading data from mmap cache.
=head2 create
Boolean value. If set, this will have L</open> create the cache file if it does not already exists.
=head2 delete
Removes the cache file ad returns true upon success, or sets an L<error|Module::Generic/error> and return C<undef> upon error.
=head2 destroy
Boolean value. If true, the cache file will be removed when this objects is destroyed by perl upon clean-up.
=head2 exclusive
Boolean value. Sets whether there should be an exclusive access to the cache file. This is currently not used.
=head2 exists
Returns true if the cache file exists, or false 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 = $cache->flags({
create => 1,
exclusive => 0,
mode => 0600,
}) || die( $cache->error );
=head2 ftok
This attempts to be a polyfil for L<POSIX/ftok> and provided with some digits, this returns a steady and reproducible serial that serves as a base file name for the cache file.
=head2 has_xs
Read-only. Returns true if the XS module L<Cache::FastMmap> is installed on your system and false otherwise.
=head2 id
Returns the id or serial of the cache file set after having opened it with L</open>
=head2 json
When called, this will set L<JSON> as the data serialisation mechanism when storing data to cache mmap.
=head2 key
The key to use to identify the cache file.
This must be unique enough to be different from other cache file and to be shared among other processes.
It returns the value currently set, if any.
=head2 lock
This locks the cache file, if any and returns the result from the lock.
If the cache has not been opened first, then this will set an L<error|Module::Generic/error> and return C<undef>.
=head2 locked
Returns the boolean value representing the lock state of the cache file.
=head2 mode
Set or get the cache file mode to be used by L</open>
=head2 open
Create an access to the cache mmap file and return a new L<Module::Generic::File::Mmap> object.
my $cache = Module::Generic::File::Mmap->new(
create => 1,
destroy => 0,
# If not provided, will use the one provided during object instantiation
key => 'my_cache',
# 64K
size => 65536,
) || die( Module::Generic::File::Mmap->error );
# Overriding some default value set during previous object instantiation
my $c = $cache->open({
mode => 0600,
size => 1024,
}) || die( $cache->error );
If the L</create> option is set to true, but the cache file already exists, L</open> will detect it and attempt to open access to the cache file without the L</create> bit on.
=head2 owner
Sets or gets the cache file owner, which is by default actually the process id (C<$$>)
=head2 rand
Get a random key to be used as identifier to create a shared mmap cache.
=head2 read
Read the content of the shared mmap cached and decode the data read using L<JSON>, L<CBOR|CBOR::XS>, L<Sereal> or L<Storable/thaw> depending on your serialiser of choice upon either object instantiation or upon using the methods L</json> or L</storable>
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 mmap cache 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 = $cache->read( $buffer ) || die( $cache->error );
But you really should more thoroughly do instead:
my( $len, $buffer );
if( !defined( $len = $cache->read( $buffer ) ) )
{
die( $cache->error );
}
If you do not provide any buffer, you can call L</read> like this and it will return you the shared mmap cache decoded content:
my $buffer;
if( !defined( $buffer = $cache->read ) )
{
die( $cache->error );
}
The content is stored in shared mmap cache after being encoded with L<Storable/freeze>.
=head2 remove
Remove entire the shared mmap cache identified with L</key>
=head2 removed
Returns true if the shared mmap cache was removed, false otherwise.
=head2 reset
Reset the shared mmap cache value. If a value is provided, it will be used as the new reset value, othewise an empty string will be used.
=head2 sereal
When called, this will set L<Sereal> as the data serialisation mechanism when storing data to cache mmap.
=head2 serial
Returns the serial number used to create or access the shared mmap cache.
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</ftok> to provide a reliable and repeatable numeric identifier. L</ftok> is a simili polyfill of L<IPC::SysV/ftok>
=head2 serialiser
Sets or gets the serialiser. Possible values are: C<cbor>, C<json>, C<sereal>, C<storable>
=head2 size
Sets or gets the shared mmap cache size.
This should be an integer representing bytes, so typically a multiple of 1024.
This has not much effect, except ensuring there is enough space on the filesystem for the cache and that whatever data is provided does not exceed that threshold.
=head2 stat
Sets or retrieve value with L<Module::Generic::File/stat> for the underlying cache file.
It returns a L<Module::Generic::SemStat> object.
=head2 storable
When called, this will set L<Storable::Improved> as the data serialisation mechanism when storing data to cache mmap.
=head2 supported
Returns always true as cache file relies solely on file.
=head2 unlock
Remove the lock, if any. The shared mmap cache must first be opened.
$cache->unlock || die( $cache->error );
=head2 write
Write the data provided to the shared mmap cache, after having encoded it using L<JSON>, L<CBOR|CBOR::XS>, L<Sereal> or L<Storable/freeze> depending on your serialiser of choice. See L</json>, L</cbor>, L</sereal> and L</storable> and more simply L</serialiser>
By default, if no serialiser is specified, it will default to C<storable>.
You can store in shared mmap cache any kind of data excepted glob, such as scalar reference, array or hash reference. You could also store module objects, but 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"
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>