Skip to content

Document repr packed(N). #553

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 6, 2019
Merged

Document repr packed(N). #553

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f5c2b0b
Document repr packed(N).
ehuss Mar 24, 2019
915ef66
Apply suggestions from Centril
Centril Mar 25, 2019
a5852dd
Try a different way to document align/packed.
ehuss Mar 25, 2019
597d727
Apply suggestions from Centril
Centril Mar 26, 2019
38b408a
Attempt to remove duplication between `align` and `packed`.
ehuss Mar 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 57 additions & 22 deletions src/type-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,13 +113,12 @@ All user-defined composite types (`struct`s, `enum`s, and `union`s) have a
*representation* that specifies what the layout is for the type.

The possible representations for a type are the default representation, `C`,
the primitive representations, `packed`, and `transparent`. Multiple
representations can be applied to a single type.
the primitive representations, and `transparent`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Itemize ^

Also make it clear what the "primitive representations" entail (by itemizing all the primitive reprs)


The representation of a type can be changed by applying the `repr` attribute
to it. The following example shows a struct with a `C` representation.

```
```rust
#[repr(C)]
struct ThreeInts {
first: i16,
Expand All @@ -128,14 +127,36 @@ struct ThreeInts {
}
```

The alignment may be raised or lowered with the `align` and `packed` modifiers
respectively. They alter the representation specified in the attribute:

```rust
// Default representation, alignment lowered to 2.
#[repr(packed(2))]
struct PackedStruct {
first: i16,
second: i8,
third: i32
}

// C representation, alignment raised to 8
#[repr(C, align(8))]
struct AlignedStruct {
first: i16,
second: i8,
third: i32
}
```

> Note: As a consequence of the representation being an attribute on the item,
> the representation does not depend on generic parameters. Any two types with
> the same name have the same representation. For example, `Foo<Bar>` and
> `Foo<Baz>` both have the same representation.

The representation of a type does not change the layout of its fields. For
example, a struct with a `C` representation that contains a struct `Inner` with
the default representation will not change the layout of Inner.
The representation of a type can change the padding between fields, but does
not change the layout of the fields themselves. For example, a struct with a
`C` representation that contains a struct `Inner` with the default
representation will not change the layout of Inner.

### The Default Representation

Expand All @@ -148,7 +169,7 @@ There are no guarantees of data layout made by this representation.

The `C` representation is designed for dual purposes. One purpose is for
creating types that are interoperable with the C Language. The second purpose is
to create types that you can soundly performing operations that rely on data
to create types that you can soundly perform operations on that rely on data
layout such as reinterpreting values as a different type.

Because of this dual purpose, it is possible to create types that are not useful
Expand Down Expand Up @@ -205,7 +226,7 @@ The union will have a size of the maximum size of all of its fields rounded to
its alignment, and an alignment of the maximum alignment of all of its fields.
These maximums may come from different fields.

```
```rust
#[repr(C)]
union Union {
f1: u16,
Expand Down Expand Up @@ -274,28 +295,42 @@ For all other enumerations, the layout is unspecified.

Likewise, combining two primitive representations together is unspecified.

### The `align` Representation
### The `align` modifier

The `align` representation can be used on `struct`s and `union`s to raise the
The `align` modifier 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 alignment is specified as an integer parameter in the form of
`#[repr(align(x))]`. The alignment value must be a power of two from 1 up to
2<sup>29</sup>.

The `align` modifier raises the type's alignment to the specified alignment.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a partial repetition of what you said in the leading paragraph.

If the specified alignment is less than the alignment of the type without the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this concept of "without the ** modifier" is referred to as the "natural **", for example "natural alignment". I think it would be good to introduce such terms earlier (when we first start to speak about alignment) and then use them.

`align` modifier, then the alignment is unaffected.

The `align` and `packed` representations cannot be applied on the same type and
a `packed` type cannot transitively contain another `align`ed type.
The `align` and `packed` modifiers cannot be applied on the same type and a
`packed` type cannot transitively contain another `align`ed type. `align` may
only be applied to the default and `C` representations.

### The `packed` Representation
### The `packed` modifier

The `packed` modifier can be used on `struct`s and `union`s to lower the
alignment of the type to a given value.

The `packed` representation can only be used on `struct`s and `union`s.
The packing value is specified as an integer parameter in the form of
`#[repr(packed(x))]`. If no value is given, as in `#[repr(packed)]`, then the
packing value is 1. The packing value must be a power of two from 1 up to
2<sup>29</sup>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you extract out the wording about the default it is the same as the paragraph for align. So extract these two out into a common notion repr_value or something and then reference that one.


It modifies the representation (either the default or `C`) by removing any
padding bytes and forcing the alignment of the type to `1`.
The `packed` modifier lowers the type's alignment to the specified packing. If
the specified packing is greater to the alignment of the type without the
`packed` modifier, then the alignment and layout is unaffected. The alignments
of each field, for the purpose of positioning fields, is the smaller of the
specified packing and the alignment of the field's 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 `align` and `packed` modifiers cannot be applied on the same type and a
`packed` type cannot transitively contain another `align`ed type. `packed` may
only be applied to the default and `C` representations.

<div class="warning">

Expand Down