Using the New Attributes Classes 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.) 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. This should be straight forward. If there is missing functionality on the Attribute class, which you feel should be there, please let me know about it. 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). 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)" c'tor. These are for backwards compatibility and may be removed in a future release (i.e. 4.0). And that's basically it! A lot of functionality is hidden behind these classes, but the interfaces are pretty straight forward. Please let me know if you have any questions about how to use these classes, or if there is any functionality you feel is missing. -bw
Very nice! Could we get this write-up added to the sphinx docs? On Sat, Feb 9, 2013 at 11:41 AM, Bill Wendling <wendling at apple.com> wrote:> Using the New Attributes Classes > > 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.) > > 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. This should be straight forward. If there > is > missing functionality on the Attribute class, which you feel should be > there, > please let me know about it. > > 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). > > 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)" c'tor. These are for backwards > compatibility and may be removed in a future release (i.e. 4.0). > > And that's basically it! A lot of functionality is hidden behind these > classes, > but the interfaces are pretty straight forward. Please let me know if you > have > any questions about how to use these classes, or if there is any > functionality > you feel is missing. > > -bw > > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >-- Thanks, Justin Holewinski -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130209/8dc06e4a/attachment.html>
On Feb 9, 2013 8:45 AM, "Bill Wendling" <wendling at apple.com> wrote:> > Using the New Attributes ClassesThanks for writing this up, Bill. Makes a fair bit of sense & should be useful. I have a few questions/comments but I'm not suggesting anything should be changed (even if my ideas were solid, which I've no reason to believe they are, I'm not really a stakeholder in this part of LLVM)> Attributes in LLVM have changed in some fundamental ways. It wasnecessary to do> this to support expanding the attributes to encompass more than a handfulof> attributes --- e.g. command line options. The old way of handlingattributes> consisted of representing them as a bit mask of values. This bit mask wasstored> in a "list" structure that was reference counted. The advantage of thiswas that> attributes could be manipulated with 'or's and 'and's. The disadvantageof this> was that there was limited room for expansion, and virtually no supportfor> attribute-value pairs other than alignment. > > In the new scheme, an Attribute object represents a single attributethat'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-dependentattribute,> 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-dependentattribute to> have a string for the value.) > > An Attribute object is designed to be passed around by value. > > Because attributes are no longer represented as a bit mask, you will needto> convert any code which does treat them as a bit mask to use the new query > methods on the Attribute class. This should be straight forward. If thereis> missing functionality on the Attribute class, which you feel should bethere,> please let me know about it. > > The next class is the AttributeSet class. This replaces the oldAttributeList> class. The AttributeSet stores a collection of Attribute objects for eachkind> 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'sattributes> are at index "AttributeSet::FunctionIndex"; the return type's attributesare at> index "AttributeSet::ReturnIndex"; and the function's parameters'attributes are> at indices 1, ..., n (where 'n' is the number of parameters). Mostmethods on> the AttributeSet class take an index parameter.This seems like a slightly curious factoring: AttributeSet is actually a list of sets of attributes, yes? Why does the list end up encapsulated within this abstraction rather than something more like vector<AttributeSet>? (Or even attaching the respective AttributeSets to the various pieces (parameters/return type etc) - though I expect that might not work as well/easily)> An AttributeSet is also a uniqued and immutable object. You create an > AttributeSet through the "AttributeSet::get" methods. You can add andremove> 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 breakencapsulation,> and may be removed in a future release (i.e. 4.0). > > Lastly, we have a 'builder' class to help create the AttributeSet objectwithout> 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. Itshould> be passed by reference. > > 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). > > And that's basically it! A lot of functionality is hidden behind theseclasses,> but the interfaces are pretty straight forward. Please let me know if youhave> any questions about how to use these classes, or if there is anyfunctionality> you feel is missing. > > -bw > > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130209/ce6fdd7c/attachment.html>
The attached patch creates a skeleton to expand Attributes documentation in the future. It is currently only linked to the index. Ok to commit? Joe -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130209/e0c7bd7e/attachment.html> -------------- next part -------------- A non-text attachment was scrubbed... Name: AttributesDoc.patch Type: application/octet-stream Size: 4356 bytes Desc: AttributesDoc.patch URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130209/e0c7bd7e/attachment.obj> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130209/e0c7bd7e/attachment.htm>