New Section - Type Layout #156

Havvy · 2017-11-17T05:32:06Z

r? @scottmcm @gankro @eddyb - Though if you don't want to, just say so and unsubscribe from the thread.

There's no good term for what the compiler calls ADTs - structs, enums, and unions. I cannot think of one either. As such, there's a FIXME in there.

I'm also choosing a very conservative definition of type layout. I'm not sure if it should be expanded or not, or if the valid values and calling convention changes should be a part or not. Although I don't think they should, I don't have any logical arguments either way. Part of the problem is that layout can probably mean multiple things at the same time. E.g. Layout for allocators is just size and alignment.

eddyb · 2017-11-17T09:58:52Z

There's no good term for what the compiler calls ADTs - structs, enums, and unions.

Nominal/user-defined data types?

Havvy · 2017-11-17T22:07:38Z

Nominal almost works but doesn't because trait objects are nominal but you can't change the representation on those. User-defined is sort of ambiguous, but could work.

Gankra · 2017-11-17T23:01:50Z

How about "Opt In Built In Types"

scottmcm · 2017-11-17T23:24:57Z

Hmm, maybe "composite types"? All three are composed of other types, either primitive or themselves composites. Which may go well with other text talking about how their layout depends on the layouts (and values) of their constituent types.

eddyb · 2017-11-17T23:27:56Z

"user-defined/nominal aggregates"?

Havvy · 2017-11-18T08:56:06Z

I considered "composite", but tuples are also composite. I could go with user-defined composite types. We can pick a different name later if needed.

More importantly than the name, I want thoughts about the definition of type layout here.

And generally, am I missing details? Should I put in a blockquote explaining how layout currently works for the default representation? Likewise for the NonZero optimization? Are all of the guarantees actually guaranteed?

Havvy · 2017-11-21T06:53:26Z

So, umm, I just found that rust-by-example is calling them "custom types". So, which do y'all like better, "custom types" or "user-defined composite types"?

Quick straw vote - use the "+1" reactji for "custom" and the "heart" reactji for "user-defined composite types".

Gankra

Left a pile of loose pedantic comments. Some of them may be dismissable as "that's not how we do these docs".

Gankra · 2017-11-21T15:51:50Z

src/glossary.md

+### Alignment
+
+The *alignment* of a value specifies what addresses are valid to store the value
+at.


This is weirdly non-descript? You should at least specify what the constraint is (the type must have an address that is a multiple of the alignment). Size must also be a multiple of alignment. Also loads are relevant for type-punning/deserialization reasons. It may also be UB to simply construct a reference that is misaligned (not clear on where that discussion went). This is because e.g. enum opts may use the fact that references are aligned to do niche-filling tricks (generalization of NonZero).

You may also wish to note the existence of read_unaligned and write_unaligned, and repr(packed). (e.g. link to other docs as "relevant")

Worth nothing: minimum alignment is 1.

I think you spent at least 10 times as long writing that comment as I did on that glossary entry. Will make these changes.

Random fact: struct / union (and enum in Rust) have a per-platform aggregate alignment baseline which may be larger than 1 byte.

