Drake
CacheEntry Class Reference

A CacheEntry belongs to a System and represents the properties of one of that System's cached computations. More...

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

Public Types

using AllocCallback = std::function< std::unique_ptr< AbstractValue >()>
 Signature of a function suitable for allocating an object that can hold a value of a particular cache entry. More...
 
using CalcCallback = std::function< void(const ContextBase &, AbstractValue *)>
 Signature of a function suitable for calculating a value of a particular cache entry, given a place to put the value. More...
 

Public Member Functions

 CacheEntry (const internal::SystemMessageInterface *owning_subsystem, CacheIndex index, DependencyTicket ticket, std::string description, AllocCallback alloc_function, CalcCallback calc_function, std::vector< DependencyTicket > prerequisites_of_calc)
 (Advanced) Constructs a cache entry within a System and specifies the resources it needs. More...
 
const std::vector< DependencyTicket > & prerequisites () const
 Returns a reference to the list of prerequisites needed by this cache entry's Calc() function. More...
 
std::unique_ptr< AbstractValueAllocate () const
 Invokes this cache entry's allocator function to allocate a concrete object suitable for holding the value to be held in this cache entry, and returns that as an AbstractValue. More...
 
void Calc (const ContextBase &context, AbstractValue *value) const
 Unconditionally computes the value this cache entry should have given a particular context, into an already-allocated object. More...
 
template<typename ValueType >
const ValueType & Eval (const ContextBase &context) const
 Returns a reference to the up-to-date value of this cache entry contained in the given Context. More...
 
const AbstractValueEvalAbstract (const ContextBase &context) const
 Returns a reference to the up-to-date abstract value of this cache entry contained in the given Context. More...
 
template<typename ValueType >
const ValueType & GetKnownUpToDate (const ContextBase &context) const
 Returns a reference to the known up-to-date value of this cache entry contained in the given Context. More...
 
const AbstractValueGetKnownUpToDateAbstract (const ContextBase &context) const
 Returns a reference to the known up-to-date abstract value of this cache entry contained in the given Context. More...
 
bool is_out_of_date (const ContextBase &context) const
 Returns true if the current value of this cache entry is out of date with respect to its prerequisites. More...
 
bool is_cache_entry_disabled (const ContextBase &context) const
 (Debugging) Returns true if caching has been disabled for this cache entry. More...
 
void disable_caching (const ContextBase &context) const
 (Debugging) Disables caching for this cache entry. More...
 
void enable_caching (const ContextBase &context) const
 (Debugging) Enables caching for this cache entry if it was previously disabled. More...
 
const std::string & description () const
 Return the human-readable description for this CacheEntry. More...
 
const CacheEntryValueget_cache_entry_value (const ContextBase &context) const
 (Advanced) Returns a const reference to the CacheEntryValue object that corresponds to this CacheEntry, from the supplied Context. More...
 
CacheEntryValueget_mutable_cache_entry_value (const ContextBase &context) const
 (Advanced) Returns a mutable reference to the CacheEntryValue object that corresponds to this CacheEntry, from the supplied Context. More...
 
CacheIndex cache_index () const
 Returns the CacheIndex used to locate this CacheEntry within the containing System. More...
 
DependencyTicket ticket () const
 Returns the DependencyTicket used to register dependencies on the value of this CacheEntry. More...
 
Does not allow copy, move, or assignment
 CacheEntry (const CacheEntry &)=delete
 
CacheEntryoperator= (const CacheEntry &)=delete
 
 CacheEntry (CacheEntry &&)=delete
 
CacheEntryoperator= (CacheEntry &&)=delete
 

Detailed Description

A CacheEntry belongs to a System and represents the properties of one of that System's cached computations.

CacheEntry objects are assigned CacheIndex values in the order they are declared; these are unique within a single System and can be used for quick access to both the CacheEntry and the corresponding CacheEntryValue in the System's Context.

CacheEntry objects are allocated automatically for known System computations like output ports and time derivatives, and may also be allocated by user code for other cached computations.

A cache entry's value is always stored as an AbstractValue, which can hold a concrete value of any copyable type. However, once a value has been allocated using a particular concrete type, the type cannot be changed.

