Documentation: HowToUseAttributes: formatting (use monospaced font)
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@174982 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
Dmitri Gribenko
parent
c5ef7eee3c
commit
1cb058f77c
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue