Guide Redux: Pointers

[steveklabnik]

This is super, super WIP, but I'm going to go get lunch for a while, and figured I'd toss my work up here in case anyone wants to see my work as I do it.

This contains a new introductory section explaining the basics of pointers, and some pitfalls that Rust attempts to solve. I'd be interested in hearing how my explanation is, as well as if this belongs here. Pointers are such a crucial concept, I don't mind having a beginners' section on them in the main docs, even though our main audience is supposed to understand them already. Reasonable people may disagree, however.

[cburgdorf]

👍 This is brilliant! I'm excited to read the rest of the pointer guide. I agree with Pascal that it would be nice to link to a explanation of Stack vs Heap there. It's probably out of the scope to describe such concepts here but how about just linking to this: http://stackoverflow.com/questions/79923/what-and-where-are-the-stack-and-heap

[cburgdorf]

👍 This is brilliant! I'm excited to read the rest of the pointer guide. I agree with Pascal that it would be nice to link to a explanation of Stack vs Heap there. It's probably out of the scope to describe such concepts here but how about just linking to this: http://stackoverflow.com/questions/79923/what-and-where-are-the-stack-and-heap

[kballard]

How about "this is pseudocode", and then actually changing the syntax of the pseudocode to be more obviously non-Rust? e.g. something like

function foo(x) {
    x = 5
}

function main() {
    i := 1
    foo(i)
    // what is the value of i here?
}

[cburgdorf]

I would probably not introduce things like := here and rather keep the "pseudocode" as simple as possible.

[kballard]

I picked := because otherwise the reader may say "where did i come from?" I know that was actually my first question, "did i come from somewhere else or is this creating it?".

[steveklabnik]

I was actually wondering if I shouldn't just make the 'psuedocode' C. What do you think of that?

[cburgdorf]

Can you post in a comment how that would look like?

[steveklabnik]

void foo(int x) {
    x = 5;
}

int main(void) {
    int i = 1;
    foo(i);
    // what is the value of i here?
}

The issue with this is that C is not pass-by-reference, but we're about to pretend that it is for the sake of discussion...

[bjeanes]

Javascript maybe? I'm actually not positive that Javascript doesn't pass by value for ints, but maybe using a more complex type like an array and pushing something to it will be clear enough and still simple enough

function foo(a) {
    a.push(1)
}

function main() {
    var a = [];
    foo(a)
    // what is the value of a here?
}

[steveklabnik]

Ahh, I like that.

[cburgdorf]

I like the pseudocode example with the simple int more. I would just go with the C syntax. We don't have to tell anyone "hey, this is C syntax" so if we say "This is pseudocode. Let's pretend this is pass by reference" that should be just fine.

[kballard]

As above, this pseudocode might be written

function foo(&int x) {
    *x = 5
}

function main() {
    i := 1
    foo(&i)
    // what is the value of i here?
}

[kballard]

All subsequent pseudocode blocks should also then be rewritten for the same syntax, but I won't call out each one individually.

[abernardes]

👍 on the link with explanations about heaps and stacks. The tutorial lost me when it mentioned heaps and stacks. Wikipedia wasn't very helpful. Thank you for that link @cburgdorf.

[abernardes]

👍 on the link with explanations about heaps and stacks. The tutorial lost me when it mentioned heaps and stacks. Wikipedia wasn't very helpful. Thank you for that link @cburgdorf.

[bachm]

It would generally be useful to have a cheat sheet showing pointer types and their typical usage with cell types. Something like:

Name	Representation	Purpose
Reference	&T	Allows one or more entities to read T.
Mutable reference	&mut T	Allows a single entity to read from and write to T.
Reference and Cell	&Cell<T>	Allows one or more entities to read from and write to T, provided T implements the Copy trait.
Owned pointer (Unique pointer?)	Box<T>	Allocates T on the heap, with unique ownership, allowing read and write access to T.
Rc pointer	Rc<T>	Allocates T on the heap, with shared ownership, allowing read access to T.
Rc pointer and RefCell	Rc<RefCell<T>>	Same as above, plus one-at-a-time write access to T.
Arc pointer	Arc<T>	Allocates T on the heap, with shared ownership across thread boundaries, allowing read access to T.
Arc pointer and Mutex	Arc<Mutex<T>>	Same as above, plus one-at-a-time write access to T.
Raw pointer	*const T	Unrestrained and potentially unsafe read access to T.
Raw mutable pointer	*mut T	Same as above, plus unrestrained and potentially unsafe write access to T.

The above is pretty basic. The purpose descriptions in particular need some work. The guide also needs to decide what names to use. Should we refer to Arc<T> as Arc pointer or atomically reference counted pointer?

By the way, I'm not sure I like the term owned pointer, because "owned" refers to the pointer itself, whereas the the key concept is the pointer owning the data it points to. At least that's how I interpret the name.

[bachm]

It would generally be useful to have a cheat sheet showing pointer types and their typical usage with cell types. Something like:

