Drake
Drake C++ Documentation
DependencyGraph Class Reference

Detailed Description

Represents the portion of the complete dependency graph that is a subgraph centered on the owning subcontext, plus some edges leading to other subcontexts.

DependencyTracker objects are the nodes of the graph, and maintain prerequisite/subscriber edges that interconnect these nodes, and may also connect to nodes contained in dependency graphs belonging to other subcontexts within the same complete context tree. Dependencies on the parent (containing DiagramContext) and children (contained subcontexts) typically arise from exported input and output ports, while sibling dependencies arise from output-to-input port connections.

A DependencyGraph creates and owns all the DependencyTracker objects for a particular subcontext, organized to allow fast access using a DependencyTicket as an index. Memory addresses of DependencyTracker objects are stable once allocated, but DependencyTicket numbers are stable even after a Context has been copied so should be preferred.

Because DependencyTrackers contain pointers, copying a DependencyGraph must always be done as part of copying an entire Context tree. There is a copy constructor here but it must be followed by a pointer-fixup step so is for internal use only.

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

Public Member Functions

 DependencyGraph (const internal::ContextMessageInterface *owning_subcontext)
 Constructor creates an empty graph referencing the system pathname service of its owning subcontext. More...
 
 ~DependencyGraph ()=default
 Deletes all DependencyTracker objects; no notifications are issued. More...
 
DependencyTrackerCreateNewDependencyTracker (DependencyTicket known_ticket, std::string description, CacheEntryValue *cache_value=nullptr)
 Allocates a new DependencyTracker with an already-known ticket number, the given description and an optional cache value to be invalidated. More...
 
DependencyTrackerCreateNewDependencyTracker (std::string description, CacheEntryValue *cache_value=nullptr)
 Assigns a new ticket number and then allocates a new DependencyTracker that can be accessed with that ticket. More...
 
bool has_tracker (DependencyTicket ticket) const
 Returns true if there is a DependencyTracker in this graph that has the given ticket number. More...
 
int trackers_size () const
 Returns the current size of the DependencyTracker container, providing for DependencyTicket numbers from 0..trackers_size()-1. More...
 
const DependencyTrackerget_tracker (DependencyTicket ticket) const
 Returns a const DependencyTracker given a ticket. More...
 
DependencyTrackerget_mutable_tracker (DependencyTicket ticket)
 Returns a mutable DependencyTracker given a ticket. More...
 
 DependencyGraph (const DependencyGraph &source)
 (Internal use only) Copy constructor partially duplicates the source DependencyGraph object, with identical structure to the source but with all internal pointers set to null, and all counters and statistics set to their default-constructed values. More...
 
void AppendToTrackerPointerMap (const DependencyGraph &clone, DependencyTracker::PointerMap *tracker_map) const
 (Internal use only) Create a mapping from the memory addresses of the trackers contained here to the corresponding ones in clone, which must have exactly the same number of trackers. More...
 
void RepairTrackerPointers (const DependencyGraph &source, const DependencyTracker::PointerMap &tracker_map, const internal::ContextMessageInterface *owning_subcontext, Cache *new_cache)
 (Internal use only) Assumes this DependencyGraph is a recent clone whose trackers do not yet contain subscriber and prerequisite pointers and sets the local pointers to point to the source-corresponding trackers in the new owning context, the appropriate cache entry values in the new cache, and to the system name providing service of the new owning Context for logging and error reporting. More...
 
Does not allow move or assignment; copy constructor limited.

The copy constructor does not copy internal pointers so requires special handling.

 DependencyGraph (DependencyGraph &&)=delete
 
DependencyGraphoperator= (const DependencyGraph &)=delete
 
DependencyGraphoperator= (DependencyGraph &&)=delete
 

Constructor & Destructor Documentation

◆ DependencyGraph() [1/3]

◆ DependencyGraph() [2/3]

DependencyGraph ( const internal::ContextMessageInterface *  owning_subcontext)
explicit

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

The supplied pointer must not be null.

◆ ~DependencyGraph()

