AstAttribute Class Reference

Description

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 reponsible 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 Sawyer::Attribute mechanism can 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 Working with attributes.

Definition at line 36 of file AstAttributeMechanism.h.

#include <midend/astProcessing/AstAttributeMechanism.h>

Inheritance diagram for AstAttribute:

Classes
class	AttributeEdgeInfo
	Support for attibutes to specify edges in the dot graphs. More...
class	AttributeNodeInfo
	Support for adding nodes to DOT graphs. More...

Public Types
enum	OwnershipPolicy {   CONTAINER_OWNERSHIP ,   NO_OWNERSHIP ,   CUSTOM_OWNERSHIP ,   UNKNOWN_OWNERSHIP }
	Who owns this attribute. More...

Public Member Functions
virtual OwnershipPolicy	getOwnershipPolicy () const
	Who owns this attribute.
virtual AstAttribute *	constructor () const
	Virtual default constructor.
virtual AstAttribute *	copy () const
	Virtual copy constructor.
virtual AstAttribute *	copy ()
virtual std::string	attribute_class_name () const
	Attribute class name.
virtual std::string	toString ()
	Convert an attribute to a string.
virtual bool	commentOutNodeInGraph ()
	Eliminate IR nodes in DOT graphs.
virtual int	packed_size ()
	Packing support.
virtual char *	packed_data ()
	Packing support.
virtual void	unpacked_data (int size, char *data)
	Packing support.
virtual std::string	additionalNodeOptions ()
	DOT support.
virtual std::vector< AttributeEdgeInfo >	additionalEdgeInfo ()
	DOT support.
virtual std::vector< AttributeNodeInfo >	additionalNodeInfo ()
	DOT support.

Member Enumeration Documentation

OwnershipPolicy

enum AstAttribute::OwnershipPolicy

Who owns this attribute.

See getOwnershipPolicy.

Enumerator
CONTAINER_OWNERSHIP	Container owns attribute. New subclasses should use this!
NO_OWNERSHIP	Attributes are always leaked.
CUSTOM_OWNERSHIP	Subclass defines ownership policy.
UNKNOWN_OWNERSHIP	Default for old subclasses.

Definition at line 41 of file AstAttributeMechanism.h.

Constructor & Destructor Documentation

AstAttribute()

AstAttribute::AstAttribute ( )

inline

Definition at line 134 of file AstAttributeMechanism.h.

~AstAttribute()

virtual AstAttribute::~AstAttribute ( )

inlinevirtual

Definition at line 135 of file AstAttributeMechanism.h.

Member Function Documentation

getOwnershipPolicy()

virtual OwnershipPolicy AstAttribute::getOwnershipPolicy ( ) const

virtual

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

Reimplemented in OmpSupport::OmpAttributeList.

constructor()

virtual AstAttribute * AstAttribute::constructor ( ) const

inlinevirtual

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].

Definition at line 146 of file AstAttributeMechanism.h.

copy() [1/2]

virtual AstAttribute * AstAttribute::copy ( ) const

inlinevirtual

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]

Reimplemented in ssa_private::VarUniqueName, MetricAttribute, AstValueAttribute< T >, AstValueAttribute< int >, AstValueAttribute< SgNode * >, AstValueAttribute< std::vector< SgNode * > >, AstRegExAttribute, AstSgNodeAttribute, AstSgNodeListAttribute, AstIntAttribute, and AstParameterizedTypeAttribute.

Definition at line 162 of file AstAttributeMechanism.h.

copy() [2/2]

virtual AstAttribute * AstAttribute::copy ( )

inlinevirtual

Definition at line 170 of file AstAttributeMechanism.h.

attribute_class_name()

virtual std::string AstAttribute::attribute_class_name ( ) const

inlinevirtual

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]

Reimplemented in OmpSupport::OmpAttributeList, MetricAttribute, AstValueAttribute< T >, AstValueAttribute< int >, AstValueAttribute< SgNode * >, AstValueAttribute< std::vector< SgNode * > >, AstRegExAttribute, AstSgNodeAttribute, AstSgNodeListAttribute, AstIntAttribute, and AstParameterizedTypeAttribute.

Definition at line 182 of file AstAttributeMechanism.h.

toString()

virtual std::string AstAttribute::toString ( )

virtual

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.

Reimplemented in AstTextAttribute, and MetricAttribute.

packed_size()

virtual int AstAttribute::packed_size ( )

virtual

Packing support.

Reimplemented in MetricAttribute.

packed_data()

virtual char * AstAttribute::packed_data ( )

virtual

Packing support.

Reimplemented in MetricAttribute.

unpacked_data()

virtual void AstAttribute::unpacked_data ( int  size, char *  data  )

virtual

Packing support.

Reimplemented in MetricAttribute.

commentOutNodeInGraph()

virtual bool AstAttribute::commentOutNodeInGraph ( )

virtual

Eliminate IR nodes in DOT graphs.

Or to tailor the presentation of information about ASTs.

---

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

• AstAttributeMechanism.h