|
Drake
|
|
Drake
|
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:
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.
#include <drake/systems/framework/cache_entry.h>
Public Member Functions | |
| CacheEntry (const internal::SystemMessageInterface *owning_system, CacheIndex index, DependencyTicket ticket, std::string description, ValueProducer value_producer, 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< 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. 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 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. 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 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. 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 in the given context. More... | |
| void | disable_caching (const ContextBase &context) const |
(Debugging) Disables caching for this cache entry in the given context. More... | |
| void | enable_caching (const ContextBase &context) const |
(Debugging) Enables caching for this cache entry in the given context if it was previously disabled. More... | |
| void | disable_caching_by_default () |
(Debugging) Marks this cache entry so that the corresponding CacheEntryValue object in any allocated Context is created with its disabled flag initially set. More... | |
| bool | is_disabled_by_default () const |
| (Debugging) Returns the current value of this flag. More... | |
| const std::string & | description () const |
| Return the human-readable description for this CacheEntry. More... | |
| 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. More... | |
| 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. 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... | |
| bool | has_default_prerequisites () const |
(Advanced) Returns true if this cache entry was created without specifying any prerequisites. More... | |
Does not allow copy, move, or assignment | |
| CacheEntry (const CacheEntry &)=delete | |
| CacheEntry & | operator= (const CacheEntry &)=delete |
| CacheEntry (CacheEntry &&)=delete | |
| CacheEntry & | operator= (CacheEntry &&)=delete |
|
delete |
|
delete |
| CacheEntry | ( | const internal::SystemMessageInterface * | owning_system, |
| CacheIndex | index, | ||
| DependencyTicket | ticket, | ||
| std::string | description, | ||
| ValueProducer | value_producer, | ||
| 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 ValueProducer embeds both an allocator and calculator function. 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 be 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.
| std::exception | if the prerequisite list is empty. |
| 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.
| std::exception | if the allocator function returned null. |
| CacheIndex cache_index | ( | ) | const |
Returns the CacheIndex used to locate this CacheEntry within the containing System.
| 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.
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. | const std::string& description | ( | ) | const |
Return the human-readable description for this CacheEntry.
| void disable_caching | ( | const ContextBase & | context | ) | const |
(Debugging) Disables caching for this cache entry in the given context.
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.
| void disable_caching_by_default | ( | ) |
(Debugging) Marks this cache entry so that the corresponding CacheEntryValue object in any allocated Context is created with its disabled flag initially set.
This can be useful for debugging when you have observed a difference between cached and non-cached behavior that can't be diagnosed with the runtime disable_caching() method.
| void enable_caching | ( | const ContextBase & | context | ) | const |
(Debugging) Enables caching for this cache entry in the given context if it was previously disabled.
| 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.
context is a subcontext that is compatible with the subsystem that owns this cache entry. | std::exception | if the value doesn't actually have type V. |
| 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.
context is a subcontext that is compatible with the subsystem that owns this cache entry. | 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.
| 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.
| 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.
context is a subcontext that is compatible with the subsystem that owns this cache entry. | std::exception | if the value is out of date or if it does not actually have type ValueType. |
| 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.
See GetKnownUpToDate() for more information.
context is a subcontext that is compatible with the subsystem that owns this cache entry. | std::exception | if the value is not up to date. |
| bool has_default_prerequisites | ( | ) | const |
(Advanced) Returns true if this cache entry was created without specifying any prerequisites.
This can be useful in determining whether the apparent dependencies should be believed, or whether they may just be due to some user's ignorance.
all_sources_ticket()) and "prerequisite
specified as `all_sources_ticket()`". Either of those cases makes this method return true now, but we intend to change so that explicit specification of all_sources_ticket() will be considered non-default. So don't depend on the current behavior. | bool is_cache_entry_disabled | ( | const ContextBase & | context | ) | const |
(Debugging) Returns true if caching has been disabled for this cache entry in the given context.
That means Eval() will recalculate even if the entry is marked up to date.
| bool is_disabled_by_default | ( | ) | const |
(Debugging) Returns the current value of this flag.
It is false unless a call to disable_caching_by_default() has previously been made.
| 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.
| std::set<DependencyTicket>& 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.
|
delete |
|
delete |
| const std::set<DependencyTicket>& 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.
| 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.