Name	Representation	Purpose
Reference	&T	Allows one or more entities to read T.
Mutable reference	&mut T	Allows a single entity to read from and write to T.
Reference and Cell	&Cell<T>	Allows one or more entities to read from and write to T, provided T implements the Copy trait.
Owned pointer (Unique pointer?)	Box<T>	Allocates T on the heap, with unique ownership, allowing read and write access to T.
Rc pointer	Rc<T>	Allocates T on the heap, with shared ownership, allowing read access to T.
Rc pointer and RefCell	Rc<RefCell<T>>	Same as above, plus one-at-a-time write access to T.
Arc pointer	Arc<T>	Allocates T on the heap, with shared ownership across thread boundaries, allowing read access to T.
Arc pointer and Mutex	Arc<Mutex<T>>	Same as above, plus one-at-a-time write access to T.
Raw pointer	*const T	Unrestrained and potentially unsafe read access to T.
Raw mutable pointer	*mut T	Same as above, plus unrestrained and potentially unsafe write access to T.

The above is pretty basic. The purpose descriptions in particular need some work. The guide also needs to decide what names to use. Should we refer to Arc<T> as Arc pointer or atomically reference counted pointer?

By the way, I'm not sure I like the term owned pointer, because "owned" refers to the pointer itself, whereas the the key concept is the pointer owning the data it points to. At least that's how I interpret the name.

[steveklabnik]

@bachm, I really like this idea.

[steveklabnik]

@bachm, I really like this idea.

[steveklabnik]

I added the cheat sheet, and modified it a bit

[steveklabnik]

I added the cheat sheet, and modified it a bit

[steveklabnik]

Okay. This now has significant upgrades, and is at least as far along as the current pointer guide. I'd like to stop work here, get this reviewed, and then merge it. The other sections can come later.

[steveklabnik]

Okay. This now has significant upgrades, and is at least as far along as the current pointer guide. I'd like to stop work here, get this reviewed, and then merge it. The other sections can come later.

[steveklabnik]

Oh, with the exception of the psudocode issue. That needs sorted before a merge.

[steveklabnik]

Oh, with the exception of the psudocode issue. That needs sorted before a merge.

[huonw]

This section is easy: "Avoid unless you are interacting with syntax::ast." :P

[steveklabnik]

😄 😅

[huonw]

(erm, this was meant to go on Gc... haha, failed joke.)

[bluss]

I would say that Cell and RefCell are containers, not pointers. (They are not indirections, just encapsulations). Of course they are rather special containers, so they should be treated on their own.

Maybe it is wise to separate basic pointer types and smart pointer types in two categories / headings for the table, just to not have readers freak out about the amount of pointers.

[bluss]

I would say that Cell and RefCell are containers, not pointers. (They are not indirections, just encapsulations). Of course they are rather special containers, so they should be treated on their own.

Maybe it is wise to separate basic pointer types and smart pointer types in two categories / headings for the table, just to not have readers freak out about the amount of pointers.

[steveklabnik]

The line gets very blurry. I consider anything that implements Deref and DerefMut to be a 'smart pointer.'

[steveklabnik]

The line gets very blurry. I consider anything that implements Deref and DerefMut to be a 'smart pointer.'

[bluss]

Absolutely, but Cell and RefCell don't implement Deref/Mut at all. Smart pointers are Rc, Arc, Gc, etc.

RefCell has associated handles that are smart pointers -- Ref and RefMut. But so has Mutex<T>, it has MutexGuard which is a smart pointer and a RAII guard at the same time.

[bluss]

Absolutely, but Cell and RefCell don't implement Deref/Mut at all. Smart pointers are Rc, Arc, Gc, etc.

RefCell has associated handles that are smart pointers -- Ref and RefMut. But so has Mutex<T>, it has MutexGuard which is a smart pointer and a RAII guard at the same time.

[steveklabnik]

Okay, addressed everything else so far.

[steveklabnik]

Okay, addressed everything else so far.

[cmr]

r+

[cmr]

r+

[bors]

saw approval from cmr
at steveklabnik@377b250

[bors]

saw approval from cmr
at steveklabnik@377b250

[bors]

merging steveklabnik/rust/guide_pointers = 377b250 into auto

[bors]

steveklabnik/rust/guide_pointers = 377b250 merged ok, testing candidate = cf1381c

[bors]

all tests pass:
success: http://buildbot.rust-lang.org/builders/auto-mac-32-opt/builds/522
success: http://buildbot.rust-lang.org/builders/auto-mac-64-opt/builds/522
success: http://buildbot.rust-lang.org/builders/auto-mac-64-nopt-c/builds/521
success: http://buildbot.rust-lang.org/builders/auto-mac-64-nopt-t/builds/522
success: http://buildbot.rust-lang.org/builders/auto-linux-32-opt/builds/522
success: http://buildbot.rust-lang.org/builders/auto-linux-32-nopt-c/builds/523
success: http://buildbot.rust-lang.org/builders/auto-linux-32-nopt-t/builds/522
success: http://buildbot.rust-lang.org/builders/auto-linux-64-opt/builds/528
success: http://buildbot.rust-lang.org/builders/auto-linux-64-nopt-c/builds/523
success: http://buildbot.rust-lang.org/builders/auto-linux-64-nopt-t/builds/522
success: http://buildbot.rust-lang.org/builders/auto-linux-64-x-android-t/builds/525
success: http://buildbot.rust-lang.org/builders/auto-win-32-opt/builds/523
success: http://buildbot.rust-lang.org/builders/auto-win-32-nopt-t/builds/523
success: http://buildbot.rust-lang.org/builders/auto-win-32-nopt-c/builds/524

[bors]

fast-forwarding master to auto = cf1381c