Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
cachestore_apcu Class Reference

The APCu cache store class. More...

Inheritance diagram for cachestore_apcu:
cache_store cache_is_key_aware cache_is_configurable cache_store_interface

Public Member Functions

 __construct ($name, array $configuration=array())
 Constructs an instance of the cache store.
 
 cache_size_details (int $samplekeys=50)
 Gets the amount of memory used by this specific cache within the store, if known.
 
 cleanup ()
 
 create_clone (array $details=array())
 Creates a clone of this store instance ready to be initialised.
 
 delete ($key)
 Deletes an item from the cache store.
 
 delete_many (array $keys)
 Deletes several keys from the cache in a single action.
 
 estimate_stored_size ($key, $value)
 Estimates the storage size used within this cache if the given value is stored with the given key.
 
 get ($key)
 Retrieves an item from the cache store given its key.
 
 get_last_io_bytes ()
 Gets the number of bytes read from or written to cache as a result of the last action.
 
 get_many ($keys)
 Retrieves several items from the cache store in a single transaction.
 
 get_warnings ()
 Can be overridden to return any warnings this store instance should make to the admin.
 
 has ($key)
 Test is a cache has a key.
 
 has_all (array $keys)
 Test is a cache has all of the given keys.
 
 has_any (array $keys)
 Test if a cache has at least one of the given keys.
 
 initialise (cache_definition $definition)
 Initialises a new instance of the cache store given the definition the instance is to be used for.
 
 instance_created ()
 Performs any necessary operation when the store instance has been created.
 
 instance_deleted ()
 Performs any necessary clean up when the store instance is being deleted.
 
 is_initialised ()
 Returns true if this cache store instance has been initialised.
 
 is_ready ()
 Returns true if this cache store instance is ready to use.
 
 is_searchable ()
 Returns true if the store instance is searchable.
 
 my_name ()
 Returns the name of this store instance.
 
 purge ()
 Purges the cache deleting all items within it.
 
 set ($key, $data)
 Sets an item in the cache given its key and data value.
 
 set_many (array $keyvaluearray)
 Sets many items in the cache in a single transaction.
 
 store_total_size ()
 Gets the amount of memory/storage currently used by this cache store if known.
 
 supports_data_guarantee ()
 Returns true if the store instance guarantees data.
 
 supports_dereferencing_objects ()
 Returns true if the store automatically dereferences objects.
 
 supports_multiple_identifiers ()
 Returns true if the store instance supports multiple identifiers.
 
 supports_native_ttl ()
 Returns true if the store instance supports native ttl.
 

Static Public Member Functions

static are_requirements_met ()
 Static method to check that the APCu stores requirements have been met.
 
static can_add_instance ()
 Returns true if the user can add an instance of the store plugin.
 
static config_get_configuration_array ($data)
 Given the data from the add instance form this function creates a configuration array.
 
static config_set_edit_form_data (moodleform $editform, array $config)
 Allows the cache store to set its data against the edit form before it is shown to the user.
 
static get_supported_features (array $configuration=array())
 Returns the supported features as a binary flag.
 
static get_supported_modes (array $configuration=array())
 Returns the supported modes as a binary flag.
 
static initialise_test_instance (cache_definition $definition)
 Generates an instance of the cache store that can be used for testing.
 
static is_supported_mode ($mode)
 Static method to check if a store is usable with the given mode.
 
static ready_to_be_used_for_testing ()
 Returns true if this cache store instance is both suitable for testing, and ready for testing.
 
static unit_test_configuration ()
 Generates the appropriate configuration required for unit testing.
 

Public Attributes

const DEREFERENCES_OBJECTS = 16
 The cache store dereferences objects.
 
const IO_BYTES_NOT_SUPPORTED = -1
 Returned from get_last_io_bytes if this cache store doesn't support counting bytes read/sent.
 
const IS_SEARCHABLE = 8
 The cache is searchable by key.
 
const MODE_APPLICATION = 1
 Application caches.
 
const MODE_REQUEST = 4
 Request caches.
 
const MODE_SESSION = 2
 Session caches.
 
const REQUIRED_VERSION = '4.0.0'
 The required version of APCu for this extension.
 
const STATIC_ACCEL = '** static accel. **'
 Static caches.
 
