Arrays and References tutorial section suggestions

[shelby3]

The tutorial section opens with a statement that is misleading because it seems to imply that literals are special w.r.t. the fact that elements of arrays are apparently always not embedded (somewhat analogous to saying they’re always boxed, although boxing isn’t the precise antithesis of embed):

Constructing an array with a literal creates new references to its elements.

That sets the mind off thinking about what is the significance of mentioning literals and do they cause arrays to use references. And then one has to have enough knowledge of programming to realize what you’re probably doing is that arrays are always “boxed” and never use embed for elements.

Or do arrays sometimes use embed instead of references such as for types that fit within the word size of the target machine?

I would suggest instead that section open by stating that arrays always use references to refer to elements (and not mention literals in that opening sentence).

Before I go further, I would like to voice the opinion the “unboxed” arrays are very important for performance in some situations. Has anyone opened any issue/feature request for them? I tried searching and couldn’t find one.

Also I had to re-read the following sentence numerous times before it clicked:

It is thus necessary to use elements that can have more than one reference of the same type (e.g. types with val or ref capability) or use ephemeral types for other capabilities (as returned from constructors or the consume expression).

The “have more than one reference of the same type” is very evasive and misleading. Makes the mind search a landscape which is too wide.

Instead I suggest, “Since elements are referenced by the array, they will need to be aliased such as when they are read, and thus elements must employ a capabilities type that allows aliases (e.g. types with val or ref capability) or use ephemeral types for other capabilities (as returned from constructors or the consume expression).”

Also note I suggest always writing “capabilities type” instead of “type” when referring to capabilities typing. Please help prevent the reader’s mind from considering a wider sea of possible meaning than necessary.

P.S. I am not complaining about the tutorial in general. It seems for the most part to be well written. It is difficult to find some topics. Even after reading many parts of the tutorial only today did I discover that arrays are always “boxed” buried in a TOC section for literals. The tutorial attempts to be chatty and tell a story from start to finish and this contributes to these issues I am raising. I have found a few other instances in the tutorial where I immediately caught a statement that was misleading because incomplete (such as, “Since behaviours are asynchronous, it's ok to run the body of a bunch of behaviours at the same time. ” which seems to imply that more than one behavior can execute simultaneously for the same “actor”¹), but then down the page the tutorial corrects itself because it was employing this style. I am more accustomed to the reference style where every statement is correct and more self-contained. But I am not criticizing the style employed. I am just offering suggestions for the issues that seemed to cause the most confusion for me.

¹ _{Pony doesn’t have the Actor model. It requires causal message ordering which the Actor model does not have. Which is another error in the documentation. Also where Pony says behaviors execute at an indeterminate time, that is true but it is only because they’re ordered at runtime in a message queue, not because of the indeterminacy of an unreliable communication channel which the Actor model was designed for.}