~DependencyGraph ( )
default

Deletes all DependencyTracker objects; no notifications are issued.

◆ DependencyGraph() [3/3]

DependencyGraph ( const DependencyGraph source)

(Internal use only) Copy constructor partially duplicates the source DependencyGraph object, with identical structure to the source but with all internal pointers set to null, and all counters and statistics set to their default-constructed values.

Pointers must be set properly using RepairTrackerPointers() once all the old-to-new pointer mappings have been determined for the whole Context, not just the containing subcontext. This should only be invoked by Context code as part of copying an entire Context tree.

See also
AppendToTrackerPointerMap(), RepairTrackerPointers()

Member Function Documentation

◆ AppendToTrackerPointerMap()

void AppendToTrackerPointerMap ( const DependencyGraph clone,
DependencyTracker::PointerMap tracker_map 
) const

(Internal use only) Create a mapping from the memory addresses of the trackers contained here to the corresponding ones in clone, which must have exactly the same number of trackers.

The mapping is appended to the supplied map, which must not be null.

◆ CreateNewDependencyTracker() [1/2]

DependencyTracker& CreateNewDependencyTracker ( DependencyTicket  known_ticket,
std::string  description,
CacheEntryValue cache_value = nullptr 
)

Allocates a new DependencyTracker with an already-known ticket number, the given description and an optional cache value to be invalidated.

The new tracker has no prerequisites or subscribers yet. This may leave gaps in the node numbering. Use has_tracker() if you need to know whether there is a tracker for a particular ticket. We promise that the returned DependencyTracker's location in memory will remain unchanged once created in a particular Context, even as more trackers are added. The DependencyTicket retains its meaning even after cloning the Context, although of course the tracker has a new address in the clone.

Precondition
The given ticket must be valid.
No DependencyTracker is already using the given ticket.

◆ CreateNewDependencyTracker() [2/2]

DependencyTracker& CreateNewDependencyTracker ( std::string  description,
CacheEntryValue cache_value = nullptr 
)

Assigns a new ticket number and then allocates a new DependencyTracker that can be accessed with that ticket.

You may obtain the assigned ticket from the returned tracker. See the other signature for details.

◆ get_mutable_tracker()

DependencyTracker& get_mutable_tracker ( DependencyTicket  ticket)

Returns a mutable DependencyTracker given a ticket.

This is very fast. Behavior is undefined if the ticket is out of range [0..num_trackers()-1].

◆ get_tracker()

const DependencyTracker& get_tracker ( DependencyTicket  ticket) const

Returns a const DependencyTracker given a ticket.

This is very fast. Behavior is undefined if the ticket is out of range [0..num_trackers()-1].

◆ has_tracker()

bool has_tracker ( DependencyTicket  ticket) const

Returns true if there is a DependencyTracker in this graph that has the given ticket number.

◆ operator=() [1/2]

DependencyGraph& operator= ( const DependencyGraph )
delete

◆ operator=() [2/2]

DependencyGraph& operator= ( DependencyGraph &&  )
delete

◆ RepairTrackerPointers()

void RepairTrackerPointers ( const DependencyGraph source,
const DependencyTracker::PointerMap tracker_map,
const internal::ContextMessageInterface *  owning_subcontext,
Cache new_cache 
)

(Internal use only) Assumes this DependencyGraph is a recent clone whose trackers do not yet contain subscriber and prerequisite pointers and sets the local pointers to point to the source-corresponding trackers in the new owning context, the appropriate cache entry values in the new cache, and to the system name providing service of the new owning Context for logging and error reporting.

The supplied map should map source pointers to their corresponding trackers. It is a fatal error if any old pointer we encounter is not present in the map; that would indicate a bug in the Context cloning code.

◆ trackers_size()

int trackers_size ( ) const

Returns the current size of the DependencyTracker container, providing for DependencyTicket numbers from 0..trackers_size()-1.

Note that it is possible to have empty slots in the container. Use has_tracker() to determine if there is a tracker associated with a particular ticket.


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