Drake
Cache Class Reference

Cache is a key-value store used within the System2 framework to avoid computing intermediate data multiple times during simulation or analysis. More...

#include <drake/systems/framework/cache.h>

Public Member Functions

 Cache ()
 
 ~Cache ()
 
CacheTicket MakeCacheTicket (const std::set< CacheTicket > &prerequisites)
 Creates a new cache ticket, which will be invalidated whenever any of the prerequisites are invalidated. More...
 
void Invalidate (CacheTicket ticket)
 Invalidates the value for ticket, and all entries that depend on it. More...
 
AbstractValueInit (CacheTicket ticket, std::unique_ptr< AbstractValue > value)
 Takes ownership of a cached item, and returns a bare pointer to the item. More...
 
template<typename T >
void Set (CacheTicket ticket, const T &value)
 Sets a cache entry to the given value. More...
 
const AbstractValueGet (CacheTicket ticket) const
 Returns the cached item for the given ticket, or nullptr if the item has been invalidated. More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 Cache (const Cache &)=default
 
Cacheoperator= (const Cache &)=default
 
 Cache (Cache &&)=default
 
Cacheoperator= (Cache &&)=default
 

Detailed Description

Cache is a key-value store used within the System2 framework to avoid computing intermediate data multiple times during simulation or analysis.

It is not a general-purpose caching layer.

Every Cache will be private to a System, stored within and accessible via the System's Context. Its function is to return a previously-computed value X, so long as no other value upon which X depends has changed. The System declares the expensive values it will compute, and their dependencies, by calling MakeCacheTicket. It provides type-erased storage for the value using Init - typically just once - and thereafter sets the value using Set, or retrieves it using Get.

Whenever Init or Set is called, all entries which depend on the ticket being written are "invalidated". Once a ticket is invalidated, calls to Get for that ticket will return nullptr until it itself is written again. For this reason, a System must call Get whenever it needs access to a cached value; it must not hold the returned pointer.

Cache is not thread-safe. It is copyable, assignable, and movable.

Constructor & Destructor Documentation

Cache ( const Cache )
default
Cache ( Cache &&  )
default
Cache ( )
~Cache ( )

Member Function Documentation

const AbstractValue * Get ( CacheTicket  ticket) const

Returns the cached item for the given ticket, or nullptr if the item has been invalidated.

The bare pointer should not be held, because the data may become invalid if the ticket's prerequisites are modified.

Here is the call graph for this function:

Here is the caller graph for this function:

AbstractValue * Init ( CacheTicket  ticket,
std::unique_ptr< AbstractValue value 
)

Takes ownership of a cached item, and returns a bare pointer to the item.

Marks the entry itself as valid, and invalidates all entries that depend on it.

The bare pointer may be used to modify the entry immediately, but should not be held, because it may become invalid if the ticket's prerequisites are modified. It will only actually be deleted on subsequent calls to Init for this ticket, or on the deletion of the Cache itself; however, only advanced, careful users should rely on that behavior.

Here is the call graph for this function:

Here is the caller graph for this function:

void Invalidate ( CacheTicket  ticket)

Invalidates the value for ticket, and all entries that depend on it.

Here is the call graph for this function:

CacheTicket MakeCacheTicket ( const std::set< CacheTicket > &  prerequisites)

Creates a new cache ticket, which will be invalidated whenever any of the prerequisites are invalidated.

Here is the caller graph for this function:

Cache& operator= ( Cache &&  )
default
Cache& operator= ( const Cache )
default
void Set ( CacheTicket  ticket,
const T &  value 
)
inline

Sets a cache entry to the given value.

Aborts if the value has not already been initialized. May throw std::bad_cast if the value has been initialized with a different type. Marks the entry itself as valid, and invalidates all entries that depend on it.

Template Parameters
TThe type of the value.

Here is the call graph for this function:

Here is the caller graph for this function:


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