]> git.proxmox.com Git - rustc.git/blob - src/libstd/thread/mod.rs
Imported Upstream version 1.2.0+dfsg1
[rustc.git] / src / libstd / thread / mod.rs
1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! Native threads
12 //!
13 //! ## The threading model
14 //!
15 //! An executing Rust program consists of a collection of native OS threads,
16 //! each with their own stack and local state.
17 //!
18 //! Communication between threads can be done through
19 //! [channels](../../std/sync/mpsc/index.html), Rust's message-passing
20 //! types, along with [other forms of thread
21 //! synchronization](../../std/sync/index.html) and shared-memory data
22 //! structures. In particular, types that are guaranteed to be
23 //! threadsafe are easily shared between threads using the
24 //! atomically-reference-counted container,
25 //! [`Arc`](../../std/sync/struct.Arc.html).
26 //!
27 //! Fatal logic errors in Rust cause *thread panic*, during which
28 //! a thread will unwind the stack, running destructors and freeing
29 //! owned resources. Thread panic is unrecoverable from within
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
33 //! exit code.
34 //!
35 //! When the main thread of a Rust program terminates, the entire program shuts
36 //! down, even if other threads are still running. However, this module provides
37 //! convenient facilities for automatically waiting for the termination of a
38 //! child thread (i.e., join).
39 //!
40 //! ## The `Thread` type
41 //!
42 //! Threads are represented via the `Thread` type, which you can
43 //! get in one of two ways:
44 //!
45 //! * By spawning a new thread, e.g. using the `thread::spawn` function.
46 //! * By requesting the current thread, using the `thread::current` function.
47 //!
48 //! Threads can be named, and provide some built-in support for low-level
49 //! synchronization (described below).
50 //!
51 //! The `thread::current()` function is available even for threads not spawned
52 //! by the APIs of this module.
53 //!
54 //! ## Spawning a thread
55 //!
56 //! A new thread can be spawned using the `thread::spawn` function:
57 //!
58 //! ```rust
59 //! use std::thread;
60 //!
61 //! thread::spawn(move || {
62 //! // some work here
63 //! });
64 //! ```
65 //!
66 //! 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.
69 //!
70 //! The parent thread can also wait on the completion of the child
71 //! thread; a call to `spawn` produces a `JoinHandle`, which provides
72 //! a `join` method for waiting:
73 //!
74 //! ```rust
75 //! use std::thread;
76 //!
77 //! let child = thread::spawn(move || {
78 //! // some work here
79 //! });
80 //! // some work here
81 //! let res = child.join();
82 //! ```
83 //!
84 //! The `join` method returns a `Result` containing `Ok` of the final
85 //! value produced by the child thread, or `Err` of the value given to
86 //! a call to `panic!` if the child panicked.
87 //!
88 //! ## Scoped threads
89 //!
90 //! The `spawn` method does not allow the child and parent threads to
91 //! share any stack data, since that is not safe in general. However,
92 //! `scoped` makes it possible to share the parent's stack by forcing
93 //! a join before any relevant stack frames are popped:
94 //!
95 //! ```rust
96 //! # #![feature(scoped)]
97 //! use std::thread;
98 //!
99 //! let guard = thread::scoped(move || {
100 //! // some work here
101 //! });
102 //!
103 //! // do some other work in the meantime
104 //! let output = guard.join();
105 //! ```
106 //!
107 //! The `scoped` function doesn't return a `Thread` directly; instead,
108 //! it returns a *join guard*. The join guard is an RAII-style guard
109 //! that will automatically join the child thread (block until it
110 //! terminates) when it is dropped. You can join the child thread in
111 //! advance by calling the `join` method on the guard, which will also
112 //! return the result produced by the thread. A handle to the thread
113 //! itself is available via the `thread` method of the join guard.
114 //!
115 //! ## Configuring threads
116 //!
117 //! A new thread can be configured before it is spawned via the `Builder` type,
118 //! which currently allows you to set the name and stack size for the child thread:
119 //!
120 //! ```rust
121 //! # #![allow(unused_must_use)]
122 //! use std::thread;
123 //!
124 //! thread::Builder::new().name("child1".to_string()).spawn(move || {
125 //! println!("Hello, world!");
126 //! });
127 //! ```
128 //!
129 //! ## Blocking support: park and unpark
130 //!
131 //! Every thread is equipped with some basic low-level blocking support, via the
132 //! `park` and `unpark` functions.
133 //!
134 //! Conceptually, each `Thread` handle has an associated token, which is
135 //! initially not present:
136 //!
137 //! * The `thread::park()` function blocks the current thread unless or until
138 //! the token is available for its thread handle, at which point it atomically
139 //! consumes the token. It may also return *spuriously*, without consuming the
140 //! token. `thread::park_timeout()` does the same, but allows specifying a
141 //! maximum time to block the thread for.
142 //!
143 //! * The `unpark()` method on a `Thread` atomically makes the token available
144 //! if it wasn't already.
145 //!
146 //! In other words, each `Thread` acts a bit like a semaphore with initial count
147 //! 0, except that the semaphore is *saturating* (the count cannot go above 1),
148 //! and can return spuriously.
149 //!
150 //! The API is typically used by acquiring a handle to the current thread,
151 //! placing that handle in a shared data structure so that other threads can
152 //! find it, and then `park`ing. When some desired condition is met, another
153 //! thread calls `unpark` on the handle.
154 //!
155 //! The motivation for this design is twofold:
156 //!
157 //! * It avoids the need to allocate mutexes and condvars when building new
158 //! synchronization primitives; the threads already provide basic blocking/signaling.
159 //!
160 //! * It can be implemented very efficiently on many platforms.
161 //!
162 //! ## Thread-local storage
163 //!
164 //! This module also provides an implementation of thread local storage for Rust
165 //! programs. Thread local storage is a method of storing data into a global
166 //! variable which each thread in the program will have its own copy of.
167 //! Threads do not share this data, so accesses do not need to be synchronized.
168 //!
169 //! At a high level, this module provides two variants of storage:
170 //!
171 //! * Owned thread-local storage. This is a type of thread local key which
172 //! owns the value that it contains, and will destroy the value when the
173 //! thread exits. This variant is created with the `thread_local!` macro and
174 //! can contain any value which is `'static` (no borrowed pointers).
175 //!
176 //! * Scoped thread-local storage. This type of key is used to store a reference
177 //! to a value into local storage temporarily for the scope of a function
178 //! call. There are no restrictions on what types of values can be placed
179 //! into this key.
180 //!
181 //! Both forms of thread local storage provide an accessor function, `with`,
182 //! which will yield a shared reference to the value to the specified
183 //! closure. Thread-local keys only allow shared access to values as there is no
184 //! way to guarantee uniqueness if a mutable borrow was allowed. Most values
185 //! will want to make use of some form of **interior mutability** through the
186 //! `Cell` or `RefCell` types.
187
188 #![stable(feature = "rust1", since = "1.0.0")]
189
190 use prelude::v1::*;
191
192 use alloc::boxed::FnBox;
193 use any::Any;
194 use cell::UnsafeCell;
195 use fmt;
196 use io;
197 use marker::PhantomData;
198 use rt::{self, unwind};
199 use sync::{Mutex, Condvar, Arc};
200 use sys::thread as imp;
201 use sys_common::{stack, thread_info};
202 use time::Duration;
203
204 ////////////////////////////////////////////////////////////////////////////////
205 // Thread-local storage
206 ////////////////////////////////////////////////////////////////////////////////
207
208 #[macro_use] mod local;
209 #[macro_use] mod scoped_tls;
210
211 #[stable(feature = "rust1", since = "1.0.0")]
212 pub use self::local::{LocalKey, LocalKeyState};
213
214 #[unstable(feature = "scoped_tls",
215 reason = "scoped TLS has yet to have wide enough use to fully \
216 consider stabilizing its interface")]
217 pub use self::scoped_tls::ScopedKey;
218
219 #[doc(hidden)] pub use self::local::__KeyInner as __LocalKeyInner;
220 #[doc(hidden)] pub use self::scoped_tls::__KeyInner as __ScopedKeyInner;
221
222 ////////////////////////////////////////////////////////////////////////////////
223 // Builder
224 ////////////////////////////////////////////////////////////////////////////////
225
226 /// Thread configuration. Provides detailed control over the properties
227 /// and behavior of new threads.
228 #[stable(feature = "rust1", since = "1.0.0")]
229 pub struct Builder {
230 // A name for the thread-to-be, for identification in panic messages
231 name: Option<String>,
232 // The size of the stack for the spawned thread
233 stack_size: Option<usize>,
234 }
235
236 impl Builder {
237 /// Generates the base configuration for spawning a thread, from which
238 /// configuration methods can be chained.
239 #[stable(feature = "rust1", since = "1.0.0")]
240 pub fn new() -> Builder {
241 Builder {
242 name: None,
243 stack_size: None,
244 }
245 }
246
247 /// Names the thread-to-be. Currently the name is used for identification
248 /// only in panic messages.
249 #[stable(feature = "rust1", since = "1.0.0")]
250 pub fn name(mut self, name: String) -> Builder {
251 self.name = Some(name);
252 self
253 }
254
255 /// Sets the size of the stack for the new thread.
256 #[stable(feature = "rust1", since = "1.0.0")]
257 pub fn stack_size(mut self, size: usize) -> Builder {
258 self.stack_size = Some(size);
259 self
260 }
261
262 /// Spawns a new thread, and returns a join handle for it.
263 ///
264 /// The child thread may outlive the parent (unless the parent thread
265 /// is the main thread; the whole process is terminated when the main
266 /// thread finishes). The join handle can be used to block on
267 /// termination of the child thread, including recovering its panics.
268 ///
269 /// # Errors
270 ///
271 /// Unlike the `spawn` free function, this method yields an
272 /// `io::Result` to capture any failure to create the thread at
273 /// the OS level.
274 #[stable(feature = "rust1", since = "1.0.0")]
275 pub fn spawn<F, T>(self, f: F) -> io::Result<JoinHandle<T>> where
276 F: FnOnce() -> T, F: Send + 'static, T: Send + 'static
277 {
278 unsafe {
279 self.spawn_inner(Box::new(f)).map(JoinHandle)
280 }
281 }
282
283 /// Spawns a new child thread that must be joined within a given
284 /// scope, and returns a `JoinGuard`.
285 ///
286 /// The join guard can be used to explicitly join the child thread (via
287 /// `join`), returning `Result<T>`, or it will implicitly join the child
288 /// upon being dropped. Because the child thread may refer to data on the
289 /// current thread's stack (hence the "scoped" name), it cannot be detached;
290 /// it *must* be joined before the relevant stack frame is popped. See the
291 /// module documentation for additional details.
292 ///
293 /// # Errors
294 ///
295 /// Unlike the `scoped` free function, this method yields an
296 /// `io::Result` to capture any failure to create the thread at
297 /// the OS level.
298 #[unstable(feature = "scoped",
299 reason = "memory unsafe if destructor is avoided, see #24292")]
300 #[deprecated(since = "1.2.0",
301 reason = "this unsafe API is unlikely to ever be stabilized \
302 in this form")]
303 pub fn scoped<'a, T, F>(self, f: F) -> io::Result<JoinGuard<'a, T>> where
304 T: Send + 'a, F: FnOnce() -> T, F: Send + 'a
305 {
306 unsafe {
307 self.spawn_inner(Box::new(f)).map(|inner| {
308 JoinGuard { inner: inner, _marker: PhantomData }
309 })
310 }
311 }
312
313 // NB: this function is unsafe as the lifetime parameter of the code to run
314 // in the new thread is not tied into the return value, and the return
315 // value must not outlast that lifetime.
316 unsafe fn spawn_inner<'a, T: Send>(self, f: Box<FnBox() -> T + Send + 'a>)
317 -> io::Result<JoinInner<T>> {
318 let Builder { name, stack_size } = self;
319
320 let stack_size = stack_size.unwrap_or(rt::min_stack());
321
322 let my_thread = Thread::new(name);
323 let their_thread = my_thread.clone();
324
325 let my_packet = Arc::new(UnsafeCell::new(None));
326 let their_packet = my_packet.clone();
327
328 // Spawning a new OS thread guarantees that __morestack will never get
329 // triggered, but we must manually set up the actual stack bounds once
330 // this function starts executing. This raises the lower limit by a bit
331 // because by the time that this function is executing we've already
332 // consumed at least a little bit of stack (we don't know the exact byte
333 // address at which our stack started).
334 let main = move || {
335 let something_around_the_top_of_the_stack = 1;
336 let addr = &something_around_the_top_of_the_stack as *const i32;
337 let my_stack_top = addr as usize;
338 let my_stack_bottom = my_stack_top - stack_size + 1024;
339 stack::record_os_managed_stack_bounds(my_stack_bottom, my_stack_top);
340
341 if let Some(name) = their_thread.name() {
342 imp::Thread::set_name(name);
343 }
344 thread_info::set(imp::guard::current(), their_thread);
345
346 let mut output = None;
347 let try_result = {
348 let ptr = &mut output;
349 unwind::try(move || *ptr = Some(f()))
350 };
351 *their_packet.get() = Some(try_result.map(|()| {
352 output.unwrap()
353 }));
354 };
355
356 Ok(JoinInner {
357 native: Some(try!(imp::Thread::new(stack_size, Box::new(main)))),
358 thread: my_thread,
359 packet: Packet(my_packet),
360 })
361 }
362 }
363
364 ////////////////////////////////////////////////////////////////////////////////
365 // Free functions
366 ////////////////////////////////////////////////////////////////////////////////
367
368 /// Spawns a new thread, returning a `JoinHandle` for it.
369 ///
370 /// The join handle will implicitly *detach* the child thread upon being
371 /// dropped. In this case, the child thread may outlive the parent (unless
372 /// the parent thread is the main thread; the whole process is terminated when
373 /// the main thread finishes.) Additionally, the join handle provides a `join`
374 /// method that can be used to join the child thread. If the child thread
375 /// panics, `join` will return an `Err` containing the argument given to
376 /// `panic`.
377 ///
378 /// # Panics
379 ///
380 /// Panics if the OS fails to create a thread; use `Builder::spawn`
381 /// to recover from such errors.
382 #[stable(feature = "rust1", since = "1.0.0")]
383 pub fn spawn<F, T>(f: F) -> JoinHandle<T> where
384 F: FnOnce() -> T, F: Send + 'static, T: Send + 'static
385 {
386 Builder::new().spawn(f).unwrap()
387 }
388
389 /// Spawns a new *scoped* thread, returning a `JoinGuard` for it.
390 ///
391 /// The join guard can be used to explicitly join the child thread (via
392 /// `join`), returning `Result<T>`, or it will implicitly join the child
393 /// upon being dropped. Because the child thread may refer to data on the
394 /// current thread's stack (hence the "scoped" name), it cannot be detached;
395 /// it *must* be joined before the relevant stack frame is popped. See the
396 /// module documentation for additional details.
397 ///
398 /// # Panics
399 ///
400 /// Panics if the OS fails to create a thread; use `Builder::scoped`
401 /// to recover from such errors.
402 #[unstable(feature = "scoped",
403 reason = "memory unsafe if destructor is avoided, see #24292")]
404 #[deprecated(since = "1.2.0",
405 reason = "this unsafe API is unlikely to ever be stabilized \
406 in this form")]
407 #[allow(deprecated)]
408 pub fn scoped<'a, T, F>(f: F) -> JoinGuard<'a, T> where
409 T: Send + 'a, F: FnOnce() -> T, F: Send + 'a
410 {
411 Builder::new().scoped(f).unwrap()
412 }
413
414 /// Gets a handle to the thread that invokes it.
415 #[stable(feature = "rust1", since = "1.0.0")]
416 pub fn current() -> Thread {
417 thread_info::current_thread().expect("use of std::thread::current() is not \
418 possible after the thread's local \
419 data has been destroyed")
420 }
421
422 /// Cooperatively gives up a timeslice to the OS scheduler.
423 #[stable(feature = "rust1", since = "1.0.0")]
424 pub fn yield_now() {
425 imp::Thread::yield_now()
426 }
427
428 /// Determines whether the current thread is unwinding because of panic.
429 #[inline]
430 #[stable(feature = "rust1", since = "1.0.0")]
431 pub fn panicking() -> bool {
432 unwind::panicking()
433 }
434
435 /// Invokes a closure, capturing the cause of panic if one occurs.
436 ///
437 /// This function will return `Ok(())` if the closure does not panic, and will
438 /// return `Err(cause)` if the closure panics. The `cause` returned is the
439 /// object with which panic was originally invoked.
440 ///
441 /// It is currently undefined behavior to unwind from Rust code into foreign
442 /// code, so this function is particularly useful when Rust is called from
443 /// another language (normally C). This can run arbitrary Rust code, capturing a
444 /// panic and allowing a graceful handling of the error.
445 ///
446 /// It is **not** recommended to use this function for a general try/catch
447 /// mechanism. The `Result` type is more appropriate to use for functions that
448 /// can fail on a regular basis.
449 ///
450 /// The closure provided is required to adhere to the `'static` bound to ensure
451 /// that it cannot reference data in the parent stack frame, mitigating problems
452 /// with exception safety. Furthermore, a `Send` bound is also required,
453 /// providing the same safety guarantees as `thread::spawn` (ensuring the
454 /// closure is properly isolated from the parent).
455 ///
456 /// # Examples
457 ///
458 /// ```
459 /// # #![feature(catch_panic)]
460 /// use std::thread;
461 ///
462 /// let result = thread::catch_panic(|| {
463 /// println!("hello!");
464 /// });
465 /// assert!(result.is_ok());
466 ///
467 /// let result = thread::catch_panic(|| {
468 /// panic!("oh no!");
469 /// });
470 /// assert!(result.is_err());
471 /// ```
472 #[unstable(feature = "catch_panic", reason = "recent API addition")]
473 pub fn catch_panic<F, R>(f: F) -> Result<R>
474 where F: FnOnce() -> R + Send + 'static
475 {
476 let mut result = None;
477 unsafe {
478 let result = &mut result;
479 try!(::rt::unwind::try(move || *result = Some(f())))
480 }
481 Ok(result.unwrap())
482 }
483
484 /// Puts the current thread to sleep for the specified amount of time.
485 ///
486 /// The thread may sleep longer than the duration specified due to scheduling
487 /// specifics or platform-dependent functionality. Note that on unix platforms
488 /// this function will not return early due to a signal being received or a
489 /// spurious wakeup.
490 #[stable(feature = "rust1", since = "1.0.0")]
491 pub fn sleep_ms(ms: u32) {
492 sleep(Duration::from_millis(ms as u64))
493 }
494
495 /// Puts the current thread to sleep for the specified amount of time.
496 ///
497 /// The thread may sleep longer than the duration specified due to scheduling
498 /// specifics or platform-dependent functionality.
499 ///
500 /// # Platform behavior
501 ///
502 /// On Unix platforms this function will not return early due to a
503 /// signal being received or a spurious wakeup. Platforms which do not support
504 /// nanosecond precision for sleeping will have `dur` rounded up to the nearest
505 /// granularity of time they can sleep for.
506 #[unstable(feature = "thread_sleep", reason = "waiting on Duration")]
507 pub fn sleep(dur: Duration) {
508 imp::Thread::sleep(dur)
509 }
510
511 /// Blocks unless or until the current thread's token is made available (may wake spuriously).
512 ///
513 /// See the module doc for more detail.
514 //
515 // The implementation currently uses the trivial strategy of a Mutex+Condvar
516 // with wakeup flag, which does not actually allow spurious wakeups. In the
517 // future, this will be implemented in a more efficient way, perhaps along the lines of
518 // http://cr.openjdk.java.net/~stefank/6989984.1/raw_files/new/src/os/linux/vm/os_linux.cpp
519 // or futuxes, and in either case may allow spurious wakeups.
520 #[stable(feature = "rust1", since = "1.0.0")]
521 pub fn park() {
522 let thread = current();
523 let mut guard = thread.inner.lock.lock().unwrap();
524 while !*guard {
525 guard = thread.inner.cvar.wait(guard).unwrap();
526 }
527 *guard = false;
528 }
529
530 /// Blocks unless or until the current thread's token is made available or
531 /// the specified duration has been reached (may wake spuriously).
532 ///
533 /// The semantics of this function are equivalent to `park()` except that the
534 /// thread will be blocked for roughly no longer than *ms*. This method
535 /// should not be used for precise timing due to anomalies such as
536 /// preemption or platform differences that may not cause the maximum
537 /// amount of time waited to be precisely *ms* long.
538 ///
539 /// See the module doc for more detail.
540 #[stable(feature = "rust1", since = "1.0.0")]
541 pub fn park_timeout_ms(ms: u32) {
542 park_timeout(Duration::from_millis(ms as u64))
543 }
544
545 /// Blocks unless or until the current thread's token is made available or
546 /// the specified duration has been reached (may wake spuriously).
547 ///
548 /// The semantics of this function are equivalent to `park()` except that the
549 /// thread will be blocked for roughly no longer than *dur*. This method
550 /// should not be used for precise timing due to anomalies such as
551 /// preemption or platform differences that may not cause the maximum
552 /// amount of time waited to be precisely *dur* long.
553 ///
554 /// See the module doc for more detail.
555 ///
556 /// # Platform behavior
557 ///
558 /// Platforms which do not support nanosecond precision for sleeping will have
559 /// `dur` rounded up to the nearest granularity of time they can sleep for.
560 #[unstable(feature = "park_timeout", reason = "waiting on Duration")]
561 pub fn park_timeout(dur: Duration) {
562 let thread = current();
563 let mut guard = thread.inner.lock.lock().unwrap();
564 if !*guard {
565 let (g, _) = thread.inner.cvar.wait_timeout(guard, dur).unwrap();
566 guard = g;
567 }
568 *guard = false;
569 }
570
571 ////////////////////////////////////////////////////////////////////////////////
572 // Thread
573 ////////////////////////////////////////////////////////////////////////////////
574
575 /// The internal representation of a `Thread` handle
576 struct Inner {
577 name: Option<String>,
578 lock: Mutex<bool>, // true when there is a buffered unpark
579 cvar: Condvar,
580 }
581
582 #[derive(Clone)]
583 #[stable(feature = "rust1", since = "1.0.0")]
584 /// A handle to a thread.
585 pub struct Thread {
586 inner: Arc<Inner>,
587 }
588
589 impl Thread {
590 // Used only internally to construct a thread object without spawning
591 fn new(name: Option<String>) -> Thread {
592 Thread {
593 inner: Arc::new(Inner {
594 name: name,
595 lock: Mutex::new(false),
596 cvar: Condvar::new(),
597 })
598 }
599 }
600
601 /// Atomically makes the handle's token available if it is not already.
602 ///
603 /// See the module doc for more detail.
604 #[stable(feature = "rust1", since = "1.0.0")]
605 pub fn unpark(&self) {
606 let mut guard = self.inner.lock.lock().unwrap();
607 if !*guard {
608 *guard = true;
609 self.inner.cvar.notify_one();
610 }
611 }
612
613 /// Gets the thread's name.
614 #[stable(feature = "rust1", since = "1.0.0")]
615 pub fn name(&self) -> Option<&str> {
616 self.inner.name.as_ref().map(|s| &**s)
617 }
618 }
619
620 #[stable(feature = "rust1", since = "1.0.0")]
621 impl fmt::Debug for Thread {
622 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
623 fmt::Debug::fmt(&self.name(), f)
624 }
625 }
626
627 // a hack to get around privacy restrictions
628 impl thread_info::NewThread for Thread {
629 fn new(name: Option<String>) -> Thread { Thread::new(name) }
630 }
631
632 ////////////////////////////////////////////////////////////////////////////////
633 // JoinHandle and JoinGuard
634 ////////////////////////////////////////////////////////////////////////////////
635
636 /// Indicates the manner in which a thread exited.
637 ///
638 /// A thread that completes without panicking is considered to exit successfully.
639 #[stable(feature = "rust1", since = "1.0.0")]
640 pub type Result<T> = ::result::Result<T, Box<Any + Send + 'static>>;
641
642 // This packet is used to communicate the return value between the child thread
643 // and the parent thread. Memory is shared through the `Arc` within and there's
644 // no need for a mutex here because synchronization happens with `join()` (the
645 // parent thread never reads this packet until the child has exited).
646 //
647 // This packet itself is then stored into a `JoinInner` which in turns is placed
648 // in `JoinHandle` and `JoinGuard`. Due to the usage of `UnsafeCell` we need to
649 // manually worry about impls like Send and Sync. The type `T` should
650 // already always be Send (otherwise the thread could not have been created) and
651 // this type is inherently Sync because no methods take &self. Regardless,
652 // however, we add inheriting impls for Send/Sync to this type to ensure it's
653 // Send/Sync and that future modifications will still appropriately classify it.
654 struct Packet<T>(Arc<UnsafeCell<Option<Result<T>>>>);
655
656 unsafe impl<T: Send> Send for Packet<T> {}
657 unsafe impl<T: Sync> Sync for Packet<T> {}
658
659 /// Inner representation for JoinHandle and JoinGuard
660 struct JoinInner<T> {
661 native: Option<imp::Thread>,
662 thread: Thread,
663 packet: Packet<T>,
664 }
665
666 impl<T> JoinInner<T> {
667 fn join(&mut self) -> Result<T> {
668 self.native.take().unwrap().join();
669 unsafe {
670 (*self.packet.0.get()).take().unwrap()
671 }
672 }
673 }
674
675 /// An owned permission to join on a thread (block on its termination).
676 ///
677 /// Unlike a `JoinGuard`, a `JoinHandle` *detaches* the child thread
678 /// when it is dropped, rather than automatically joining on drop.
679 ///
680 /// Due to platform restrictions, it is not possible to `Clone` this
681 /// handle: the ability to join a child thread is a uniquely-owned
682 /// permission.
683 #[stable(feature = "rust1", since = "1.0.0")]
684 pub struct JoinHandle<T>(JoinInner<T>);
685
686 impl<T> JoinHandle<T> {
687 /// Extracts a handle to the underlying thread
688 #[stable(feature = "rust1", since = "1.0.0")]
689 pub fn thread(&self) -> &Thread {
690 &self.0.thread
691 }
692
693 /// Waits for the associated thread to finish.
694 ///
695 /// If the child thread panics, `Err` is returned with the parameter given
696 /// to `panic`.
697 #[stable(feature = "rust1", since = "1.0.0")]
698 pub fn join(mut self) -> Result<T> {
699 self.0.join()
700 }
701 }
702
703 /// An RAII-style guard that will block until thread termination when dropped.
704 ///
705 /// The type `T` is the return type for the thread's main function.
706 ///
707 /// Joining on drop is necessary to ensure memory safety when stack
708 /// data is shared between a parent and child thread.
709 ///
710 /// Due to platform restrictions, it is not possible to `Clone` this
711 /// handle: the ability to join a child thread is a uniquely-owned
712 /// permission.
713 #[must_use = "thread will be immediately joined if `JoinGuard` is not used"]
714 #[unstable(feature = "scoped",
715 reason = "memory unsafe if destructor is avoided, see #24292")]
716 pub struct JoinGuard<'a, T: Send + 'a> {
717 inner: JoinInner<T>,
718 _marker: PhantomData<&'a T>,
719 }
720
721 #[stable(feature = "rust1", since = "1.0.0")]
722 unsafe impl<'a, T: Send + 'a> Sync for JoinGuard<'a, T> {}
723
724 impl<'a, T: Send + 'a> JoinGuard<'a, T> {
725 /// Extracts a handle to the thread this guard will join on.
726 #[stable(feature = "rust1", since = "1.0.0")]
727 pub fn thread(&self) -> &Thread {
728 &self.inner.thread
729 }
730
731 /// Waits for the associated thread to finish, returning the result of the
732 /// thread's calculation.
733 ///
734 /// # Panics
735 ///
736 /// Panics on the child thread are propagated by panicking the parent.
737 #[stable(feature = "rust1", since = "1.0.0")]
738 pub fn join(mut self) -> T {
739 match self.inner.join() {
740 Ok(res) => res,
741 Err(_) => panic!("child thread {:?} panicked", self.thread()),
742 }
743 }
744 }
745
746 #[unstable(feature = "scoped",
747 reason = "memory unsafe if destructor is avoided, see #24292")]
748 impl<'a, T: Send + 'a> Drop for JoinGuard<'a, T> {
749 fn drop(&mut self) {
750 if self.inner.native.is_some() && self.inner.join().is_err() {
751 panic!("child thread {:?} panicked", self.thread());
752 }
753 }
754 }
755
756 fn _assert_sync_and_send() {
757 fn _assert_both<T: Send + Sync>() {}
758 _assert_both::<JoinHandle<()>>();
759 _assert_both::<JoinGuard<()>>();
760 _assert_both::<Thread>();
761 }
762
763 ////////////////////////////////////////////////////////////////////////////////
764 // Tests
765 ////////////////////////////////////////////////////////////////////////////////
766
767 #[cfg(test)]
768 mod tests {
769 use prelude::v1::*;
770
771 use any::Any;
772 use sync::mpsc::{channel, Sender};
773 use result;
774 use super::{Builder};
775 use thread;
776 use thunk::Thunk;
777 use time::Duration;
778 use u32;
779
780 // !!! These tests are dangerous. If something is buggy, they will hang, !!!
781 // !!! instead of exiting cleanly. This might wedge the buildbots. !!!
782
783 #[test]
784 fn test_unnamed_thread() {
785 thread::spawn(move|| {
786 assert!(thread::current().name().is_none());
787 }).join().ok().unwrap();
788 }
789
790 #[test]
791 fn test_named_thread() {
792 Builder::new().name("ada lovelace".to_string()).scoped(move|| {
793 assert!(thread::current().name().unwrap() == "ada lovelace".to_string());
794 }).unwrap().join();
795 }
796
797 #[test]
798 fn test_run_basic() {
799 let (tx, rx) = channel();
800 thread::spawn(move|| {
801 tx.send(()).unwrap();
802 });
803 rx.recv().unwrap();
804 }
805
806 #[test]
807 fn test_join_success() {
808 assert!(thread::scoped(move|| -> String {
809 "Success!".to_string()
810 }).join() == "Success!");
811 }
812
813 #[test]
814 fn test_join_panic() {
815 match thread::spawn(move|| {
816 panic!()
817 }).join() {
818 result::Result::Err(_) => (),
819 result::Result::Ok(()) => panic!()
820 }
821 }
822
823 #[test]
824 fn test_scoped_success() {
825 let res = thread::scoped(move|| -> String {
826 "Success!".to_string()
827 }).join();
828 assert!(res == "Success!");
829 }
830
831 #[test]
832 #[should_panic]
833 fn test_scoped_panic() {
834 thread::scoped(|| panic!()).join();
835 }
836
837 #[test]
838 #[should_panic]
839 fn test_scoped_implicit_panic() {
840 let _ = thread::scoped(|| panic!());
841 }
842
843 #[test]
844 fn test_spawn_sched() {
845 use clone::Clone;
846
847 let (tx, rx) = channel();
848
849 fn f(i: i32, tx: Sender<()>) {
850 let tx = tx.clone();
851 thread::spawn(move|| {
852 if i == 0 {
853 tx.send(()).unwrap();
854 } else {
855 f(i - 1, tx);
856 }
857 });
858
859 }
860 f(10, tx);
861 rx.recv().unwrap();
862 }
863
864 #[test]
865 fn test_spawn_sched_childs_on_default_sched() {
866 let (tx, rx) = channel();
867
868 thread::spawn(move|| {
869 thread::spawn(move|| {
870 tx.send(()).unwrap();
871 });
872 });
873
874 rx.recv().unwrap();
875 }
876
877 fn avoid_copying_the_body<F>(spawnfn: F) where F: FnOnce(Thunk<'static>) {
878 let (tx, rx) = channel();
879
880 let x: Box<_> = box 1;
881 let x_in_parent = (&*x) as *const i32 as usize;
882
883 spawnfn(Box::new(move|| {
884 let x_in_child = (&*x) as *const i32 as usize;
885 tx.send(x_in_child).unwrap();
886 }));
887
888 let x_in_child = rx.recv().unwrap();
889 assert_eq!(x_in_parent, x_in_child);
890 }
891
892 #[test]
893 fn test_avoid_copying_the_body_spawn() {
894 avoid_copying_the_body(|v| {
895 thread::spawn(move || v());
896 });
897 }
898
899 #[test]
900 fn test_avoid_copying_the_body_thread_spawn() {
901 avoid_copying_the_body(|f| {
902 thread::spawn(move|| {
903 f();
904 });
905 })
906 }
907
908 #[test]
909 fn test_avoid_copying_the_body_join() {
910 avoid_copying_the_body(|f| {
911 let _ = thread::spawn(move|| {
912 f()
913 }).join();
914 })
915 }
916
917 #[test]
918 fn test_child_doesnt_ref_parent() {
919 // If the child refcounts the parent thread, this will stack overflow when
920 // climbing the thread tree to dereference each ancestor. (See #1789)
921 // (well, it would if the constant were 8000+ - I lowered it to be more
922 // valgrind-friendly. try this at home, instead..!)
923 const GENERATIONS: u32 = 16;
924 fn child_no(x: u32) -> Thunk<'static> {
925 return Box::new(move|| {
926 if x < GENERATIONS {
927 thread::spawn(move|| child_no(x+1)());
928 }
929 });
930 }
931 thread::spawn(|| child_no(0)());
932 }
933
934 #[test]
935 fn test_simple_newsched_spawn() {
936 thread::spawn(move || {});
937 }
938
939 #[test]
940 fn test_try_panic_message_static_str() {
941 match thread::spawn(move|| {
942 panic!("static string");
943 }).join() {
944 Err(e) => {
945 type T = &'static str;
946 assert!(e.is::<T>());
947 assert_eq!(*e.downcast::<T>().unwrap(), "static string");
948 }
949 Ok(()) => panic!()
950 }
951 }
952
953 #[test]
954 fn test_try_panic_message_owned_str() {
955 match thread::spawn(move|| {
956 panic!("owned string".to_string());
957 }).join() {
958 Err(e) => {
959 type T = String;
960 assert!(e.is::<T>());
961 assert_eq!(*e.downcast::<T>().unwrap(), "owned string".to_string());
962 }
963 Ok(()) => panic!()
964 }
965 }
966
967 #[test]
968 fn test_try_panic_message_any() {
969 match thread::spawn(move|| {
970 panic!(box 413u16 as Box<Any + Send>);
971 }).join() {
972 Err(e) => {
973 type T = Box<Any + Send>;
974 assert!(e.is::<T>());
975 let any = e.downcast::<T>().unwrap();
976 assert!(any.is::<u16>());
977 assert_eq!(*any.downcast::<u16>().unwrap(), 413);
978 }
979 Ok(()) => panic!()
980 }
981 }
982
983 #[test]
984 fn test_try_panic_message_unit_struct() {
985 struct Juju;
986
987 match thread::spawn(move|| {
988 panic!(Juju)
989 }).join() {
990 Err(ref e) if e.is::<Juju>() => {}
991 Err(_) | Ok(()) => panic!()
992 }
993 }
994
995 #[test]
996 fn test_park_timeout_unpark_before() {
997 for _ in 0..10 {
998 thread::current().unpark();
999 thread::park_timeout_ms(u32::MAX);
1000 }
1001 }
1002
1003 #[test]
1004 fn test_park_timeout_unpark_not_called() {
1005 for _ in 0..10 {
1006 thread::park_timeout_ms(10);
1007 }
1008 }
1009
1010 #[test]
1011 fn test_park_timeout_unpark_called_other_thread() {
1012 for _ in 0..10 {
1013 let th = thread::current();
1014
1015 let _guard = thread::spawn(move || {
1016 super::sleep_ms(50);
1017 th.unpark();
1018 });
1019
1020 thread::park_timeout_ms(u32::MAX);
1021 }
1022 }
1023
1024 #[test]
1025 fn sleep_ms_smoke() {
1026 thread::sleep_ms(2);
1027 }
1028
1029 // NOTE: the corresponding test for stderr is in run-pass/thread-stderr, due
1030 // to the test harness apparently interfering with stderr configuration.
1031 }