Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
cache_definition Class Reference

The cache definition class. More...

Public Member Functions

 can_use_localstore ()
 Returns true if this definition allows local storage to be used for caching.
 
 generate_definition_hash ()
 Generates a hash of this definition and returns it.
 
 generate_multi_key_parts ()
 Generates a multi key prefix for this definition.
 
 generate_single_key_prefix ()
 Generates a single key prefix for this definition.
 
 get_area ()
 Returns the area this definition is associated with.
 
 get_cache_class ()
 Returns the cache loader class that should be used for this definition.
 
 get_component ()
 Returns the component this definition is associated with.
 
 get_data_source ()
 Returns an instance of the data source class used for this definition.
 
 get_id ()
 Returns the id of this definition.
 
 get_identifiers ()
 Returns the identifiers that are being used for this definition.
 
 get_invalidation_events ()
 Returns all of the invalidation events for this definition.
 
 get_maxsize ()
 Returns the maximum number of items allowed in this cache.
 
 get_mode ()
 Returns the mode of this definition.
 
 get_name ()
 Returns the name for this definition.
 
 get_persistent_max_size ()
 Please call cache_definition::get_static_acceleration_size() instead.
 
 get_requirements_bin ()
 Returns the requirements of this definition as a binary flag.
 
 get_selected_sharing_option ()
 Returns the user selected sharing option for this definition.
 
 get_sharing_options ()
 Returns the possible sharing options that can be used with this defintion.
 
 get_static_acceleration_size ()
 Returns the max size for the static acceleration array.
 
 get_ttl ()
 Returns the ttl in seconds for this definition if there is one, or null if not.
 
 get_user_input_sharing_key ()
 Returns the user entered sharing key for this definition.
 
 has_data_source ()
 Returns true if this definition has an associated data source.
 
 has_invalidation_events ()
 Check if the definition has any invalidation events.
 
 has_required_identifiers ()
 Returns true if this definition requires identifiers.
 
 invalidates_on_event ($event)
 Check if this definition should invalidate on the given event.
 
 is_for_mappings_only ()
 Returns true if this definition should only be used with mappings.
 
 require_data_guarantee ()
 Returns true if this definition requires a data guarantee from the cache stores being used.
 
 require_locking ()
 Returns true if this definition requires locking functionality.
 
 require_locking_before_write ()
 Returns true if this definition requires a lock to be aquired before a write is attempted.
 
 require_locking_read ()
 Returns true if this definition requires read locking.
 
 require_locking_write ()
 Returns true if this definition requires write locking.
 
 require_multiple_identifiers ()
 Returns true if this definition requires that the cache stores support multiple identifiers.
 
 require_searchable ()
 Returns true if this definition requires a searchable cache.
 
 set_identifiers (array $identifiers=array())
 Sets the identifiers for this definition, or updates them if they have already been set.
 
 should_be_persistent ()
 Please call cache_definition::use_static_acceleration() instead.
 
 use_static_acceleration ()
 Returns true if we should hold onto the data flowing through the cache.
 
 uses_simple_data ()
 Returns true if the data is known to be scalar or array of scalar.
 
 uses_simple_keys ()
 Returns true if this definition is using simple keys.
 

Static Public Member Functions

static load ($id, array $definition, $unused=null)
 Creates a cache definition given a definition from the cache configuration or from a caches.php file.
 
static load_adhoc ($mode, $component, $area, array $options=array())
 Creates an ah-hoc cache definition given the required params.
 

Public Attributes

const SHARING_ALL = 1
 The cache can be shared with everyone.
 
const SHARING_DEFAULT = 2
 The default sharing option that gets used if none have been selected.
 
const SHARING_DEFAULTOPTIONS = 15
 The default sharing options available.
 
const SHARING_INPUT = 8
 The cache can be shared with other sites using the same key.
 
const SHARING_SITEID = 2
 The cache can be shared with other sites using the same siteid.
 