const SUPPORTS_DATA_GUARANTEE = 2
 Ensures data remains in the cache once set.
 
const SUPPORTS_MULTIPLE_IDENTIFIERS = 1
 Supports multi-part keys.
 
const SUPPORTS_NATIVE_TTL = 4
 Supports a native ttl system.
 

Protected Member Functions

 prepare_key ($key)
 Prepares the given key for use.
 

Protected Attributes

string $cacheprefix = null
 The prefix added specifically for this cache.
 
cache_definition $definition = null
 The definition used when this instance was initialised.
 
string $name
 The name of this store instance.
 
string $storeprefix = null
 The storeprefix to use on all instances of this store.
 

Detailed Description

The APCu cache store class.

License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

cachestore_apcu::__construct ( $name,
array $configuration = array() )

Constructs an instance of the cache store.

This method should not create connections or perform and processing, it should be used

Parameters
string$nameThe name of the cache store
array$configurationThe configuration for this store instance.

Reimplemented from cache_store.

Member Function Documentation

◆ are_requirements_met()

static cachestore_apcu::are_requirements_met ( )
static

Static method to check that the APCu stores requirements have been met.

It checks that the APCu extension has been loaded and that it has been enabled.

Return values
boolTrue if the stores software/hardware requirements have been met and it can be used. False otherwise.

Implements cache_store_interface.

◆ cache_size_details()

cache_store::cache_size_details ( int $samplekeys = 50)
inherited

Gets the amount of memory used by this specific cache within the store, if known.

This function may be slow and should not be called in normal usage, only for administration pages. The value is usually an estimate, and may not be available at all.

When estimating, a number of sample items will be used for the estimate. If set to 50 (default), then this function will retrieve 50 random items and use that to estimate the total size.

The return value has the following fields:

  • supported (true if any other values are completed)
  • items (number of items)
  • mean (mean size of one item in bytes)
  • sd (standard deviation of item size in bytes, based on sample)
  • margin (95% confidence margin for mean - will be 0 if exactly computed)
Parameters
int$samplekeysNumber of samples to use
Return values
stdClassObject with information about the store size

Reimplemented in cachestore_file.

◆ can_add_instance()

static cache_store::can_add_instance ( )
staticinherited

Returns true if the user can add an instance of the store plugin.

Return values
bool

Reimplemented in cachestore_dummy, cachestore_session, and cachestore_static.

◆ cleanup()

cache_store::cleanup ( )
inherited
Deprecated
since 2.5
See also
cache_store\instance_deleted()

Reimplemented in cachestore_dummy.

◆ config_get_configuration_array()

static cachestore_apcu::config_get_configuration_array ( $data)
static

Given the data from the add instance form this function creates a configuration array.

Parameters
stdClass$data
Return values
array

Implements cache_is_configurable.

◆ config_set_edit_form_data()

static cachestore_apcu::config_set_edit_form_data ( moodleform $editform,
array $config )
static

Allows the cache store to set its data against the edit form before it is shown to the user.

Parameters
moodleform$editform
array$config

Implements cache_is_configurable.

◆ create_clone()

cache_store::create_clone ( array $details = array())
inherited

Creates a clone of this store instance ready to be initialised.

This method is used so that a cache store needs only be constructed once. Future requests for an instance of the store will be given a cloned instance.

If you are writing a cache store that isn't compatible with the clone operation you can override this method to handle any situations you want before cloning.

Parameters
array$detailsAn array containing the details of the store from the cache config.
Return values
cache_store

◆ delete()

cachestore_apcu::delete ( $key)

Deletes an item from the cache store.

Parameters
string$keyThe key to delete.
Return values
boolReturns true if the operation was a success, false otherwise.

Reimplemented from cache_store.

◆ delete_many()

cachestore_apcu::delete_many ( array $keys)

Deletes several keys from the cache in a single action.

Parameters
array$keysThe keys to delete
Return values
intThe number of items successfully deleted.

Reimplemented from cache_store.

◆ estimate_stored_size()

cache_store::estimate_stored_size ( $key,
$value )
inherited

Estimates the storage size used within this cache if the given value is stored with the given key.

This function is not exactly accurate; it does not necessarily take into account all the overheads involved. It is only intended to give a good idea of the relative size of different caches.

