docs/HowToUseAttributes.rst

   1 =====================
   2 How To Use Attributes
   3 =====================
   4
   5 .. contents::
   6   :local:
   7
   8 Introduction
   9 ============
  10
  11 Attributes in LLVM have changed in some fundamental ways.  It was necessary to
  12 do this to support expanding the attributes to encompass more than a handful of
  13 attributes --- e.g. command line options.  The old way of handling attributes
  14 consisted of representing them as a bit mask of values.  This bit mask was
  15 stored in a "list" structure that was reference counted.  The advantage of this
  16 was that attributes could be manipulated with 'or's and 'and's.  The
  17 disadvantage of this was that there was limited room for expansion, and
  18 virtually no support for attribute-value pairs other than alignment.
  19
  20 In the new scheme, an ``Attribute`` object represents a single attribute that's
  21 uniqued.  You use the ``Attribute::get`` methods to create a new ``Attribute``
  22 object.  An attribute can be a single "enum" value (the enum being the
  23 ``Attribute::AttrKind`` enum), a string representing a target-dependent
  24 attribute, or an attribute-value pair.  Some examples:
  25
  26 * Target-independent: ``noinline``, ``zext``
  27 * Target-dependent: ``"no-sse"``, ``"thumb2"``
  28 * Attribute-value pair: ``"cpu" = "cortex-a8"``, ``align = 4``
  29
  30 Note: for an attribute value pair, we expect a target-dependent attribute to
  31 have a string for the value.
  32
  33 ``Attribute``
  34 =============
  35 An ``Attribute`` object is designed to be passed around by value.
  36
  37 Because attributes are no longer represented as a bit mask, you will need to
  38 convert any code which does treat them as a bit mask to use the new query
  39 methods on the Attribute class.
  40
  41 ``AttributeList``
  42 =================
  43
  44 The ``AttributeList`` stores a collection of Attribute objects for each kind of
  45 object that may have an attribute associated with it: the function as a whole,
  46 the return type, or the function's parameters.  A function's attributes are at
  47 index ``AttributeList::FunctionIndex``; the return type's attributes are at
  48 index ``AttributeList::ReturnIndex``; and the function's parameters' attributes
  49 are at indices 1, ..., n (where 'n' is the number of parameters).  Most methods
  50 on the ``AttributeList`` class take an index parameter.
  51
  52 An ``AttributeList`` is also a uniqued and immutable object.  You create an
  53 ``AttributeList`` through the ``AttributeList::get`` methods.  You can add and
  54 remove attributes, which result in the creation of a new ``AttributeList``.
  55
  56 An ``AttributeList`` object is designed to be passed around by value.
  57
  58 Note: It is advised that you do *not* use the ``AttributeList`` "introspection"
  59 methods (e.g. ``Raw``, ``getRawPointer``, etc.).  These methods break
  60 encapsulation, and may be removed in a future release (i.e. LLVM 4.0).
  61
  62 ``AttrBuilder``
  63 ===============
  64
  65 Lastly, we have a "builder" class to help create the ``AttributeList`` object
  66 without having to create several different intermediate uniqued
  67 ``AttributeList`` objects.  The ``AttrBuilder`` class allows you to add and
  68 remove attributes at will.  The attributes won't be uniqued until you call the
  69 appropriate ``AttributeList::get`` method.
  70
  71 An ``AttrBuilder`` object is *not* designed to be passed around by value.  It
  72 should be passed by reference.
  73
  74 Note: It is advised that you do *not* use the ``AttrBuilder::addRawValue()``
  75 method or the ``AttrBuilder(uint64_t Val)`` constructor.  These are for
  76 backwards compatibility and may be removed in a future release (i.e. LLVM 4.0).
  77
  78 And that's basically it! A lot of functionality is hidden behind these classes,
  79 but the interfaces are pretty straight forward.
  80