const SHARING_VERSION = 4
 The cache can be shared with other sites of the same version.
 

Protected Member Functions

 get_cache_identifier ()
 Returns a cache identification string.
 

Protected Attributes

string $area
 The area this definition is associated with.
 
bool $canuselocalstore = false
 Whether this cache supports local storages.
 
string $component
 The component this definition is associated with.
 
string $datasource = null
 The data source class to use with this definition.
 
string $datasourcefile = null
 The file in which the data source class exists.
 
string $definitionhash = null
 A hash identifier of this definition.
 
string $id
 The identifier for the definition.
 
array $identifiers = null
 An array of identifiers provided to this cache when it was initialised.
 
array $invalidationevents = array()
 An array of events that should cause this cache to invalidate.
 
array $keyprefixmulti = null
 Key prefix to use with cache stores that support multi keys.
 
string $keyprefixsingle = null
 Key prefix for use with single key cache stores.
 
bool $mappingsonly = false
 Set to true if this cache should only use mapped cache stores and not the default mode cache store.
 
int $maxsize = null
 Sets the maximum number of items that can exist in the cache.
 
int $mode
 The mode for the defintion.
 
string $overrideclass = null
 The class to use as the cache loader for this definition.
 
string $overrideclassfile = null
 The file in which the override class exists.
 
bool $requiredataguarantee = false
 If set to true then only stores that guarantee data may be used with this definition.
 
array $requireidentifiers = array()
 An array of identifiers that must be provided when the definition is used to create a cache.
 
bool $requirelocking = false
 If set to true then we know that this definition requires the locking functionality.
 
bool $requirelockingbeforewrite = false
 Gets set to true if this definition requires a lock to be acquired before a write is attempted.
 
bool $requirelockingread = false
 Set to true if this definition requires read locking.
 
bool $requirelockingwrite = false
 Gets set to true if this definition requires write locking.
 
bool $requiremultipleidentifiers = false
 If set to true then only stores that support multple identifiers may be used with this definition.
 
bool $requiresearchable = false
 Gets set to true if this definition requires searchable stores.
 
int $selectedsharingoption = self::SHARING_DEFAULT
 The selected sharing option.
 
int $sharingoptions
 The selected sharing mode for this definition.
 
bool $simpledata = false
 Set to true if we know the data is scalar or array of scalar.
 
bool $simplekeys = false
 If set to true we know the keys are simple.
 
bool $staticacceleration = false
 Set to true if the cache should hold onto items passing through it to speed up subsequent requests.
 
int $staticaccelerationsize = false
 The maximum number of items that static acceleration cache should hold onto.
 
int $ttl = 0
 The TTL for data in this cache.
 
string $userinputsharingkey = ''
 The user input key to use if the SHARING_INPUT option has been selected.
 

Detailed Description

The cache definition class.

Cache definitions need to be defined in db/caches.php files. They can be constructed with the following options.

Required settings:

  • mode [int] Sets the mode for the definition. Must be one of cache_store\MODE_*

