From 777ad8b20452d94111f9c834d0f277575a564ca3 Mon Sep 17 00:00:00 2001 From: Daniel Micay Date: Fri, 29 Mar 2013 14:16:52 -0400 Subject: [PATCH 1/4] tutorial: use "owned box" consistently --- doc/tutorial.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 9f36786648a..ad422aa8ea2 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -1035,10 +1035,10 @@ let z = x; // no new memory allocated, x can no longer be used # Borrowed pointers Rust's borrowed pointers are a general purpose reference type. In contrast with -owned pointers, where the holder of an owned pointer is the owner of the -pointed-to memory, borrowed pointers never imply ownership. A pointer can be -borrowed to any object, and the compiler verifies that it cannot outlive the -lifetime of the object. +owned boxes, where the holder of an owned box is the owner of the pointed-to +memory, borrowed pointers never imply ownership. A pointer can be borrowed to +any object, and the compiler verifies that it cannot outlive the lifetime of +the object. As an example, consider a simple struct type, `Point`: From 85ed840e234184b7975d9ee7b022c0ca2cb5d8ff Mon Sep 17 00:00:00 2001 From: Daniel Micay Date: Fri, 29 Mar 2013 14:51:52 -0400 Subject: [PATCH 2/4] tutorial: improve the owned boxes section --- doc/tutorial.md | 45 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 40 insertions(+), 5 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index ad422aa8ea2..009c1054737 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -1002,11 +1002,46 @@ refer to that through a pointer. ## Owned boxes -An owned box (`~`) is a uniquely owned allocation on the heap. An owned box -inherits the mutability and lifetime of the owner as it would if there was no -box. The purpose of an owned box is to add a layer of indirection in order to -create recursive data structures or cheaply pass around an object larger than a -pointer. +An owned box (`~`) is a uniquely owned allocation on the heap. It inherits the +mutability and lifetime of the owner as it would if there was no box. + +~~~~ +let x = 5; // immutable +let mut y = 5; // mutable +y += 2; + +let x = ~5; // immutable +let mut y = ~5; // mutable +*y += 2; // the * operator is needed to access the contained value +~~~~ + +The purpose of an owned box is to add a layer of indirection in order to create +recursive data structures or cheaply pass around an object larger than a +pointer. Since an owned box has a unique owner, it can be used to represent any +tree data structure. + +The following struct won't compile, because the lack of indirection would mean +it has an infinite size: + +~~~~ {.xfail-test} +struct Foo { + child: Option +} +~~~~ + +> ***Note:*** The `Option` type is an enum that represents an *optional* value. +> It's comparable to a nullable pointer in many other languages, but stores the +> contained value unboxed. + +Adding indirection with an owned pointer allocates the child outside of the +struct on the heap, which makes it a finite size and won't result in a +compile-time error: + +~~~~ +struct Foo { + child: Option<~Foo> +} +~~~~ ## Managed boxes From f78af18127e2bc0075479e8495bfa63807e938fc Mon Sep 17 00:00:00 2001 From: Daniel Micay Date: Fri, 29 Mar 2013 15:07:36 -0400 Subject: [PATCH 3/4] tutorial: improve the managed boxes section --- doc/tutorial.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/tutorial.md b/doc/tutorial.md index 009c1054737..fbeda4257f5 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -1053,6 +1053,20 @@ mutability. They do own the contained object, and mutability is defined by the type of the shared box (`@` or `@mut`). An object containing a managed box is not `Owned`, and can't be sent between tasks. +~~~~ +let a = @5; // immutable + +let mut b = @5; // mutable variable, immutable box +b = @10; + +let c = @mut 5; // immutable variable, mutable box +*c = 10; + +let mut d = @mut 5; // mutable variable, mutable box +*d += 5; +d = @mut 15; +~~~~ + # Move semantics Rust uses a shallow copy for parameter passing, assignment and returning values From 0189ef360092dbebfef5bdfd7a2ebe0c0ccc0f3c Mon Sep 17 00:00:00 2001 From: Daniel Micay Date: Fri, 29 Mar 2013 15:34:14 -0400 Subject: [PATCH 4/4] tutorial: add an example of freezing a managed box --- doc/tutorial.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index fbeda4257f5..7518e3ef676 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -1173,10 +1173,7 @@ For a more in-depth explanation of borrowed pointers, read the ## Freezing Borrowing an immutable pointer to an object freezes it and prevents mutation. -`Owned` objects have freezing enforced statically at compile-time. Mutable -managed boxes handle freezing dynamically when any of their contents are -borrowed, and the task will fail if an attempt to modify them is made while -they are frozen. +`Owned` objects have freezing enforced statically at compile-time. ~~~~ let mut x = 5; @@ -1186,6 +1183,20 @@ let mut x = 5; // x is now unfrozen again ~~~~ +Mutable managed boxes handle freezing dynamically when any of their contents +are borrowed, and the task will fail if an attempt to modify them is made while +they are frozen: + +~~~~ +let x = @mut 5; +let y = x; +{ + let y = &*y; // the managed box is now frozen + // modifying it through x or y will cause a task failure +} +// the box is now unfrozen again +~~~~ + # Dereferencing pointers Rust uses the unary star operator (`*`) to access the contents of a