|
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 | | -//! panic may optionally be detected from a different thread. If |
32 | | -//! the main thread panics the application will exit with a non-zero |
| 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 |
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), described below. |
| 38 | +//! child thread (i.e., join). |
39 | 39 | //! |
40 | 40 | //! ## The `Thread` type |
41 | 41 | //! |
42 | | -//! Already-running threads are represented via the `Thread` type, which you can |
| 42 | +//! 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` constructor; |
| 45 | +//! * By spawning a new thread, e.g. using the `thread::spawn` function. |
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 | | -//! println!("Hello, World!"); |
63 | | -//! // some computation here |
| 62 | +//! // some work here |
64 | 63 | //! }); |
65 | 64 | //! ``` |
66 | 65 | //! |
67 | 66 | //! In this example, the spawned thread is "detached" from the current |
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.) |
| 67 | +//! thread. This means that it can outlive its parent (the thread that spawned |
| 68 | +//! it), unless this parent is the main thread. |
71 | 69 | //! |
72 | 70 | //! ## Scoped threads |
73 | 71 | //! |
74 | 72 | //! Often a parent thread uses a child thread to perform some particular task, |
75 | 73 | //! and at some point must wait for the child to complete before continuing. |
76 | | -//! For this scenario, use the `scoped` constructor: |
| 74 | +//! For this scenario, use the `thread::scoped` function: |
77 | 75 | //! |
78 | 76 | //! ```rust |
79 | 77 | //! use std::thread; |
80 | 78 | //! |
81 | 79 | //! let guard = thread::scoped(move || { |
82 | | -//! println!("Hello, World!"); |
83 | | -//! // some computation here |
| 80 | +//! // some work here |
84 | 81 | //! }); |
| 82 | +//! |
85 | 83 | //! // do some other work in the meantime |
86 | 84 | //! let output = guard.join(); |
87 | 85 | //! ``` |
|
92 | 90 | //! terminates) when it is dropped. You can join the child thread in |
93 | 91 | //! advance by calling the `join` method on the guard, which will also |
94 | 92 | //! return the result produced by the thread. A handle to the thread |
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.) |
| 93 | +//! itself is available via the `thread` method of the join guard. |
100 | 94 | //! |
101 | 95 | //! ## Configuring threads |
102 | 96 | //! |
|
108 | 102 | //! use std::thread; |
109 | 103 | //! |
110 | 104 | //! thread::Builder::new().name("child1".to_string()).spawn(move || { |
111 | | -//! println!("Hello, world!") |
| 105 | +//! println!("Hello, world!"); |
112 | 106 | //! }); |
113 | 107 | //! ``` |
114 | 108 | //! |
|
121 | 115 | //! initially not present: |
122 | 116 | //! |
123 | 117 | //! * The `thread::park()` function blocks the current thread unless or until |
124 | | -//! the token is available for its thread handle, at which point It atomically |
| 118 | +//! the token is available for its thread handle, at which point it atomically |
125 | 119 | //! consumes the token. It may also return *spuriously*, without consuming the |
126 | 120 | //! token. `thread::park_timeout()` does the same, but allows specifying a |
127 | 121 | //! maximum time to block the thread for. |
|
143 | 137 | //! * It avoids the need to allocate mutexes and condvars when building new |
144 | 138 | //! synchronization primitives; the threads already provide basic blocking/signaling. |
145 | 139 | //! |
146 | | -//! * It can be implemented highly efficiently on many platforms. |
| 140 | +//! * It can be implemented very efficiently on many platforms. |
147 | 141 |
|
148 | 142 | #![stable(feature = "rust1", since = "1.0.0")] |
149 | 143 |
|
|
0 commit comments