doc: Boxes diagram shows enum value inside box.

[divtxt]

I found the boxes diagram in the tutorial misleading about how the enum worked.

The current diagram makes it seem that there is a separate Cons struct when there is only one type of struct for the List type, and Nil is drawn almost as if it's not consuming memory.

I'm aware of the optimization that happens for this enum which takes advantage of the fact that pointer cannot be null but this is an implementation detail and not the only one that applies here. I can add a note below the diagram mentioning this if you like.

[emberian]

It is not merely an implementation detail. It's likely to be formalized in the language semantics, because it's such a useful guarantee to have, esp in FFI.

cc @pcwalton @jld @nikomatsakis

[divtxt]

We're mostly on the same page - people on IRC explained to me that the enum discriminant is formally optimized away in this case. I'm just arguing that since this is the tutorial talking about boxes, this diagram should stick to the logical model of the enum that readers will have at this point. BTW, size_of<List> is padded to 16 bytes (at least on 64-bit). I expect this will be mentioned in FFI as well, but we're not showing a padded box in this context.

• Would this change be acceptable if I added a note about optimization/layout right below the diagram?

• I would at least like to fix the diagram so that it does not look like a traditional linked list diagram. Unless I've misunderstood, the following linked list will allocate two List boxes:

  let list = Cons(1, ~Nil);
  // list -> 16 bytes containing Cons(1,~) -> 16 bytes containing Nil
  

  vs a C/C++/Java linked list would allocate only one List element and having an actual null pointer in the first element.

[emberian]

Yeah, with the note I think it'd be fine.

On Thu, Jan 16, 2014 at 12:37 AM, Div Shekhar [email protected]:

We're mostly on the same page - people on IRC explained to me that the
enum discriminant is formally optimized away in this case. I'm just arguing
that since this is the tutorial talking about boxes, this diagram should
stick to the logical model of the enum that readers will have at this
point. BTW, size_of is padded to 16 bytes (at least on 64-bit). I
expect this will be mentioned in FFI as well, but we're not showing a
padded box in this context.

Would this change be acceptable if I added a note about
optimization/layout right below the diagram?

I would at least like to fix the diagram so that it does not look like
a traditional linked list diagram. Unless I've misunderstood, the following
linked list will allocate two List boxes:

let list = Cons(1, Nil);
// list -> 16 bytes containing Cons(1,) -> 16 bytes containing Nil

vs a C/C++/Java linked list would allocate only one List element and
having an actual null pointer in the first element.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/11567#issuecomment-32443670
.