Module::Generic::File::Cache - File-based Cache
use Module::Generic::File::Cache; my $cache = Module::Generic::File::Cache->new( key => 'something', create => 1, mode => 0666, base64 => 1, # Could also be CBOR, Storable::Improved serialiser => 'Sereal', ) || die( Module::Generic::File::Cache->error, "\n" );
v0.2.2
This module provides a file-based shared space that can be shared across proceses. It behaves like Module::Generic::SharedMem, but instead of using shared memory block that requires IPC::SysV, it uses a file.
This is particularly useful for system that lack support for shared cache. See perlport for that.
This instantiates a shared cache object. It takes the following parameters:
When set, this will instruct the serialiser used (see option serialiser) to base64 encode and decode the data before writing and after reading.
The value can be either a simple true value, such as 1, or a base64 encoder/decoder. Currently the only supported ones are: Crypt::Misc and MIME::Base64, or it can also be an array reference of 2 code references, one for encoding and one for decoding.
1
Provided with a value (true or false does not matter), and this will set CBOR::XS as the data serialisation mechanism when storing data to cache file.
A debug value will enable debugging output (equal or above 3 actually)
A boolean value to indicate whether the shared cache file should be created if it does not exist. Default to false.
A boolean value to indicate if the shared cache file should be removed when the object is destroyed upon end of the script process.
See perlmod for more about object destruction.
Provided with a value (true or false does not matter), and this will set JSON as the data serialisation mechanism when storing data to cache file.
Please note that if you want to store objects, you need to use cbor, sereal or storable instead, because JSON is not suitable to serialise objects.
The shared cache key identifier to use. It defaults to a random one created with "rand"
If you provide an empty value, it will revert to one created with "rand".
If you provide a number, it will be used to call "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 "ftok" and will produce a unique and repeatable value.
Either way, the resulting value is used to create a shared cache file by "open".
The octal mode value to use when opening the shared cache file.
Shared cache files are owned by system users and access to shared 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 0600 is fine.
0600
Provided with a value (true or false does not matter), and this will set Sereal as the data serialisation mechanism when storing data to cache file.
The class name of the serialiser to use. Currently supported ones are: CBOR, Sereal, Storable::Improved (or the legacy Storable)
The size in byte of the shared cache.
This is set once it is created. You can create again the shared cache file with a smaller size. No need to remove it first.
Provided with a value (true or false does not matter), and this will set Storable::Improved as the data serialisation mechanism when storing data to cache file.
An object will be returned if it successfully initiated, or undef() upon error, which can then be retrieved with "error" in Module::Generic inherited by Module::Generic::SharedMem. You should always check the return value of the methods used here for their definedness.
undef()
my $shmem = Module::Generic::SharedMem->new( create => 1, destroy => 0, key => 'my_memory', # 64K size => 65536, storable => 1, ) || die( Module::Generic::SharedMem->error );
When called, this will set CBOR::XS as the data serialisation mechanism when storing data to cache file or reading data from cache file.
Boolean value. If set, this will have "open" create the cache file if it does not already exists.
Removes the cache file ad returns true upon success, or sets an error and return undef upon error.
undef
Boolean value. If true, the cache file will be removed when this objects is destroyed by perl upon clean-up.
Boolean value. Sets whether there should be an exclusive access to the cache file. This is currently not used.
Returns true if the cache file exists, or false otherwise.
Provided with an optional hash or hash reference and this return a bitwise value of flags used by "open".
my $flags = $cache->flags({ create => 1, exclusive => 0, mode => 0600, }) || die( $cache->error );
This attempts to be a polyfil for "ftok" in POSIX and provided with some digits, this returns a steady and reproducible serial that serves as a base file name for the cache file.
Returns the id or serial of the cache file set after having opened it with "open"
Sets the data serialising method to JSON
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.
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 error and return undef.
Returns the boolean value representing the lock state of the cache file.
Set or get the cache file mode to be used by "open"
Create an access to the cache file and return a new Module::Generic::File::Cache object.
my $cache = Module::Generic::File::Cache->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::Cache->error ); # Overriding some default value set during previous object instantiation my $c = $cache->open({ mode => 0600, size => 1024, }) || die( $cache->error );
If the "create" option is set to true, but the cache file already exists, "open" will detect it and attempt to open access to the cache file without the "create" bit on.
Sets or gets the cache file owner, which is by default actually the process id ($$)
$$
Get a random key to be used as identifier to create a shared cache.
Read the content of the shared cached and decode the data read using JSON, CBOR, Sereal or "thaw" in Storable depending on your choice of serialiser upon either object instantiation or upon using the methods "json", "cbor", "sereal" or "storable" or even more simply "serialiser"
By default, if no serialiser is specified, it will default to storable.
storable
You can optionally provide a buffer, and a maximum length and it will read that much length and put the shared cache content decoded in that buffer, if it were provided.
It then return the length read, or 0E0 if no data was retrieved. 0E0 still is treated as 0, but as a positive value, so you can do:
0E0
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 "read" like this and it will return you the shared cache decoded content:
my $buffer; if( !defined( $buffer = $cache->read ) ) { die( $cache->error ); }
The content is stored in shared cache after being encoded with the serialiser of choice.
Remove entire the shared cache identified with "key"
Returns true if the shared cache was removed, false otherwise.
Reset the shared cache value. If a value is provided, it will be used as the new reset value, othewise an empty string will be used.
Returns the serial number used to create or access the shared cache.
This serial is created based on the key parameter provided either upon object instantiation or upon using the "open" method.
The serial is created by calling "ftok" to provide a reliable and repeatable numeric identifier. "ftok" is a simili polyfill of "ftok" in IPC::SysV
Sets or gets the serialiser. Possible values are: cbor, json, sereal, storable
cbor
json
sereal
Sets or gets the shared 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.
Sets or retrieve value with "stat" in Module::Generic::File for the underlying cache file.
It returns a Module::Generic::SemStat object.
When called, this will set Storable as the data packing mechanism when storing data to memory.
Returns always true as cache file relies solely on file.
Remove the lock, if any. The shared cache must first be opened.
$cache->unlock || die( $cache->error );
Write the data provided to the shared cache, after having encoded it using JSON, CBOR, Sereal or "freeze" in Storable depending on your serialiser of choice. See "json", "cbor", "sereal" and "storable" and more simply "serialiser"
You can store in shared cache any kind of data excepted glob, such as scalar reference, array or hash reference. You could also store module objects, but JSON only supports encoding objects that are based on array or hash. As the JSON documentation states "other blessed references will be converted into null"
It returns the current object for chaining, or undef if there was an error, which can then be retrieved with "error" in Module::Generic
Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw
FREEZE
THAW
STORABLE_freeze
STORABLE_thaw
Jacques Deguest <jack@deguest.jp>
Module::Generic::SharedMem, Cache::File, File::Cache, Cache::FileCache
JSON, Storable
Copyright(c) 2022 DEGUEST Pte. Ltd.
All rights reserved This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Module::Generic, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Generic
CPAN shell
perl -MCPAN -e shell install Module::Generic
For more information on module installation, please visit the detailed CPAN module installation guide.