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 do
  12 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 stored
  15 in a "list" structure that was reference counted. The advantage of this was that
  16 attributes could be manipulated with 'or's and 'and's. The disadvantage of this
  17 was that there was limited room for expansion, and virtually no support for
  18 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 attribute,
  24 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 AttributeSet
  42 ============
  43
  44 The next class is the AttributeSet class. This replaces the old AttributeList
  45 class. The AttributeSet stores a collection of Attribute objects for each kind
  46 of object that may have an attribute associated with it: the function as a
  47 whole, the return type, or the function's parameters. A function's attributes
  48 are at index "AttributeSet::FunctionIndex"; the return type's attributes are at
  49 index "AttributeSet::ReturnIndex"; and the function's parameters' attributes are
  50 at indices 1, ..., n (where 'n' is the number of parameters). Most methods on
  51 the AttributeSet class take an index parameter.
  52
  53 An AttributeSet is also a uniqued and immutable object. You create an
  54 AttributeSet through the "AttributeSet::get" methods. You can add and remove
  55 attributes, which result in the creation of a new AttributeSet.
  56
  57 An AttributeSet object is designed to be passed around by value.
  58
  59 Note: It is advised that you do *not* use the AttributeSet "Introspection"
  60 methods (e.g. 'Raw', 'getRawPointer', etc.). These methods break encapsulation,
  61 and may be removed in a future release (i.e. 4.0).
  62
  63 AttrBuilder
  64 ================
  65
  66 Lastly, we have a 'builder' class to help create the AttributeSet object without
  67 having to create several different intermediate uniqued AttributeSet
  68 objects. The AttrBuilder class allows you to add and remove attributes at
  69 will. The attributes won't be uniqued until you call the appropriate
  70 "AttributeSet::get" method.
  71
  72 An AttrBuilder object is *not* designed to be passed around by value. It should
  73 be passed by reference.
  74
  75 Note: It is advised that you do *not* use the "AttrBuilder::addRawValue()"
  76 method or the "AttrBuilder(uint64_t Val)" c'tor. These are for backwards
  77 compatibility and may be removed in a future release (i.e. 4.0).
  78
  79 And that's basically it! A lot of functionality is hidden behind these classes,
  80 but the interfaces are pretty straight forward.