Drake
Drake C++ Documentation
Cache Class Reference

Detailed Description

(Advanced) Stores all the CacheEntryValue objects owned by a particular Context, organized to allow fast access using a CacheIndex as an index.

Most users will not use this class directly – System and CacheEntry provide the most common APIs, and Context provides additional useful methods.

See also
System, CacheEntry, Context for user-facing APIs.

Memory addresses of CacheEntryValue objects are stable once allocated, but CacheIndex numbers are stable even after a Context has been copied so should be preferred as a means for identifying particular cache entries.

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

Public Member Functions

 Cache (const internal::ContextMessageInterface *owning_subcontext)
 Constructor creates an empty cache referencing the system pathname service of its owning subcontext. More...
 
 ~Cache ()=default
 Destruction deletes all cache entries and their contained values; no dependency notifications are issued. More...
 
CacheEntryValueCreateNewCacheEntryValue (CacheIndex index, DependencyTicket ticket, const std::string &description, const std::set< DependencyTicket > &prerequisites, DependencyGraph *graph)
 Allocates a new CacheEntryValue and provides it a DependencyTracker using the given CacheIndex and DependencyTicket number. More...
 
bool has_cache_entry_value (CacheIndex index) const
 Returns true if there is a CacheEntryValue in this cache that has the given index. More...
 
int cache_size () const
 Returns the current size of the Cache container, providing for CacheIndex values from 0..cache_size()-1. More...
 
const CacheEntryValueget_cache_entry_value (CacheIndex index) const
 Returns a const CacheEntryValue given an index. More...
 
CacheEntryValueget_mutable_cache_entry_value (CacheIndex index)
 Returns a mutable CacheEntryValue given an index. More...
 
void DisableCaching ()
 (Advanced) Disables caching for all the entries in this Cache. More...
 
void EnableCaching ()
 (Advanced) Re-enables caching for all entries in this Cache if any were previously disabled. More...
 
void SetAllEntriesOutOfDate ()
 (Advanced) Mark every entry in this cache as "out of date". More...
 
void freeze_cache ()
 (Advanced) Sets the "is frozen" flag. More...
 
void unfreeze_cache ()
 (Advanced) Clears the "is frozen" flag, permitting normal cache activity. More...
 
bool is_cache_frozen () const
 (Advanced) Reports the current value of the "is frozen" flag. More...
 
CacheEntryValuedummy_cache_entry_value ()
 (Internal use only) Returns a mutable reference to a dummy CacheEntryValue that can serve as a /dev/null-like destination for throw-away writes. More...
 
Does not allow move or assignment; copy constructor is private.
 Cache (Cache &&)=delete
 
void operator= (const Cache &)=delete
 
void operator= (Cache &&)=delete
 

Friends

class ContextBase
 

Constructor & Destructor Documentation

◆ Cache() [1/2]

Cache ( Cache &&  )
delete

◆ Cache() [2/2]

Cache ( const internal::ContextMessageInterface *  owning_subcontext)
explicit

Constructor creates an empty cache referencing the system pathname service of its owning subcontext.

The supplied pointer must not be null.

◆ ~Cache()

~Cache ( )
default

Destruction deletes all cache entries and their contained values; no dependency notifications are issued.

Member Function Documentation

◆ cache_size()

int cache_size ( ) const

Returns the current size of the Cache container, providing for CacheIndex values from 0..cache_size()-1.

Note that it is possible to have empty slots in the cache. Use has_cache_entry_value() to determine if there is a cache entry associated with a particular index.

◆ CreateNewCacheEntryValue()

CacheEntryValue& CreateNewCacheEntryValue ( CacheIndex  index,
DependencyTicket  ticket,
const std::string &  description,
const std::set< DependencyTicket > &  prerequisites,
DependencyGraph graph 
)

Allocates a new CacheEntryValue and provides it a DependencyTracker using the given CacheIndex and DependencyTicket number.

The CacheEntryValue object is owned by this Cache and the returned reference remains valid if other cache entry values are created. If there is a pre-existing tracker with the given ticket number (allowed only for well-known cached computations, such as time derivatives), it is assigned the new cache entry value to manage. Otherwise a new DependencyTracker is created. The created tracker object is owned by the given DependencyGraph, which must be owned by the same Context that owns this Cache. The graph must already contain trackers for the indicated prerequisites. The tracker will retain a pointer to the created CacheEntryValue for invalidation purposes.

◆ DisableCaching()

void DisableCaching ( )

(Advanced) Disables caching for all the entries in this Cache.

Note that this is done by setting individual is_disabled flags in the entries, so it can be changed on a per-entry basis later. This has no effect on the out_of_date flags.

◆ dummy_cache_entry_value()

CacheEntryValue& dummy_cache_entry_value ( )

(Internal use only) Returns a mutable reference to a dummy CacheEntryValue that can serve as a /dev/null-like destination for throw-away writes.

◆ EnableCaching()

void EnableCaching ( )

(Advanced) Re-enables caching for all entries in this Cache if any were previously disabled.

Note that this is done by clearing individual is_disabled flags in the entries, so it overrides any disabling that may have been done to individual entries. This has no effect on the out_of_date flags so subsequent Eval() calls might not initiate recomputation. Use SetAllEntriesOutOfDate() if you want to force recomputation.

◆ freeze_cache()

void freeze_cache ( )

(Advanced) Sets the "is frozen" flag.

Cache entry values should check this before permitting mutable access to values.

See also
ContextBase::FreezeCache() for the user-facing API

◆ get_cache_entry_value()

const CacheEntryValue& get_cache_entry_value ( CacheIndex  index) const

Returns a const CacheEntryValue given an index.

This is very fast. Behavior is undefined if the index is out of range [0..cache_size()-1] or if there is no CacheEntryValue with that index. Use has_cache_entry_value() first if you aren't sure.

◆ get_mutable_cache_entry_value()

CacheEntryValue& get_mutable_cache_entry_value ( CacheIndex  index)

Returns a mutable CacheEntryValue given an index.

This is very fast. Behavior is undefined if the index is out of range [0..cache_size()-1] or if there is no CacheEntryValue with that index. Use has_cache_entry_value() first if you aren't sure.

◆ has_cache_entry_value()

bool has_cache_entry_value ( CacheIndex  index) const

Returns true if there is a CacheEntryValue in this cache that has the given index.

◆ is_cache_frozen()

bool is_cache_frozen ( ) const

(Advanced) Reports the current value of the "is frozen" flag.

See also
ContextBase::is_cache_frozen() for the user-facing API

◆ operator=() [1/2]

void operator= ( const Cache )
delete

◆ operator=() [2/2]

void operator= ( Cache &&  )
delete

◆ SetAllEntriesOutOfDate()

void SetAllEntriesOutOfDate ( )

(Advanced) Mark every entry in this cache as "out of date".

This forces the next Eval() request for an entry to perform a recalculation. After that normal caching behavior resumes.

◆ unfreeze_cache()

void unfreeze_cache ( )

(Advanced) Clears the "is frozen" flag, permitting normal cache activity.

See also
ContextBase::UnfreezeCache() for the user-facing API

Friends And Related Function Documentation

◆ ContextBase

friend class ContextBase
friend

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