diff --git a/docs/HowToUseAttributes.rst b/docs/HowToUseAttributes.rst index 48725c7399d..66c44c01f63 100644 --- a/docs/HowToUseAttributes.rst +++ b/docs/HowToUseAttributes.rst @@ -1,80 +1,81 @@ -============================================== +===================== How To Use Attributes -============================================== +===================== .. contents:: - :local: + :local: Introduction ============ -Attributes in LLVM have changed in some fundamental ways. It was necessary to do -this to support expanding the attributes to encompass more than a handful of -attributes --- e.g. command line options. The old way of handling attributes -consisted of representing them as a bit mask of values. This bit mask was stored -in a "list" structure that was reference counted. The advantage of this was that -attributes could be manipulated with 'or's and 'and's. The disadvantage of this -was that there was limited room for expansion, and virtually no support for -attribute-value pairs other than alignment. +Attributes in LLVM have changed in some fundamental ways. It was necessary to +do this to support expanding the attributes to encompass more than a handful of +attributes --- e.g. command line options. The old way of handling attributes +consisted of representing them as a bit mask of values. This bit mask was +stored in a "list" structure that was reference counted. The advantage of this +was that attributes could be manipulated with 'or's and 'and's. The +disadvantage of this was that there was limited room for expansion, and +virtually no support for attribute-value pairs other than alignment. -In the new scheme, an Attribute object represents a single attribute that's -uniqued. You use the "Attribute::get" methods to create a new Attribute -object. An attribute can be a single "enum" value (the enum being the -Attribute::AttrKind enum), a string representing a target-dependent attribute, -or an attribute-value pair. Some examples: +In the new scheme, an ``Attribute`` object represents a single attribute that's +uniqued. You use the ``Attribute::get`` methods to create a new ``Attribute`` +object. An attribute can be a single "enum" value (the enum being the +``Attribute::AttrKind`` enum), a string representing a target-dependent +attribute, or an attribute-value pair. Some examples: -* Target-independent:   noinline, zext -* Target-dependent:     "no-sse", "thumb2" -* Attribute-value pair: "cpu" = "cortex-a8", align = 4 +* Target-independent: ``noinline``, ``zext`` +* Target-dependent: ``"no-sse"``, ``"thumb2"`` +* Attribute-value pair: ``"cpu" = "cortex-a8"``, ``align = 4`` Note: for an attribute value pair, we expect a target-dependent attribute to have a string for the value. -Attribute -========= -An Attribute object is designed to be passed around by value. +``Attribute`` +============= +An ``Attribute`` object is designed to be passed around by value. Because attributes are no longer represented as a bit mask, you will need to convert any code which does treat them as a bit mask to use the new query methods on the Attribute class. -AttributeSet -============ - -The next class is the AttributeSet class. This replaces the old AttributeList -class. The AttributeSet stores a collection of Attribute objects for each kind -of object that may have an attribute associated with it: the function as a -whole, the return type, or the function's parameters. A function's attributes -are at index "AttributeSet::FunctionIndex"; the return type's attributes are at -index "AttributeSet::ReturnIndex"; and the function's parameters' attributes are -at indices 1, ..., n (where 'n' is the number of parameters). Most methods on -the AttributeSet class take an index parameter. - -An AttributeSet is also a uniqued and immutable object. You create an -AttributeSet through the "AttributeSet::get" methods. You can add and remove -attributes, which result in the creation of a new AttributeSet. - -An AttributeSet object is designed to be passed around by value. - -Note: It is advised that you do *not* use the AttributeSet "Introspection" -methods (e.g. 'Raw', 'getRawPointer', etc.). These methods break encapsulation, -and may be removed in a future release (i.e. 4.0). - -AttrBuilder +``AttributeSet`` ================ -Lastly, we have a 'builder' class to help create the AttributeSet object without -having to create several different intermediate uniqued AttributeSet -objects. The AttrBuilder class allows you to add and remove attributes at -will. The attributes won't be uniqued until you call the appropriate -"AttributeSet::get" method. +The ``AttributeSet`` class replaces the old ``AttributeList`` class. The +``AttributeSet`` stores a collection of Attribute objects for each kind of +object that may have an attribute associated with it: the function as a +whole, the return type, or the function's parameters. A function's attributes +are at index ``AttributeSet::FunctionIndex``; the return type's attributes are +at index ``AttributeSet::ReturnIndex``; and the function's parameters' +attributes are at indices 1, ..., n (where 'n' is the number of parameters). +Most methods on the ``AttributeSet`` class take an index parameter. -An AttrBuilder object is *not* designed to be passed around by value. It should -be passed by reference. +An ``AttributeSet`` is also a uniqued and immutable object. You create an +``AttributeSet`` through the ``AttributeSet::get`` methods. You can add and +remove attributes, which result in the creation of a new ``AttributeSet``. -Note: It is advised that you do *not* use the "AttrBuilder::addRawValue()" -method or the "AttrBuilder(uint64_t Val)" c'tor. These are for backwards -compatibility and may be removed in a future release (i.e. 4.0). +An ``AttributeSet`` object is designed to be passed around by value. + +Note: It is advised that you do *not* use the ``AttributeSet`` "introspection" +methods (e.g. ``Raw``, ``getRawPointer``, etc.). These methods break +encapsulation, and may be removed in a future release (i.e. LLVM 4.0). + +``AttrBuilder`` +=============== + +Lastly, we have a "builder" class to help create the ``AttributeSet`` object +without having to create several different intermediate uniqued +``AttributeSet`` objects. The ``AttrBuilder`` class allows you to add and +remove attributes at will. The attributes won't be uniqued until you call the +appropriate ``AttributeSet::get`` method. + +An ``AttrBuilder`` object is *not* designed to be passed around by value. It +should be passed by reference. + +Note: It is advised that you do *not* use the ``AttrBuilder::addRawValue()`` +method or the ``AttrBuilder(uint64_t Val)`` constructor. These are for +backwards compatibility and may be removed in a future release (i.e. LLVM 4.0). And that's basically it! A lot of functionality is hidden behind these classes, but the interfaces are pretty straight forward. +