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

Copyright: 2012 Sam Hemelryk

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

string A 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

int	One 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

bool	True 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

bool	True 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	$unused	Used 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	$mode	One of cache_store\MODE_*
string	$component	The component this definition relates to.
string	$area	The area this definition relates to.
array	$options	An 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

bool	false 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:

cache/classes/definition.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ can_use_localstore()

◆ generate_definition_hash()

◆ generate_multi_key_parts()

◆ generate_single_key_prefix()

◆ get_area()

◆ get_cache_class()

◆ get_cache_identifier()

◆ get_component()

◆ get_data_source()

◆ get_id()

◆ get_identifiers()

◆ get_invalidation_events()

◆ get_maxsize()

◆ get_mode()

◆ get_name()

◆ get_persistent_max_size()

◆ get_requirements_bin()

◆ get_selected_sharing_option()

◆ get_sharing_options()

◆ get_static_acceleration_size()

◆ get_ttl()

◆ get_user_input_sharing_key()

◆ has_data_source()

◆ has_invalidation_events()

◆ has_required_identifiers()

◆ invalidates_on_event()

◆ is_for_mappings_only()

◆ load()

◆ load_adhoc()

◆ require_data_guarantee()

◆ require_locking()

◆ require_locking_before_write()

◆ require_locking_read()

◆ require_locking_write()

◆ require_multiple_identifiers()

◆ require_searchable()

◆ set_identifiers()

◆ should_be_persistent()

◆ use_static_acceleration()

◆ uses_simple_data()

◆ uses_simple_keys()

Member Data Documentation

◆ $datasourcefile

◆ $maxsize

◆ $mode

◆ $overrideclassfile

◆ $requirelocking

◆ $requiresearchable

◆ $selectedsharingoption

◆ $simplekeys

◆ $ttl

◆ $userinputsharingkey

◆ SHARING_DEFAULT

◆ SHARING_DEFAULTOPTIONS