Drupal 8  8.0.2
ChainedFastBackend Class Reference
Inheritance diagram for ChainedFastBackend:

Public Member Functions

 __construct (CacheBackendInterface $consistent_backend, CacheBackendInterface $fast_backend, $bin)
 
 get ($cid, $allow_invalid=FALSE)
 
 getMultiple (&$cids, $allow_invalid=FALSE)
 
 set ($cid, $data, $expire=Cache::PERMANENT, array $tags=array())
 
 setMultiple (array $items)
 
 delete ($cid)
 
 deleteMultiple (array $cids)
 
 deleteAll ()
 
 invalidate ($cid)
 
 invalidateMultiple (array $cids)
 
 invalidateTags (array $tags)
 
 invalidateAll ()
 
 garbageCollection ()
 
 removeBin ()
 
 reset ()
 

Data Fields

const LAST_WRITE_TIMESTAMP_PREFIX = 'last_write_timestamp_'
 
- Data Fields inherited from CacheBackendInterface
const CACHE_PERMANENT = -1
 

Protected Member Functions

 getLastWriteTimestamp ()
 
 markAsOutdated ()
 

Protected Attributes

 $bin
 
 $consistentBackend
 
 $fastBackend
 
 $lastWriteTimestamp
 

Detailed Description

Defines a backend with a fast and a consistent backend chain.

In order to mitigate a network roundtrip for each cache get operation, this cache allows a fast backend to be put in front of a slow(er) backend. Typically the fast backend will be something like APCu, and be bound to a single web node, and will not require a network round trip to fetch a cache item. The fast backend will also typically be inconsistent (will only see changes from one web node). The slower backend will be something like Mysql, Memcached or Redis, and will be used by all web nodes, thus making it consistent, but also require a network round trip for each cache get.

In addition to being useful for sites running on multiple web nodes, this backend can also be useful for sites running on a single web node where the fast backend (e.g., APCu) isn't shareable between the web and CLI processes. Single-node configurations that don't have that limitation can just use the fast cache backend directly.

We always use the fast backend when reading (get()) entries from cache, but check whether they were created before the last write (set()) to this (chained) cache backend. Those cache entries that were created before the last write are discarded, but we use their cache IDs to then read them from the consistent (slower) cache backend instead; at the same time we update the fast cache backend so that the next read will hit the faster backend again. Hence we can guarantee that the cache entries we return are all up-to-date, and maximally exploit the faster cache backend. This cache backend uses and maintains a "last write timestamp" to determine which cache entries should be discarded.

Because this backend will mark all the cache entries in a bin as out-dated for each write to a bin, it is best suited to bins with fewer changes.

Note that this is designed specifically for combining a fast inconsistent cache backend with a slower consistent cache back-end. To still function correctly, it needs to do a consistency check (see the "last write timestamp" logic). This contrasts with , which assumes both chained cache backends are consistent, thus a consistency check being pointless.

See Also

Constructor & Destructor Documentation

__construct ( CacheBackendInterface  $consistent_backend,
CacheBackendInterface  $fast_backend,
  $bin 
)

Constructs a ChainedFastBackend object.

Parameters
\Drupal\Core\Cache\CacheBackendInterface$consistent_backendThe consistent cache backend.
\Drupal\Core\Cache\CacheBackendInterface$fast_backendThe fast cache backend.
string$binThe cache bin for which the object is created.

Member Function Documentation

delete (   $cid)

{Deletes an item from the cache.If the cache item is being deleted because it is no longer "fresh", you may consider using invalidate() instead. This allows callers to retrieve the invalid item by calling get() with $allow_invalid set to TRUE. In some cases an invalid item may be acceptable rather than having to rebuild the cache.

Parameters
string$cidThe cache ID to delete.
See Also
::invalidate()
::deleteMultiple()
::deleteAll()
}

Implements CacheBackendInterface.

References ChainedFastBackend\markAsOutdated().

Here is the call graph for this function:

deleteAll ( )

{Deletes all cache items in a bin.

See Also
::invalidateAll()
::delete()
::deleteMultiple()
}

Implements CacheBackendInterface.

References ChainedFastBackend\markAsOutdated().

Here is the call graph for this function:

deleteMultiple ( array  $cids)

{Deletes multiple items from the cache.If the cache items are being deleted because they are no longer "fresh", you may consider using invalidateMultiple() instead. This allows callers to retrieve the invalid items by calling get() with $allow_invalid set to TRUE. In some cases an invalid item may be acceptable rather than having to rebuild the cache.

Parameters
array$cidsAn array of cache IDs to delete.
See Also
::invalidateMultiple()
::delete()
::deleteAll()
}

Implements CacheBackendInterface.

References ChainedFastBackend\markAsOutdated().

Here is the call graph for this function:

garbageCollection ( )

{Performs garbage collection on a cache bin.The backend may choose to delete expired or invalidated items.}

Implements CacheBackendInterface.

get (   $cid,
  $allow_invalid = FALSE 
)

{Returns data from the persistent cache.

Parameters
string$cidThe cache ID of the data to retrieve.
bool$allow_invalid(optional) If TRUE, a cache item may be returned even if it is expired or has been invalidated. Such items may sometimes be preferred, if the alternative is recalculating the value stored in the cache, especially if another concurrent request is already recalculating the same value. The "valid" property of the returned object indicates whether the item is valid or not. Defaults to FALSE.
Returns
object|false The cache item or FALSE on failure.
See Also
::getMultiple()
}

Implements CacheBackendInterface.

References ChainedFastBackend\getMultiple(), and ChainedFastBackend\reset().

Referenced by ChainedFastBackendFactory\get().

Here is the call graph for this function:

Here is the caller graph for this function:

