Guide Redux: Pointers #15789

steveklabnik · 2014-07-18T18:18:52Z

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.

dreoliv · 2014-07-18T18:32:06Z

src/doc/guide-pointers.md

+                                  ^
+```
+
+We can **dereference** the pointer by using the `*` operator. This will work:


dereference sounds scary 😨

What if you introduce the concept first, like: We have to make rust follow the pointer and fetch the value at that memory address. We can do it by using the * operator. This is called dereferencing, btw.

This is of course just a suggestion. Great work btw, I'm eagerly following each released chapter of the guides 😄

I think the word "dereference" is fine. It means the same thing in Rust that it does in every other language with pointers/references. And I like the bolding of the word, it highlights the fact that this is a potentially unfamiliar but important term that's being introduced for the first time.

I do agree though that this might use some elaboration in case the reader is not in fact familiar with pointers/references already.

We can dereference the pointer by using the * operator. Dereferencing a pointer means accessing the value at the location stored in the pointer. This will work:

Yeah, probably how the concept is explained might be a matter of personal taste. I think your suggestion would also do it just fine. I'm glad I'm not the only one who thinks the word dereference calls for more clarification. 😄

Agreed. Updated.

cburgdorf · 2014-07-18T18:47:53Z

👍 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

jonah-williams · 2014-07-18T18:50:30Z

src/doc/guide-pointers.md

-fn main() {
-    let origin =    &Point { x: 0.0, y: 0.0 };
-    let p1     = box Point { x: 5.0, y: 3.0 };
+Use references when you want to use a pointer, but do not want to take ownership.


Here "best practices" discusses ownership as an important concept but I don't think it's ever mentioned above in the current version. Is it safe to assume a reader will have seen that in a previous guide before reaching this point? Should this at least reference an in depth discussion of what ownership means and why it matters in Rust?

Good call. Eventually, the 'lifetimes' guide will be the 'ownership' guide, so maybe a link here is warranted.

dreoliv · 2014-07-18T20:34:56Z

👍 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.

killercup · 2014-07-18T20:35:56Z

src/doc/guide-pointers.md

+--------  -----
+0xd3e010  5
+0xd3e030  8
+```


Would it make sense to add a "name" column?

Can you use markdown tables? (I'm not sure which markdown extensions are supported by rustdoc or whatever is rendering this in the end. I'm assuming the Github-flavored version here.) This would probably look better then "code". And you just need to add some pipe symbols.

location | value -------- | ----- 0xd3e010 | 5 0xd3e030 | 8

location value

0xd3e010 5

0xd3e030 8

Yeah, since Markdown has no tables, I have no idea.

Well, you could always use HTML… but especially tables are really ugly.

@huonw do you know if rustdoc has any kind of table support?

ghost · 2014-07-19T11:59:53Z

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 · 2014-07-19T14:36:58Z

@bachm, I really like this idea.

steveklabnik · 2014-07-19T15:16:30Z

I added the cheat sheet, and modified it a bit

steveklabnik · 2014-07-19T18:07:09Z

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 · 2014-07-19T18:09:38Z

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

badboy · 2014-07-19T19:03:17Z

src/doc/guide-pointers.md

+
+This part is coming soon.
+
+# Cheat Sheet<a id="cheat-sheet" href="#cheat-sheet">


This link should probably be closed, right?

Doesn't need to be.

Ok, I don't know how the Rust docu is compiled. Just my local markdown parser couldn't handle this.

Ahh weird. A non-closed <a> is perfectly legal.

FWIW, you don't need an explicit link here, rustdoc automatically inserts ids in this format (and makes the headings links to themselves). E.g. http://doc.rust-lang.org/master/guide.html#ownership-and-lifetimes

bluss · 2014-07-21T14:31:13Z

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 · 2014-07-21T14:41:05Z

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

bluss · 2014-07-21T16:59:59Z

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 · 2014-07-21T23:35:49Z

Okay, addressed everything else so far.

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.

Store binding mode for each instance of a binding independently fix rust-lang#15787

dreoliv reviewed Jul 18, 2014
View reviewed changes

jonah-williams reviewed Jul 18, 2014
View reviewed changes

killercup reviewed Jul 18, 2014
View reviewed changes

badboy reviewed Jul 19, 2014
View reviewed changes

Guide Redux: Pointers

377b250

bors closed this Jul 26, 2014

steveklabnik deleted the guide_pointers branch July 30, 2014 13:48

bors added a commit to rust-lang-ci/rust that referenced this pull request Nov 13, 2023

Auto merge of rust-lang#15789 - HKalbasi:unused-var, r=HKalbasi

1087295

Store binding mode for each instance of a binding independently fix rust-lang#15787

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Guide Redux: Pointers #15789

Guide Redux: Pointers #15789

steveklabnik commented Jul 18, 2014

dreoliv Jul 18, 2014

lilyball Jul 18, 2014

dreoliv Jul 18, 2014

steveklabnik Jul 19, 2014

cburgdorf commented Jul 18, 2014

jonah-williams Jul 18, 2014

steveklabnik Jul 18, 2014

dreoliv commented Jul 18, 2014

killercup Jul 18, 2014

steveklabnik Jul 18, 2014

killercup Jul 18, 2014

steveklabnik Jul 19, 2014

ghost commented Jul 19, 2014

steveklabnik commented Jul 19, 2014

steveklabnik commented Jul 19, 2014

steveklabnik commented Jul 19, 2014

steveklabnik commented Jul 19, 2014

badboy Jul 19, 2014

steveklabnik Jul 19, 2014

badboy Jul 19, 2014

steveklabnik Jul 19, 2014

huonw Jul 20, 2014

bluss commented Jul 21, 2014

steveklabnik commented Jul 21, 2014

bluss commented Jul 21, 2014

steveklabnik commented Jul 21, 2014


		This part is coming soon.

		# Cheat Sheet<a id="cheat-sheet" href="#cheat-sheet">

Guide Redux: Pointers #15789

Guide Redux: Pointers #15789

Conversation

steveklabnik commented Jul 18, 2014

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

cburgdorf commented Jul 18, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dreoliv commented Jul 18, 2014

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

ghost commented Jul 19, 2014

steveklabnik commented Jul 19, 2014

steveklabnik commented Jul 19, 2014

steveklabnik commented Jul 19, 2014

steveklabnik commented Jul 19, 2014

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

bluss commented Jul 21, 2014

steveklabnik commented Jul 21, 2014

bluss commented Jul 21, 2014

steveklabnik commented Jul 21, 2014