CacheEntry objects support four important operations:

  • Allocate() returns an object that can hold the cached value.
  • Calc() unconditionally computes the cached value.
  • Eval() returns a reference to the cached value, first updating with Calc() if it was out of date.
  • GetKnownUpToDate() returns a reference to the current value that you are certain must already be up to date.

The allocation and calculation functions must be provided at the time a cache entry is declared. That is typically done in a System constructor, in a manner very similar to the declaration of output ports.

Member Typedef Documentation

using AllocCallback = std::function<std::unique_ptr<AbstractValue>()>

Signature of a function suitable for allocating an object that can hold a value of a particular cache entry.

The result is always returned as an AbstractValue but must contain the correct concrete type.

using CalcCallback = std::function<void(const ContextBase&, AbstractValue*)>

Signature of a function suitable for calculating a value of a particular cache entry, given a place to put the value.

Constructor & Destructor Documentation

CacheEntry ( const CacheEntry )
delete
CacheEntry ( CacheEntry &&  )
delete
CacheEntry ( const internal::SystemMessageInterface *  owning_subsystem,
CacheIndex  index,
DependencyTicket  ticket,
std::string  description,
AllocCallback  alloc_function,
CalcCallback  calc_function,
std::vector< DependencyTicket prerequisites_of_calc 
)

(Advanced) Constructs a cache entry within a System and specifies the resources it needs.

This method is intended only for use by the framework which provides much nicer APIs for end users. See DeclareCacheEntry for the user-facing API documentation.

The supplied allocator must return a suitable AbstractValue in which to hold the result. The supplied calculator function must write to an AbstractValue of the same underlying concrete type as is returned by the allocator. The allocator function is not invoked here during construction of the cache entry. Instead allocation is deferred until the allocator can be provided with a complete Context, which cannot occur until the full Diagram containing this subsystem has been completed. That way the initial type, size, or value can Context-dependent. The supplied prerequisite tickets are interpreted as belonging to the same subsystem that owns this CacheEntry.

The list of prerequisites cannot be empty – a cache entry that really has no prerequisites must say so explicitly by providing a list containing only nothing_ticket() as a prerequisite. The subsystem pointer must not be null, and the cache index and ticket must be valid. The description is an arbitrary string not interpreted in any way by Drake.

Exceptions
std::logic_errorif the prerequisite list is empty.
See also
drake::systems::SystemBase::DeclareCacheEntry()

Here is the call graph for this function:

Member Function Documentation

std::unique_ptr< AbstractValue > Allocate ( ) const

Invokes this cache entry's allocator function to allocate a concrete object suitable for holding the value to be held in this cache entry, and returns that as an AbstractValue.

The returned object will never be null.

Exceptions
std::logic_errorif the allocator function returned null.

Here is the caller graph for this function:

CacheIndex cache_index ( ) const
inline

Returns the CacheIndex used to locate this CacheEntry within the containing System.

Here is the caller graph for this function:

void Calc ( const ContextBase context,
AbstractValue value 
) const

Unconditionally computes the value this cache entry should have given a particular context, into an already-allocated object.

Precondition
context is a subcontext that is compatible with the subsystem that owns this cache entry.
value is non null and has exactly the same concrete type as that of the object returned by this entry's Allocate() method.

Here is the call graph for this function:

Here is the caller graph for this function:

const std::string& description ( ) const
inline

Return the human-readable description for this CacheEntry.

Here is the caller graph for this function:

void disable_caching ( const ContextBase context) const
inline

(Debugging) Disables caching for this cache entry.

Eval() will recompute the cached value every time it is invoked, regardless of the state of the out_of_date flag. That should have no effect on any computed results, other than speed. See class documentation for ideas as to what might be wrong if you see a change. Note that the context is const here; cache entry values are mutable.

Here is the call graph for this function:

void enable_caching ( const ContextBase context) const
inline

(Debugging) Enables caching for this cache entry if it was previously disabled.

Here is the call graph for this function:

const ValueType& Eval ( const ContextBase context) const
inline

Returns a reference to the up-to-date value of this cache entry contained in the given Context.

