Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in
Toggle navigation
D
drupal
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Locked Files
Custom Issue Tracker
Custom Issue Tracker
Labels
Merge Requests
294
Merge Requests
294
Requirements
Requirements
List
Security & Compliance
Security & Compliance
Dependency List
License Compliance
Analytics
Analytics
Code Review
Insights
Issue
Repository
Value Stream
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Commits
Open sidebar
project
drupal
Commits
32befa4b
Commit
32befa4b
authored
Mar 20, 2014
by
webchick
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Issue
#2216543
by jhodgdon, Berdir: Fill in topic/@defgroup docs for Cache overview.
parent
94b457f1
Changes
11
Hide whitespace changes
Inline
Side-by-side
Showing
11 changed files
with
154 additions
and
58 deletions
+154
-58
core/lib/Drupal.php
core/lib/Drupal.php
+2
-0
core/lib/Drupal/Core/Cache/BackendChain.php
core/lib/Drupal/Core/Cache/BackendChain.php
+2
-0
core/lib/Drupal/Core/Cache/Cache.php
core/lib/Drupal/Core/Cache/Cache.php
+2
-0
core/lib/Drupal/Core/Cache/CacheBackendInterface.php
core/lib/Drupal/Core/Cache/CacheBackendInterface.php
+1
-54
core/lib/Drupal/Core/Cache/CacheCollector.php
core/lib/Drupal/Core/Cache/CacheCollector.php
+2
-0
core/lib/Drupal/Core/Cache/CacheCollectorInterface.php
core/lib/Drupal/Core/Cache/CacheCollectorInterface.php
+2
-0
core/lib/Drupal/Core/Cache/CacheableInterface.php
core/lib/Drupal/Core/Cache/CacheableInterface.php
+2
-0
core/lib/Drupal/Core/Cache/DatabaseBackend.php
core/lib/Drupal/Core/Cache/DatabaseBackend.php
+2
-0
core/lib/Drupal/Core/Cache/MemoryBackend.php
core/lib/Drupal/Core/Cache/MemoryBackend.php
+1
-0
core/lib/Drupal/Core/Cache/NullBackend.php
core/lib/Drupal/Core/Cache/NullBackend.php
+2
-0
core/modules/system/core.api.php
core/modules/system/core.api.php
+136
-4
No files found.
core/lib/Drupal.php
View file @
32befa4b
...
...
@@ -225,6 +225,8 @@ public static function database() {
*
* @return \Drupal\Core\Cache\CacheBackendInterface
* The cache object associated with the specified bin.
*
* @ingroup cache
*/
public
static
function
cache
(
$bin
=
'cache'
)
{
return
static
::
$container
->
get
(
'cache.'
.
$bin
);
...
...
core/lib/Drupal/Core/Cache/BackendChain.php
View file @
32befa4b
...
...
@@ -19,6 +19,8 @@
* volatile backend but found in the persistent one will be propagated back up
* to ensure fast retrieval on the next request. On cache sets and deletes, both
* backends will be invoked to ensure consistency.
*
* @ingroup cache
*/
class
BackendChain
implements
CacheBackendInterface
{
...
...
core/lib/Drupal/Core/Cache/Cache.php
View file @
32befa4b
...
...
@@ -9,6 +9,8 @@
/**
* Helper methods for cache.
*
* @ingroup cache
*/
class
Cache
{
...
...
core/lib/Drupal/Core/Cache/CacheBackendInterface.php
View file @
32befa4b
...
...
@@ -14,60 +14,7 @@
* Drupal\Core\Cache\DatabaseBackend provides the default implementation, which
* can be consulted as an example.
*
* To make Drupal use your implementation for a certain cache bin, you have to
* set a variable with the name of the cache bin as its key and the name of
* your class as its value. For example, if your implementation of
* Drupal\Core\Cache\CacheBackendInterface was called MyCustomCache, the
* following line would make Drupal use it for the 'cache_page' bin:
* @code
* $settings['cache_classes']['cache_page'] = 'MyCustomCache';
* @endcode
*
* Additionally, you can register your cache implementation to be used by
* default for all cache bins by setting the $settings['cache_classes'] variable and
* changing the value of the 'cache' key to the name of your implementation of
* the Drupal\Core\Cache\CacheBackendInterface, e.g.
* @code
* $settings['cache_classes']['cache'] = 'MyCustomCache';
* @endcode
*
* To implement a completely custom cache bin, use the same variable format:
* @code
* $settings['cache_classes']['custom_bin'] = 'MyCustomCache';
* @endcode
* To access your custom cache bin, specify the name of the bin when storing
* or retrieving cached data:
* @code
* \Drupal::cache('custom_bin')->set($cid, $data, $expire);
* \Drupal::cache('custom_bin')->get($cid);
* @endcode
*
* There are two ways to "remove" a cache item:
* - Deletion (using delete(), deleteMultiple(), deleteTags() or deleteAll()):
* Permanently removes the item from the cache.
* - Invalidation (using invalidate(), invalidateMultiple(), invalidateTags()
* or invalidateAll()): a "soft" delete that only marks the items as
* "invalid", meaning "not fresh" or "not fresh enough". Invalid items are
* not usually returned from the cache, so in most ways they behave as if they
* have been deleted. However, it is possible to retrieve the invalid entries,
* if they have not yet been permanently removed by the garbage collector, by
* passing TRUE as the second argument for get($cid, $allow_invalid).
*
* Cache items should be deleted if they are no longer considered useful. This
* is relevant e.g. if the cache item contains references to data that has been
* deleted. On the other hand, it may be relevant to just invalidate the item
* if the cached data may be useful to some callers until the cache item has
* been updated with fresh data. The fact that it was fresh a short while ago
* may often be sufficient.
*
* Invalidation is particularly useful to protect against stampedes. Rather than
* having multiple concurrent requests updating the same cache item when it
* expires or is deleted, there can be one request updating the cache, while
* the other requests can proceed using the stale value. As soon as the cache
* item has been updated, all future requests will use the updated value.
*
* @see \Drupal::cache()
* @see \Drupal\Core\Cache\DatabaseBackend
* @ingroup cache
*/
interface
CacheBackendInterface
{
...
...
core/lib/Drupal/Core/Cache/CacheCollector.php
View file @
32befa4b
...
...
@@ -22,6 +22,8 @@
* CacheCollector->has() needs to correctly return (equivalent to
* array_key_exists() vs. isset()). This should not be necessary in the majority
* of cases.
*
* @ingroup cache
*/
abstract
class
CacheCollector
implements
CacheCollectorInterface
,
DestructableInterface
{
...
...
core/lib/Drupal/Core/Cache/CacheCollectorInterface.php
View file @
32befa4b
...
...
@@ -18,6 +18,8 @@
* request, and memory usage from static caches of that same data.
*
* The default implementation is \Drupal\Core\Cache\CacheCollector.
*
* @ingroup cache
*/
interface
CacheCollectorInterface
{
...
...
core/lib/Drupal/Core/Cache/CacheableInterface.php
View file @
32befa4b
...
...
@@ -8,6 +8,8 @@
/**
* Defines an interface for objects which are potentially cacheable.
*
* @ingroup cache
*/
interface
CacheableInterface
{
...
...
core/lib/Drupal/Core/Cache/DatabaseBackend.php
View file @
32befa4b
...
...
@@ -15,6 +15,8 @@
*
* This is Drupal's default cache implementation. It uses the database to store
* cached data. Each cache bin corresponds to a database table by the same name.
*
* @ingroup cache
*/
class
DatabaseBackend
implements
CacheBackendInterface
{
...
...
core/lib/Drupal/Core/Cache/MemoryBackend.php
View file @
32befa4b
...
...
@@ -15,6 +15,7 @@
* Should be used for unit tests and specialist use-cases only, does not
* store cached items between requests.
*
* @ingroup cache
*/
class
MemoryBackend
implements
CacheBackendInterface
{
...
...
core/lib/Drupal/Core/Cache/NullBackend.php
View file @
32befa4b
...
...
@@ -17,6 +17,8 @@
* operations would have a negative impact on performance.
*
* This also can be used for testing purposes.
*
* @ingroup cache
*/
class
NullBackend
implements
CacheBackendInterface
{
...
...
core/modules/system/core.api.php
View file @
32befa4b
...
...
@@ -173,10 +173,142 @@
* @{
* Information about the Drupal Cache API
*
* @todo write this
*
* Additional documentation paragraphs need to be written, and functions,
* classes, and interfaces need to be added to this topic.
* @section basics Basics
*
* Note: If not specified, all of the methods mentioned here belong to
* \Drupal\Core\Cache\CacheBackendInterface.
*
* The Cache API is used to store data that takes a long time to
* compute. Caching can be permanent, temporary, or valid for a certain
* timespan, and the cache can contain any type of data.
*
* To use the Cache API:
* - Request a cache object through \Drupal::cache() or by injecting a cache
* service.
* - Define a Cache ID (cid) value for your data. A cid is a string, which must
* contain enough information to uniquely identify the data. For example, if
* your data contains translated strings, then your cid value must include the
* current interface language.
* - Call the get() method to attempt a cache read, to see if the cache already
* contains your data.
* - If your data is not already in the cache, compute it and add it to the
* cache using the set() method. The third argument of set() can be used to
* control the lifetime of your cache item.
*
* Example:
* @code
* $cache = \Drupal::cache();
* $cid = 'mymodule_example:' . \Drupal::languageManager()->getCurrentLanguage()->id();
*
* $data = NULL;
* if ($cache = \Drupal::cache()->get($cid)) {
* $data = $cache->data;
* }
* else {
* $data = my_module_complicated_calculation();
* \Drupal::cache()->set($cid, $data);
* }
* @endcode
*
* @section bins Cache bins
*
* Cache storage is separated into "bins", each containing various cache items.
* Each bin can be configured separately; see @ref configuration.
*
* When you request a cache object, you can specify the bin name in your call to
* \Drupal::cache(). Alternatively, you can request a bin by getting service
* "cache.nameofbin" from the container. The default bin is called "cache", with
* service name "cache.cache".
*
* @todo: Document common cache bins in https://drupal.org/node/1194136
*
* A module can define a cache bin by defining a service in its
* modulename.services.yml file as follows (substituting the desired name for
* "nameofbin"):
* @code
* cache.nameofbin:
* class: Drupal\Core\Cache\CacheBackendInterface
* tags:
* - { name: cache.bin }
* factory_method: get
* factory_service: cache_factory
* arguments: [nameofbin]
* @endcode
*
* @section delete Deletion
*
* There are two ways to remove an item from the cache:
* - Deletion (using delete(), deleteMultiple() or deleteAll()) permanently
* removes the item from the cache.
* - Invalidation (using invalidate(), invalidateMultiple() or invalidateAll())
* is a "soft" delete that only marks items as "invalid", meaning "not fresh"
* or "not fresh enough". Invalid items are not usually returned from the
* cache, so in most ways they behave as if they have been deleted. However,
* it is possible to retrieve invalid items, if they have not yet been
* permanently removed by the garbage collector, by passing TRUE as the second
* argument for get($cid, $allow_invalid).
*
* Use deletion if a cache item is no longer useful; for instance, if the item
* contains references to data that has been deleted. Use invalidation if the
* cached item may still be useful to some callers until it has been updated
* with fresh data. The fact that it was fresh a short while ago may often be
* sufficient.
*
* Invalidation is particularly useful to protect against stampedes. Rather than
* having multiple concurrent requests updating the same cache item when it
* expires or is deleted, there can be one request updating the cache, while the
* other requests can proceed using the stale value. As soon as the cache item
* has been updated, all future requests will use the updated value.
*
* @section tags Cache Tags
*
* The fourth argument of the set() method can be used to specify cache tags,
* which are used to identify what type of data is included in each cache. Each
* cache can have multiple tags, and each tag has a string key and a value. The
* value can be:
* - TRUE, to indicate that this type of data is present in the cache.
* - An array of values. For example, the "node" tag indicates that particular
* nodes' data is present in the cache, so its value is an array of node IDs.
* Data that has been tagged can be deleted or invalidated as a group.
*
* Example:
* @code
* // A cache item with nodes, users, and some custom module data.
* $tags = array(
* 'my_custom_tag' => TRUE,
* 'node' => array(1, 3),
* 'user' => array(7),
* );
* \Drupal::cache()->set($cid, $data, CacheBackendInterface::CACHE_PERMANENT, $tags);
*
* // Delete or invalidate all caches with certain tags.
* \Drupal\Core\Cache\Cache::deleteTags(array('node' => array(1));
* \Drupal\Core\Cache\Cache::invalidateTags(array('user' => array(1)));
* @endcode
*
* @todo Update cache tag deletion in https://drupal.org/node/918538
*
* @todo Extend entity cache tags based on https://drupal.org/node/2217749
*
* @section configuration Configuration
*
* Each cache bin can be configured separately; for instance, each bin can use a
* different cache backend, such as APC or Memcache. The default backend stores
* the cached data in the Drupal database.
*
* In a settings.php file, you can override the class used for a particular
* cache bin. For example, if your implementation of
* \Drupal\Core\Cache\CacheBackendInterface was called MyCustomCache, the
* following line would make Drupal use it for the 'cache_page' bin:
* @code
* $settings['cache_classes']['cache_page'] = 'Drupal\full\namespace\to\MyCustomCache';
* @endcode
*
* Additionally, you can register your cache implementation to be used by
* default for all cache bins with:
* @code
* $settings['cache_classes']['cache'] = 'Drupal\full\namespace\to\MyCustomCache';
* @endcode
*
* @see https://drupal.org/node/1884796
* @}
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment