Ownership guide

[steveklabnik]

This is a work in progress, but this should get extensive review, so I'm putting it up early and often.

This is the start of a draft of the new 'ownership guide,' which explains ownership, borrowing, etc. I'm feeling better about this framing than last time's, but we'll see.

[emberian]

@steveklabnik to what extent do you want this reviewed right now?

[emberian]

Rendered view

[huonw]

Is it worth putting something like "(experience has shown that the compiler is often right)" here, or is that too twerpish?

[steveklabnik]

I was really tempted to write it, but had the same wonder.

Sent from my iPhone

On Nov 4, 2014, at 13:56, Huon Wilson notifications@github.com wrote:

In src/doc/guide-ownership.md:

+# Meta
+
+Before we get to the details, two important notes about the ownership system.
+
+Rust has a focus on safety and speed. It accomplishes these goals through "zero
+cost abstractions," which means that in Rust, abstractions cost as little as
+possible in order to make them work. The ownership system is a prime example of
+a zero-cost abstraction. All of the analysis we'll talk about in this guide is
+done at compile time. You do not pay any run-time cost for all of these
+features.
+
+However, this system does have a certain cost: learning curve. Many new users
+to Rust experience something we like to call "fighting with the borrow
+checker," where the Rust compiler refuses to compile a program that the author
+thinks is valid. You probably will experience similar things at first. There is
Is it worth putting something like "(experience has shown that the compiler is often right)" here, or is that too twerpish?

�
Reply to this email directly or view it on GitHub.

[pcn]

I'd say 👎

[DanielKeep]

Another way you could phrase it (that being the sentiment of "the compiler is often right") that's less dismissive of the reader: "this often happens because the programmer's mental model of how ownership should work doesn't match the actual rules that Rust implements." This could then lead into talking about how, as you gain experience with Rust, you start to internalise the rules.

[steveklabnik]

I like it. incoming!

[steveklabnik]

@steveklabnik to what extent do you want this reviewed right now?

Well this is the first draft of the first fourth or so, so anything that comes to mind, really. Structure, depth, fact-checking, whatever :)=

[huonw]

In the vein of concreteness, is it worth clarifying that it is a pointer? (e.g. "what we are given back is a handle to that memory (a pointer). This ...")

I guess some people might be confused calling it a handle without acknowledging the conventional term (i.e. be asking "is this handle somehow different to a pointer?? Is my life a lie?" etc. etc.)

[steveklabnik]

yeah, maybe. I can totally see this. hmm.

[MatejLach]

@simias I feel like the word "ideal" is supposed to mean that the code shown above can be written in a better, more robust way, despite the fact that it "works" as is.
I am not convinced that "interesting", "practical" nor "useful" are better words for such an example, but @steveklabnik may disagree.

[simias]

On Wed, Nov 05, 2014 at 07:33:37AM -0800, Matej Ľach wrote:

@simias I feel like the word "ideal" is supposed to mean that the code shown above can be written in a better, more robust way, despite the fact that it "works" as is.
I am not convinced that "interesting", "practical" nor "useful" are better words for such an example, but @steveklabnik may disagree.

Aaaah, I misunderstood what was meant here. I thought the remark was
because the code was effectively useless, not because the design was
bad. Nevermind then.

Lionel Flandrin

[steveklabnik]

Yes, that is exactly correct.

[jpetkau]

You introduce 'resources' here but don't define them. Maybe something like:

"At its core, ownership is about 'resources', which are anything that must be acquired before using, and released or closed when no longer needed."

[huonw]

I think this section may be clearer as:

The box keyword creates a Box (specifically Box<int> in this case) by allocating a small segment of memory on the heap with enough space to fit an int. But where does the code say the box is deallocated?

Or, the last sentence could be But when is the box deallocated?.

(This is continuing @mdinger's point, but is a new thread so it's not lost in other old discussion.)

[mdinger]

+1

This is clearer.

[steveklabnik]

Ahhh, so this ties into the 'lifetime' vs 'scope' thing, I think. I prefer "where does it say" to subtly reinfore that this isn't a time-based thing, it's a static thing. But yeah, I sitll like the wording.

[steveklabnik]

@thomasahle yes, it should be an &, thank you.