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_system, CacheIndex index, DependencyTicket ticket, std::string description, AllocCallback alloc_function, CalcCallback calc_function, std::set< DependencyTicket > prerequisites_of_calc)
(Advanced) Constructs a cache entry within a System and specifies the resources it needs. More...

const std::set< DependencyTicket > & prerequisites () const
Returns a reference to the set of prerequisites needed by this cache entry's Calc() function. More...

std::set< DependencyTicket > & mutable_prerequisites ()
(Advanced) Returns a mutable reference to the set of prerequisites needed by this 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.

## ◆ AllocCallback

 using AllocCallback = std::function()>

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.

## ◆ CalcCallback

 using CalcCallback = std::function

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

## ◆ CacheEntry() [1/3]

 CacheEntry ( const CacheEntry & )
delete

## ◆ CacheEntry() [2/3]

 CacheEntry ( CacheEntry && )
delete

## ◆ CacheEntry() [3/3]

 CacheEntry ( const internal::SystemMessageInterface * owning_system, CacheIndex index, DependencyTicket ticket, std::string description, AllocCallback alloc_function, CalcCallback calc_function, std::set< 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_error if the prerequisite list is empty.
drake::systems::SystemBase::DeclareCacheEntry()

## ◆ Allocate()

 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_error if the allocator function returned null.

## ◆ cache_index()

 CacheIndex cache_index ( ) const

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

## ◆ Calc()

 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.

## ◆ description()

 const std::string& description ( ) const

Return the human-readable description for this CacheEntry.

## ◆ disable_caching()

 void disable_caching ( const ContextBase & context ) const

(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.

## ◆ enable_caching()

 void enable_caching ( const ContextBase & context ) const

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

## ◆ Eval()

 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.

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_error if the value doesn't actually have type V.

## ◆ EvalAbstract()

 const AbstractValue& EvalAbstract ( const ContextBase & context ) const

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.

## ◆ get_cache_entry_value()

 const CacheEntryValue& get_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.

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.

## ◆ get_mutable_cache_entry_value()

 CacheEntryValue& get_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.

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.

## ◆ GetKnownUpToDate()

 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.

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_error if the value is out of date or if it does not actually have type ValueType.

## ◆ GetKnownUpToDateAbstract()

 const AbstractValue& GetKnownUpToDateAbstract ( const ContextBase & context ) const

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

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

## ◆ is_cache_entry_disabled()

 bool is_cache_entry_disabled ( const ContextBase & context ) const

(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.

## ◆ is_out_of_date()

 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.

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.

## ◆ mutable_prerequisites()

 std::set& mutable_prerequisites ( )

(Advanced) Returns a mutable reference to the set of prerequisites needed by this entry's Calc() function.

Any tickets in this set are interpreted as referring to prerequisites within the same subsystem that owns this CacheEntry. Modifications take effect the next time the containing System is asked to create a Context.

A cache entry should normally be given its complete set of prerequisites at the time it is declared (typically in a System constructor). If possible, defer declaration of cache entries until all their prerequisites have been declared so that all necessary tickets are available. In Systems with complicated extended construction phases it may be awkward or impossible to know all the prerequisites at that time. In that case, consider choosing a comprehensive prerequisite like all_input_ports_ticket() that can include as-yet-undeclared prerequisites. If performance requirements preclude that approach, then an advanced user may use this method to add more prerequisites as their tickets become available.

## ◆ operator=() [1/2]

 CacheEntry& operator= ( CacheEntry && )
delete

## ◆ operator=() [2/2]

 CacheEntry& operator= ( const CacheEntry & )
delete

## ◆ prerequisites()

 const std::set& prerequisites ( ) const

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

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

## ◆ ticket()

 DependencyTicket ticket ( ) const

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.

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