The default implementation serializes both key and value and sums the lengths (as a rough estimate which is probably good enough for everything unless the cache offers compression).

Parameters
mixed$keyKey
mixed$valueValue
Return values
intSize in bytes

Reimplemented in cachestore_redis.

◆ get()

cachestore_apcu::get ( $key)

Retrieves an item from the cache store given its key.

Parameters
string$keyThe key to retrieve
Return values
mixedThe data that was associated with the key, or false if the key did not exist.

Reimplemented from cache_store.

◆ get_last_io_bytes()

cache_store::get_last_io_bytes ( )
inherited

Gets the number of bytes read from or written to cache as a result of the last action.

This includes calls to the functions get(), get_many(), set(), and set_many(). The number is reset by calling any of these functions.

This should be the actual number of bytes of the value read from or written to cache, giving an impression of the network or other load. It will not be exactly the same amount as netowrk traffic because of protocol overhead, key text, etc.

If not supported, returns IO_BYTES_NOT_SUPPORTED.

Return values
intBytes read (or 0 if none/not supported)
Since
Moodle 4.0

Reimplemented in cachestore_file, and cachestore_redis.

◆ get_many()

cachestore_apcu::get_many ( $keys)

Retrieves several items from the cache store in a single transaction.

If not all of the items are available in the cache then the data value for those that are missing will be set to false.

Parameters
array$keysThe array of keys to retrieve
Return values
arrayAn array of items from the cache. There will be an item for each key, those that were not in the store will be set to false.

Reimplemented from cache_store.

◆ get_supported_features()

static cachestore_apcu::get_supported_features ( array $configuration = array())
static

Returns the supported features as a binary flag.

Parameters
array$configurationThe configuration of a store to consider specifically.
Return values
intThe supported features.

Implements cache_store_interface.

◆ get_supported_modes()

static cachestore_apcu::get_supported_modes ( array $configuration = array())
static

Returns the supported modes as a binary flag.

Parameters
array$configurationThe configuration of a store to consider specifically.
Return values
intThe supported modes.

Implements cache_store_interface.

◆ get_warnings()

cache_store::get_warnings ( )
inherited

Can be overridden to return any warnings this store instance should make to the admin.

This should be used to notify things like configuration conflicts etc. The warnings returned here will be displayed on the cache configuration screen.

Return values
string[]An array of warning strings from the store instance.

◆ has()

cachestore_apcu::has ( $key)

Test is a cache has a key.

Parameters
string | int$key
Return values
boolTrue if the cache has the requested key, false otherwise.

Implements cache_is_key_aware.

◆ has_all()

cachestore_apcu::has_all ( array $keys)

Test is a cache has all of the given keys.

Parameters
array$keys
Return values
boolTrue if the cache has all of the given keys, false otherwise.

Implements cache_is_key_aware.

◆ has_any()

cachestore_apcu::has_any ( array $keys)

Test if a cache has at least one of the given keys.

Parameters
array$keys
Return values
boolTrue if the cache has at least one of the given keys

Implements cache_is_key_aware.

◆ initialise()

cachestore_apcu::initialise ( cache_definition $definition)

Initialises a new instance of the cache store given the definition the instance is to be used for.

This function should prepare any given connections etc.

Parameters
cache_definition$definition
Return values
bool

Reimplemented from cache_store.

◆ initialise_test_instance()

static cachestore_apcu::initialise_test_instance ( cache_definition $definition)
static

Generates an instance of the cache store that can be used for testing.

Returns an instance of the cache store, or false if one cannot be created.

Parameters
cache_definition$definition
Return values
cache_store

Implements cache_store_interface.

◆ instance_created()

cache_store::instance_created ( )
inherited

Performs any necessary operation when the store instance has been created.

Since
Moodle 2.5

Reimplemented in cachestore_file.

◆ instance_deleted()

cachestore_apcu::instance_deleted ( )

Performs any necessary clean up when the store instance is being deleted.

Reimplemented from cache_store.

◆ is_initialised()

cachestore_apcu::is_initialised ( )

Returns true if this cache store instance has been initialised.

Return values
bool

Reimplemented from cache_store.

◆ is_ready()

cache_store::is_ready ( )
inherited

Returns true if this cache store instance is ready to use.