This is the preferred way to obtain a cached value. If the value is not already up to date with respect to its prerequisites, or if caching is disabled for this entry, then this entry's Calc() method is used first to update the value before the reference is returned. The Calc() method may be arbitrarily expensive, but this method is constant time and very fast if the value is already up to date. If you are certain the value should be up to date already, you may use the GetKnownUpToDate() method instead.

Precondition
context is a subcontext that is compatible with the subsystem that owns this cache entry.
Exceptions
std::logic_errorif the value doesn't actually have type V.

Here is the call graph for this function:

const AbstractValue& EvalAbstract ( const ContextBase context) const
inline

Returns a reference to the up-to-date abstract value of this cache entry contained in the given Context.

If the value is not already up to date with respect to its prerequisites, or if caching is disabled for this entry, the Calc() method above is used first to update the value before the reference is returned. This method is constant time and very fast if the value doesn't need to be recomputed.

Precondition
context is a subcontext that is compatible with the subsystem that owns this cache entry.

Here is the call graph for this function:

Here is the caller graph for this function:

const CacheEntryValue& get_cache_entry_value ( const ContextBase context) const
inline

(Advanced) Returns a const reference to the CacheEntryValue object that corresponds to this CacheEntry, from the supplied Context.

The returned object contains the current value and tracks whether it is up to date with respect to its prerequisites. If you just need the value, use the Eval() method rather than this one. This method is constant time and very fast in all circumstances.

Here is the call graph for this function:

Here is the caller graph for this function:

CacheEntryValue& get_mutable_cache_entry_value ( const ContextBase context) const
inline

(Advanced) Returns a mutable reference to the CacheEntryValue object that corresponds to this CacheEntry, from the supplied Context.

Note that context is const; cache values are mutable. Don't call this method unless you know what you're doing. This method is constant time and very fast in all circumstances.

Here is the call graph for this function:

Here is the caller graph for this function:

const ValueType& GetKnownUpToDate ( const ContextBase context) const
inline

Returns a reference to the known up-to-date value of this cache entry contained in the given Context.

The purpose of this method is to avoid unexpected recomputations in circumstances where you believe the value must already be up to date. Unlike Eval(), this method will throw an exception if the value is out of date; it will never attempt a recomputation. The behavior here is unaffected if caching is disabled for this cache entry – it looks only at the out_of_date flag which is still maintained when caching is disabled. This method is constant time and very fast if it succeeds.

Precondition
context is a subcontext that is compatible with the subsystem that owns this cache entry.
Exceptions
std::logic_errorif the value is out of date or if it does not actually have type ValueType.

Here is the call graph for this function:

const AbstractValue& GetKnownUpToDateAbstract ( const ContextBase context) const
inline

Returns a reference to the known up-to-date abstract value of this cache entry contained in the given Context.

See GetKnownUpToDate() for more information.

Precondition
context is a subcontext that is compatible with the subsystem that owns this cache entry.
Exceptions
std::logic_errorif the value is not up to date.

Here is the call graph for this function:

bool is_cache_entry_disabled ( const ContextBase context) const
inline

(Debugging) Returns true if caching has been disabled for this cache entry.

That means Eval() will recalculate even if the entry is marked up to date.

Here is the call graph for this function:

bool is_out_of_date ( const ContextBase context) const
inline

Returns true if the current value of this cache entry is out of date with respect to its prerequisites.

If this returns false then the Eval() method will not perform any computation when invoked, unless caching has been disabled for this entry. If this returns true the GetKnownUpToDate() methods will fail if invoked.

Here is the call graph for this function:

CacheEntry& operator= ( CacheEntry &&  )
delete
CacheEntry& operator= ( const CacheEntry )
delete
const std::vector<DependencyTicket>& prerequisites ( ) const
inline

Returns a reference to the list of prerequisites needed by this cache entry's Calc() function.

These are all within the same subsystem that owns this CacheEntry.

Here is the call graph for this function:

Here is the caller graph for this function:

DependencyTicket ticket ( ) const
inline

Returns the DependencyTicket used to register dependencies on the value of this CacheEntry.

This can also be used to locate the DependencyTracker that manages dependencies at runtime for the associated CacheEntryValue in a Context.

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: