WebSVN – Moodle – Diff – /cache/README.md



 

A definition:
 
     $definitions = array(
        'string' => array(                            // Required, unique to the component
            'mode' => \core_cache\store::MODE_APPLICATION,  // Required
            'simplekeys' => false,                    // Optional
            'simpledata' => false,                    // Optional
            'requireidentifiers' => array(            // Optional

        )
    );

 

Getting something from a cache using the definition:
 
    $cache = \core_cache\cache::make('core', 'string');
    if (!$component = $cache->get('component')) {
        // get returns false if its not there and can't be loaded.
        $component = generate_data();

        $cache->set($component);

    }
 
The same thing but using params:
 
    $cache = \core_cache\cache::make_from_params(\core_cache\store::MODE_APPLICATION, 'core', 'string');
    if (!$component = $cache->get('component')) {

        // get returns false if its not there and can't be loaded.

        $component = generate_data();
        $cache->set($component);

    }
 
If a data source had been specified in the definition, the following would be all that was needed.

 
    $cache = \core_cache\cache::make('core', 'string');

    $component = $cache->get('component');
 
Disabling the cache stores.
There are times in code when you will want to disable the cache stores.

While the cache API must still be functional in order for calls to it to work it is possible to disable the use of the cache stores separately so that you can be sure only the cache will function in all circumstances.
 
    // Disable the cache store at the start of your script with:
    define('CACHE_DISABLE_STORES', true);

### Loader
The loader is central to the whole thing.
It is used by the end developer to get an object that handles caching.
90% of end developers will not need to know or use anything else in the cache API.
In order to get a loader you must use one of two static methods, make or make_from_params.
The loader has been kept as simple as possible, interaction is summarised by the core_cache\loader_interface interface.
Internally there is lots of magic going on. The important parts to know about are:
* There are two ways to get a loader, the first with a definition (discussed below) the second with params. When params are used they are turned into an adhoc definition with default params.
* A loader is passed three things when being constructed, a definition, a store, and another loader or datasource if there is either.
* If a loader is the third arg then requests will be chained to provide redundancy.
* If a data source is provided then requests for an item that is not cached will be passed to the data source and that will be expected to load the data. If it loads data, that data is stored in each store on its way back to the user.

### Store
The store is the bridge between the cache API and a cache solution.
Cache store plugins exist within moodle/cache/store.
The administrator of a site can configure multiple instances of each plugin, the configuration gets initialised as a store for the loader when required in code (during construction of the loader).
The following points highlight things you should know about stores.
* A \core_cache\store interface is used to define the requirements of a store plugin.
* The store plugin can inherit the \core_cache\lockable_cache_interface interface to handle its own locking.
* The store plugin can inherit the \core_cache\key_aware_cache_interface interface to handle is own has checks.
* Store plugins inform the cache API about the things they support. Features can be required by a definition.
  * Data guarantee - Data is guaranteed to exist in the cache once it is set there. It is never cleaned up to free space or because it has not been recently used.
  * Multiple identifiers - Rather than a single string key, the parts that make up the key are passed as an array.
  * Native TTL support - When required, the store supports native ttl and doesn't require the cache API to manage ttl of things given to the store.
* There are two reserved store names, base and dummy. These are both used internally.

* requirelockingbeforewrite - If set to true the system will throw an error if you write to a cache without having a lock on the relevant key.
* requiresearchable - If set to true only stores that support key searching will be used for this definition. Its not recommended to use this unless absolutely unavoidable.
* maxsize - This gives a cache an indication about the maximum items it should store. Cache stores don't have to use this, it is up to them to decide if its required.
* overrideclass - If provided this class will be used for the loader. It must extend one of the core loader classes (based upon mode).
* overrideclassfile - Included if required when using the overrideclass param.
* datasource - If provided this class will be used as a data source for the definition. It must implement the \core_cache\data_source_interface interface.
* datasourcefile - Included if required when using the datasource param.
* staticacceleration - Any data passing through the cache will be held onto to make subsequent requests for it faster.
* staticaccelerationsize - If set to an int this will be the maximum number of items stored in the static acceleration array.
* ttl - Can be used to set a ttl value for data being set for this cache.
* mappingsonly - This definition can only be used if there is a store mapping for it. More on this later.

By default all sharing options are available to select. This particular option allows the developer to limit the options available to the admin configuring the cache.

 
### Data source
Data sources allow cache _misses_ (requests for a key that doesn't exist) to be handled and loaded internally.
The loader gets used as the last resort if provided and means that code using the cache doesn't need to handle the situation that information isn't cached.

They can be specified in a cache definition and must implement the \core_cache\data_source_interface interface.
 

### How it all chains together.

Other internal magic you should be aware of
-------------------------------------------
The following should fill you in on a bit more of the behind-the-scenes stuff for the cache API.

 
### Helper class
There is a helper class called \core_cache\helper which is abstract with static methods.
This class handles much of the internal generation and initialisation requirements.

In normal use this class will not be needed outside of the API (mostly internal use only)
 
### Configuration
There are two configuration classes \core_cache\config and \core_cache\config_writer.
The reader class is used for every request, the writer is only used when modifying the configuration.
Because the cache API is designed to cache database configuration and meta data it must be able to operate prior to database configuration being loaded.
To get around this we store the configuration information in a file in the dataroot.

Proyectos de Subversion Moodle

(root)/cache/README.md – Rev 1 → 1441

Rev 1		Rev 1441
Línea 6...		Línea 6...
6		6
Línea 7...		Línea 7...
7	`A definition:`	7	`A definition:`
8		8
9	`$definitions = array(`	9	`$definitions = array(`
10	`'string' => array( // Required, unique to the component`	10	`'string' => array( // Required, unique to the component`
11	`'mode' => cache_store::MODE_APPLICATION, // Required`	11	`'mode' => \core_cache\store::MODE_APPLICATION, // Required`
12	`'simplekeys' => false, // Optional`	12	`'simplekeys' => false, // Optional`
13	`'simpledata' => false, // Optional`	13	`'simpledata' => false, // Optional`
14	`'requireidentifiers' => array( // Optional`	14	`'requireidentifiers' => array( // Optional`
Línea 36...		Línea 36...
36	`)`	36	`)`
37	`);`	37	`);`
Línea 38...		Línea 38...
38		38
Línea 39...		Línea 39...
39	`Getting something from a cache using the definition:`	39	`Getting something from a cache using the definition:`
40		40
41	`$cache = cache::make('core', 'string');`	41	`$cache = \core_cache\cache::make('core', 'string');`
42	`if (!$component = $cache->get('component')) {`	42	`if (!$component = $cache->get('component')) {`
43	`// get returns false if its not there and can't be loaded.`	43	`// get returns false if its not there and can't be loaded.`
44	`$component = generate_data();`	44	`$component = generate_data();`
Línea 45...		Línea 45...
45	`$cache->set($component);`	45	`$cache->set($component);`
Línea 46...		Línea 46...
46	`}`	46	`}`
47		47
48	`The same thing but using params:`	48	`The same thing but using params:`
49		49
50	`$cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'core', 'string');`	50	`$cache = \core_cache\cache::make_from_params(\core_cache\store::MODE_APPLICATION, 'core', 'string');`
51	`if (!$component = $cache->get('component')) {`	51	`if (!$component = $cache->get('component')) {`
Línea 52...		Línea 52...
52	`// get returns false if its not there and can't be loaded.`	52	`// get returns false if its not there and can't be loaded.`
Línea 53...		Línea 53...
53	`$component = generate_data();`	53	`$component = generate_data();`
54	`$cache->set($component);`	54	`$cache->set($component);`
Línea 55...		Línea 55...
55	`}`	55	`}`
56		56
57	`If a data source had been specified in the definition, the following would be all that was needed.`	57	`If a data source had been specified in the definition, the following would be all that was needed.`
Línea 58...		Línea 58...
58		58
59	`$cache = cache::make('core', 'string');`	59	`$cache = \core_cache\cache::make('core', 'string');`
Línea 60...		Línea 60...
60	`$component = $cache->get('component');`	60	`$component = $cache->get('component');`
61		61
62	`Disabling the cache stores.`	62	`Disabling the cache stores.`
63	`There are times in code when you will want to disable the cache stores.`	63	`There are times in code when you will want to disable the cache stores.`
Línea 64...		Línea 64...
64	`While the cache API must still be functional in order for calls to it to work it is possible to disable the use of the cache stores separately so that you can be sure only the cache will function in all circumstances.`	64	`While the cache API must still be functional in order for calls to it to work it is possible to disable the use of the cache stores separately so that you can be sure only the cache will function in all circumstances.`
65		65
66	`// Disable the cache store at the start of your script with:`	66	`// Disable the cache store at the start of your script with:`
67	`define('CACHE_DISABLE_STORES', true);`	67	`define('CACHE_DISABLE_STORES', true);`
Línea 88...		Línea 88...
88	`### Loader`	88	`### Loader`
89	`The loader is central to the whole thing.`	89	`The loader is central to the whole thing.`
90	`It is used by the end developer to get an object that handles caching.`	90	`It is used by the end developer to get an object that handles caching.`
91	`90% of end developers will not need to know or use anything else in the cache API.`	91	`90% of end developers will not need to know or use anything else in the cache API.`
92	`In order to get a loader you must use one of two static methods, make or make_from_params.`	92	`In order to get a loader you must use one of two static methods, make or make_from_params.`
93	`The loader has been kept as simple as possible, interaction is summarised by the cache_loader interface.`	93	`The loader has been kept as simple as possible, interaction is summarised by the core_cache\loader_interface interface.`
94	`Internally there is lots of magic going on. The important parts to know about are:`	94	`Internally there is lots of magic going on. The important parts to know about are:`
95	`* There are two ways to get a loader, the first with a definition (discussed below) the second with params. When params are used they are turned into an adhoc definition with default params.`	95	`* There are two ways to get a loader, the first with a definition (discussed below) the second with params. When params are used they are turned into an adhoc definition with default params.`
96	`* A loader is passed three things when being constructed, a definition, a store, and another loader or datasource if there is either.`	96	`* A loader is passed three things when being constructed, a definition, a store, and another loader or datasource if there is either.`
97	`* If a loader is the third arg then requests will be chained to provide redundancy.`	97	`* If a loader is the third arg then requests will be chained to provide redundancy.`
98	`* If a data source is provided then requests for an item that is not cached will be passed to the data source and that will be expected to load the data. If it loads data, that data is stored in each store on its way back to the user.`	98	`* If a data source is provided then requests for an item that is not cached will be passed to the data source and that will be expected to load the data. If it loads data, that data is stored in each store on its way back to the user.`
Línea 104...		Línea 104...
104	`### Store`	104	`### Store`
105	`The store is the bridge between the cache API and a cache solution.`	105	`The store is the bridge between the cache API and a cache solution.`
106	`Cache store plugins exist within moodle/cache/store.`	106	`Cache store plugins exist within moodle/cache/store.`
107	`The administrator of a site can configure multiple instances of each plugin, the configuration gets initialised as a store for the loader when required in code (during construction of the loader).`	107	`The administrator of a site can configure multiple instances of each plugin, the configuration gets initialised as a store for the loader when required in code (during construction of the loader).`
108	`The following points highlight things you should know about stores.`	108	`The following points highlight things you should know about stores.`
109	`* A cache_store interface is used to define the requirements of a store plugin.`	109	`* A \core_cache\store interface is used to define the requirements of a store plugin.`
110	`* The store plugin can inherit the cache_is_lockable interface to handle its own locking.`	110	`* The store plugin can inherit the \core_cache\lockable_cache_interface interface to handle its own locking.`
111	`* The store plugin can inherit the cache_is_key_aware interface to handle is own has checks.`	111	`* The store plugin can inherit the \core_cache\key_aware_cache_interface interface to handle is own has checks.`
112	`* Store plugins inform the cache API about the things they support. Features can be required by a definition.`	112	`* Store plugins inform the cache API about the things they support. Features can be required by a definition.`
113	`* Data guarantee - Data is guaranteed to exist in the cache once it is set there. It is never cleaned up to free space or because it has not been recently used.`	113	`* Data guarantee - Data is guaranteed to exist in the cache once it is set there. It is never cleaned up to free space or because it has not been recently used.`
114	`* Multiple identifiers - Rather than a single string key, the parts that make up the key are passed as an array.`	114	`* Multiple identifiers - Rather than a single string key, the parts that make up the key are passed as an array.`
115	`* Native TTL support - When required, the store supports native ttl and doesn't require the cache API to manage ttl of things given to the store.`	115	`* Native TTL support - When required, the store supports native ttl and doesn't require the cache API to manage ttl of things given to the store.`
116	`* There are two reserved store names, base and dummy. These are both used internally.`	116	`* There are two reserved store names, base and dummy. These are both used internally.`
Línea 139...		Línea 139...
139	`* requirelockingbeforewrite - If set to true the system will throw an error if you write to a cache without having a lock on the relevant key.`	139	`* requirelockingbeforewrite - If set to true the system will throw an error if you write to a cache without having a lock on the relevant key.`
140	`* requiresearchable - If set to true only stores that support key searching will be used for this definition. Its not recommended to use this unless absolutely unavoidable.`	140	`* requiresearchable - If set to true only stores that support key searching will be used for this definition. Its not recommended to use this unless absolutely unavoidable.`
141	`* maxsize - This gives a cache an indication about the maximum items it should store. Cache stores don't have to use this, it is up to them to decide if its required.`	141	`* maxsize - This gives a cache an indication about the maximum items it should store. Cache stores don't have to use this, it is up to them to decide if its required.`
142	`* overrideclass - If provided this class will be used for the loader. It must extend one of the core loader classes (based upon mode).`	142	`* overrideclass - If provided this class will be used for the loader. It must extend one of the core loader classes (based upon mode).`
143	`* overrideclassfile - Included if required when using the overrideclass param.`	143	`* overrideclassfile - Included if required when using the overrideclass param.`
144	`* datasource - If provided this class will be used as a data source for the definition. It must implement the cache_data_source interface.`	144	`* datasource - If provided this class will be used as a data source for the definition. It must implement the \core_cache\data_source_interface interface.`
145	`* datasourcefile - Included if required when using the datasource param.`	145	`* datasourcefile - Included if required when using the datasource param.`
146	`* staticacceleration - Any data passing through the cache will be held onto to make subsequent requests for it faster.`	146	`* staticacceleration - Any data passing through the cache will be held onto to make subsequent requests for it faster.`
147	`* staticaccelerationsize - If set to an int this will be the maximum number of items stored in the static acceleration array.`	147	`* staticaccelerationsize - If set to an int this will be the maximum number of items stored in the static acceleration array.`
148	`* ttl - Can be used to set a ttl value for data being set for this cache.`	148	`* ttl - Can be used to set a ttl value for data being set for this cache.`
149	`* mappingsonly - This definition can only be used if there is a store mapping for it. More on this later.`	149	`* mappingsonly - This definition can only be used if there is a store mapping for it. More on this later.`
Línea 169...		Línea 169...
169	`By default all sharing options are available to select. This particular option allows the developer to limit the options available to the admin configuring the cache.`	169	`By default all sharing options are available to select. This particular option allows the developer to limit the options available to the admin configuring the cache.`
Línea 170...		Línea 170...
170		170
171	`### Data source`	171	`### Data source`
172	`Data sources allow cache _misses_ (requests for a key that doesn't exist) to be handled and loaded internally.`	172	`Data sources allow cache _misses_ (requests for a key that doesn't exist) to be handled and loaded internally.`
173	`The loader gets used as the last resort if provided and means that code using the cache doesn't need to handle the situation that information isn't cached.`	173	`The loader gets used as the last resort if provided and means that code using the cache doesn't need to handle the situation that information isn't cached.`
Línea 174...		Línea 174...
174	`They can be specified in a cache definition and must implement the cache_data_source interface.`	174	`They can be specified in a cache definition and must implement the \core_cache\data_source_interface interface.`
175		175
Línea 176...		Línea 176...
176	`### How it all chains together.`	176	`### How it all chains together.`
Línea 210...		Línea 210...
210	`Other internal magic you should be aware of`	210	`Other internal magic you should be aware of`
211	`-------------------------------------------`	211	`-------------------------------------------`
212	`The following should fill you in on a bit more of the behind-the-scenes stuff for the cache API.`	212	`The following should fill you in on a bit more of the behind-the-scenes stuff for the cache API.`
Línea 213...		Línea 213...
213		213
214	`### Helper class`	214	`### Helper class`
215	`There is a helper class called cache_helper which is abstract with static methods.`	215	`There is a helper class called \core_cache\helper which is abstract with static methods.`
216	`This class handles much of the internal generation and initialisation requirements.`	216	`This class handles much of the internal generation and initialisation requirements.`
Línea 217...		Línea 217...
217	`In normal use this class will not be needed outside of the API (mostly internal use only)`	217	`In normal use this class will not be needed outside of the API (mostly internal use only)`
218		218
219	`### Configuration`	219	`### Configuration`
220	`There are two configuration classes cache_config and cache_config_writer.`	220	`There are two configuration classes \core_cache\config and \core_cache\config_writer.`
221	`The reader class is used for every request, the writer is only used when modifying the configuration.`	221	`The reader class is used for every request, the writer is only used when modifying the configuration.`
222	`Because the cache API is designed to cache database configuration and meta data it must be able to operate prior to database configuration being loaded.`	222	`Because the cache API is designed to cache database configuration and meta data it must be able to operate prior to database configuration being loaded.`
223	`To get around this we store the configuration information in a file in the dataroot.`	223	`To get around this we store the configuration information in a file in the dataroot.`