|
28 | 28 | //! a thread will unwind the stack, running destructors and freeing |
29 | 29 | //! owned resources. Thread panic is unrecoverable from within |
30 | 30 | //! the panicking thread (i.e. there is no 'try/catch' in Rust), but |
31 | | -//! the panic may optionally be detected from a different thread. If |
32 | | -//! the main thread panics, the application will exit with a non-zero |
| 31 | +//! panic may optionally be detected from a different thread. If |
| 32 | +//! the main thread panics the application will exit with a non-zero |
33 | 33 | //! exit code. |
34 | 34 | //! |
35 | 35 | //! When the main thread of a Rust program terminates, the entire program shuts |
36 | 36 | //! down, even if other threads are still running. However, this module provides |
37 | 37 | //! convenient facilities for automatically waiting for the termination of a |
38 | | -//! child thread (i.e., join). |
| 38 | +//! child thread (i.e., join), described below. |
39 | 39 | //! |
40 | 40 | //! ## The `Thread` type |
41 | 41 | //! |
42 | | -//! Threads are represented via the `Thread` type, which you can |
| 42 | +//! Already-running threads are represented via the `Thread` type, which you can |
43 | 43 | //! get in one of two ways: |
44 | 44 | //! |
45 | | -//! * By spawning a new thread, e.g. using the `thread::spawn` function. |
| 45 | +//! * By spawning a new thread, e.g. using the `thread::spawn` constructor; |
46 | 46 | //! * By requesting the current thread, using the `thread::current` function. |
47 | 47 | //! |
48 | 48 | //! Threads can be named, and provide some built-in support for low-level |
49 | | -//! synchronization (described below). |
| 49 | +//! synchronization described below. |
50 | 50 | //! |
51 | 51 | //! The `thread::current()` function is available even for threads not spawned |
52 | 52 | //! by the APIs of this module. |
|
59 | 59 | //! use std::thread; |
60 | 60 | //! |
61 | 61 | //! thread::spawn(move || { |
62 | | -//! // some work here |
| 62 | +//! println!("Hello, World!"); |
| 63 | +//! // some computation here |
63 | 64 | //! }); |
64 | 65 | //! ``` |
65 | 66 | //! |
66 | 67 | //! In this example, the spawned thread is "detached" from the current |
67 | | -//! thread. This means that it can outlive its parent (the thread that spawned |
68 | | -//! it), unless this parent is the main thread. |
| 68 | +//! thread, meaning that it can outlive the thread that spawned |
| 69 | +//! it. (Note, however, that when the main thread terminates all |
| 70 | +//! detached threads are terminated as well.) |
69 | 71 | //! |
70 | 72 | //! ## Scoped threads |
71 | 73 | //! |
72 | 74 | //! Often a parent thread uses a child thread to perform some particular task, |
73 | 75 | //! and at some point must wait for the child to complete before continuing. |
74 | | -//! For this scenario, use the `thread::scoped` function: |
| 76 | +//! For this scenario, use the `scoped` constructor: |
75 | 77 | //! |
76 | 78 | //! ```rust |
77 | 79 | //! use std::thread; |
78 | 80 | //! |
79 | 81 | //! let guard = thread::scoped(move || { |
80 | | -//! // some work here |
| 82 | +//! println!("Hello, World!"); |
| 83 | +//! // some computation here |
81 | 84 | //! }); |
82 | | -//! |
83 | 85 | //! // do some other work in the meantime |
84 | 86 | //! let output = guard.join(); |
85 | 87 | //! ``` |
|
90 | 92 | //! terminates) when it is dropped. You can join the child thread in |
91 | 93 | //! advance by calling the `join` method on the guard, which will also |
92 | 94 | //! return the result produced by the thread. A handle to the thread |
93 | | -//! itself is available via the `thread` method of the join guard. |
| 95 | +//! itself is available via the `thread` method on the join guard. |
| 96 | +//! |
| 97 | +//! (Note: eventually, the `scoped` constructor will allow the parent and child |
| 98 | +//! threads to data that lives on the parent thread's stack, but some language |
| 99 | +//! changes are needed before this is possible.) |
94 | 100 | //! |
95 | 101 | //! ## Configuring threads |
96 | 102 | //! |
|
102 | 108 | //! use std::thread; |
103 | 109 | //! |
104 | 110 | //! thread::Builder::new().name("child1".to_string()).spawn(move || { |
105 | | -//! println!("Hello, world!"); |
| 111 | +//! println!("Hello, world!") |
106 | 112 | //! }); |
107 | 113 | //! ``` |
108 | 114 | //! |
|
115 | 121 | //! initially not present: |
116 | 122 | //! |
117 | 123 | //! * The `thread::park()` function blocks the current thread unless or until |
118 | | -//! the token is available for its thread handle, at which point it atomically |
| 124 | +//! the token is available for its thread handle, at which point It atomically |
119 | 125 | //! consumes the token. It may also return *spuriously*, without consuming the |
120 | 126 | //! token. `thread::park_timeout()` does the same, but allows specifying a |
121 | 127 | //! maximum time to block the thread for. |
|
137 | 143 | //! * It avoids the need to allocate mutexes and condvars when building new |
138 | 144 | //! synchronization primitives; the threads already provide basic blocking/signaling. |
139 | 145 | //! |
140 | | -//! * It can be implemented very efficiently on many platforms. |
| 146 | +//! * It can be implemented highly efficiently on many platforms. |
141 | 147 |
|
142 | 148 | #![stable(feature = "rust1", since = "1.0.0")] |
143 | 149 |
|
|
0 commit comments