Class AstAttribute

Class AstAttribute#

Nested Relationships#

Nested Types#

Inheritance Relationships#

Derived Types#

Class Documentation#

class AstAttribute#

Base class for all IR node attribute values.

This is the base class for all attribute values stored in the Sage IR node using the AstAttributeMechanism. IR node attributes are polymorphic based on this abstract class, and are always allocated on the heap. Once the attribute value is handed to an attribute container method the container owns the value and is responsible for deleting it. In the case of methods that only optionally insert a value, the value is deleted immediately if it’s not inserted. But see getOwnershipPolicy for additional information.

The underlying mechanism is designed to store values of any type, including POD, 3rd party types, and pointers. On the other hand, the AstAttributeMechanism interface described here stores only pointers to values allocated on the stack, owns those values, and supports operations that are useful specifically in IR nodes.

Subclasses should each implement a virtual copy constructor, which should allocate a new copy of the value. The implementation in this base class returns a null pointer, which means that the attribute is not copied into a new AST node when its AST node is copied. If a subclass fails to implement the virtual copy constructor and a superclass has an implementation that return non-null, then copying the AST node will copy only the superclass part of the attribute and the new attribute will have the dynamic type of the superclass—probably not what you want!

For a more detailed description of using attributes in ROSE (and your own classes) see attributes.

Subclassed by AstValueAttribute< int >, AstValueAttribute< SgNode * >, AstAttributeDOT, AstRegExAttribute, AstTextAttribute, AstUnparseAttribute, AstValueAttribute< T >, FrontierDetectionForTokenStreamMappingAttribute, MetricAttribute, PreviousAndNextAttribute, SageInterface::UniqueNameAttribute, StaticCFG::CFGEdgeAttribute< EdgeT >, StaticCFG::CFGNodeAttribute, VarUniqueName

Unnamed Group

virtual int packed_size()#

Packing support.

virtual char *packed_data()#
virtual void unpacked_data(int size, char *data)#

Unnamed Group

virtual std::string additionalNodeOptions()#

DOT support.

virtual std::vector<AttributeEdgeInfo> additionalEdgeInfo()#
virtual std::vector<AttributeNodeInfo> additionalNodeInfo()#

Public Types

enum OwnershipPolicy#

Who owns this attribute.

See getOwnershipPolicy.

Values:

enumerator CONTAINER_OWNERSHIP#

Container owns attribute.

New subclasses should use this!

enumerator NO_OWNERSHIP#

Attributes are always leaked.

enumerator CUSTOM_OWNERSHIP#

Subclass defines ownership policy.

enumerator UNKNOWN_OWNERSHIP#

Default for old subclasses.

Public Functions

virtual OwnershipPolicy getOwnershipPolicy() const#

Who owns this attribute.

The original implementation of this class from the early 2000’s did not have clear rules about who owned a heap-allocated attribute. The documentation was silent on the issue, and the implementation seemed to imply that container ownership was intended but was then commented out at some point. Any ownership policy should have the following properties:

  • Attributes allocated on the heap should not be leaked. For instance, if an AST is deleted, then the attributes that were referenced by the AST nodes should also be eventually deleted.

  • The mechanism should not place undue burden on the user. For instance, if a user copies and later deletes an AST to which some analysis has attached attributes, the user should not need to be concerned with deleting attributes stored in the copy.

  • The mechanism should be able to support either deep or shallow attribute copies as appropriate for the attribute. The deep vs. shallow copying policy is implemented by the virtual copy method, which must coordinate with the ownership policy to ensure no leaks.

