| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081 |
- =====================
- How To Use Attributes
- =====================
- .. contents::
- :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.
- 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``
- 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.
- 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 ``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 ``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. 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.
|
