From c3ef8057b6a05d324eef05e8ddd38fb22ee3712f Mon Sep 17 00:00:00 2001 From: Cameron Hart Date: Tue, 26 Dec 2017 13:05:36 +1100 Subject: [PATCH] Documented the `#[repr(align(x))]` attribute. --- src/attributes.md | 27 ++++++--------------------- src/type-layout.md | 18 +++++++++++++++++- 2 files changed, 23 insertions(+), 22 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 1ff115f4a..b4bc84293 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -13,6 +13,7 @@ > _MetaItem_ : >       IDENTIFIER >    | IDENTIFIER `=` LITERAL +>    | IDENTIFIER `(` LITERAL `)` >    | IDENTIFIER `(` _MetaSeq_ `)` >    | IDENTIFIER `(` _MetaSeq_ `,` `)` > @@ -30,6 +31,8 @@ may appear as any of: * A single identifier, the attribute name * An identifier followed by the equals sign '=' and a literal, providing a key/value pair +* An identifier followed by a parenthesized literal, providing a + key/value pair * An identifier followed by a parenthesized list of sub-attribute arguments Attributes with a bang ("!") after the hash ("#") apply to the item that the @@ -130,26 +133,8 @@ interpreted: - `linkage` - on a static, this specifies the [linkage type](http://llvm.org/docs/LangRef.html#linkage-types). -On `enum`s: - -- `repr` - on C-like enums, this sets the underlying type used for - representation. Takes one argument, which is the primitive - type this enum should be represented for, or `C`, which specifies that it - should be the default `enum` size of the C ABI for that platform. Note that - enum representation in C is undefined, and this may be incorrect when the C - code is compiled with certain flags. - -On `struct`s: - -- `repr` - specifies the representation to use for this struct. Takes a list - of options. The currently accepted ones are `C` and `packed`, which may be - combined. `C` will use a C ABI compatible struct layout, and `packed` will - remove any padding between fields (note that this is very fragile and may - break platforms which require aligned access). - -On `union`s: - -- `repr` - Same as per `struct`. +See [type layout](type-layout.html) for documentation on the `repr` attribute +which can be used to control type layout. ## Macro-related attributes @@ -416,4 +401,4 @@ You can implement `derive` for your own type through [procedural macros]. [Doc comments]: comments.html#doc-comments [The Rustdoc Book]: ../rustdoc/the-doc-attribute.html -[procedural macros]: procedural-macros.html \ No newline at end of file +[procedural macros]: procedural-macros.html diff --git a/src/type-layout.md b/src/type-layout.md index e1e0c81fe..48349d55f 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -264,6 +264,19 @@ For all other enumerations, the layout is unspecified. Likewise, combining two primitive representations together is unspecified. +### The `align` Representation + +The `align` representation can be used on `struct`s and `union`s to raise the +alignment of the type to a given value. + +Alignment is specified as a parameter in the form of `#[repr(align(x))]`. The +alignment value must be a power of two of type `u32`. The `align` representation +can raise the alignment of a type to be greater than it's primitive alignment, +it cannot lower the alignment of a type. + +The `align` and `packed` representations cannot be applied on the same type and +a `packed` type cannot transitively contain another `align`ed type. + ### The `packed` Representation The `packed` representation can only be used on `struct`s and `union`s. @@ -271,6 +284,9 @@ The `packed` representation can only be used on `struct`s and `union`s. It modifies the representation (either the default or `C`) by removing any padding bytes and forcing the alignment of the type to `1`. +The `align` and `packed` representations cannot be applied on the same type and +a `packed` type cannot transitively contain another `align`ed type. + > Warning: Dereferencing an unaligned pointer is [undefined behaviour] and it is > possible to [safely create unaligned pointers to `packed` fields][27060]. > Like all ways to create undefined behavior in safe Rust, this is a bug. @@ -284,4 +300,4 @@ padding bytes and forcing the alignment of the type to `1`. [C-like enumerations]: items/enumerations.html#custom-discriminant-values-for-field-less-enumerations [zero-variant enumerations]: items/enumerations.html#zero-variant-enums [undefined behavior]: behavior-considered-undefined.html -[27060]: https://github.com/rust-lang/rust/issues/27060 \ No newline at end of file +[27060]: https://github.com/rust-lang/rust/issues/27060