We define four ownership policies, although from the standpoint of an attribute container there are really only two: the container either deletes attributes or doesn’t delete attributes. The four ownership policies are:

  • CONTAINER_OWHERSHIP: The simple approach to ownership, and the one that we recommend for all new attribute subclasses, is that the attribute container owns the attributes. When the container is copied (e.g., as part of copying an AST node) then it invokes the copy

    methods of its attributes, and when the container is deleted (e.g., as part of deleting an AST node) then it explicitly deletes its attributes. This policy is an “allocate and

    forget” approach: once the creator inserts an attribute into the container it transfers/moves ownership to the container and the creator never needs to invoke

    delete. This policy also means that users never need to explicitly delete attributes if they copy and then delete an AST. Newly designed attribute subclasses should use this policy unless they have a very good reason to use another policy.

  • NO_OWNERSHIP: Another simple approach is that ownership is transfered to the operating system. In other words, the attribute is never deleted by the program and its memory is reclaimed only when the program terminates. Attribute containers that are incorporated into objects that are frequently allocated and/or copied and then deleted will result in a large number of leaked attributes. This approach is not recommended and is present only for laziness.

  • CUSTOM_OWNERSHIP: A third approach is that the attribute subclass implements its own ownership policy, which ideally should have the properties listed above. An attribute using this policy will never be deleted by an attribute container; the class must implement some other mechanism for tracking which attributes are allocated and whether they can be safely deleted.

  • UNKNOWN_OWNERSHIP: This final policy is for subclasses implemented before clear attribute ownership rules were defined. Due to the ambiguity in the original AstAttributeMechanism implementation and the fact that attributes are used by code outside the ROSE library, this must be the default implementation.

Regardless of the ownership policy, an attribute must not be deleted while it is a member of an AstAttributeMechanism container. This is because in order for the container to decide whether it should delete the attribute, it must first ask the attribute for its ownership policy. In other words, the following code will likely result in a segmentation fault:

SgDirectedGraphEdge *edge = ...;
delete edge->getAttribute("info");
delete edge; // INVALID ACCESS TO EDGE ATTRIBUTE HERE
inline AstAttribute()#
inline virtual ~AstAttribute()#
inline virtual AstAttribute *constructor() const#

Virtual default constructor.

Default-constructs a new object on the heap and returns its pointer. All subclasses must implement this in order to instantiate the correct dynamic type, although many don’t. Invoking this constructor in a subclass that fails to implement it will return an attribute that’s an incorrect dynamic type.

It would be nice if we could make this pure virtual, but unfortunately ROSETTA-generated code fails to compile because it generates an instantiation of this interface (whether or not that code is ever executed is unknown). [Robb Matzke 2015-11-10].

inline virtual AstAttribute *copy() const#

Virtual copy constructor.

Copy-constructs a new object on the heap and returns its pointer. All subclasses must implement this in order to instantiate the correct dynamic type, although many don’t. If this copy method returns a null pointer (like the base implementation) then the attribute is not copied as part of copying its container. E.g., an attribute stored in an AST will not be copied when the AST is copied if that attribute is directly derived from AstAttribute and fails to implement copy. If a subclass fails to implement copy and inherits from a class that does implement a copy that returns non-null, then the copied attribute will have an incorrect dynamic type.

It would be nice if we could make this pure virtual, but unfortunately ROSETTA-generated code fails to compile because it generates an instantiation of this interface (whether or not that code is ever executed is unkown). [Robb Matzke 2015-11-10]

inline virtual AstAttribute *copy()#
inline virtual std::string attribute_class_name() const#

Attribute class name.

Returns the name of the dynamic type. All subclasses must implement this in order to return the correct type name, although many don’t. If a subclass fails to implement this then it will return an incorrect class name.

It would be nice if this could be pure virtual, but unfortunately ROSETTA-generated code fails to compile because it generates an instantiation of this interface (whether or not that code is ever executed is unknown). [Robb Matzke 2015-11-10]

virtual std::string toString()#

Convert an attribute to a string.

This is used by other components to print the value of an attribute. For example the pdf generation calls this function to print the value of an attribute in the pdf file. The default implementation is to return the attribute address in the heap as a string.

virtual bool commentOutNodeInGraph()#

Eliminate IR nodes in DOT graphs.

Or to tailor the presentation of information about ASTs.

class AttributeEdgeInfo#

Support for attributes to specify edges in the dot graphs.

Public Functions

inline AttributeEdgeInfo(SgNode *fromNode, SgNode *toNode, std::string label, std::string options)#
inline ~AttributeEdgeInfo()#

Public Members

SgNode *fromNode#
SgNode *toNode#
std::string label#
std::string options#
class AttributeNodeInfo#

Support for adding nodes to DOT graphs.

Public Functions

inline AttributeNodeInfo(SgNode *nodePtr, std::string label, std::string options)#
inline ~AttributeNodeInfo()#

Public Members

SgNode *nodePtr#
std::string label#
std::string options#