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 1 commit
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
28 changes: 19 additions & 9 deletions src/type-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ representations can be applied to a single type.
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 Down Expand Up @@ -148,7 +148,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 +205,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 @@ -280,19 +280,29 @@ 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.
alignment value must be a power of two up to 2<sup>29</sup>. 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.
The `packed` representation can be used on `struct`s and `union`s to lower the
alignment and padding of the type.

The packing value is specified as a 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 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` representation sets the alignment to the smaller of the specified
packing and the current alignment (either default or `C`). The alignments of
Copy link
Contributor

Choose a reason for hiding this comment

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

Here the "default" alignment is referenced but above "primitive alignment" is used... we should pick one phrasing.

Copy link
Contributor

Choose a reason for hiding this comment

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

Get rid of both "current' and "primitive". Get rid of the parenthetical. Instead spell it out explicitly that if the type has the default or C representation, and the alignment from that representation is smaller, it will use that alignment.

Copy link
Contributor

Choose a reason for hiding this comment

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

"or C" is not super clear wrt. referring to C-the-language

each field for the purpose of positioning fields would also be the smaller of
the specified packing and the alignment of the type of that field. If the
specified packing is greater than or equal to the default alignment of the
type, then the alignment and layout 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.
Expand Down