The Sparta Modeling Framework
|
Node in a composite tree representing a sparta Tree item. More...
#include <TreeNode.hpp>
Classes | |
struct | ANY_TYPE |
Type for indicating that ANY notification source type should be included in a search performed by locateNotificationSources. More... | |
class | delegate |
Temporary delegate for notificaiton invokation until the implementation is working. This will then be merged with sparta::SpartaHandler. More... | |
class | ExtensionsBase |
Base class used to extend TreeNode parameter sets. More... | |
struct | NotificationInfo |
Notification type/name information. More... | |
class | type_info_container |
Container for std::type_info. More... | |
Public Types | |
Types | |
typedef uint64_t | node_uid_type |
Type of unique-identifier assigned to every node. | |
typedef std::vector< TreeNode * > | ChildrenVector |
Vector of TreeNode children. | |
typedef std::vector< std::string > | AliasVector |
Vector of aliases (other names for this node) | |
typedef std::multimap< std::string, TreeNode * > | ChildNameMapping |
Mapping of names, aliases, and groups to individual child nodes within one node. This must be in a deterministic order, so an ordered container (e.g. std::map) is required. A sorted contained is probably desirable, but not required. | |
typedef uint32_t | group_idx_type |
Index within a group. | |
typedef std::weak_ptr< TreeNode > | WeakPtr |
Weak pointer to a TreeNode. Acquire with getWeakPtr. | |
typedef std::weak_ptr< const TreeNode > | ConstWeakPtr |
Weak pointer to a const TreeNode. Acquire with getWeakPtr. | |
typedef std::shared_ptr< TreeNode > | SharedPtr |
Shared pointer to TreeNode. Acquire with WeakPtr::lock(). | |
typedef std::map< const std::string *, std::vector< TreeNode * > > | TagsMap |
Map of strings (interned in StringManager) tags to TreeNodes. | |
![]() | |
enum | TreePhase { TREE_BUILDING = 0 , TREE_CONFIGURING = 1 , TREE_FINALIZING = 2 , TREE_FINALIZED = 3 , TREE_TEARDOWN = 4 } |
Current phase of tree construction (applies to node and entire tree). More... | |
Public Member Functions | |
const Clock * | getClock () override |
Walks up parents (starting with self) until a parent with an associated local clock is found, then returns that clock. | |
const Clock * | getClock () const |
const Clock * | getLocalClock () |
Gets the clock associated directly with this Node. This is useful for configuration and simulator debug, but not at run-time. | |
const Clock * | getLocalClock () const |
virtual void | setClock (const Clock *clk) |
Assigns a clock to this node. This clock will then be accessed by any descendant which has no assigned clock or an ancestor with an assigned clock between that descendant and this node. getClock returns the Clock associated with the nearest ancestor. | |
Scheduler * | getScheduler (const bool must_exist=false) |
Get the scheduler associated with this tree node's root. | |
const Scheduler * | getScheduler (const bool must_exist=false) const |
WeakPtr | getWeakPtr () |
Gets a weak pointer to this TreeNode. This weak pointer is guaranteed to expire when this TreeNode is destructed unless locked. | |
ConstWeakPtr | getWeakPtr () const |
Const variant of getWeakPtr. | |
virtual void | addLink (TreeNode *node, const std::string &label) |
Link this tree node with another tree node. | |
virtual void | activateLink (const std::string &label) |
Activate one of the links added with addLink. | |
Construction | |
TreeNode ()=delete | |
Not default-constructable. | |
TreeNode (const TreeNode &)=delete | |
Not copy-constructable. | |
TreeNode (TreeNode &&rhp) | |
Move constructor. | |
TreeNode & | operator= (const TreeNode &)=delete |
Not assign-constructable. | |
TreeNode (TreeNode *parent, const std::string &name, const std::string &group, group_idx_type group_idx, const std::string &desc, bool is_indexable) | |
TreeNode full constructor. Initializes node and adds it as a child of an existing tree node (if parent is not null). | |
TreeNode (TreeNode *parent, const std::string &name, const std::string &group, group_idx_type group_idx, const std::string &desc) | |
TreeNode constructor with no is_indexable parameter [defaults to true]. | |
TreeNode (const std::string &name, const std::string &group, group_idx_type group_idx, const std::string &desc) | |
TreeNode constructor with no parent Node. | |
TreeNode (TreeNode *parent, const std::string &name, const std::string &desc) | |
TreeNode constructor with no group information. | |
TreeNode (TreeNode *parent, const std::string &group, group_idx_type group_idx, const std::string &desc) | |
TreeNode constructor for anonymous node with group information. | |
TreeNode (const std::string &name, const std::string &desc) | |
TreeNode constructor with no parent node or group information. | |
virtual | ~TreeNode () |
Virtual destructor. | |
Identification | |
void | addAlias (const std::string &alias) |
Add a single alias for this node. | |
void | addAliases (const AliasVector &v) |
Adds each element of a vector of aliases to this node.. | |
void | addTag (const std::string &tag) |
Adds single tag to this node. | |
void | addTags (const std::vector< std::string > &v) |
Adds each elements of a vector of tags to this node. | |
Node-Representation | |
virtual std::string | stringize (bool pretty=false) const |
Create a string representation of this node. | |
void | stringizeTags (std::stringstream &ss) const |
Render tags to a string in the form: " tags:[tag0, tag1]" If there are any tags. The leading space makes this a useful sub-utility of stringize because if there are no tags, returns empty string with no leading space. | |
Node Attributes | |
node_uid_type | getNodeUID () const |
Gets the unique ID of this node. | |
const std::string & | getName () const override |
Gets the name of this node. | |
const std::string * | getNamePtr () const |
Gets the name of this node's string pointer which isinterned in StringManager) | |
bool | isAnonymous () const |
Is this node anonymous. | |
bool | isExpired () const |
Is this expired (i.e. has it been the rhp of a move constructor) | |
bool | isIndexableByGroup () const |
Returns whether this object is accessible through its parent's interfaces for getting children by group and index. | |
const std::string & | getGroup () const |
Gets the group name of this node. | |
const std::string * | getGroupNamePtr () const |
Gets the group name string pointer (interned in StringManager singleton) of this node. | |
group_idx_type | getGroupIdx () const |
Gets the group index of this node. | |
const std::vector< const std::string * > & | getTags () const |
Gets the set of tags associated with this TreeNode. | |
bool | hasTag (const std::string &tag) const |
Does this node have a specific tag (by name) | |
bool | hasTag (const std::string *interned_tag_name) const |
Does this node have a specific tag (by string pointer interned with StringManager). This is faster than the alternate hasTag method because it relies only on pointer comparisons. | |
const std::string & | getDesc () const |
Gets the description of this node. | |
bool | isBuiltin () const |
Is this node in the builtins group. | |
void | markHidden (bool hidden=true) |
Marks this TreeNode hidden for the purposes of printint out nodes. This does not make the node inaccessible, but causes it (and its subtree) to be hidden from typical recursive tree printouts. | |
bool | isHidden () const |
Is this TreeNode supposed to be hidden during tree printouts This value does not have to be respected by anything using TreeNode and is mainly a UI/printout convenience. | |
Node Validation | |
void | validateName (const std::string &nm) |
Validates the given name string for this TreeNode. Does not consider context (e.g. name collisions) | |
void | validateGroup (const std::string &name, const std::string &group, group_idx_type idx) |
Validates the given group name string and group index for this TreeNode. Does not consider context (e.g. name collisions) | |
void | validateDesc (const std::string &desc) |
Validates the given description string for this TreeNode. | |
TreeNode extensions | |
void | addExtensionParameters (const std::string &extension_name, std::unique_ptr< ParameterSet > extension_params) |
Add a named parameter set to extend this tree node's metadata. | |
void | addExtensionFactory (const std::string &extension_name, std::function< ExtensionsBase *()> factory) |
Add an extension factory to this tree node by its type (name). This method does not actually create any objects at this time. It will validate and create the extension only if asked for later on during simulation. | |
ExtensionsBase * | getExtension (const std::string &extension_name) |
Get an extension object by type string. Returns nullptr if not found (unrecognized). | |
ExtensionsBase * | getExtension () |
Get an extension without needing to specify any particular type string. If no extensions exist, returns nullptr. If only one extension exists, returns that extension. If more than one extension exists, throws an exception. | |
const std::set< std::string > & | getAllExtensionNames () |
Extension names, if any. Tree node extensions are typically instantiated on-demand for best performance (you have to explicitly ask for an extension by its name, or it won't be created) - so note that calling this method will trigger the creation of all this node's extensions. The performance cost is proportional to the number of nodes in the virtual parameter tree. | |
Tree-Building | |
void | addChild (TreeNode *child, bool inherit_phase=true) |
Adds a TreeNode to this node as a child. | |
void | addChild (TreeNode &child) |
AddChild by reference for convenience. | |
void | makeSubtreePrivate () |
Make the entire subtree private. | |
void | setScopeRoot () |
bool | isScopeRoot () const |
![]() | |
ResourceContainer () | |
Consturct with a null, unlocked resource. | |
ResourceContainer (const ResourceContainer &)=delete | |
Copy construction disbled. | |
ResourceContainer (ResourceContainer &&)=default | |
Move constructor. | |
virtual | ~ResourceContainer () |
Destructor. | |
Resource * | getResource () |
Gets the resource contained by this node if any. May only be called after finalization begins or during teardown. | |
const Resource * | getResource () const |
Const variant of getResource. | |
bool | hasResource () const |
Determines if this node has a resource. This method exists in case the TreeNode is being explored by a tool or interactive UI. Typical TreeNode clients (such as Resources) will assume that there is a resource if they are expecting one. | |
template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type> | |
const T | getResourceAs () const |
Gets the resource contained by this node (if any) as the given type. | |
template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type> | |
const T * | getResourceAs () const |
Overload of getResourceAs for const access with a non-pointer template type. | |
template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type> | |
T | getResourceAs () |
Non-const overload of getResourceAs. | |
template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type> | |
T * | getResourceAs () |
Non-const overload of getResourceAs. | |
virtual std::string | getResourceType () const |
Gets the typename of the resource that this node will eventually contain. | |
virtual std::string | getResourceTypeRaw () const |
Gets the typename of the resource that this node will eventually contain. | |
![]() | |
PhasedObject (PhasedObject &&)=default | |
TreePhase | getPhase () const |
Gets the trees current phase. | |
virtual bool | isBuilding () const |
Is this node (and thus the entire tree above and below it) currently in the TREE_BUILDING phase. | |
virtual bool | isBuilt () const |
Is this node (and thus the entire tree above it) "built". Checks that getPhase has passed TREE_BUILDING. | |
virtual bool | isConfigured () const |
Is this node (and thus the entire tree above it) "configured". Checks that getPhase has passed TREE_CONFIGURING (i.e. FINALIZED, FINALIZING, TEARDOWN, etc). | |
virtual bool | isConfiguring () const |
Is this node (and thus the entire tree above it) currently in the TREE_CONFIGURING phase. | |
virtual bool | isFinalizing () const |
Is this node (and thus the entire tree above it) "finalized". | |
virtual bool | isFinalized () const |
Is this node (and thus the entire tree above it) "finalized". | |
virtual bool | isTearingDown () const |
Is this node (and thus the entire tree above it) in the "teardown" phase. | |
![]() | |
std::vector< ArchData * > | getAssociatedArchDatas () |
Retrieves all ArchDatas associated with this TreeNode so that children can use it to allocate their data. | |
const std::vector< ArchData * > | getAssociatedArchDatas () const |
Const variant of getAssociatedArchDatas. | |
ArchDataContainer ()=default | |
Default constructor. | |
ArchDataContainer (ArchDataContainer &)=delete | |
Copy construction disabled. | |
ArchDataContainer (ArchDataContainer &&)=default | |
Move constructor. | |
virtual | ~ArchDataContainer () |
Virtual destructor. | |
Static Public Member Functions | |
static std::string | createSearchRegexPattern (const std::string &pat) |
Compute a regex pattern for a node child path containing any number of wildcard characters (not a dot-separated location) which can be used to test against child node names. | |
static bool | hasWildcardCharacters (const std::string &name) |
Determines if a given node name has any wildcard characters which will be substituted in createSearchRegexPattern. | |
static std::string | getNextName (const std::string &name, size_t &pos) |
Gets the next name between two '.' chars in a string starting at pos. | |
static bool | matchesGlobLike (const std::string &pattern, const std::string &other) |
Determine if a glob-like search pattern matches some other string. | |
Static Public Attributes | |
Constants | |
static const group_idx_type | GROUP_IDX_NONE = (group_idx_type)-1 |
GroupIndex indicating that a node has no group index because it belongs to no group. | |
static const node_uid_type | MAX_NODE_UID |
Maximum value of node_uid_ before the framework throws an exception. | |
static constexpr char | GROUP_NAME_NONE [] = "" |
Group name indicating that a node belongs to no group. | |
static constexpr char | NODE_NAME_NONE [] = "" |
Node name for anonymous node. | |
static const std::string | DEBUG_DUMP_SECTION_DIVIDER |
String dividing sections in a debug dump file. | |
static constexpr char | NODE_NAME_VIRTUAL_GLOBAL [] = "_SPARTA_virtual_global_" |
Node name for the virtual glopbal node. | |
static constexpr char | LOCATION_NODE_SEPARATOR_ATTACHED = '.' |
Separator character between node identifiers in a location string when the child is attached to the parent. | |
static constexpr char | LOCATION_NODE_SEPARATOR_EXPECTING = ',' |
Separator character between node identifiers in a location string when the child is being attached to the parent but has not been entirely attached (i.g. during construction of the child node) | |
static constexpr char | LOCATION_NODE_SEPARATOR_UNATTACHED = '~' |
Separator character preceding a node identifiers in a location string when that node has no parent and is not in the process of being attached to one. | |
static const uint32_t | RENDER_SUBTREE_INDENT = 2 |
Spaces to indent for each tree level in sparta::TreeNode::renderSubtree. | |
static constexpr char | GROUP_NAME_BUILTIN [] = "_SPARTA_builtin_group_" |
Reserved name for built-in nodes. | |
static const uint64_t | CHILD_FIND_THRESHOLD = 100000 |
Threshold for number of findChildren calls after finalization before a warning message is printed about framework misuse. | |
static const uint64_t | CHILD_GET_THRESHOLD = 100000 |
Threshold for number of getChild calls after finalization before a warning message is printed about framework misuse. | |
static const uint32_t | TEARDOWN_ERROR_LIMIT = 5 |
Number of teardown-phase-related messages that can be printed before the rest will be suppressed. | |
static const std::vector< std::pair< const char *, std::function< void(std::string &)> > > | TREE_NODE_PATTERN_SUBS |
List of pattern susbtitutions when creating a search pattern from a TreeNode name containing wildcards. | |
Protected Member Functions | |
std::pair< uint32_t, std::string > | recursGetDeepestMatchingPath_ (const std::string &path, size_t name_pos) const |
Finds the deepest node path mathing the input path. Implements getDeepestMatchingPath. | |
void | setExpectedParent_ (const TreeNode *parent) |
Tracks a node as an expected parent without actually adding this node as a child. This is used almost exclusively for printing error messages which include a device-tree location BEFORE actually inserting this node into the device tree since node construction can fail. | |
void | enterFinalizing_ () |
Recursively enter TREE_FINALIZING phase. | |
void | finalizeTree_ () |
Recursively create resources based on tree configuration. enter_finalize_ should be invoked after this method successfully completes for an entire tree. Finalizes in the order of construction. | |
void | validateTree_ () |
Iterates the finalized tree and validates each node (e.g. ensures statistics can be evaluated) | |
void | enterFinalized_ () |
Recursively enter TREE_FINALIZED phase. | |
void | enterConfig_ () noexcept |
Recursively enter TREE_CONFIGURING phase. | |
void | bindTreeEarly_ () |
Recursively invoke TreeNode::onBindTreeEarly_ and Resource::onBindTreeEarly_ (in that order for each node) | |
void | bindTreeLate_ () |
Recursively invoke TreeNode::onBindTreeEarly_ and Resource::onBindTreeLate_ (in that order for each node) | |
void | simulationTerminating_ () |
Hook to allow simulation resources to clean-up before simulation is ended. | |
void | validatePostRun_ (const PostRunValidationInfo &info) const |
Hook to check the state of the simulator post-run and throw exceptions if something is incorrect. | |
void | dumpDebugContent_ (std::ostream &out) const noexcept |
Allows resources to write out detailed textual debugging information about the node. This is typically called by a simulator when shutting down due to an exception (or depending on simulator config). However, it could also be called at other times. | |
void | enterTeardown_ () noexcept |
Recursively enter TREE_TEARDOWN phase while alerting nodes through onEnteringTeardown_ and alterting Resources through Resource::onStartingTeardown_. Nodes already in TREE_TEARDOWN phase will not be alerted (neither will their associated Resources). All nodes are visited regardless of their parent's phase. | |
void | verifyUniqueChildIdentifier_ (const std::string &ident, bool ignore_group_collision=false) |
Verifies that the given identifier is unique for all children of this node by comparing against names, groups, and aliases. Throws SpartaException if not unique. | |
void | removeChildForTeardown_ (TreeNode *child) |
"Removes" the given child by invoking onDestroyingChild_ then removing this child from the children_ list | |
void | removeFromParentForTeardown_ (TreeNode *parent) |
Protected Wrapper for getParent()->removeChildForTeardown_ which allows subclases of TreeNode to indirectly invoke removeChildForTeardown_ with themselves as the argument. | |
void | detachFromParent_ () |
Removes a node from its parent with the expectation this node will be immediately destroyed (i.e. is an xvalue) | |
void | detachFromChildren_ () |
Removes a node from its children with the expectation this node will be immediately destroyed (i.e. is an xvalue) | |
bool | areParametersLocked_ () const |
This method informs whether the tree is past the lockdown phase for all LOCKED and HIDDEN parameters. Modifying LOCKED and HIDDEN parameters after this phase is disallowed. Tree can be locked down during TREE_BUILDING phase or TREE_CONFIGURING phase. During TREE_FINALIZING phase, all parameters are locked down as is. | |
![]() | |
std::string | getResourceTypeName_ () const |
Gets the rtti type name (demangled) of the resource type held by this container. If there is no resource held, returns empty string. | |
void | setResource_ (Resource *r) |
Allows subclasses to assign the resource associated with this node. | |
void | unsetResource_ () |
Allows a resource to unset the resource set with setResource_. | |
void | lockResource_ () |
Allows subclasses to assign the resource associated with this node. | |
Resource * | getResource_ () noexcept |
Returns the currently held resource of this node (if any). This method can be called at any time. | |
const Resource * | getResource_ () const noexcept |
Const variant of getResource_. | |
![]() | |
void | setPhase_ (TreePhase phase) |
Sets the current phase. | |
Static Protected Member Functions | |
static bool | identityMatchesPattern_ (const std::string &ident, std::regex &expr, std::vector< std::string > &replacements) |
Performs pattern matching on a identity string. | |
static bool | identityMatchesPattern_ (const std::string &ident, std::regex &expr) |
Variant of identityMatchesPattern_ with no replacements vector. | |
static std::string | getPreviousName_ (const std::string &name, size_t &pos) |
Gets the previous name between two '.' chars in a string starting at pos. | |
Friends | |
class | VirtualGlobalTreeNode |
Allow this class access internals for handling notification observation registration/deregistration broadcasts in a way that does not fit the composite tree pattern. | |
class | ClockManager |
Allow ClockManager to directly change phase on nodes. | |
class | SpartaStaticInitializer |
This class is responsible for instantiating the static container held by this TreeNode. | |
class | TreeNodePrivateAttorney |
Friend an attorney pattern that can expose access to getAllChildren_ or other methods that bypass privacy_level_. | |
Internal Notification System | |
typedef std::vector< delegate > | DelegateVector |
Vector of delegates representing a list of observers to notify. | |
typedef std::map< type_info_container, DelegateVector > | NotificationObserverMap |
Map of delegate vectors containing all observers. | |
template<typename DataT > | |
void | postPropagatingNotification_ (const TreeNode *origin, const DataT &data, const std::string *name_id) |
Starts a notification propagating up the tree. | |
template<typename DataT , typename T , void(T::*)(const TreeNode &, const TreeNode &, const DataT &) TMethod> | |
DelegateVector::iterator | findDelegate_ (DelegateVector &dvec, T *obj, const std::string &target_name) |
Finds a delegate associated with the given type T, object pointer, DataT, and TMethod within a DelevateVector. The intent of this function is to help see if a delegate is already registered with a calback by checking all known information associated with that callback against the input arguments. | |
template<typename DataT , typename T , void(T::*)(const DataT &) TMethod> | |
DelegateVector::iterator | findDelegate_ (DelegateVector &dvec, T *obj, const std::string &target_name) |
virtual void | broadcastRegistrationForNotificationToChildren_ (const std::type_info &tinfo, const std::vector< const std::string * > &name_ids, TreeNode *obs_node, const delegate *del, const bool allow_private) |
Recursively notifies children that the notification described is now (or still is) being observed at the observation point TreeNode obs_node with the newly registered delegate del. | |
virtual void | broadcastDeregistrationForNotificationToChildren_ (const std::type_info &tinfo, const std::vector< const std::string * > &name_ids, TreeNode *obs_node, const delegate *del, const bool allow_private) |
Recursively notifies children that the notification described has lost one particular observer (del) which was observing at the observation point TreeNode obs_node with the delegate del. | |
void | broadcastRegistrationForNotificationListStringToChildren_ (const std::type_info &tinfo, const std::string &name, TreeNode *obs_node, const delegate *del, const bool private_only) |
Entry point to broadcastRegistrationForNotificationToChildren_ recursion. Breaks a name string. | |
void | broadcastDeregistrationForNotificationListStringToChildren_ (const std::type_info &tinfo, const std::string &name, TreeNode *obs_node, const delegate *del, const bool private_only) |
Symmetric oppostie of broadcastRegistrationForNotificationListStringToChildren_. | |
template<typename DataT > | |
void | invokeDelegatesOn_ (TreeNode *to_invoke, const DataT &data, const std::string *name_id) |
Protected wrapper for invokeDelegates_ which allows a TreeNode to invoke delegates on another TreeNode using itself as the origin. | |
Diagnostics | |
void | lockdownParameters () |
Method to put the device tree in lockdown phase. All LOCKED and HIDDEN parameters are frozen after this point. Regular parameters are not affected by this phase. This method requires a Simulation pointer and will assert at compile time if anyone tries to lockdown the tree without the context of a Simulation. | |
static const std::map< const TreeNode *, WeakPtr > & | getParentlessNodes () |
static const std::map< const TreeNode *, WeakPtr > & | getAllNodes () |
Gets the vector of all TreeNodes currently known to be constructed. | |
static std::string | formatAllNodes () |
Prints the list of all TreeNodes currently known to be constructed. | |
static bool | isNodeConstructed (const TreeNode *) |
Is a given node constructed? | |
Tree Navigation & State | |
virtual bool | isAttached () const |
Is this node part of a device tree with a proper RootTreeNode at the root. | |
virtual TreeNode * | getParent () |
Gets immediate parent of this node if one exists. | |
virtual const TreeNode * | getParent () const |
template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type> | |
const T | getParentAs (bool must_exist=true) const |
Retrieves a parent casted to type T* if this node has a parent. | |
template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type> | |
const T * | getParentAs (bool must_exist=true) const |
template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type> | |
T | getParentAs (bool must_exist=true) |
template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type> | |
T * | getParentAs (bool must_exist=true) |
virtual TreeNode * | getRoot () |
Gets farthest ancestor of this node. | |
virtual const TreeNode * | getRoot () const |
TreeNode * | getScopeRoot () |
const TreeNode * | getScopeRoot () const |
const TreeNode * | getExpectedRoot () const |
build-time equivalent to getRoot before an object is actually attached to a tree. This is a mainly a framework and debugging tool for determining what the root of a node being constructed will be when complete | |
app::Simulation * | getSimulation () const |
Gets the simulation (if any) associated with this tree. | |
uint32_t | getNumChildren () const |
Gets the number of children that this node has including those in the sparta builtins group. | |
TreeNode * | getChildAt (uint32_t idx) const |
Gets a child at a position in the children vector in the order in which they were added to this node. | |
const ChildrenVector | getChildren () const |
Gets a vector of all children of this node in any group in the order in which they were added to this node. | |
uint32_t | getChildren (std::vector< TreeNode * > &results, bool ignore_builtin_group=true, bool ignore_anonymous_nodes=true) |
Gets all children of this node in the order in which they were added to this node. | |
template<class T > | |
uint32_t | getChildrenOfType (std::vector< T * > &results) const |
return all the children matching a particular type using dynamic cast. | |
sparta::TreeNode * | findAncestorByName (const std::string &name) |
Find ancestor by name. | |
template<typename T > | |
sparta::TreeNode * | findAncestorByType () |
Find ancestor by type. | |
sparta::TreeNode * | findAncestorByTag (const std::string &tag) |
Find the first ancestor with a particular tag. | |
template<typename T > | |
T * | findAncestorResourceByType () |
Find an ancestor's resource with a certain type. | |
const AliasVector & | getAliases () const |
Gets a vector of all aliases of this node. | |
uint32_t | getChildrenIdentifiers (std::vector< std::string > &idents, bool ignore_builtin_group=true) const |
Gets all child identifiers, aliases, group names, and group-aliases which can be used to refer to a child of this node. | |
std::vector< const std::string * > | getIdentifiers () const |
Gets all the identifiers for this node (excluding groups) | |
uint32_t | getGroupSize (const std::string &group) |
Gets the number of nodes in a group. | |
group_idx_type | getGroupIndexMax (const std::string &group) |
Gets the largest index of a node in the given group. | |
uint32_t | getGroup (const std::string &group, std::vector< TreeNode * > &results) |
Gets all nodes in a child group. | |
uint32_t | findChildren (const std::string &pattern, std::vector< TreeNode * > &results, std::vector< std::vector< std::string > > &replacements) |
Finds all children starting at this node with a given pattern relative to this node by matching names an aliases. Appends each found child to <results>. | |
uint32_t | findChildren (const std::string &pattern, std::vector< TreeNode * > &results) |
Version of findChildren with no replacements vector. | |
virtual uint32_t | findImmediateChildren_ (std::regex &expr, std::vector< TreeNode * > &found, std::vector< std::vector< std::string > > &replacements, bool allow_private=false) |
Finds immediate children with some identity (name or alias) matching a regex. | |
uint32_t | findImmediateChildren_ (std::regex &expr, std::vector< TreeNode * > &found, bool allow_private=false) |
Variant of findImmediateChildren_ with no replacements vector. | |
virtual uint32_t | findImmediateChildren_ (std::regex &expr, std::vector< const TreeNode * > &found, std::vector< std::vector< std::string > > &replacements, bool allow_private=false) const |
Const-qualified variant of findImmediateChildren_. | |
uint32_t | findImmediateChildren_ (std::regex &expr, std::vector< const TreeNode * > &found, bool allow_private=false) const |
Variant of const-qualified findImmediateChildren_ with no replacements vector. | |
bool | locationMatchesPattern (const std::string &pattern, const TreeNode *pat_loc) const |
Determines if the given pattern (which may contain wildcards) can describe this node. | |
TreeNode * | getChild (const std::string &name, bool must_exist=true) |
Retrieves a child with this dotted path name. | |
const TreeNode * | getChild (const std::string &name, bool must_exist=true) const |
Overloaded const-qualified. | |
std::string | getDeepestMatchingPath (const std::string &path) const |
Gets the deepest whole node location starting from this node that matches some part of path starting at its beginning. | |
bool | hasChild (const std::string &name) const noexcept |
Determines if a child can be found with the given dotted path. | |
bool | hasImmediateChild (const TreeNode *n) const noexcept |
Determines if the node n is an immediate child of this node. | |
template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type, class ConstT = typename ptr_to_const_obj_ptr<T>::type> | |
const ConstT | getChildAs (const std::string &name, bool must_exist=true) const |
Retrieves a child that is castable to T with the given dotted path. | |
template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type> | |
const T * | getChildAs (const std::string &name, bool must_exist=true) const |
template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type> | |
T | getChildAs (const std::string &name, bool must_exist=true) |
template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type> | |
T * | getChildAs (const std::string &name, bool must_exist=true) |
template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type, class ConstT = typename ptr_to_const_obj_ptr<T>::type> | |
ConstT | getAs () const |
Retrieves this node after casting to type T. | |
template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type> | |
const T * | getAs () const |
Retrieves this node after casting to type const T. | |
template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type> | |
T | getAs () |
Retrieves this node after casting to type const T. | |
template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type> | |
T * | getAs () |
Retrieves this node after casting to type const T. | |
uint32_t | findChildrenByTag (const std::string &tag, std::vector< TreeNode * > &results, int32_t max_depth=-1) |
Finds a set of all children having the selected tag which this node or descendants of this node within a distance of the given max_depth. | |
bool | isDescendantOf (const TreeNode *ancestor, int32_t max_depth=-1) const |
Determines if this node is a descendant of the specified ancestor node within some number of generations (depth). | |
std::string | getLocation () const override final |
std::string | getDisplayLocation () const |
Returns the location of this node in the device tree which might not be usable for navigating the device tree (it cannot be used as an argument for getChild/findChildren). | |
std::string | getExpectedLocation () const |
build-time equivalent to getLocation before an object is actually attached to a tree. This is a mainly a framework and debugging tool for determining what the location of a node currently being constructed will be when complete. | |
std::string | renderSubtree (int32_t max_depth=-1, bool show_builtins=false, bool names_only=false, bool hide_hidden=false, bool(*leaf_filt_fxn)(const TreeNode *)=nullptr) const |
Renders the subtree starting at this node as a string containing an indentation-based depth-first representation. | |
uint32_t | getLevel () const |
Gets the level of this node. 0 is root. | |
template<typename T > | |
uint32_t | getRecursiveNodeCount () const |
Recursively gets the count of a nodes that are a subclass of a particular type (determined by dynamic_cast). Includes all descendants of this node in the tree, but excludes this node. | |
static TreeNode * | getVirtualGlobalNode () |
Gets the virtual global node singleton. This node can have no parent and no children. It receives notifications from all nodes in the simulator as if it were the parent of every node in the simulation that has no parent. | |
Public Notification System | |
uint32_t | getPossibleNotifications (std::vector< NotificationInfo > &infos) const |
Gets information on the possible notifications generated by this node (excludes children). | |
void | dumpPossibleNotifications (std::ostream &o) const noexcept |
Dumps a listing of the notifications which this node can generate to the ostream o. | |
template<typename DataT = ANY_TYPE> | |
uint32_t | locateNotificationSources (std::vector< TreeNode * > &nodes, const std::string &name="") |
Gets all possible notification info from NotificationSources within this node's subtree. | |
template<typename DataT = ANY_TYPE> | |
void | dumpLocatedNotificationSources (std::ostream &o, const std::string &name="") |
Retrieves the relevant NotificationSources from locateNotificationSources and prints them to the output o. | |
uint32_t | getPossibleSubtreeNotifications (std::vector< NotificationInfo > &infos) const noexcept |
Gets information on the possible notifications generated by this node and all its descendants. | |
void | dumpPossibleSubtreeNotifications (std::ostream &o) const noexcept |
Dumps a listing of the notifications which this node and its descendants can generate to the ostream o. | |
bool | canGenerateNotification (const std::type_info &tinfo, const std::string *name) const |
Can this TreeNode generate a notification of the given type having the given name or pattern. | |
bool | canGenerateNotification (const std::type_info &tinfo, const std::string &name) const |
Can this TreeNode generate a notification of the given type having the given name (does not require interned string - will intern automatically with StringManager). | |
bool | canGenerateNotification (const NotificationInfo &info) const |
Can this TreeNode generate a notification of the given NotificationInfo. | |
bool | canSubtreeGenerateNotification (const std::type_info &tinfo, const std::string *name) const |
Can this TreeNode or its descendants (of any distance) generate a notification of the given type having the given name. | |
bool | canSubtreeGenerateNotification (const std::type_info &tinfo, const std::string &name) const |
Can this TreeNode or its descendants (of any distance) generate a notification of the given type having the given name (does not require interned string) | |
bool | canSubtreeGenerateNotifications (const std::type_info &tinfo, const std::vector< const std::string * > &names) const |
Checks to see if any a subtree can generate any of several notification names which may be patterns. | |
template<typename DataT , typename T , void(T::*)(const TreeNode &, const TreeNode &, const DataT &) TMethod> | |
void | registerForNotification (T *obj, const std::string &name, bool ensure_possible=true) |
Registers a callback method to listen for all notifications having the specified data type DataT and name (or any name if name is "") occuring on this node or any descendant (subtree). | |
template<typename DataT , typename T , void(T::*)(const DataT &) TMethod> | |
void | registerForNotification (T *obj, const std::string &name, bool ensure_possible=true) |
template<typename DataT , typename T , void(T::*)(const TreeNode &, const TreeNode &, const DataT &) TMethod> | |
void | deregisterForNotification (T *obj, const std::string &name) |
Removes at most one registration made with registerForNotification. | |
template<typename DataT , typename T , void(T::*)(const DataT &) TMethod> | |
void | deregisterForNotification (T *obj, const std::string &name) |
bool | hasObserversRegisteredForNotification (const std::type_info &tinfo, const std::string *name) const noexcept |
Determines if this TreeNode (not descendants) has any observers for this type of event and name. | |
void | getDelegatesRegisteredForNotification (const std::type_info &tinfo, const std::string *name, std::vector< delegate > &dels) noexcept |
Gets the vector of delegates registered for a notification on this TreeNode. | |
static std::vector< const std::string * > | parseNotificationNameString (const std::string &csl) |
Parses a comma-separated list of notification names (or patterns) separated by commas and ignoring whitespace around commas. | |
static bool | notificationCategoryMatch (const std::string *query_id, const std::string *node_id) |
Checks if two notification categories match where one is an actual category. | |
Node in a composite tree representing a sparta Tree item.
Because this class expects to be used with a composite pattern, several refinements exist elsewhere in sparta.
Searching and getting child nodes is done by getChild, findChildren, and getChildAt only.
TreeNodes cannot be removed from the tree once added until the Tree enters the TREE_TEARDOWN phase (see isTearingDown). Place the Tree's RootTreeNode into the teardown phase using sparta::RootTreeNode::enterTeardown.
Definition at line 204 of file TreeNode.hpp.
typedef std::vector<std::string> sparta::TreeNode::AliasVector |
Vector of aliases (other names for this node)
Definition at line 248 of file TreeNode.hpp.
typedef std::multimap<std::string, TreeNode*> sparta::TreeNode::ChildNameMapping |
Mapping of names, aliases, and groups to individual child nodes within one node. This must be in a deterministic order, so an ordered container (e.g. std::map) is required. A sorted contained is probably desirable, but not required.
Definition at line 256 of file TreeNode.hpp.
typedef std::vector<TreeNode*> sparta::TreeNode::ChildrenVector |
Vector of TreeNode children.
Definition at line 243 of file TreeNode.hpp.
typedef std::weak_ptr<const TreeNode> sparta::TreeNode::ConstWeakPtr |
Weak pointer to a const TreeNode. Acquire with getWeakPtr.
Definition at line 271 of file TreeNode.hpp.
|
protected |
Vector of delegates representing a list of observers to notify.
Definition at line 3074 of file TreeNode.hpp.
typedef uint32_t sparta::TreeNode::group_idx_type |
Index within a group.
Definition at line 261 of file TreeNode.hpp.
typedef uint64_t sparta::TreeNode::node_uid_type |
Type of unique-identifier assigned to every node.
Definition at line 238 of file TreeNode.hpp.
|
protected |
Map of delegate vectors containing all observers.
Definition at line 3079 of file TreeNode.hpp.
typedef std::shared_ptr<TreeNode> sparta::TreeNode::SharedPtr |
Shared pointer to TreeNode. Acquire with WeakPtr::lock().
Definition at line 276 of file TreeNode.hpp.
typedef std::map<const std::string*, std::vector<TreeNode*> > sparta::TreeNode::TagsMap |
Map of strings (interned in StringManager) tags to TreeNodes.
Definition at line 281 of file TreeNode.hpp.
typedef std::weak_ptr<TreeNode> sparta::TreeNode::WeakPtr |
Weak pointer to a TreeNode. Acquire with getWeakPtr.
Definition at line 266 of file TreeNode.hpp.
sparta::TreeNode::TreeNode | ( | TreeNode && | rhp | ) |
Move constructor.
sparta::TreeNode::TreeNode | ( | TreeNode * | parent, |
const std::string & | name, | ||
const std::string & | group, | ||
group_idx_type | group_idx, | ||
const std::string & | desc, | ||
bool | is_indexable | ||
) |
TreeNode full constructor. Initializes node and adds it as a child of an existing tree node (if parent is not null).
parent | TreeNode to which this will be added as a child. If this constructor is being invoked by a subclass, parent must be nullptr (or use a constructor with no parent argument). Subclass constructor is then responsible for adding the node. |
name | Name of this node. Name must satisfy validateName. May be NODE_NAME_NONE to indicate anonymous node. A group and group index is required for anonymous nodes. name must not be the same as any alias or name of another child of parent. It is HIGHLY recommended that name end in a number if there are multiple instances of similar objects at the same level in the tree (e.g. core0, core1). Even if only one such object exists at some level in the tree, having a numeric suffix now will ensure it is easy to adapt Python scripts to handle muliple instanecs later. |
group | Group name of this node. Must satisfy validateGroup. May be GROUP_NAME_NONE if a valid node name is given and group_idx == GROUP_IDX_NONE. |
group_idx | Group index within group. Must satisfy validateGroup. Must be GROUP_IDX_NONE unless group != GROUP_NAME_NONE. |
desc | Description of this TreeNode. Must satisfy validateDesc |
is_indexable | Is this node indexable by its parent such that it can be accessed by group and index. Set this to false if children will have colliding group numbers and indexes (e.g. a banked register set). In almost all cases, this should be true. |
* // given TreeNode* parent with name "parent" * TreeNode foo2(&parent, "foo2", "foo", 2, "This is a Foo...") * TreeNode foo3(&parent, "foo3", "foo", 3, "This is a Foo...") *
In a Python shell atop sparta, might allow the following means of accessing foo:
* >>> parent.foo * <Group of 2 Nodes> * >>> parent.foo2 # Node name * <foo2 node> * >>> parent.foo3 * <foo3 node> * >>> parent.foo[2] # Node group[index] * <foo2 node> * >>> parent.foo[3] * <foo3 node> * >>> for n in parent.foo: print n # Iterate Node group * <foo2 node> * <foo3 node> * \endvarbatim * * <h4>Example 2: Using groups for Nodes which have no siblings</h4> * Even if you will only have one node having a certain name prefix at * some point in the sparta tree (e.g. "soc"), it may make sense to make * it indexable. One day, a multi-soc/board simulation may need to be * created. * \verbatim * // given TreeNode* parent with name "parent" * TreeNode foo(&parent, "foo", "foo", 0, "This is a Foo...") *
In a Python shell atop sparta, might allow the following means of accessing foo:
* >>> parent.foo # Name * <foo node> * >>> parent.foo[0] # Group * <foo node> * >>> for f in parent.foo: print f * <foo node> *
sparta::TreeNode::TreeNode | ( | TreeNode * | parent, |
const std::string & | name, | ||
const std::string & | group, | ||
group_idx_type | group_idx, | ||
const std::string & | desc | ||
) |
TreeNode constructor with no is_indexable parameter [defaults to true].
sparta::TreeNode::TreeNode | ( | const std::string & | name, |
const std::string & | group, | ||
group_idx_type | group_idx, | ||
const std::string & | desc | ||
) |
TreeNode constructor with no parent Node.
sparta::TreeNode::TreeNode | ( | TreeNode * | parent, |
const std::string & | name, | ||
const std::string & | desc | ||
) |
TreeNode constructor with no group information.
group defaults to GROUP_NAME_NONE. group_idx defaults to GROUP_IDX_NONE.
sparta::TreeNode::TreeNode | ( | TreeNode * | parent, |
const std::string & | group, | ||
group_idx_type | group_idx, | ||
const std::string & | desc | ||
) |
TreeNode constructor for anonymous node with group information.
Name defaults to NODE_NAME_NONE. group and group_idx should be meaningful
sparta::TreeNode::TreeNode | ( | const std::string & | name, |
const std::string & | desc | ||
) |
TreeNode constructor with no parent node or group information.
group defaults to GROUP_NAME_NONE. group_idx defaults to GROUP_IDX_NONE.
|
virtual |
Virtual destructor.
SpartaException | if node is attached to a root (via isAttached) and tree is not in TREE_TEARDOWN phase |
|
virtual |
Activate one of the links added with addLink.
label | The label of the tree node |
What it means to activate a link can differ from simulator to simulator and each simulator that use the link notion is free to define the semantics of the link and what it means to active a link.
In case this method is not overriden, we assume that it has a resource and will let its resource know about what tree nodes are being shadowed.
void sparta::TreeNode::addAlias | ( | const std::string & | alias | ) |
Add a single alias for this node.
alias | Alias to assign to this node. alias is subject to the same constraints as a node name and must satisfy validateName. Additionally, aliases must not be empty strings |
void sparta::TreeNode::addAliases | ( | const AliasVector & | v | ) |
Adds each element of a vector of aliases to this node..
v | Vector of alias strings. Each alias in the vector is subject to the conditions of addAlias |
void sparta::TreeNode::addChild | ( | TreeNode & | child | ) |
AddChild by reference for convenience.
Overloads addChild(TreeNode* child)
void sparta::TreeNode::addChild | ( | TreeNode * | child, |
bool | inherit_phase = true |
||
) |
Adds a TreeNode to this node as a child.
child | borrowed pointer to TreeNode to add as a child. child must not already be a parent of *this. child cannot already be an immediate child of *this. Child cannot have the same name or alias as another name or alias of a child of *this (group names may be repeated though). Child must not be nullptr. |
inherit_phase | Does the child inherit its phase from the parent This should be true in almost all uses of the framework |
SpartaException | if the child cannot be added for any reason. |
Invokes onAddingChild_ before finally attaching the child. This gives subclasses a chance to either reject the node or perform some local actions like caching the child or determining its type.
Invokes setParent_ on the child which handles passing information about the new parent-child relationship to child's subtree.
|
virtual |
Link this tree node with another tree node.
node | The tree node to link with |
label | The label of the tree node |
This method is a generic interface for linking a tree node to other tree nodes. Linking is not bi-directinal, linking a tree node A with tree node be by calling this method on A, links A with B but not B with A.
In case this method is not overriden, we assume that it has a resource and will let its resource know about what tree nodes are being shadowed.
Reimplemented in sparta::MirrorNotificationSource< NotificationDataT >.
void sparta::TreeNode::addTag | ( | const std::string & | tag | ) |
Adds single tag to this node.
tag | Tag to add to this node. Tag is subject to the same constraints as a node name and must satisfy validateName. Additionally, tags must not be empty strings |
void sparta::TreeNode::addTags | ( | const std::vector< std::string > & | v | ) |
Adds each elements of a vector of tags to this node.
v | Vector of tag strings. Each tag in the vector is subject to the conditions of addTag |
|
inlineprotected |
This method informs whether the tree is past the lockdown phase for all LOCKED and HIDDEN parameters. Modifying LOCKED and HIDDEN parameters after this phase is disallowed. Tree can be locked down during TREE_BUILDING phase or TREE_CONFIGURING phase. During TREE_FINALIZING phase, all parameters are locked down as is.
Definition at line 2746 of file TreeNode.hpp.
|
protected |
Recursively invoke TreeNode::onBindTreeEarly_ and Resource::onBindTreeEarly_ (in that order for each node)
|
protected |
Recursively invoke TreeNode::onBindTreeEarly_ and Resource::onBindTreeLate_ (in that order for each node)
|
inlineprotected |
Symmetric oppostie of broadcastRegistrationForNotificationListStringToChildren_.
Definition at line 3230 of file TreeNode.hpp.
|
protectedvirtual |
Recursively notifies children that the notification described has lost one particular observer (del) which was observing at the observation point TreeNode obs_node with the delegate del.
This is the symmetric opposite of broadcastRegistrationForNotificationToChildren_
Override to use a non-standard child-list. By default, this method simply iterates this node's children and call itself recursively for each
|
inlineprotected |
Entry point to broadcastRegistrationForNotificationToChildren_ recursion. Breaks a name string.
Definition at line 3214 of file TreeNode.hpp.
|
protectedvirtual |
Recursively notifies children that the notification described is now (or still is) being observed at the observation point TreeNode obs_node with the newly registered delegate del.
[in] | tinfo | Type info of the notification |
[in] | name_ids | vector of pointers to names or glob-like treenode identifier patterns. that may or may not be interned with sparta::StringManager. |
[in] | obs_node | Node at which observer was installed |
[in] | del | Delegate to invoke when the notification posts |
This method allows Notification nodes to keep a map of which TreeNodes are observing observing a notification and what delegates are registered to observe that notification. The delegates can then be invoked directly by notification sources when appropriate notifications are posted.
Override to use a non-standard child-list. By default, this method simply iterates this node's children.
bool sparta::TreeNode::canGenerateNotification | ( | const NotificationInfo & | info | ) | const |
Can this TreeNode generate a notification of the given NotificationInfo.
bool sparta::TreeNode::canGenerateNotification | ( | const std::type_info & | tinfo, |
const std::string & | name | ||
) | const |
Can this TreeNode generate a notification of the given type having the given name (does not require interned string - will intern automatically with StringManager).
This is a version of the other canGenerateNotification function which does not require name to be a string interned with StringManager. Though the other variant is faster, this can be more convenient.
bool sparta::TreeNode::canGenerateNotification | ( | const std::type_info & | tinfo, |
const std::string * | name | ||
) | const |
Can this TreeNode generate a notification of the given type having the given name or pattern.
tinfo | type_info from typeid on the type of notification being queried. |
name | Pointer to interned name or pattern of notifications to query (from StringManager::internString). If This value is StringManager::EMPTY, looks for notifications having any name. glob-like patterns are supported (see matchesGlobLike). |
Example
bool sparta::TreeNode::canSubtreeGenerateNotification | ( | const std::type_info & | tinfo, |
const std::string & | name | ||
) | const |
Can this TreeNode or its descendants (of any distance) generate a notification of the given type having the given name (does not require interned string)
This is a version of the other canGenerateNotification function which does not require name to be a string interned with StringManager. Though the other variant is faster, this can be more convenient.
bool sparta::TreeNode::canSubtreeGenerateNotification | ( | const std::type_info & | tinfo, |
const std::string * | name | ||
) | const |
Can this TreeNode or its descendants (of any distance) generate a notification of the given type having the given name.
tinfo | type_info from typeid on the type of notification being queried. |
name | Pointer to interned name of notifications to query about (from StringManager::internString). If This value is StringManager::EMPTY, looks for notifications having any name. |
Uses canGenerateNotification at each node to check. Returns on first match.
Example
bool sparta::TreeNode::canSubtreeGenerateNotifications | ( | const std::type_info & | tinfo, |
const std::vector< const std::string * > & | names | ||
) | const |
Checks to see if any a subtree can generate any of several notification names which may be patterns.
|
static |
Compute a regex pattern for a node child path containing any number of wildcard characters (not a dot-separated location) which can be used to test against child node names.
pat | Pattern for searching immediate children (e.g. "core*" or "core0") |
|
inline |
Removes at most one registration made with registerForNotification.
Refer to registerForNotification for more information about parameters. To deregister an observer delegate registered through registerForNotification, pass the same arguments.
Definition at line 3693 of file TreeNode.hpp.
|
inline |
Definition at line 3700 of file TreeNode.hpp.
|
protectednoexcept |
Allows resources to write out detailed textual debugging information about the node. This is typically called by a simulator when shutting down due to an exception (or depending on simulator config). However, it could also be called at other times.
out | Output osteam to which this node should write all of its debug state. Note that this is not necessarily the same ostream for all nodes and resources, so this should not be shared. |
Must | not throw! |
|
inline |
Retrieves the relevant NotificationSources from locateNotificationSources and prints them to the output o.
DataT | type of notification to search for or ANY_TYPE. See locateNotificationSource. |
o | ostream to write found nodes to. |
Definition at line 3470 of file TreeNode.hpp.
|
noexcept |
Dumps a listing of the notifications which this node can generate to the ostream o.
o | ostream to which the notification info list will be dumped |
|
noexcept |
Dumps a listing of the notifications which this node and its descendants can generate to the ostream o.
o | ostream to which the noitification info list will be dumped |
|
protectednoexcept |
Recursively enter TREE_CONFIGURING phase.
Cannot | throw /post res_ of this node contains allocated Resource unless there was an exception |
|
protected |
Recursively enter TREE_FINALIZED phase.
SpartaException | if already in TREE_FINALIZED phase or beyond |
|
protected |
Recursively enter TREE_FINALIZING phase.
SpartaException | already in TREE_FINALIZING phase or beyond |
|
protectednoexcept |
Recursively enter TREE_TEARDOWN phase while alerting nodes through onEnteringTeardown_ and alterting Resources through Resource::onStartingTeardown_. Nodes already in TREE_TEARDOWN phase will not be alerted (neither will their associated Resources). All nodes are visited regardless of their parent's phase.
Cannot | throw |
|
protected |
Recursively create resources based on tree configuration. enter_finalize_ should be invoked after this method successfully completes for an entire tree. Finalizes in the order of construction.
exception | if there is an error anywhere in the finalization procedure. No actions are rolled-back, but this method can be called again. |
|
inline |
Find ancestor by name.
name | The name of the ancestor, can include wildcards understood by Sparta |
Definition at line 1154 of file TreeNode.hpp.
|
inline |
Find the first ancestor with a particular tag.
tag | the tag we are searching for. |
This method will traverse up the tree until it finds a TreeNode who's tag matches the searched tag. This does not, by any means, guarantee that the resource is actually available yet.
Definition at line 1203 of file TreeNode.hpp.
|
inline |
Find ancestor by type.
T | The Resource type to check for |
This method will traverse up the tree until it finds a TreeNode who's resource type matches the given type. This does not, by any means, guarantee that the resource is available for obtaining.
Definition at line 1181 of file TreeNode.hpp.
|
inline |
Find an ancestor's resource with a certain type.
T | the resource type you'd like to return. |
This method is similar to findAncestorByType but will return the parent's resource instead.
Definition at line 1226 of file TreeNode.hpp.
|
inline |
Version of findChildren with no replacements vector.
Definition at line 1431 of file TreeNode.hpp.
|
inline |
Finds all children starting at this node with a given pattern relative to this node by matching names an aliases. Appends each found child to <results>.
pattern | Search pattern in a restricted glob format. |
results | All children with identifiers matching the pattern (alias or name) are appended to the back of this vector. Order of results appended is implementation dependent and not guaranteed consistent. All children found from this invocation of findChildren (and any deeper recursion) will be adjacent in <results>. |
replacements | Vector of replacements made on wildcards in path in order to find children. For each result added to results, a vector element is added to replacements. That vector element vector contains as many replacements as there are wildcards in the pattern. To clarify results.size()=replacements.size() and If replacements.size() > 1, replacements[0].size() is the number of wildcards in pattern. |
const
to allow the caller to modify the found TreeNodes Does | not throw. May print a warning when a pattern attempts to search up and the current node has no parent. |
The following glob wildcard patterns are supported
The following additional patterns are supported
The following glob patterns are not supported
For example:
Definition at line 1421 of file TreeNode.hpp.
uint32_t sparta::TreeNode::findChildrenByTag | ( | const std::string & | tag, |
std::vector< TreeNode * > & | results, | ||
int32_t | max_depth = -1 |
||
) |
Finds a set of all children having the selected tag which this node or descendants of this node within a distance of the given max_depth.
tag | Nodes having this tag will be placed into results vector |
results | Vector of to which all results found by this method will be appended. This vector is not cleared |
max_depth | Maximum depth of a ancestor/descendant relationship when filtring children. 0 means that any nodes returned must be the node on which this method is invoked, 1 means that any nodes returned can be this or immediate children, and so on. A max_depth of -1 means that there is no limit on ancestor-descendant distance |
This search works by searching the global tag map for the specified tag and then filtering this list for nodes which are a descendants of the node on which this method is invoked.
|
inlineprotected |
Finds a delegate associated with the given type T, object pointer, DataT, and TMethod within a DelevateVector. The intent of this function is to help see if a delegate is already registered with a calback by checking all known information associated with that callback against the input arguments.
[in] | dvec | Vector of delegates to search |
[in] | obj | Object which owns the delegate |
[in] | target_name | Name or pattern of notification type. that this is used as-is. |
Definition at line 3134 of file TreeNode.hpp.
|
inlineprotected |
Definition at line 3149 of file TreeNode.hpp.
|
virtual |
Const-qualified variant of findImmediateChildren_.
Reimplemented in sparta::VirtualGlobalTreeNode.
|
virtual |
Finds immediate children with some identity (name or alias) matching a regex.
expr | Expression to match with child node identities |
found | All nodes with matching identities are appended to this vector. This vector is not cleared |
Reimplemented in sparta::VirtualGlobalTreeNode.
const AliasVector & sparta::TreeNode::getAliases | ( | ) | const |
Gets a vector of all aliases of this node.
|
inline |
Retrieves this node after casting to type const T.
T | Type of child expected |
SpartaException | if this node could not be cast to T |
Overload of getAs for non-const access with pointer T type.
Definition at line 1712 of file TreeNode.hpp.
|
inline |
Retrieves this node after casting to type const T.
T | Type of child expected |
SpartaException | if this node could not be cast to T |
Overload of getAs for non-const access with non-pointer T type
Definition at line 1735 of file TreeNode.hpp.
|
inline |
Retrieves this node after casting to type T.
T | Type of child expected |
SpartaException | if this node could not be cast to T |
This could eventually be optimized or used to provide meaningful errors by storing type information in TreeNode.
Definition at line 1674 of file TreeNode.hpp.
|
inline |
Retrieves this node after casting to type const T.
T | Type of child expected |
SpartaException | if this node could not be cast to T |
Overload of getAs for const access with a pointer T type.
Definition at line 1697 of file TreeNode.hpp.
|
inline |
Retrieves a child with this dotted path name.
name | path to child. This may be a single name or a dotted path refering to a node several levels below this node. |
must_exist | If true, requires the child to exist by throwing an exception if it does not. If false, allows the method to return nullptr when no child is found. |
SpartaException | if child is not found and must_exist==true |
Example:
Definition at line 1531 of file TreeNode.hpp.
|
inline |
Overloaded const-qualified.
Definition at line 1538 of file TreeNode.hpp.
|
inline |
Definition at line 1634 of file TreeNode.hpp.
|
inline |
Definition at line 1655 of file TreeNode.hpp.
|
inline |
Retrieves a child that is castable to T with the given dotted path.
T | Type of child expected |
name | Name of child. May be a dotted path indicating multiple levels of device-tree traversal. |
must_exist | If true, Causes an exception to be thrown if no child by this name could be found. If false, a nullptr is returned. Finding a child and failing to cast to T always causes an exception to be thrown |
SpartaException | if must_exist==true and either the child by the given name (path) could not be found or the found node was not castable to T |
Definition at line 1606 of file TreeNode.hpp.
|
inline |
Definition at line 1628 of file TreeNode.hpp.
TreeNode * sparta::TreeNode::getChildAt | ( | uint32_t | idx | ) | const |
Gets a child at a position in the children vector in the order in which they were added to this node.
SpartaException | if idx is out of range. |
This method is for iteration-purposes only (so that wrappers may avoid STL). The index used here is NOT a consistent property with any TreeNode or Resource.
const ChildrenVector sparta::TreeNode::getChildren | ( | ) | const |
Gets a vector of all children of this node in any group in the order in which they were added to this node.
uint32_t sparta::TreeNode::getChildren | ( | std::vector< TreeNode * > & | results, |
bool | ignore_builtin_group = true , |
||
bool | ignore_anonymous_nodes = true |
||
) |
Gets all children of this node in the order in which they were added to this node.
results | Vector to which all children will be appended. This vector is not result. |
ignore_builtin_group | Ignore any children in group GROUP_NAME_BUILTIN. |
ignore_anonymous_nodes | Ignore any children in group GROUP_NAME_ |
uint32_t sparta::TreeNode::getChildrenIdentifiers | ( | std::vector< std::string > & | idents, |
bool | ignore_builtin_group = true |
||
) | const |
Gets all child identifiers, aliases, group names, and group-aliases which can be used to refer to a child of this node.
idents | Vector to fill with new identities. Vector is not cleared. |
ignore_builtin_group=true | If true, rejects the builtin group. |
This is useful for shell completion when browsing the children of a node.
|
inline |
return all the children matching a particular type using dynamic cast.
Definition at line 1136 of file TreeNode.hpp.
|
inline |
Definition at line 2053 of file TreeNode.hpp.
|
inlineoverridevirtual |
Walks up parents (starting with self) until a parent with an associated local clock is found, then returns that clock.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Implements sparta::ResourceContainer.
Definition at line 2033 of file TreeNode.hpp.
std::string sparta::TreeNode::getDeepestMatchingPath | ( | const std::string & | path | ) | const |
Gets the deepest whole node location starting from this node that matches some part of path starting at its beginning.
path | Path to node relative this this node. |
Ths intent of this is to find out where a path given by a user (e.g. configuration file) diverged from the actual tree for feedback purposes
|
noexcept |
Gets the vector of delegates registered for a notification on this TreeNode.
tinfo | typeid of the notification to be queried |
name | Name of the notification to be queried (Can be "" to ignore name) |
dels | Vector to which all found delegates matching search parameters will be appended. This vector is not cleared |
const std::string & sparta::TreeNode::getDesc | ( | ) | const |
Gets the description of this node.
std::string sparta::TreeNode::getDisplayLocation | ( | ) | const |
Returns the location of this node in the device tree which might not be usable for navigating the device tree (it cannot be used as an argument for getChild/findChildren).
This differs from getLocation by representing nodes with groups and no names as "group[group_index]" instead of "name". This string cannot currently be used to find children by pattern or name because it refers to a group.
A motifivation for this method is to allow identification of elements in anonymous buffers and queue resources to simulator tools.
ExtensionsBase * sparta::TreeNode::getExtension | ( | const std::string & | extension_name | ) |
Get an extension object by type string. Returns nullptr if not found (unrecognized).
extension_name | The name of the extension to find |
const std::string & sparta::TreeNode::getGroup | ( | ) | const |
uint32_t sparta::TreeNode::getGroup | ( | const std::string & | group, |
std::vector< TreeNode * > & | results | ||
) |
Gets all nodes in a child group.
group | Name of group to get children from. If GROUP_NAME_NONE, will retrieve only children with group=GROUP_NAME_NONE. |
results | Vector of nodes to which results will be appended. |
To get all children regardless of group, use getChildren
group_idx_type sparta::TreeNode::getGroupIdx | ( | ) | const |
group_idx_type sparta::TreeNode::getGroupIndexMax | ( | const std::string & | group | ) |
Gets the largest index of a node in the given group.
group | Name of group to get the index from. |
const std::string * sparta::TreeNode::getGroupNamePtr | ( | ) | const |
Gets the group name string pointer (interned in StringManager singleton) of this node.
uint32_t sparta::TreeNode::getGroupSize | ( | const std::string & | group | ) |
Gets the number of nodes in a group.
group | Name of group to get children from. If GROUP_NAME_NONE, will retrieve only children with group=GROUP_NAME_NONE. |
To count all children regardless of group, use getNumChildren
std::vector< const std::string * > sparta::TreeNode::getIdentifiers | ( | ) | const |
Gets all the identifiers for this node (excluding groups)
uint32_t sparta::TreeNode::getLevel | ( | ) | const |
Gets the level of this node. 0 is root.
This is computed based on the number of parents iterated until a node with no parents is reached.
|
inline |
Gets the clock associated directly with this Node. This is useful for configuration and simulator debug, but not at run-time.
By default TreeNodes are not associated (or required to be associated) with a sparta::Clock. Subclasses may require this, however.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Definition at line 2083 of file TreeNode.hpp.
|
inline |
Definition at line 2090 of file TreeNode.hpp.
|
finaloverridevirtual |
Implements sparta::PhasedObject.
|
overridevirtual |
const std::string * sparta::TreeNode::getNamePtr | ( | ) | const |
Gets the name of this node's string pointer which isinterned in StringManager)
|
static |
Gets the next name between two '.' chars in a string starting at pos.
name | Name string to parse |
pos | Position in name to begin parsing. Will be updated to location of the next '.' found plus 1. |
Used for parsing tree paths:
uint32_t sparta::TreeNode::getNumChildren | ( | ) | const |
Gets the number of children that this node has including those in the sparta builtins group.
|
inlinevirtual |
Gets immediate parent of this node if one exists.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Reimplemented in sparta::GlobalTreeNode, sparta::RootTreeNode, and sparta::VirtualGlobalTreeNode.
Definition at line 965 of file TreeNode.hpp.
|
inlinevirtual |
Definition at line 972 of file TreeNode.hpp.
|
inline |
Definition at line 1010 of file TreeNode.hpp.
|
inline |
Definition at line 1024 of file TreeNode.hpp.
|
inline |
Retrieves a parent casted to type T* if this node has a parent.
T | Type of parent to cast to |
must_exist | If true, Causes an exception to be thrown if node has no parent or the parent cannot be dynamically cast to T*. If false, a nullptr is returned when this node has no parent that can be cast to T*. |
SpartaException | if must_exist==true and the parent was null or the parent could not be cast to a T*. |
Definition at line 990 of file TreeNode.hpp.
|
inline |
Definition at line 1004 of file TreeNode.hpp.
uint32_t sparta::TreeNode::getPossibleNotifications | ( | std::vector< NotificationInfo > & | infos | ) | const |
Gets information on the possible notifications generated by this node (excludes children).
infos | Vector of notification inormation to which this node's information will be added |
|
noexcept |
Gets information on the possible notifications generated by this node and all its descendants.
infos | Vector of notification information to which this node's information will be added |
|
staticprotected |
Gets the previous name between two '.' chars in a string starting at pos.
name | Name string to parse |
pos | Position in name to begin parsing in reverse. Must coincide with a '.' or end of string. Will be updated to location of the next '.' found. Set to npos if the beginning of the string is reached. To start parsing a string from the end, should be set to length of string. |
Used for parsing tree paths:
|
inline |
Recursively gets the count of a nodes that are a subclass of a particular type (determined by dynamic_cast). Includes all descendants of this node in the tree, but excludes this node.
Definition at line 1854 of file TreeNode.hpp.
|
virtual |
Gets farthest ancestor of this node.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
TreeNode * sparta::TreeNode::getScopeRoot | ( | ) |
Returns the root of the scope that this tree node is in.
const TreeNode * sparta::TreeNode::getScopeRoot | ( | ) | const |
Returns the root of the scope that this tree node is in.
app::Simulation * sparta::TreeNode::getSimulation | ( | ) | const |
Gets the simulation (if any) associated with this tree.
const std::vector< const std::string * > & sparta::TreeNode::getTags | ( | ) | const |
Gets the set of tags associated with this TreeNode.
Tags are useful for associating meta-data with a TreeNode and forming virtual groupings of nodes independent of hierarchy. For example, all nodes (e.g. counters and notification sources) having to do with power-modeling may have "power" tags indicating presence in a virtual "power" group.
|
static |
Gets the virtual global node singleton. This node can have no parent and no children. It receives notifications from all nodes in the simulator as if it were the parent of every node in the simulation that has no parent.
This node is typically used to add logging taps that receive messages before the entire device tree hierarchy is defined. This allows warning messages from a newly-constructed node to be sent somewhere, even before that node is part of any device tree.
WeakPtr sparta::TreeNode::getWeakPtr | ( | ) |
Gets a weak pointer to this TreeNode. This weak pointer is guaranteed to expire when this TreeNode is destructed unless locked.
Example
|
inlinenoexcept |
Determines if a child can be found with the given dotted path.
name | Dotted path to child |
Definition at line 1571 of file TreeNode.hpp.
|
noexcept |
Determines if the node n is an immediate child of this node.
n | Node to test for child-ness of this |
|
noexcept |
Determines if this TreeNode (not descendants) has any observers for this type of event and name.
tinfo | typeid of the notification to be queried |
name | Name of the notification to be queried (Can be "" to ignore name) |
bool sparta::TreeNode::hasTag | ( | const std::string * | interned_tag_name | ) | const |
Does this node have a specific tag (by string pointer interned with StringManager). This is faster than the alternate hasTag method because it relies only on pointer comparisons.
[in] | interned_tag_name | Tag pointer. Caller must get this pointer argument from sparta StringManager or it may not match |
|
static |
Determines if a given node name has any wildcard characters which will be substituted in createSearchRegexPattern.
This is useful for identifying which nodes are patterns and which are concrete node names. It is important to keep this in ssync with createSearchRegexPattern
|
staticprotected |
Performs pattern matching on a identity string.
ident | Regex identity. This could be generated from an input glob pattern |
expr | Expression to compare against ident |
replacements | Returns each captured replacement of a in the expression |
|
inlineprotected |
Protected wrapper for invokeDelegates_ which allows a TreeNode to invoke delegates on another TreeNode using itself as the origin.
to_invoke | TreeNodes whose delegates will be invoked (those which are appropriate for the specified DataT and name_id) |
See invokeDelegates_ for other argument semantics
Definition at line 3250 of file TreeNode.hpp.
bool sparta::TreeNode::isAnonymous | ( | ) | const |
Is this node anonymous.
|
inlinevirtual |
Is this node part of a device tree with a proper RootTreeNode at the root.
Reimplemented in sparta::GlobalTreeNode, sparta::RootTreeNode, and sparta::VirtualGlobalTreeNode.
Definition at line 957 of file TreeNode.hpp.
bool sparta::TreeNode::isBuiltin | ( | ) | const |
Is this node in the builtins group.
bool sparta::TreeNode::isDescendantOf | ( | const TreeNode * | ancestor, |
int32_t | max_depth = -1 |
||
) | const |
Determines if this node is a descendant of the specified ancestor node within some number of generations (depth).
ancestor | TreeNode that will be tested for being a parent this TreeNode |
max_depth | Maximum depth (distance) between ancestor and this node that will allow this test to return true. A more distance ancestor/descendant relationship will cause this method to false. A max depth of 0 implies this node and ancestor must be the same node, a max_depth of 1 means that the ancestor must be an immediate parent or self, 2 means parent of parent or closer, and so on. max_depth of -1 means no limit. |
bool sparta::TreeNode::isExpired | ( | ) | const |
Is this expired (i.e. has it been the rhp of a move constructor)
bool sparta::TreeNode::isHidden | ( | ) | const |
|
static |
Is a given node constructed?
|
inline |
Returns true if this tree node is a scope root
Definition at line 2017 of file TreeNode.hpp.
|
inline |
Gets all possible notification info from NotificationSources within this node's subtree.
DataT | type of data for which to search. This must be non-const, non-volatile, non-pointer, and non-reference. |
nodes | Result set of nodes to which all found nodes will be appended. This vector is not cleared. |
name | Name of the NotificationSource to search for. Specifying "" locates any sourcee matching on DataT. |
Example:
Definition at line 3444 of file TreeNode.hpp.
bool sparta::TreeNode::locationMatchesPattern | ( | const std::string & | pattern, |
const TreeNode * | pat_loc | ||
) | const |
Determines if the given pattern (which may contain wildcards) can describe this node.
pattern | Pattern to compare this node's location against. This pattern CANNOT have any upward traversal (parent references). |
pat_loc | TreeNode representing the starting point of pattern. This pat_loc node must be AT or ABOVE *this in the tree, otherwise this method will always report false. |
SpartaException | if pattern contains upward traversal |
Example:
|
inline |
Method to put the device tree in lockdown phase. All LOCKED and HIDDEN parameters are frozen after this point. Regular parameters are not affected by this phase. This method requires a Simulation pointer and will assert at compile time if anyone tries to lockdown the tree without the context of a Simulation.
Lockdown the tree node if Simulation is valid
Definition at line 430 of file TreeNode.hpp.
|
inline |
Make the entire subtree private.
This will add 1 to privacy_level_ for every node below, this means it should work if B->C, where C is private on B, and B is added as a private child of A, A.privacy_level_ = 0, B.privacy_level_ = 1, C.privacy_level_ = 2 (C.privacy_level_ was previously == 1).
See documentation for the privacy_level_ variable to really understand what this is doing and why.
Definition at line 2000 of file TreeNode.hpp.
|
static |
Determine if a glob-like search pattern matches some other string.
[in] | pattern | Glob-like pattern to search with. This is standard SPARTA tree identifier pattern syntax |
[in] | other | Other string with which pattern is being compared |
|
static |
Checks if two notification categories match where one is an actual category.
[in] | query_id | pointer to StringManager interned string which may be a single category or a glob-like pattern. If StringManager.EMPTY, matches all patterns. |
[in] | node_id | concrete category. This is a name, not a pattern. |
|
static |
Parses a comma-separated list of notification names (or patterns) separated by commas and ignoring whitespace around commas.
[in] | csl | Comma-separated list (e.g. "a,b,foo*"). Most common case will be a single name with no commas |
|
inlineprotected |
Starts a notification propagating up the tree.
name_id | Pointer to interned name in StringManager. Compared against delegate name. The pointer is treated like a numeric ID for comparison. |
Definition at line 3091 of file TreeNode.hpp.
|
protected |
Finds the deepest node path mathing the input path. Implements getDeepestMatchingPath.
|
inline |
Registers a callback method to listen for all notifications having the specified data type DataT and name (or any name if name is "") occuring on this node or any descendant (subtree).
DataT | Type of data object given to the notification callback function registered. This type must be a C++ typename of a type which is copyable, non-const, non-reference, and non-pointer. Useful values for this type can be found by locating sparta::NotificationSource nodes throughout the device tree and then by looking at sparta::NotificationSource::getNotificationTypeName. Note that ANY_TYPE is not a valid argument for DataT. |
T | Class of object on which callback member function will be invoked. |
TMethod | member function pointer of class T that will be invoked when the specified notification is posted. This member function signature must be: ClassName::func(// TreeNode from which the notification originated
const TreeNode& origin_node,
// TreeNode at which the notifications was observed, causing this callback
const TreeNode& observation_node,
// Notification event data
const datat& data)
Node in a composite tree representing a sparta Tree item. Definition TreeNode.hpp:205 |
name | Name of notification being observed. If name is "", all notifications having a data type of DataT will cause this callback to be notified. Locating a notificationSource in the device tree and and using sparta::NotificationSource::getNotificationName can help to determine useful values for name. |
ensure_possible | If true, this method will check that one or more nodes in this node's subtree can generate the notification described by DataT and name. If false, this test is not performed. |
SpartaException | if a ensure_possible=true and a registration is made on a DataT/name combination that cannot be posted by this the node's subtree (since there are no ancestor NotificationSource nodes). |
NotificationSources can be located throughout the simulation using the sparta::TreeNode::locateNotificationSources method.
The methods getPossibleSubtreeNotifications and dumpPossibleSubtreeNotifications can assist in finding NotificationSource nodes in the device tree.
Example:
Definition at line 3671 of file TreeNode.hpp.
|
inline |
Definition at line 3678 of file TreeNode.hpp.
|
protected |
"Removes" the given child by invoking onDestroyingChild_ then removing this child from the children_ list
child | Child to remove from this node. Must actually be a current child of SpartaException is thrown |
SpartaException | if child is not an actual child of this node |
|
protected |
Protected Wrapper for getParent()->removeChildForTeardown_ which allows subclases of TreeNode to indirectly invoke removeChildForTeardown_ with themselves as the argument.
parent | Parent to remove this child from. Must be this TreeNode's parent. Must not be nullptr |
std::string sparta::TreeNode::renderSubtree | ( | int32_t | max_depth = -1 , |
bool | show_builtins = false , |
||
bool | names_only = false , |
||
bool | hide_hidden = false , |
||
bool(*)(const TreeNode *) | leaf_filt_fxn = nullptr |
||
) | const |
Renders the subtree starting at this node as a string containing an indentation-based depth-first representation.
max_depth | Number of levels below this Node to traverse. 0 means this node only. Negative depth means no limit. |
show_builtins | When false, hides all TreeNodes in the GROUP_NAME_BUILTIN group. If true, shows all nodes |
names_only | When true, renders names of nodes. Otherwise, renders string representation of nodes prints only this node. |
hide_hidden | Hides any nodes (and their subtrees) maked as hidden |
leaf_filt_fxn | Filtering function. If nullptr, has no effect. If not nullptr, this function is invoked on each LEAF node encountered to determine whether it should be displayed. If this function returns false, the leaf node is not rendered. If true, the leaf node is rendered. Non-leaf nodes are not subject to filtering, but will be omitted if they contain no leaves (at any depth) which pass the leaf filter function. Note that max_depth prohibits recursion past a certain depth, so nodes may not be shown even if they have ancestor leaves that would be visible (according to the filter) but are below the max_depth threshold. |
|
virtual |
Assigns a clock to this node. This clock will then be accessed by any descendant which has no assigned clock or an ancestor with an assigned clock between that descendant and this node. getClock returns the Clock associated with the nearest ancestor.
clk | Clock to assign. Must not be null. |
Reimplemented in sparta::RootTreeNode.
|
protected |
Tracks a node as an expected parent without actually adding this node as a child. This is used almost exclusively for printing error messages which include a device-tree location BEFORE actually inserting this node into the device tree since node construction can fail.
parent | Parent TreeNode that will act as the parent for the purposes of printing device-tree location for this node. |
Typical usage is to invoke this at the very beginning of the constructor of a sparta::TreeNode subclass. This allows sparta::TreeNode::getLocation to function as if this node were actually part of a tree. After successful construction, addChild can be used to connect this node to a parent in the device tree. At that time, the expected parent is set back to nullptr.
Using an expected parent for the purposes of printing a device-tree location during construction is much cleaner and simpler than adding a child node to some parent and then trying to remove it if something goes wrong during construction.
|
inline |
Make this tree node the root of a scope
Definition at line 2008 of file TreeNode.hpp.
|
protected |
Hook to allow simulation resources to clean-up before simulation is ended.
Any | exceptions related to post-run state |
|
inlinevirtual |
Create a string representation of this node.
pretty | Print a more verbose, multi-line representaiton (if available). |
Subclasses should override this with representations appropriate for their type.
Reimplemented in sparta::CounterBase, sparta::EventSet, sparta::RegisterBase::Field, sparta::Register, sparta::RegisterSet, sparta::log::MessageSource, sparta::NotificationSourceBase, sparta::memory::BlockingMemoryIFNode, sparta::ExportedPort, sparta::Clock, sparta::DynamicResourceTreeNode< ResourceT, ParamsT >, sparta::GlobalTreeNode, sparta::ParameterBase, sparta::ParameterSet, sparta::ResourceTreeNode, sparta::RootTreeNode, sparta::Counter, sparta::CycleCounter, sparta::ReadOnlyCounter, sparta::StatisticDef, sparta::StatisticSet, and sparta::Port.
Definition at line 723 of file TreeNode.hpp.
|
inline |
Render tags to a string in the form: " tags:[tag0, tag1]" If there are any tags. The leading space makes this a useful sub-utility of stringize because if there are no tags, returns empty string with no leading space.
ss | stringstream to write to |
Definition at line 743 of file TreeNode.hpp.
void sparta::TreeNode::validateDesc | ( | const std::string & | desc | ) |
Validates the given description string for this TreeNode.
SpartaException | if the string is invalid |
Constraints:
void sparta::TreeNode::validateGroup | ( | const std::string & | name, |
const std::string & | group, | ||
group_idx_type | idx | ||
) |
Validates the given group name string and group index for this TreeNode. Does not consider context (e.g. name collisions)
name | Node name |
group | Group name |
idx | Group index |
SpartaException | if the group name and group index combination is invalid (i.e. already used by another node) |
Constraints:
void sparta::TreeNode::validateName | ( | const std::string & | nm | ) |
Validates the given name string for this TreeNode. Does not consider context (e.g. name collisions)
SpartaException | if the name is invalid. |
Constraints:
|
protected |
Hook to check the state of the simulator post-run and throw exceptions if something is incorrect.
Any | exceptions related to post-run state |
|
protected |
Iterates the finalized tree and validates each node (e.g. ensures statistics can be evaluated)
SpartaException | if any node cannot be validated |
|
protected |
Verifies that the given identifier is unique for all children of this node by comparing against names, groups, and aliases. Throws SpartaException if not unique.
ident | Identifier of child to check for uniqueness (e.g. a name or alias) |
ignore_group_collision | If true, collisions of keys where the existing value in the names_ map is a Grouping are ignored. (default false: throw exception on collision). |
SpartaException | if a ident is not unique. |
|
friend |
Allow ClockManager to directly change phase on nodes.
Definition at line 217 of file TreeNode.hpp.
|
friend |
This class is responsible for instantiating the static container held by this TreeNode.
Definition at line 223 of file TreeNode.hpp.
|
friend |
Friend an attorney pattern that can expose access to getAllChildren_ or other methods that bypass privacy_level_.
Definition at line 229 of file TreeNode.hpp.
|
friend |
Allow this class access internals for handling notification observation registration/deregistration broadcasts in a way that does not fit the composite tree pattern.
Definition at line 212 of file TreeNode.hpp.
|
static |
Threshold for number of findChildren calls after finalization before a warning message is printed about framework misuse.
This value should be large enough that a few accesses by tools or lookups for caching pointers to other objects are allowed, but small enough that a findChildren call happening every N cycles of execution in the simulator will be detected during runs that take more than a few minutes. Consider that Parameters are also part of a tree and ParameterSet or RegisterSet nodes may be the target of some getChild calls after finalization, but generaly these nodes should be cached in the requesting component.
Definition at line 392 of file TreeNode.hpp.
|
static |
Threshold for number of getChild calls after finalization before a warning message is printed about framework misuse.
See CHILD_FIND_THRESHOLD for explanation of threshold value choice
Definition at line 400 of file TreeNode.hpp.
|
static |
String dividing sections in a debug dump file.
Definition at line 324 of file TreeNode.hpp.
|
static |
GroupIndex indicating that a node has no group index because it belongs to no group.
Definition at line 303 of file TreeNode.hpp.
|
staticconstexpr |
Reserved name for built-in nodes.
Nodes in this group are exempt from certain restrictions and filtered from printing and searching operations.
Definition at line 370 of file TreeNode.hpp.
|
staticconstexpr |
Group name indicating that a node belongs to no group.
Definition at line 314 of file TreeNode.hpp.
|
staticconstexpr |
Separator character between node identifiers in a location string when the child is attached to the parent.
Definition at line 337 of file TreeNode.hpp.
|
staticconstexpr |
Separator character between node identifiers in a location string when the child is being attached to the parent but has not been entirely attached (i.g. during construction of the child node)
Definition at line 346 of file TreeNode.hpp.
|
staticconstexpr |
Separator character preceding a node identifiers in a location string when that node has no parent and is not in the process of being attached to one.
Definition at line 355 of file TreeNode.hpp.
|
static |
Maximum value of node_uid_ before the framework throws an exception.
Definition at line 309 of file TreeNode.hpp.
|
staticconstexpr |
Node name for anonymous node.
Definition at line 319 of file TreeNode.hpp.
|
staticconstexpr |
Node name for the virtual glopbal node.
Definition at line 329 of file TreeNode.hpp.
|
static |
Spaces to indent for each tree level in sparta::TreeNode::renderSubtree.
Definition at line 362 of file TreeNode.hpp.
|
static |
Number of teardown-phase-related messages that can be printed before the rest will be suppressed.
Definition at line 406 of file TreeNode.hpp.
|
static |
List of pattern susbtitutions when creating a search pattern from a TreeNode name containing wildcards.
Definition at line 412 of file TreeNode.hpp.