Return values
bool

Reimplemented in cachestore_file, and cachestore_redis.

◆ is_searchable()

cache_store::is_searchable ( )
inherited

Returns true if the store instance is searchable.

Return values
bool

◆ is_supported_mode()

static cachestore_apcu::is_supported_mode ( $mode)
static

Static method to check if a store is usable with the given mode.

Parameters
int$modeOne of cache_store\MODE_*
Return values
boolTrue if the mode is supported.

Implements cache_store_interface.

◆ my_name()

cachestore_apcu::my_name ( )

Returns the name of this store instance.

Return values
string

Reimplemented from cache_store.

◆ prepare_key()

cachestore_apcu::prepare_key ( $key)
protected

Prepares the given key for use.

Should be called before all interaction.

Parameters
string$keyThe key to prepare for storing in APCu.
Return values
string

◆ purge()

cachestore_apcu::purge ( )

Purges the cache deleting all items within it.

Return values
booleanTrue on success. False otherwise.

Reimplemented from cache_store.

◆ ready_to_be_used_for_testing()

static cachestore_apcu::ready_to_be_used_for_testing ( )
static

Returns true if this cache store instance is both suitable for testing, and ready for testing.

Cache stores that support being used as the default store for unit and acceptance testing should override this function and return true if there requirements have been met.

Return values
bool

Reimplemented from cache_store.

◆ set()

cachestore_apcu::set ( $key,
$data )

Sets an item in the cache given its key and data value.

Parameters
string$keyThe key to use.
mixed$dataThe data to set.
Return values
boolTrue if the operation was a success false otherwise.

Reimplemented from cache_store.

◆ set_many()

cachestore_apcu::set_many ( array $keyvaluearray)

Sets many items in the cache in a single transaction.

Parameters
array$keyvaluearrayAn array of key value pairs. Each item in the array will be an associative array with two keys, 'key' and 'value'.
Return values
intThe number of items successfully set. It is up to the developer to check this matches the number of items sent ... if they care that is.

Reimplemented from cache_store.

◆ store_total_size()

cache_store::store_total_size ( )
inherited

Gets the amount of memory/storage currently used by this cache store if known.

This value should be obtained quickly from the store itself, if available.

This is the total memory usage of the entire store, not for ther specific cache in question.

Where not supported (default), will always return null.

Return values
int|nullAmount of memory used in bytes or null

Reimplemented in cachestore_file, and cachestore_redis.

◆ supports_data_guarantee()

cache_store::supports_data_guarantee ( )
inherited

Returns true if the store instance guarantees data.

Return values
bool

◆ supports_dereferencing_objects()

cache_store::supports_dereferencing_objects ( )
inherited

Returns true if the store automatically dereferences objects.

Return values
bool

◆ supports_multiple_identifiers()

cache_store::supports_multiple_identifiers ( )
inherited

Returns true if the store instance supports multiple identifiers.

Return values
bool

Reimplemented in cachestore_file, cachestore_session, and cachestore_static.

◆ supports_native_ttl()

cache_store::supports_native_ttl ( )
inherited

Returns true if the store instance supports native ttl.

Return values
bool

◆ unit_test_configuration()

static cachestore_apcu::unit_test_configuration ( )
static

Generates the appropriate configuration required for unit testing.

Return values
arrayArray of unit test configuration data to be used by initialise().

Implements cache_store_interface.

Member Data Documentation

◆ $storeprefix

string cachestore_apcu::$storeprefix = null
protected

The storeprefix to use on all instances of this store.

Configured as part store setup.

◆ DEREFERENCES_OBJECTS

const cache_store::DEREFERENCES_OBJECTS = 16
inherited

The cache store dereferences objects.

When set, loaders will assume that all data coming from this store has already had all references resolved. So even for complex object structures it will not try to remove references again.

◆ MODE_APPLICATION

const cache_store::MODE_APPLICATION = 1
inherited

Application caches.

These are shared caches.

◆ MODE_REQUEST

const cache_store::MODE_REQUEST = 4
inherited

Request caches.

Static caches really.

◆ MODE_SESSION

const cache_store::MODE_SESSION = 2
inherited

Session caches.

Just access to the PHP session.


The documentation for this class was generated from the following file: