@@ -94,6 +94,54 @@ fn main() {
9494}
9595```
9696
97+ As closures can capture variables from their environment, we can also try to
98+ bring some data into the other thread:
99+
100+ ``` rust,ignore
101+ use std::thread;
102+
103+ fn main() {
104+ let x = 1;
105+ thread::spawn(|| {
106+ println!("x is {}", x);
107+ });
108+ }
109+ ```
110+
111+ However, this gives us an error:
112+
113+ ``` text
114+ 5:19: 7:6 error: closure may outlive the current function, but it
115+ borrows `x`, which is owned by the current function
116+ ...
117+ 5:19: 7:6 help: to force the closure to take ownership of `x` (and any other referenced variables),
118+ use the `move` keyword, as shown:
119+ thread::spawn(move || {
120+ println!("x is {}", x);
121+ });
122+ ```
123+
124+ This is because by default closures capture variables by reference, and thus the
125+ closure only captures a _ reference to ` x ` _ . This is a problem, because the
126+ thread may outlive the scope of ` x ` , leading to a dangling pointer.
127+
128+ To fix this, we use a ` move ` closure as mentioned in the error message. ` move `
129+ closures are explained in depth [ here] ( closures.html#move-closures ) ; basically
130+ they move variables from their environment into themselves. This means that ` x `
131+ is now owned by the closure, and cannot be used in ` main() ` after the call to
132+ ` spawn() ` .
133+
134+ ``` rust
135+ use std :: thread;
136+
137+ fn main () {
138+ let x = 1 ;
139+ thread :: spawn (move || {
140+ println! (" x is {}" x );
141+ });
142+ }
143+ ```
144+
97145Many languages have the ability to execute threads, but it's wildly unsafe.
98146There are entire books about how to prevent errors that occur from shared
99147mutable state. Rust helps out with its type system here as well, by preventing
@@ -145,23 +193,64 @@ This gives us an error:
145193```
146194
147195Rust knows this wouldn't be safe! If we had a reference to ` data ` in each
148- thread, and the thread takes ownership of the reference, we'd have three
149- owners!
196+ thread, and the thread takes ownership of the reference, we'd have three owners!
197+ ` data ` gets moved out of ` main ` in the first call to ` spawn() ` , so subsequent
198+ calls in the loop cannot use this variable.
199+
200+ So, we need some type that lets us have more than one owning reference to a
201+ value. Usually, we'd use ` Rc<T> ` for this, which is a reference counted type
202+ that provides shared ownership. It has some runtime bookkeeping that keeps track
203+ of the number of references to it, hence the "reference count" part of its name.
204+
205+ Calling ` clone() ` on an ` Rc<T> ` will return a new owned reference and bump the
206+ internal reference count. We create one of these for each thread:
150207
151- So, we need some type that lets us have more than one reference to a value and
152- that we can share between threads, that is it must implement ` Sync ` .
153208
154- We'll use ` Arc<T> ` , Rust's standard atomic reference count type, which
155- wraps a value up with some extra runtime bookkeeping which allows us to
156- share the ownership of the value between multiple references at the same time.
209+ ``` ignore
210+ use std::thread;
211+ use std::time::Duration;
212+ use std::rc::Rc;
157213
158- The bookkeeping consists of a count of how many of these references exist to
159- the value, hence the reference count part of the name.
214+ fn main() {
215+ let mut data = Rc::new(vec![1, 2, 3]);
216+
217+ for i in 0..3 {
218+ // create a new owned reference
219+ let data_ref = data.clone();
220+
221+ // use it in a thread
222+ thread::spawn(move || {
223+ data_ref[i] += 1;
224+ });
225+ }
226+
227+ thread::sleep(Duration::from_millis(50));
228+ }
229+ ```
230+
231+ This won't work, however, and will give us the error:
232+
233+ ``` text
234+ 13:9: 13:22 error: the trait `core::marker::Send` is not
235+ implemented for the type `alloc::rc::Rc<collections::vec::Vec<i32>>`
236+ ...
237+ 13:9: 13:22 note: `alloc::rc::Rc<collections::vec::Vec<i32>>`
238+ cannot be sent between threads safely
239+ ```
240+
241+ As the error message mentions, ` Rc ` cannot be sent between threads safely. This
242+ is because the internal reference count is not maintained in a thread safe
243+ matter and can have a data race.
244+
245+ To solve this, we'll use ` Arc<T> ` , Rust's standard atomic reference count type.
160246
161247The Atomic part means ` Arc<T> ` can safely be accessed from multiple threads.
162248To do this the compiler guarantees that mutations of the internal count use
163249indivisible operations which can't have data races.
164250
251+ In essence, ` Arc<T> ` is a type that lets us share ownership of data _ across
252+ threads_ .
253+
165254
166255``` ignore
167256use std::thread;
@@ -182,7 +271,7 @@ fn main() {
182271}
183272```
184273
185- We now call ` clone() ` on our ` Arc<T> ` , which increases the internal count .
274+ Similarly to las time, we use ` clone() ` to create a new owned handle .
186275This handle is then moved into the new thread.
187276
188277And... still gives us an error.
@@ -193,14 +282,21 @@ And... still gives us an error.
193282 ^~~~
194283```
195284
196- ` Arc<T> ` assumes one more property about its contents to ensure that it is safe
197- to share across threads: it assumes its contents are ` Sync ` . This is true for
198- our value if it's immutable, but we want to be able to mutate it, so we need
199- something else to persuade the borrow checker we know what we're doing.
285+ `Arc<T > by default has immutable contents. It allows the _ sharing _ of data
286+ between threads, but shared mutable data is unsafe and when threads are
287+ involved can cause data races!
288+
200289
201- It looks like we need some type that allows us to safely mutate a shared value,
202- for example a type that can ensure only one thread at a time is able to
203- mutate the value inside it at any one time.
290+ Usually when we wish to make something in an immutable position mutable, we use
291+ ` Cell<T> ` or ` RefCell<T> ` which allow safe mutation via runtime checks or
292+ otherwise (see also: [ Choosing Your Guarantees] ( choosing-your-guarantees.html ) ).
293+ However, similar to ` Rc ` , these are not thread safe. If we try using these, we
294+ will get an error about these types not being ` Sync ` , and the code will fail to
295+ compile.
296+
297+ It looks like we need some type that allows us to safely mutate a shared value
298+ across threads, for example a type that can ensure only one thread at a time is
299+ able to mutate the value inside it at any one time.
204300
205301For that, we can use the ` Mutex<T> ` type!
206302
@@ -229,7 +325,17 @@ fn main() {
229325Note that the value of ` i ` is bound (copied) to the closure and not shared
230326among the threads.
231327
232- Also note that [ ` lock ` ] ( ../std/sync/struct.Mutex.html#method.lock ) method of
328+ We're "locking" the mutex here. A mutex (short for "mutual exclusion"), as
329+ mentioned, only allows one thread at a time to access a value. When we wish to
330+ access the value, we use ` lock() ` on it. This will "lock" the mutex, and no
331+ other thread will be able to lock it (and hence, do anything with the value)
332+ until we're done with it. If a thread attempts to lock a mutex which is already
333+ locked, it will wait until the other thread releases the lock.
334+
335+ The lock "release" here is implicit; when the result of the lock (in this case,
336+ ` data ` ) goes out of scope, the lock is automatically released.
337+
338+ Note that [ ` lock ` ] ( ../std/sync/struct.Mutex.html#method.lock ) method of
233339[ ` Mutex ` ] ( ../std/sync/struct.Mutex.html ) has this signature:
234340
235341``` ignore
0 commit comments