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 //! ## Configuring threads
  89 //!
  90 //! A new thread can be configured before it is spawned via the `Builder` type,
  91 //! which currently allows you to set the name and stack size for the child thread:
  92 //!
  93 //! ```rust
  94 //! # #![allow(unused_must_use)]
  95 //! use std::thread;
  96 //!
  97 //! thread::Builder::new().name("child1".to_string()).spawn(move || {
  98 //!     println!("Hello, world!");
  99 //! });
 100 //! ```
 101 //!
 102 //! ## Blocking support: park and unpark
 103 //!
 104 //! Every thread is equipped with some basic low-level blocking support, via the
 105 //! `park` and `unpark` functions.
 106 //!
 107 //! Conceptually, each `Thread` handle has an associated token, which is
 108 //! initially not present:
 109 //!
 110 //! * The `thread::park()` function blocks the current thread unless or until
 111 //!   the token is available for its thread handle, at which point it atomically
 112 //!   consumes the token. It may also return *spuriously*, without consuming the
 113 //!   token. `thread::park_timeout()` does the same, but allows specifying a
 114 //!   maximum time to block the thread for.
 115 //!
 116 //! * The `unpark()` method on a `Thread` atomically makes the token available
 117 //!   if it wasn't already.
 118 //!
 119 //! In other words, each `Thread` acts a bit like a semaphore with initial count
 120 //! 0, except that the semaphore is *saturating* (the count cannot go above 1),
 121 //! and can return spuriously.
 122 //!
 123 //! The API is typically used by acquiring a handle to the current thread,
 124 //! placing that handle in a shared data structure so that other threads can
 125 //! find it, and then `park`ing. When some desired condition is met, another
 126 //! thread calls `unpark` on the handle.
 127 //!
 128 //! The motivation for this design is twofold:
 129 //!
 130 //! * It avoids the need to allocate mutexes and condvars when building new
 131 //!   synchronization primitives; the threads already provide basic blocking/signaling.
 132 //!
 133 //! * It can be implemented very efficiently on many platforms.
 134 //!
 135 //! ## Thread-local storage
 136 //!
 137 //! This module also provides an implementation of thread local storage for Rust
 138 //! programs. Thread local storage is a method of storing data into a global
 139 //! variable which each thread in the program will have its own copy of.
 140 //! Threads do not share this data, so accesses do not need to be synchronized.
 141 //!
 142 //! At a high level, this module provides two variants of storage:
 143 //!
 144 //! * Owned thread-local storage. This is a type of thread local key which
 145 //!   owns the value that it contains, and will destroy the value when the
 146 //!   thread exits. This variant is created with the `thread_local!` macro and
 147 //!   can contain any value which is `'static` (no borrowed pointers).
 148 //!
 149 //! * Scoped thread-local storage. This type of key is used to store a reference
 150 //!   to a value into local storage temporarily for the scope of a function
 151 //!   call. There are no restrictions on what types of values can be placed
 152 //!   into this key.
 153 //!
 154 //! Both forms of thread local storage provide an accessor function, `with`,
 155 //! which will yield a shared reference to the value to the specified
 156 //! closure. Thread-local keys only allow shared access to values as there is no
 157 //! way to guarantee uniqueness if a mutable borrow was allowed. Most values
 158 //! will want to make use of some form of **interior mutability** through the
 159 //! `Cell` or `RefCell` types.
 160
 161 #![stable(feature = "rust1", since = "1.0.0")]
 162
 163 use prelude::v1::*;
 164
 165 use any::Any;
 166 use cell::UnsafeCell;
 167 use fmt;
 168 use io;
 169 use sync::{Mutex, Condvar, Arc};
 170 use sys::thread as imp;
 171 use sys_common::thread_info;
 172 use sys_common::unwind;
 173 use sys_common::util;
 174 use sys_common::{AsInner, IntoInner};
 175 use time::Duration;
 176
 177 ////////////////////////////////////////////////////////////////////////////////
 178 // Thread-local storage
 179 ////////////////////////////////////////////////////////////////////////////////
 180
 181 #[macro_use] mod local;
 182 #[macro_use] mod scoped_tls;
 183
 184 #[stable(feature = "rust1", since = "1.0.0")]
 185 pub use self::local::{LocalKey, LocalKeyState};
 186
 187 #[unstable(feature = "scoped_tls",
 188            reason = "scoped TLS has yet to have wide enough use to fully \
 189                      consider stabilizing its interface",
 190            issue = "27715")]
 191 pub use self::scoped_tls::ScopedKey;
 192
 193 #[unstable(feature = "libstd_thread_internals", issue = "0")]
 194 #[doc(hidden)] pub use self::local::__KeyInner as __LocalKeyInner;
 195 #[unstable(feature = "libstd_thread_internals", issue = "0")]
 196 #[doc(hidden)] pub use self::scoped_tls::__KeyInner as __ScopedKeyInner;
 197
 198 ////////////////////////////////////////////////////////////////////////////////
 199 // Builder
 200 ////////////////////////////////////////////////////////////////////////////////
 201
 202 /// Thread configuration. Provides detailed control over the properties
 203 /// and behavior of new threads.
 204 #[stable(feature = "rust1", since = "1.0.0")]
 205 pub struct Builder {
 206     // A name for the thread-to-be, for identification in panic messages
 207     name: Option<String>,
 208     // The size of the stack for the spawned thread
 209     stack_size: Option<usize>,
 210 }
 211
 212 impl Builder {
 213     /// Generates the base configuration for spawning a thread, from which
 214     /// configuration methods can be chained.
 215     #[stable(feature = "rust1", since = "1.0.0")]
 216     pub fn new() -> Builder {
 217         Builder {
 218             name: None,
 219             stack_size: None,
 220         }
 221     }
 222
 223     /// Names the thread-to-be. Currently the name is used for identification
 224     /// only in panic messages.
 225     #[stable(feature = "rust1", since = "1.0.0")]
 226     pub fn name(mut self, name: String) -> Builder {
 227         self.name = Some(name);
 228         self
 229     }
 230
 231     /// Sets the size of the stack for the new thread.
 232     #[stable(feature = "rust1", since = "1.0.0")]
 233     pub fn stack_size(mut self, size: usize) -> Builder {
 234         self.stack_size = Some(size);
 235         self
 236     }
 237
 238     /// Spawns a new thread, and returns a join handle for it.
 239     ///
 240     /// The child thread may outlive the parent (unless the parent thread
 241     /// is the main thread; the whole process is terminated when the main
 242     /// thread finishes). The join handle can be used to block on
 243     /// termination of the child thread, including recovering its panics.
 244     ///
 245     /// # Errors
 246     ///
 247     /// Unlike the `spawn` free function, this method yields an
 248     /// `io::Result` to capture any failure to create the thread at
 249     /// the OS level.
 250     #[stable(feature = "rust1", since = "1.0.0")]
 251     pub fn spawn<F, T>(self, f: F) -> io::Result<JoinHandle<T>> where
 252         F: FnOnce() -> T, F: Send + 'static, T: Send + 'static
 253     {
 254         let Builder { name, stack_size } = self;
 255
 256         let stack_size = stack_size.unwrap_or(util::min_stack());
 257
 258         let my_thread = Thread::new(name);
 259         let their_thread = my_thread.clone();
 260
 261         let my_packet : Arc<UnsafeCell<Option<Result<T>>>>
 262             = Arc::new(UnsafeCell::new(None));
 263         let their_packet = my_packet.clone();
 264
 265         let main = move || {
 266             if let Some(name) = their_thread.name() {
 267                 imp::Thread::set_name(name);
 268             }
 269             unsafe {
 270                 thread_info::set(imp::guard::current(), their_thread);
 271                 let mut output = None;
 272                 let try_result = {
 273                     let ptr = &mut output;
 274                     unwind::try(move || *ptr = Some(f()))
 275                 };
 276                 *their_packet.get() = Some(try_result.map(|()| {
 277                     output.unwrap()
 278                 }));
 279             }
 280         };
 281
 282         Ok(JoinHandle(JoinInner {
 283             native: unsafe {
 284                 Some(try!(imp::Thread::new(stack_size, Box::new(main))))
 285             },
 286             thread: my_thread,
 287             packet: Packet(my_packet),
 288         }))
 289     }
 290 }
 291
 292 ////////////////////////////////////////////////////////////////////////////////
 293 // Free functions
 294 ////////////////////////////////////////////////////////////////////////////////
 295
 296 /// Spawns a new thread, returning a `JoinHandle` for it.
 297 ///
 298 /// The join handle will implicitly *detach* the child thread upon being
 299 /// dropped. In this case, the child thread may outlive the parent (unless
 300 /// the parent thread is the main thread; the whole process is terminated when
 301 /// the main thread finishes.) Additionally, the join handle provides a `join`
 302 /// method that can be used to join the child thread. If the child thread
 303 /// panics, `join` will return an `Err` containing the argument given to
 304 /// `panic`.
 305 ///
 306 /// # Panics
 307 ///
 308 /// Panics if the OS fails to create a thread; use `Builder::spawn`
 309 /// to recover from such errors.
 310 #[stable(feature = "rust1", since = "1.0.0")]
 311 pub fn spawn<F, T>(f: F) -> JoinHandle<T> where
 312     F: FnOnce() -> T, F: Send + 'static, T: Send + 'static
 313 {
 314     Builder::new().spawn(f).unwrap()
 315 }
 316
 317 /// Gets a handle to the thread that invokes it.
 318 #[stable(feature = "rust1", since = "1.0.0")]
 319 pub fn current() -> Thread {
 320     thread_info::current_thread().expect("use of std::thread::current() is not \
 321                                           possible after the thread's local \
 322                                           data has been destroyed")
 323 }
 324
 325 /// Cooperatively gives up a timeslice to the OS scheduler.
 326 #[stable(feature = "rust1", since = "1.0.0")]
 327 pub fn yield_now() {
 328     imp::Thread::yield_now()
 329 }
 330
 331 /// Determines whether the current thread is unwinding because of panic.
 332 #[inline]
 333 #[stable(feature = "rust1", since = "1.0.0")]
 334 pub fn panicking() -> bool {
 335     unwind::panicking()
 336 }
 337
 338 /// Invokes a closure, capturing the cause of panic if one occurs.
 339 ///
 340 /// This function will return `Ok` with the closure's result if the closure
 341 /// does not panic, and will return `Err(cause)` if the closure panics. The
 342 /// `cause` returned is the object with which panic was originally invoked.
 343 ///
 344 /// It is currently undefined behavior to unwind from Rust code into foreign
 345 /// code, so this function is particularly useful when Rust is called from
 346 /// another language (normally C). This can run arbitrary Rust code, capturing a
 347 /// panic and allowing a graceful handling of the error.
 348 ///
 349 /// It is **not** recommended to use this function for a general try/catch
 350 /// mechanism. The `Result` type is more appropriate to use for functions that
 351 /// can fail on a regular basis.
 352 ///
 353 /// The closure provided is required to adhere to the `'static` bound to ensure
 354 /// that it cannot reference data in the parent stack frame, mitigating problems
 355 /// with exception safety. Furthermore, a `Send` bound is also required,
 356 /// providing the same safety guarantees as `thread::spawn` (ensuring the
 357 /// closure is properly isolated from the parent).
 358 ///
 359 /// # Examples
 360 ///
 361 /// ```
 362 /// #![feature(catch_panic)]
 363 ///
 364 /// use std::thread;
 365 ///
 366 /// let result = thread::catch_panic(|| {
 367 ///     println!("hello!");
 368 /// });
 369 /// assert!(result.is_ok());
 370 ///
 371 /// let result = thread::catch_panic(|| {
 372 ///     panic!("oh no!");
 373 /// });
 374 /// assert!(result.is_err());
 375 /// ```
 376 #[unstable(feature = "catch_panic", reason = "recent API addition",
 377            issue = "27719")]
 378 pub fn catch_panic<F, R>(f: F) -> Result<R>
 379     where F: FnOnce() -> R + Send + 'static
 380 {
 381     let mut result = None;
 382     unsafe {
 383         let result = &mut result;
 384         try!(unwind::try(move || *result = Some(f())))
 385     }
 386     Ok(result.unwrap())
 387 }
 388
 389 /// Puts the current thread to sleep for the specified amount of time.
 390 ///
 391 /// The thread may sleep longer than the duration specified due to scheduling
 392 /// specifics or platform-dependent functionality. Note that on unix platforms
 393 /// this function will not return early due to a signal being received or a
 394 /// spurious wakeup.
 395 #[stable(feature = "rust1", since = "1.0.0")]
 396 #[rustc_deprecated(since = "1.6.0", reason = "replaced by `std::thread::sleep`")]
 397 pub fn sleep_ms(ms: u32) {
 398     sleep(Duration::from_millis(ms as u64))
 399 }
 400
 401 /// Puts the current thread to sleep for the specified amount of time.
 402 ///
 403 /// The thread may sleep longer than the duration specified due to scheduling
 404 /// specifics or platform-dependent functionality.
 405 ///
 406 /// # Platform behavior
 407 ///
 408 /// On Unix platforms this function will not return early due to a
 409 /// signal being received or a spurious wakeup. Platforms which do not support
 410 /// nanosecond precision for sleeping will have `dur` rounded up to the nearest
 411 /// granularity of time they can sleep for.
 412 #[stable(feature = "thread_sleep", since = "1.4.0")]
 413 pub fn sleep(dur: Duration) {
 414     imp::Thread::sleep(dur)
 415 }
 416
 417 /// Blocks unless or until the current thread's token is made available.
 418 ///
 419 /// Every thread is equipped with some basic low-level blocking support, via
 420 /// the `park()` function and the [`unpark()`][unpark] method. These can be
 421 /// used as a more CPU-efficient implementation of a spinlock.
 422 ///
 423 /// [unpark]: struct.Thread.html#method.unpark
 424 ///
 425 /// The API is typically used by acquiring a handle to the current thread,
 426 /// placing that handle in a shared data structure so that other threads can
 427 /// find it, and then parking (in a loop with a check for the token actually
 428 /// being acquired).
 429 ///
 430 /// A call to `park` does not guarantee that the thread will remain parked
 431 /// forever, and callers should be prepared for this possibility.
 432 ///
 433 /// See the [module documentation][thread] for more detail.
 434 ///
 435 /// [thread]: index.html
 436 //
 437 // The implementation currently uses the trivial strategy of a Mutex+Condvar
 438 // with wakeup flag, which does not actually allow spurious wakeups. In the
 439 // future, this will be implemented in a more efficient way, perhaps along the lines of
 440 //   http://cr.openjdk.java.net/~stefank/6989984.1/raw_files/new/src/os/linux/vm/os_linux.cpp
 441 // or futuxes, and in either case may allow spurious wakeups.
 442 #[stable(feature = "rust1", since = "1.0.0")]
 443 pub fn park() {
 444     let thread = current();
 445     let mut guard = thread.inner.lock.lock().unwrap();
 446     while !*guard {
 447         guard = thread.inner.cvar.wait(guard).unwrap();
 448     }
 449     *guard = false;
 450 }
 451
 452 /// Blocks unless or until the current thread's token is made available or
 453 /// the specified duration has been reached (may wake spuriously).
 454 ///
 455 /// The semantics of this function are equivalent to `park()` except that the
 456 /// thread will be blocked for roughly no longer than *ms*. This method
 457 /// should not be used for precise timing due to anomalies such as
 458 /// preemption or platform differences that may not cause the maximum
 459 /// amount of time waited to be precisely *ms* long.
 460 ///
 461 /// See the module doc for more detail.
 462 #[stable(feature = "rust1", since = "1.0.0")]
 463 #[rustc_deprecated(since = "1.6.0", reason = "replaced by `std::thread::park_timeout`")]
 464 pub fn park_timeout_ms(ms: u32) {
 465     park_timeout(Duration::from_millis(ms as u64))
 466 }
 467
 468 /// Blocks unless or until the current thread's token is made available or
 469 /// the specified duration has been reached (may wake spuriously).
 470 ///
 471 /// The semantics of this function are equivalent to `park()` except that the
 472 /// thread will be blocked for roughly no longer than *dur*. This method
 473 /// should not be used for precise timing due to anomalies such as
 474 /// preemption or platform differences that may not cause the maximum
 475 /// amount of time waited to be precisely *dur* long.
 476 ///
 477 /// See the module doc for more detail.
 478 ///
 479 /// # Platform behavior
 480 ///
 481 /// Platforms which do not support nanosecond precision for sleeping will have
 482 /// `dur` rounded up to the nearest granularity of time they can sleep for.
 483 #[stable(feature = "park_timeout", since = "1.4.0")]
 484 pub fn park_timeout(dur: Duration) {
 485     let thread = current();
 486     let mut guard = thread.inner.lock.lock().unwrap();
 487     if !*guard {
 488         let (g, _) = thread.inner.cvar.wait_timeout(guard, dur).unwrap();
 489         guard = g;
 490     }
 491     *guard = false;
 492 }
 493
 494 ////////////////////////////////////////////////////////////////////////////////
 495 // Thread
 496 ////////////////////////////////////////////////////////////////////////////////
 497
 498 /// The internal representation of a `Thread` handle
 499 struct Inner {
 500     name: Option<String>,
 501     lock: Mutex<bool>,          // true when there is a buffered unpark
 502     cvar: Condvar,
 503 }
 504
 505 #[derive(Clone)]
 506 #[stable(feature = "rust1", since = "1.0.0")]
 507 /// A handle to a thread.
 508 pub struct Thread {
 509     inner: Arc<Inner>,
 510 }
 511
 512 impl Thread {
 513     // Used only internally to construct a thread object without spawning
 514     fn new(name: Option<String>) -> Thread {
 515         Thread {
 516             inner: Arc::new(Inner {
 517                 name: name,
 518                 lock: Mutex::new(false),
 519                 cvar: Condvar::new(),
 520             })
 521         }
 522     }
 523
 524     /// Atomically makes the handle's token available if it is not already.
 525     ///
 526     /// See the module doc for more detail.
 527     #[stable(feature = "rust1", since = "1.0.0")]
 528     pub fn unpark(&self) {
 529         let mut guard = self.inner.lock.lock().unwrap();
 530         if !*guard {
 531             *guard = true;
 532             self.inner.cvar.notify_one();
 533         }
 534     }
 535
 536     /// Gets the thread's name.
 537     #[stable(feature = "rust1", since = "1.0.0")]
 538     pub fn name(&self) -> Option<&str> {
 539         self.inner.name.as_ref().map(|s| &**s)
 540     }
 541 }
 542
 543 #[stable(feature = "rust1", since = "1.0.0")]
 544 impl fmt::Debug for Thread {
 545     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 546         fmt::Debug::fmt(&self.name(), f)
 547     }
 548 }
 549
 550 // a hack to get around privacy restrictions
 551 impl thread_info::NewThread for Thread {
 552     fn new(name: Option<String>) -> Thread { Thread::new(name) }
 553 }
 554
 555 ////////////////////////////////////////////////////////////////////////////////
 556 // JoinHandle
 557 ////////////////////////////////////////////////////////////////////////////////
 558
 559 /// Indicates the manner in which a thread exited.
 560 ///
 561 /// A thread that completes without panicking is considered to exit successfully.
 562 #[stable(feature = "rust1", since = "1.0.0")]
 563 pub type Result<T> = ::result::Result<T, Box<Any + Send + 'static>>;
 564
 565 // This packet is used to communicate the return value between the child thread
 566 // and the parent thread. Memory is shared through the `Arc` within and there's
 567 // no need for a mutex here because synchronization happens with `join()` (the
 568 // parent thread never reads this packet until the child has exited).
 569 //
 570 // This packet itself is then stored into a `JoinInner` which in turns is placed
 571 // in `JoinHandle` and `JoinGuard`. Due to the usage of `UnsafeCell` we need to
 572 // manually worry about impls like Send and Sync. The type `T` should
 573 // already always be Send (otherwise the thread could not have been created) and
 574 // this type is inherently Sync because no methods take &self. Regardless,
 575 // however, we add inheriting impls for Send/Sync to this type to ensure it's
 576 // Send/Sync and that future modifications will still appropriately classify it.
 577 struct Packet<T>(Arc<UnsafeCell<Option<Result<T>>>>);
 578
 579 unsafe impl<T: Send> Send for Packet<T> {}
 580 unsafe impl<T: Sync> Sync for Packet<T> {}
 581
 582 /// Inner representation for JoinHandle
 583 struct JoinInner<T> {
 584     native: Option<imp::Thread>,
 585     thread: Thread,
 586     packet: Packet<T>,
 587 }
 588
 589 impl<T> JoinInner<T> {
 590     fn join(&mut self) -> Result<T> {
 591         self.native.take().unwrap().join();
 592         unsafe {
 593             (*self.packet.0.get()).take().unwrap()
 594         }
 595     }
 596 }
 597
 598 /// An owned permission to join on a thread (block on its termination).
 599 ///
 600 /// A `JoinHandle` *detaches* the child thread when it is dropped.
 601 ///
 602 /// Due to platform restrictions, it is not possible to `Clone` this
 603 /// handle: the ability to join a child thread is a uniquely-owned
 604 /// permission.
 605 #[stable(feature = "rust1", since = "1.0.0")]
 606 pub struct JoinHandle<T>(JoinInner<T>);
 607
 608 impl<T> JoinHandle<T> {
 609     /// Extracts a handle to the underlying thread
 610     #[stable(feature = "rust1", since = "1.0.0")]
 611     pub fn thread(&self) -> &Thread {
 612         &self.0.thread
 613     }
 614
 615     /// Waits for the associated thread to finish.
 616     ///
 617     /// If the child thread panics, `Err` is returned with the parameter given
 618     /// to `panic`.
 619     #[stable(feature = "rust1", since = "1.0.0")]
 620     pub fn join(mut self) -> Result<T> {
 621         self.0.join()
 622     }
 623 }
 624
 625 impl<T> AsInner<imp::Thread> for JoinHandle<T> {
 626     fn as_inner(&self) -> &imp::Thread { self.0.native.as_ref().unwrap() }
 627 }
 628
 629 impl<T> IntoInner<imp::Thread> for JoinHandle<T> {
 630     fn into_inner(self) -> imp::Thread { self.0.native.unwrap() }
 631 }
 632
 633 fn _assert_sync_and_send() {
 634     fn _assert_both<T: Send + Sync>() {}
 635     _assert_both::<JoinHandle<()>>();
 636     _assert_both::<Thread>();
 637 }
 638
 639 ////////////////////////////////////////////////////////////////////////////////
 640 // Tests
 641 ////////////////////////////////////////////////////////////////////////////////
 642
 643 #[cfg(test)]
 644 mod tests {
 645     use prelude::v1::*;
 646
 647     use any::Any;
 648     use sync::mpsc::{channel, Sender};
 649     use result;
 650     use super::{Builder};
 651     use thread;
 652     use time::Duration;
 653     use u32;
 654
 655     // !!! These tests are dangerous. If something is buggy, they will hang, !!!
 656     // !!! instead of exiting cleanly. This might wedge the buildbots.       !!!
 657
 658     #[test]
 659     fn test_unnamed_thread() {
 660         thread::spawn(move|| {
 661             assert!(thread::current().name().is_none());
 662         }).join().ok().unwrap();
 663     }
 664
 665     #[test]
 666     fn test_named_thread() {
 667         Builder::new().name("ada lovelace".to_string()).spawn(move|| {
 668             assert!(thread::current().name().unwrap() == "ada lovelace".to_string());
 669         }).unwrap().join().unwrap();
 670     }
 671
 672     #[test]
 673     fn test_run_basic() {
 674         let (tx, rx) = channel();
 675         thread::spawn(move|| {
 676             tx.send(()).unwrap();
 677         });
 678         rx.recv().unwrap();
 679     }
 680
 681     #[test]
 682     fn test_join_panic() {
 683         match thread::spawn(move|| {
 684             panic!()
 685         }).join() {
 686             result::Result::Err(_) => (),
 687             result::Result::Ok(()) => panic!()
 688         }
 689     }
 690
 691     #[test]
 692     fn test_spawn_sched() {
 693         use clone::Clone;
 694
 695         let (tx, rx) = channel();
 696
 697         fn f(i: i32, tx: Sender<()>) {
 698             let tx = tx.clone();
 699             thread::spawn(move|| {
 700                 if i == 0 {
 701                     tx.send(()).unwrap();
 702                 } else {
 703                     f(i - 1, tx);
 704                 }
 705             });
 706
 707         }
 708         f(10, tx);
 709         rx.recv().unwrap();
 710     }
 711
 712     #[test]
 713     fn test_spawn_sched_childs_on_default_sched() {
 714         let (tx, rx) = channel();
 715
 716         thread::spawn(move|| {
 717             thread::spawn(move|| {
 718                 tx.send(()).unwrap();
 719             });
 720         });
 721
 722         rx.recv().unwrap();
 723     }
 724
 725     fn avoid_copying_the_body<F>(spawnfn: F) where F: FnOnce(Box<Fn() + Send>) {
 726         let (tx, rx) = channel();
 727
 728         let x: Box<_> = box 1;
 729         let x_in_parent = (&*x) as *const i32 as usize;
 730
 731         spawnfn(Box::new(move|| {
 732             let x_in_child = (&*x) as *const i32 as usize;
 733             tx.send(x_in_child).unwrap();
 734         }));
 735
 736         let x_in_child = rx.recv().unwrap();
 737         assert_eq!(x_in_parent, x_in_child);
 738     }
 739
 740     #[test]
 741     fn test_avoid_copying_the_body_spawn() {
 742         avoid_copying_the_body(|v| {
 743             thread::spawn(move || v());
 744         });
 745     }
 746
 747     #[test]
 748     fn test_avoid_copying_the_body_thread_spawn() {
 749         avoid_copying_the_body(|f| {
 750             thread::spawn(move|| {
 751                 f();
 752             });
 753         })
 754     }
 755
 756     #[test]
 757     fn test_avoid_copying_the_body_join() {
 758         avoid_copying_the_body(|f| {
 759             let _ = thread::spawn(move|| {
 760                 f()
 761             }).join();
 762         })
 763     }
 764
 765     #[test]
 766     fn test_child_doesnt_ref_parent() {
 767         // If the child refcounts the parent thread, this will stack overflow when
 768         // climbing the thread tree to dereference each ancestor. (See #1789)
 769         // (well, it would if the constant were 8000+ - I lowered it to be more
 770         // valgrind-friendly. try this at home, instead..!)
 771         const GENERATIONS: u32 = 16;
 772         fn child_no(x: u32) -> Box<Fn() + Send> {
 773             return Box::new(move|| {
 774                 if x < GENERATIONS {
 775                     thread::spawn(move|| child_no(x+1)());
 776                 }
 777             });
 778         }
 779         thread::spawn(|| child_no(0)());
 780     }
 781
 782     #[test]
 783     fn test_simple_newsched_spawn() {
 784         thread::spawn(move || {});
 785     }
 786
 787     #[test]
 788     fn test_try_panic_message_static_str() {
 789         match thread::spawn(move|| {
 790             panic!("static string");
 791         }).join() {
 792             Err(e) => {
 793                 type T = &'static str;
 794                 assert!(e.is::<T>());
 795                 assert_eq!(*e.downcast::<T>().unwrap(), "static string");
 796             }
 797             Ok(()) => panic!()
 798         }
 799     }
 800
 801     #[test]
 802     fn test_try_panic_message_owned_str() {
 803         match thread::spawn(move|| {
 804             panic!("owned string".to_string());
 805         }).join() {
 806             Err(e) => {
 807                 type T = String;
 808                 assert!(e.is::<T>());
 809                 assert_eq!(*e.downcast::<T>().unwrap(), "owned string".to_string());
 810             }
 811             Ok(()) => panic!()
 812         }
 813     }
 814
 815     #[test]
 816     fn test_try_panic_message_any() {
 817         match thread::spawn(move|| {
 818             panic!(box 413u16 as Box<Any + Send>);
 819         }).join() {
 820             Err(e) => {
 821                 type T = Box<Any + Send>;
 822                 assert!(e.is::<T>());
 823                 let any = e.downcast::<T>().unwrap();
 824                 assert!(any.is::<u16>());
 825                 assert_eq!(*any.downcast::<u16>().unwrap(), 413);
 826             }
 827             Ok(()) => panic!()
 828         }
 829     }
 830
 831     #[test]
 832     fn test_try_panic_message_unit_struct() {
 833         struct Juju;
 834
 835         match thread::spawn(move|| {
 836             panic!(Juju)
 837         }).join() {
 838             Err(ref e) if e.is::<Juju>() => {}
 839             Err(_) | Ok(()) => panic!()
 840         }
 841     }
 842
 843     #[test]
 844     fn test_park_timeout_unpark_before() {
 845         for _ in 0..10 {
 846             thread::current().unpark();
 847             thread::park_timeout_ms(u32::MAX);
 848         }
 849     }
 850
 851     #[test]
 852     fn test_park_timeout_unpark_not_called() {
 853         for _ in 0..10 {
 854             thread::park_timeout_ms(10);
 855         }
 856     }
 857
 858     #[test]
 859     fn test_park_timeout_unpark_called_other_thread() {
 860         for _ in 0..10 {
 861             let th = thread::current();
 862
 863             let _guard = thread::spawn(move || {
 864                 super::sleep_ms(50);
 865                 th.unpark();
 866             });
 867
 868             thread::park_timeout_ms(u32::MAX);
 869         }
 870     }
 871
 872     #[test]
 873     fn sleep_ms_smoke() {
 874         thread::sleep_ms(2);
 875     }
 876
 877     // NOTE: the corresponding test for stderr is in run-pass/thread-stderr, due
 878     // to the test harness apparently interfering with stderr configuration.
 879 }