Optional settings:

  • simplekeys [bool] Set to true if your cache will only use simple keys for its items. Simple keys consist of digits, underscores and the 26 chars of the english language. a-zA-Z0-9_ If true the keys won't be hashed before being passed to the cache store for gets/sets/deletes. It will be better for performance and possible only becase we know the keys are safe.
  • simpledata [bool] If set to true we know that the data is scalar or array of scalar.
  • requireidentifiers [array] An array of identifiers that must be provided to the cache when it is created.
  • requiredataguarantee [bool] If set to true then only stores that can guarantee data will remain available once set will be used.
  • requiremultipleidentifiers [bool] If set to true then only stores that support multiple identifiers will be used.
  • requirelockingread [bool] If set to true then a lock will be gained before reading from the cache store. It is recommended not to use this setting unless 100% absolutely positively required. Remember 99.9% of caches will NOT need this setting. This setting will only be used for application caches presently.
  • requirelockingwrite [bool] If set to true then a lock will be gained before writing to the cache store. As above this is not recommended unless truly needed. Please think about the order of your code and deal with race conditions there first. This setting will only be used for application caches presently.
  • maxsize [int] If set this will be used as the maximum number of entries within the cache store for this definition. Its important to note that cache stores don't actually have to acknowledge this setting or maintain it as a hard limit.
  • overrideclass [string] A class to use as the loader for this cache. This is an advanced setting and will allow the developer of the definition to take 100% control of the caching solution. Any class used here must inherit the cache_loader interface and must extend default cache loader for the mode they are using.
  • overrideclassfile [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.
  • datasource [string] A class to use as the data loader for this definition. Any class used here must inherit the cache_data_loader interface.
  • datasourcefile [string] Supplements the above setting indicating the file containing the class to be used. This file is included when required.
  • staticacceleration The cache loader will keep an array of the items set and retrieved to the cache during the request. Consider using this setting when you know that there are going to be many calls to the cache for the same information. Requests for data in this array will be ultra fast, but it will cost memory.
  • staticaccelerationsize [int] This supplements the above setting by limiting the number of items in the static acceleration array. Tweaking this setting lower will allow you to minimise the memory implications above while hopefully still managing to offset calls to the cache store.
  • ttl [int] A time to live for the data (in seconds). It is strongly recommended that you don't make use of this and instead try to create an event driven invalidation system. Not all cache stores will support this natively and there are undesired performance impacts if the cache store does not.
  • mappingsonly [bool] If set to true only the mapped cache store(s) will be used and the default mode store will not. This is a super advanced setting and should not be used unless absolutely required. It allows you to avoid the default stores for one reason or another.
  • invalidationevents [array] An array of events that should cause this cache to invalidate some or all of the items within it.
  • sharingoptions [int] The sharing options that are appropriate for this definition. Should be the sum of the possible options.
  • defaultsharing [int] The default sharing option to use. It's highly recommended that you don't set this unless there is a very specific reason not to use the system default.
  • canuselocalstore [bool] The cache is able to safely run with multiple copies on different webservers without any need for administrator intervention to ensure that data stays in sync across nodes. This is usually managed by a revision system as seen in modinfo cache or language cache. Requiring purge on upgrade is not sufficient as it requires administrator intervention on each node to make it work.

For examples take a look at lib/db/caches.php

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

Member Function Documentation

◆ can_use_localstore()

cache_definition::can_use_localstore ( )

Returns true if this definition allows local storage to be used for caching.

Since
Moodle 3.1.0
Return values
bool

◆ generate_definition_hash()

cache_definition::generate_definition_hash ( )

Generates a hash of this definition and returns it.

Return values
string

◆ generate_multi_key_parts()

cache_definition::generate_multi_key_parts ( )

Generates a multi key prefix for this definition.

Return values
array

◆ generate_single_key_prefix()

cache_definition::generate_single_key_prefix ( )

Generates a single key prefix for this definition.

Return values
string

◆ get_area()

cache_definition::get_area ( )

Returns the area this definition is associated with.

Return values
string

◆ get_cache_class()

cache_definition::get_cache_class ( )

Returns the cache loader class that should be used for this definition.

Return values
string

◆ get_cache_identifier()

cache_definition::get_cache_identifier ( )
protected

Returns a cache identification string.

Return values
stringA string to be used as part of keys.

◆ get_component()

cache_definition::get_component ( )

Returns the component this definition is associated with.

Return values
string

◆ get_data_source()

cache_definition::get_data_source ( )

Returns an instance of the data source class used for this definition.

Return values
cache_data_source
Exceptions
coding_exception

◆ get_id()

cache_definition::get_id ( )

Returns the id of this definition.

Return values
string

◆ get_identifiers()

cache_definition::get_identifiers ( )

Returns the identifiers that are being used for this definition.

Return values
array

◆ get_invalidation_events()

cache_definition::get_invalidation_events ( )

Returns all of the invalidation events for this definition.

Return values
array

◆ get_maxsize()

cache_definition::get_maxsize ( )

Returns the maximum number of items allowed in this cache.

Return values
int

◆ get_mode()

cache_definition::get_mode ( )

Returns the mode of this definition.

Return values
intOne more cache_store\MODE_

◆ get_name()

cache_definition::get_name ( )

Returns the name for this definition.

Return values
string

◆ get_persistent_max_size()

cache_definition::get_persistent_max_size ( )

Please call cache_definition::get_static_acceleration_size() instead.

See also
cache_definition\get_static_acceleration_size()
Deprecated
since 2.6

◆ get_requirements_bin()

cache_definition::get_requirements_bin ( )

Returns the requirements of this definition as a binary flag.

Return values
int

◆ get_selected_sharing_option()

cache_definition::get_selected_sharing_option ( )

Returns the user selected sharing option for this definition.

Return values
int

◆ get_sharing_options()

cache_definition::get_sharing_options ( )

Returns the possible sharing options that can be used with this defintion.

Return values
int

◆ get_static_acceleration_size()

cache_definition::get_static_acceleration_size ( )

Returns the max size for the static acceleration array.

Return values
int

◆ get_ttl()

cache_definition::get_ttl ( )

Returns the ttl in seconds for this definition if there is one, or null if not.

Return values
int|null

◆ get_user_input_sharing_key()

cache_definition::get_user_input_sharing_key ( )

Returns the user entered sharing key for this definition.

Return values
string

◆ has_data_source()

cache_definition::has_data_source ( )

Returns true if this definition has an associated data source.

Return values
bool

◆ has_invalidation_events()

cache_definition::has_invalidation_events ( )

Check if the definition has any invalidation events.

Return values
boolTrue if it does, false otherwise

◆ has_required_identifiers()

cache_definition::has_required_identifiers ( )

Returns true if this definition requires identifiers.

Parameters
bool

◆ invalidates_on_event()

cache_definition::invalidates_on_event ( $event)

Check if this definition should invalidate on the given event.

Parameters
string$event
Return values
boolTrue if the definition should invalidate on the event. False otherwise.

◆ is_for_mappings_only()

cache_definition::is_for_mappings_only ( )

Returns true if this definition should only be used with mappings.

Return values
bool

◆ load()

static cache_definition::load ( $id,
array $definition,
$unused = null )
static

Creates a cache definition given a definition from the cache configuration or from a caches.php file.

Parameters
string$id
array$definition
string$unusedUsed to be datasourceaggregate but that was removed and this is now unused.
Return values
cache_definition
Exceptions
coding_exception

◆ load_adhoc()

static cache_definition::load_adhoc ( $mode,
$component,
$area,
array $options = array() )
static

Creates an ah-hoc cache definition given the required params.

Please note that when using an adhoc definition you cannot set any of the optional params. This is because we cannot guarantee consistent access and we don't want to mislead people into thinking that.

Parameters
int$modeOne of cache_store\MODE_*
string$componentThe component this definition relates to.
string$areaThe area this definition relates to.
array$optionsAn array of options, available options are:
  • simplekeys : Set to true if the keys you will use are a-zA-Z0-9_
  • simpledata : Set to true if the type of the data you are going to store is scalar, or an array of scalar vars
  • overrideclass : The class to use as the loader.
  • staticacceleration : If set to true the cache will hold onto data passing through it.
  • staticaccelerationsize : Set it to an int to limit the size of the staticacceleration cache.
Return values
cache_application|cache_session|cache_request

◆ require_data_guarantee()

cache_definition::require_data_guarantee ( )

Returns true if this definition requires a data guarantee from the cache stores being used.

Return values
bool

◆ require_locking()

cache_definition::require_locking ( )

Returns true if this definition requires locking functionality.

Either read or write locking.

Return values
bool

◆ require_locking_before_write()

cache_definition::require_locking_before_write ( )

Returns true if this definition requires a lock to be aquired before a write is attempted.

Return values
bool

◆ require_locking_read()

cache_definition::require_locking_read ( )

Returns true if this definition requires read locking.

Return values
bool

◆ require_locking_write()

cache_definition::require_locking_write ( )

Returns true if this definition requires write locking.

Return values
bool

◆ require_multiple_identifiers()

cache_definition::require_multiple_identifiers ( )

Returns true if this definition requires that the cache stores support multiple identifiers.

Return values
bool

◆ require_searchable()

cache_definition::require_searchable ( )

Returns true if this definition requires a searchable cache.

Since
Moodle 2.4.4
Return values
bool

◆ set_identifiers()

cache_definition::set_identifiers ( array $identifiers = array())

Sets the identifiers for this definition, or updates them if they have already been set.

Parameters
array$identifiers
Return values
boolfalse if no identifiers where changed, true otherwise.
Exceptions
coding_exception

◆ should_be_persistent()

cache_definition::should_be_persistent ( )

Please call cache_definition::use_static_acceleration() instead.

See also
cache_definition\use_static_acceleration()
Deprecated
since 2.6

◆ use_static_acceleration()

cache_definition::use_static_acceleration ( )

Returns true if we should hold onto the data flowing through the cache.

If set to true data flowing through the cache will be stored in a static variable to make subsequent requests for the data much faster.

Return values
bool

◆ uses_simple_data()

cache_definition::uses_simple_data ( )

Returns true if the data is known to be scalar or array of scalar.

Return values
bool

◆ uses_simple_keys()

cache_definition::uses_simple_keys ( )

Returns true if this definition is using simple keys.

Simple keys contain only a-zA-Z0-9_

Return values
bool

Member Data Documentation

◆ $datasourcefile

string cache_definition::$datasourcefile = null
protected

The file in which the data source class exists.

This will be included if required.

◆ $maxsize

int cache_definition::$maxsize = null
protected

Sets the maximum number of items that can exist in the cache.

Please note this isn't a hard limit, and doesn't need to be enforced by the caches. They can choose to do so optionally.

◆ $mode

int cache_definition::$mode
protected

The mode for the defintion.

One of cache_store\MODE_*

◆ $overrideclassfile

string cache_definition::$overrideclassfile = null
protected

The file in which the override class exists.

This will be included if required. Absolute path

◆ $requirelocking

bool cache_definition::$requirelocking = false
protected

If set to true then we know that this definition requires the locking functionality.

This gets set during construction based upon the settings requirelockingread and requirelockingwrite.

◆ $requiresearchable

bool cache_definition::$requiresearchable = false
protected

Gets set to true if this definition requires searchable stores.

Since
Moodle 2.4.4

◆ $selectedsharingoption

int cache_definition::$selectedsharingoption = self::SHARING_DEFAULT
protected

The selected sharing option.

One of self\SHARING_*

◆ $simplekeys

bool cache_definition::$simplekeys = false
protected

If set to true we know the keys are simple.

a-zA-Z0-9_

◆ $ttl

int cache_definition::$ttl = 0
protected

The TTL for data in this cache.

Please don't use this, instead use event driven invalidation.

◆ $userinputsharingkey

string cache_definition::$userinputsharingkey = ''
protected

The user input key to use if the SHARING_INPUT option has been selected.

Must be ALPHANUMEXT

◆ SHARING_DEFAULT

const cache_definition::SHARING_DEFAULT = 2

The default sharing option that gets used if none have been selected.

SiteID. It is the most restrictive.

◆ SHARING_DEFAULTOPTIONS

const cache_definition::SHARING_DEFAULTOPTIONS = 15

The default sharing options available.

All + SiteID + Version + Input.


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