getLastWriteTimestamp ( )
protected

Gets the last write timestamp.

Referenced by ChainedFastBackend\getMultiple(), and ChainedFastBackend\markAsOutdated().

Here is the caller graph for this function:

getMultiple ( $cids,
  $allow_invalid = FALSE 
)

{Returns data from the persistent cache when given an array of cache IDs.

Parameters
array$cidsAn array of cache IDs for the data to retrieve. This is passed by reference, and will have the IDs successfully returned from cache removed.
bool$allow_invalid(optional) If TRUE, cache items may be returned even if they have expired or been invalidated. Such items may sometimes be preferred, if the alternative is recalculating the value stored in the cache, especially if another concurrent thread is already recalculating the same value. The "valid" property of the returned objects indicates whether the items are valid or not. Defaults to FALSE.
Returns
array An array of cache item objects indexed by cache ID.
See Also
::get()
}

Implements CacheBackendInterface.

References ChainedFastBackend\getLastWriteTimestamp().

Referenced by ChainedFastBackend\get().

Here is the call graph for this function:

Here is the caller graph for this function:

invalidate (   $cid)

{Marks a cache item as invalid.Invalid items may be returned in later calls to get(), if the $allow_invalid argument is TRUE.

Parameters
string$cidThe cache ID to invalidate.
See Also
::delete()
::invalidateMultiple()
::invalidateAll()
}

Implements CacheBackendInterface.

References ChainedFastBackend\invalidateMultiple().

Here is the call graph for this function:

invalidateAll ( )

{Marks all cache items as invalid.Invalid items may be returned in later calls to get(), if the $allow_invalid argument is TRUE.

See Also
::deleteAll()
::invalidate()
::invalidateMultiple()
}

Implements CacheBackendInterface.

References ChainedFastBackend\markAsOutdated().

Here is the call graph for this function:

invalidateMultiple ( array  $cids)

{Marks cache items as invalid.Invalid items may be returned in later calls to get(), if the $allow_invalid argument is TRUE.

Parameters
string[]$cids An array of cache IDs to invalidate.
See Also
::deleteMultiple()
::invalidate()
::invalidateAll()
}

Implements CacheBackendInterface.

References ChainedFastBackend\markAsOutdated().

Referenced by ChainedFastBackend\invalidate().

Here is the call graph for this function:

Here is the caller graph for this function:

invalidateTags ( array  $tags)

{Marks cache items with any of the specified tags as invalid.

Parameters
string[]$tags The list of tags for which to invalidate cache items.
}

Implements CacheTagsInvalidatorInterface.

References ChainedFastBackend\markAsOutdated().

Here is the call graph for this function:

markAsOutdated ( )
protected

Marks the fast cache bin as outdated because of a write.

References ChainedFastBackend\getLastWriteTimestamp().

Referenced by ChainedFastBackend\delete(), ChainedFastBackend\deleteAll(), ChainedFastBackend\deleteMultiple(), ChainedFastBackend\invalidateAll(), ChainedFastBackend\invalidateMultiple(), ChainedFastBackend\invalidateTags(), ChainedFastBackend\set(), and ChainedFastBackend\setMultiple().

Here is the call graph for this function:

Here is the caller graph for this function:

removeBin ( )

{Remove a cache bin.}

Implements CacheBackendInterface.

reset ( )
Todo:
Document in https://www.drupal.org/node/2311945.

Referenced by ChainedFastBackend\get().

Here is the caller graph for this function:

set (   $cid,
  $data,
  $expire = Cache::PERMANENT,
array  $tags = array() 
)

{Stores data in the persistent cache.Core cache implementations set the created time on cache item with microtime(TRUE) rather than REQUEST_TIME_FLOAT, because the created time of cache items should match when they are created, not when the request started. Apart from being more accurate, this increases the chance an item will legitimately be considered valid.

Parameters
string$cidThe cache ID of the data to store.
mixed$dataThe data to store in the cache. Some storage engines only allow objects up to a maximum of 1MB in size to be stored by default. When caching large arrays or similar, take care to ensure $data does not exceed this size.
int$expireOne of the following values:
  • CacheBackendInterface::CACHE_PERMANENT: Indicates that the item should not be removed unless it is deleted explicitly.
  • A Unix timestamp: Indicates that the item will be considered invalid after this time, i.e. it will not be returned by get() unless $allow_invalid has been set to TRUE. When the item has expired, it may be permanently deleted by the garbage collector at any time.
array$tagsAn array of tags to be stored with the cache item. These should normally identify objects used to build the cache item, which should trigger cache invalidation when updated. For example if a cached item represents a node, both the node ID and the author's user ID might be passed in as tags. For example array('node' => array(123), 'user' => array(92)).
See Also
::get()
::getMultiple()
}

Implements CacheBackendInterface.

References ChainedFastBackend\markAsOutdated().

Here is the call graph for this function:

setMultiple ( array  $items)

{Store multiple items in the persistent cache.

Parameters
array$itemsAn array of cache items, keyed by cid. In the form:
$items = array(
$cid => array(
// Required, will be automatically serialized if not a string.
'data' => $data,
// Optional, defaults to CacheBackendInterface::CACHE_PERMANENT.
// (optional) The cache tags for this item, see CacheBackendInterface::set().
'tags' => array(),
),
);
}

Implements CacheBackendInterface.

References ChainedFastBackend\markAsOutdated().

Here is the call graph for this function:

Field Documentation

const LAST_WRITE_TIMESTAMP_PREFIX = 'last_write_timestamp_'

Cache key prefix for the bin-specific entry to track the last write.

Referenced by ChainedFastBackendTest\testFallThroughToConsistentCache(), and ChainedFastBackendTest\testGetDoesntHitConsistentBackend().


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