For some reason, LLVM allows setting ABI alignment not just preferred alignment for this, and some targets use 0, some use 8 bits (i.e. 1 byte) for ABI aggregate alignment, despite the two options being identical (you can't have 0 alignment).

It'd be nice to have some assurance that there's no minimum mandated ABI alignment on any platform and that LLVM is just using this for preferred alignment (which mainly exists for when a platform doesn't need something to be aligned, but may perform better, either at runtime or LLVM can choose faster instructions to work with that data).

🔧 into my 📋

Gankra · 2017-11-21T15:59:48Z

src/glossary.md

+### Size
+
+The *size* of a value is the offset in bytes between successive elements in an
+array with that item type including alignment padding.


This is worded awkwardly. I would cut the reference to "alignment padding", at least in this sentence. It's also just "how much memory must be allocated to store a value of that type". e.g. Box<T> cannot somehow forego the alignment padding, because it's valid to read/write that padding.

Worth Considering: restate that size must be a multiple of alignment.

Worth Considering: note that the size may depend on the compiler version (optimizations) or the target (usize, references, etc)

Worth Considering: note that zero-sized types exist.

Gankra · 2017-11-21T16:02:35Z

src/items/enumerations.md

-zero, and add one for each variant, in order. Each enum value is just its
-discriminant which you can specify explicitly:
+If there is no data attached to *any* of the variants of an enumeration and
+there is at least one variant then it is called a *c-like enumeration*.


Does anyone actually call enums "enumerations"? Like yeah it's technically short for it etymologically, but you don't get to call every Alex "Alexander".

Umm...looks at others for opinions on this. I personally prefer spelling out enumeration, but if we want to officially call them enums, that's cool too.

https://doc.rust-lang.org/book/second-edition/ch06-00-enums.html

In this chapter we’ll look at enumerations, also referred to as enums. Enums allow you to define a type by enumerating its possible values.

we then say "enums" every time after

I'll add the "also referred as enums" into the reference, and likewise use "enums" every time after.

Gankra · 2017-11-21T16:04:00Z

src/items/enumerations.md

    Quux,           // 124
 }
+
+let baz_discriminant = Foo::Baz as u32;
+assert_eq!(baz_discriminant, 123u32);


Redundant suffix?

Probably. I don't like eliding suffixes personally. Is there a style rule against it?

i'm not 100% sure but i def don't add it unless needed

Gankra · 2017-11-21T16:08:31Z

src/items/enumerations.md

-The [`repr` attribute] can be added in order to change the type of the right
-hand side and specify the memory layout.
+Under the [default representation], the specified discriminant is interpreted as
+an `isize` value although the compiler is allowed to use a smaller type in the


TIL! (weird)

Gankra · 2017-11-21T16:56:42Z

src/type-layout.md

+alignment of the field. If the current offset is not a multiple of the field's
+alignment, then add padding bytes increasing the current offset until the
+current offset is a multiple of the field's alignment. The offset for the field
+is what the current offset is now. Then increase the current offset by the size


"The offset for the field is..." seems superfluous. idk. consider rewording.

I don't feel that it's superfluous - just overly explicit.

I was considering turning this into psuedocode. As psuedocode, this line would be field.offset = current_offset.

algorithmic desc sounds really good!

Gankra · 2017-11-21T16:59:22Z

src/type-layout.md

+
+A union declared with `#[repr(C)]` will have the same size and alignment as an
+equivalent C union declaration in the C language for the target platform.
+Usually, a union would have the maximum size of the maximum size of all of its


Can we remove this usually? When isn't it true? This is important for low-level Rust code.

I don't know enough C to answer this.

#[repr(C)] union A { a: u32, b: [u16; 3], }

has size 8.

Oh yes, this is a good point. It should be, "Has an alignment equal to the maximum alignment of its fields. Has a size equal to the maximum size of its fields, rounded up to its alignment."

Gankra · 2017-11-21T16:59:27Z

src/type-layout.md

+equivalent C union declaration in the C language for the target platform.
+Usually, a union would have the maximum size of the maximum size of all of its
+fields, and the maximum alignment of the maximum alignment of all of its fields.
+These maximums may come from different fields.


doubled "maximum size" and "maximum alignment" here?

maximum size of the union vs. maximum size of a field of the union. It looks silly, but it's wrong to remove either "maximum".

I don't understand the notion of a union having a "maximum" size. It just has a size?

Oh, yeah. Right. Will fix.

Also we don't really have a notion of "maximum" alignment anymore? We squashed alignment into one number pre 1.0.

Gankra · 2017-11-21T17:04:26Z

src/type-layout.md

+It is an error for [zero-variant enumerations] to have a primitive
+representation.
+
+For all other enumerations, the layout is unspecified.


Also unspecified: (C, primitive), (primitive1, primitive2)

For now, I'm pretending you cannot do that. The first one will come in once your RFC is merged. The second one should probably be an error.

It's currently only ever been a warning, so I think we should be clear here. Technically not back-compat to make an error.

Gankra · 2017-11-21T17:05:10Z

src/type-layout.md

+It modifies the representation (either the default or `C`) by removing any
+padding bytes and forcing the alignment of the type to `1`.
+
+> Warning: Dereferencing an unaligned pointer is [undefined behaviour] and is


and "it" is

Havvy · 2017-11-22T10:32:36Z

src/type-layout.md

+
+Type | `size_of::\<Type>()`
+- | - | -
+bool | 1


This is explicitly not stable.

Havvy · 2017-11-22T10:47:30Z

I'll address @gankro's comments on Thursday. Thank you so very much for them. 💟

Havvy · 2017-11-27T08:39:01Z

I've procrastinated too much on this, but I now have the changes. They're in their own commit if you want to look at them specifically.

Havvy · 2017-12-02T04:32:05Z

Rebased because grammar changes caused merge conflict.

Havvy · 2017-12-05T21:54:32Z

Rebased once again because C-like enum -> field-less enum rename caused merge conflict.

steveklabnik · 2017-12-08T17:30:58Z

src/glossary.md

+
+It is a multiple of the alignment, including zero. The size can change
+depending on compiler version (as new optimizations are made) and target
+platform (as `usize` varies).


this is very very very minor, but i'd say "similar to how usize varies per-platform", as this wording (to me) makes it sound like it's based off of the size of usize.

steveklabnik · 2017-12-08T17:32:08Z

src/items/enumerations.md

+
+## Zero-variant Enums
+
+Enums with zero variants are known as *zero-variant enumss*. As they have


extra s in enumss

steveklabnik · 2017-12-08T17:36:14Z

src/type-layout.md

+struct.size = current_offset + current_offset % struct.alignment;
+```
+
+> Note: You can have zero-sized structs from this algorithm. This differs from


I would say

Note: This algorithm can produce zero-sized structs.

Havvy · 2017-12-08T18:46:11Z

All three of those changes have been made. They were all good changes.

steveklabnik

🤘

Havvy added the New Content Missing features or aspects of language not currently documented. label Nov 17, 2017

Havvy force-pushed the reprs branch from d32069e to 394a2f4 Compare November 17, 2017 22:11

Havvy force-pushed the reprs branch from 394a2f4 to 4491448 Compare November 17, 2017 23:06

Havvy force-pushed the reprs branch from bee031c to 268b1d9 Compare November 20, 2017 19:20

Havvy changed the title ~~[WIP - Do NOT Merge] New Section - Type Layout~~ New Section - Type Layout Nov 21, 2017

Havvy requested a review from steveklabnik November 21, 2017 06:42

Gankra requested changes Nov 21, 2017

View reviewed changes

Havvy commented Nov 22, 2017

View reviewed changes

src/type-layout.md Outdated

Type | `size_of::\<Type>()`

- | - | -

bool | 1

Copy link

Contributor Author

Havvy Nov 22, 2017

Choose a reason for hiding this comment

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

This is explicitly not stable.

Havvy force-pushed the reprs branch from 41c94b3 to 6032b43 Compare December 2, 2017 04:29

Havvy force-pushed the reprs branch from 6032b43 to fc09e34 Compare December 5, 2017 21:53

steveklabnik reviewed Dec 8, 2017

View reviewed changes

Havvy added 3 commits December 8, 2017 10:37

New Section - Type Layout

f6c95a8

Gankro's suggestions plus more.

35d7db1

Minor typos and wording in type-layout

c19106d

Havvy force-pushed the reprs branch from fc09e34 to c19106d Compare December 8, 2017 18:45

steveklabnik approved these changes Dec 8, 2017

View reviewed changes

steveklabnik merged commit d812ea2 into rust-lang:master Dec 8, 2017

Havvy mentioned this pull request Dec 8, 2017

Document Sized Trait #102

Closed

frewsxcv mentioned this pull request Jan 3, 2018

Document behavior of enum when casted to an integer #10

Closed


		## Zero-variant Enums

		Enums with zero variants are known as zero-variant enumss. As they have

New Section - Type Layout #156

New Section - Type Layout #156

Conversation

Havvy commented Nov 17, 2017

eddyb commented Nov 17, 2017

Havvy commented Nov 17, 2017

Gankra commented Nov 17, 2017

scottmcm commented Nov 17, 2017

eddyb commented Nov 17, 2017

Havvy commented Nov 18, 2017

Havvy commented Nov 21, 2017

Gankra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Havvy commented Nov 22, 2017

Havvy commented Nov 27, 2017

Havvy commented Dec 2, 2017

Havvy commented Dec 5, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Havvy commented Dec 8, 2017

steveklabnik left a comment

Choose a reason for hiding this comment