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.
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.
13 //! ## The threading model
15 //! An executing Rust program consists of a collection of native OS threads,
16 //! each with their own stack and local state.
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).
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
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).
40 //! ## The `Thread` type
42 //! Threads are represented via the `Thread` type, which you can
43 //! get in one of two ways:
45 //! * By spawning a new thread, e.g. using the `thread::spawn` function.
46 //! * By requesting the current thread, using the `thread::current` function.
48 //! Threads can be named, and provide some built-in support for low-level
49 //! synchronization (described below).
51 //! The `thread::current()` function is available even for threads not spawned
52 //! by the APIs of this module.
54 //! ## Spawning a thread
56 //! A new thread can be spawned using the `thread::spawn` function:
61 //! thread::spawn(move || {
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.
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:
77 //! let child = thread::spawn(move || {
81 //! let res = child.join();
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.
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:
96 //! # #![feature(scoped)]
99 //! let guard = thread::scoped(move || {
100 //! // some work here
103 //! // do some other work in the meantime
104 //! let output = guard.join();
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.
115 //! ## Configuring threads
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:
121 //! # #![allow(unused_must_use)]
124 //! thread::Builder::new().name("child1".to_string()).spawn(move || {
125 //! println!("Hello, world!");
129 //! ## Blocking support: park and unpark
131 //! Every thread is equipped with some basic low-level blocking support, via the
132 //! `park` and `unpark` functions.
134 //! Conceptually, each `Thread` handle has an associated token, which is
135 //! initially not present:
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.
143 //! * The `unpark()` method on a `Thread` atomically makes the token available
144 //! if it wasn't already.
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.
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.
155 //! The motivation for this design is twofold:
157 //! * It avoids the need to allocate mutexes and condvars when building new
158 //! synchronization primitives; the threads already provide basic blocking/signaling.
160 //! * It can be implemented very efficiently on many platforms.
162 //! ## Thread-local storage
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.
169 //! At a high level, this module provides two variants of storage:
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).
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
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.
188 #![stable(feature = "rust1", since = "1.0.0")]
192 use alloc
::boxed
::FnBox
;
194 use cell
::UnsafeCell
;
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}
;
204 ////////////////////////////////////////////////////////////////////////////////
205 // Thread-local storage
206 ////////////////////////////////////////////////////////////////////////////////
208 #[macro_use] mod local;
209 #[macro_use] mod scoped_tls;
211 #[stable(feature = "rust1", since = "1.0.0")]
212 pub use self::local
::{LocalKey, LocalKeyState}
;
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
;
219 #[doc(hidden)] pub use self::local::__KeyInner as __LocalKeyInner;
220 #[doc(hidden)] pub use self::scoped_tls::__KeyInner as __ScopedKeyInner;
222 ////////////////////////////////////////////////////////////////////////////////
224 ////////////////////////////////////////////////////////////////////////////////
226 /// Thread configuration. Provides detailed control over the properties
227 /// and behavior of new threads.
228 #[stable(feature = "rust1", since = "1.0.0")]
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>,
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
{
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
);
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
);
262 /// Spawns a new thread, and returns a join handle for it.
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.
271 /// Unlike the `spawn` free function, this method yields an
272 /// `io::Result` to capture any failure to create the thread at
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
279 self.spawn_inner(Box
::new(f
)).map(JoinHandle
)
283 /// Spawns a new child thread that must be joined within a given
284 /// scope, and returns a `JoinGuard`.
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.
295 /// Unlike the `scoped` free function, this method yields an
296 /// `io::Result` to capture any failure to create the thread at
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 \
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
307 self.spawn_inner(Box
::new(f
)).map(|inner
| {
308 JoinGuard { inner: inner, _marker: PhantomData }
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;
320 let stack_size
= stack_size
.unwrap_or(rt
::min_stack());
322 let my_thread
= Thread
::new(name
);
323 let their_thread
= my_thread
.clone();
325 let my_packet
= Arc
::new(UnsafeCell
::new(None
));
326 let their_packet
= my_packet
.clone();
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).
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
);
341 if let Some(name
) = their_thread
.name() {
342 imp
::Thread
::set_name(name
);
344 thread_info
::set(imp
::guard
::current(), their_thread
);
346 let mut output
= None
;
348 let ptr
= &mut output
;
349 unwind
::try(move || *ptr
= Some(f()))
351 *their_packet
.get() = Some(try_result
.map(|()| {
357 native
: Some(try
!(imp
::Thread
::new(stack_size
, Box
::new(main
)))),
359 packet
: Packet(my_packet
),
364 ////////////////////////////////////////////////////////////////////////////////
366 ////////////////////////////////////////////////////////////////////////////////
368 /// Spawns a new thread, returning a `JoinHandle` for it.
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
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
386 Builder
::new().spawn(f
).unwrap()
389 /// Spawns a new *scoped* thread, returning a `JoinGuard` for it.
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.
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 \
408 pub fn scoped
<'a
, T
, F
>(f
: F
) -> JoinGuard
<'a
, T
> where
409 T
: Send
+ 'a
, F
: FnOnce() -> T
, F
: Send
+ 'a
411 Builder
::new().scoped(f
).unwrap()
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")
422 /// Cooperatively gives up a timeslice to the OS scheduler.
423 #[stable(feature = "rust1", since = "1.0.0")]
425 imp
::Thread
::yield_now()
428 /// Determines whether the current thread is unwinding because of panic.
430 #[stable(feature = "rust1", since = "1.0.0")]
431 pub fn panicking() -> bool
{
435 /// Invokes a closure, capturing the cause of panic if one occurs.
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.
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.
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.
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).
459 /// # #![feature(catch_panic)]
462 /// let result = thread::catch_panic(|| {
463 /// println!("hello!");
465 /// assert!(result.is_ok());
467 /// let result = thread::catch_panic(|| {
468 /// panic!("oh no!");
470 /// assert!(result.is_err());
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
476 let mut result
= None
;
478 let result
= &mut result
;
479 try
!(::rt
::unwind
::try(move || *result
= Some(f())))
484 /// Puts the current thread to sleep for the specified amount of time.
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
490 #[stable(feature = "rust1", since = "1.0.0")]
491 pub fn sleep_ms(ms
: u32) {
492 sleep(Duration
::from_millis(ms
as u64))
495 /// Puts the current thread to sleep for the specified amount of time.
497 /// The thread may sleep longer than the duration specified due to scheduling
498 /// specifics or platform-dependent functionality.
500 /// # Platform behavior
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
)
511 /// Blocks unless or until the current thread's token is made available (may wake spuriously).
513 /// See the module doc for more detail.
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")]
522 let thread
= current();
523 let mut guard
= thread
.inner
.lock
.lock().unwrap();
525 guard
= thread
.inner
.cvar
.wait(guard
).unwrap();
530 /// Blocks unless or until the current thread's token is made available or
531 /// the specified duration has been reached (may wake spuriously).
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.
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))
545 /// Blocks unless or until the current thread's token is made available or
546 /// the specified duration has been reached (may wake spuriously).
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.
554 /// See the module doc for more detail.
556 /// # Platform behavior
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();
565 let (g
, _
) = thread
.inner
.cvar
.wait_timeout(guard
, dur
).unwrap();
571 ////////////////////////////////////////////////////////////////////////////////
573 ////////////////////////////////////////////////////////////////////////////////
575 /// The internal representation of a `Thread` handle
577 name
: Option
<String
>,
578 lock
: Mutex
<bool
>, // true when there is a buffered unpark
583 #[stable(feature = "rust1", since = "1.0.0")]
584 /// A handle to a thread.
590 // Used only internally to construct a thread object without spawning
591 fn new(name
: Option
<String
>) -> Thread
{
593 inner
: Arc
::new(Inner
{
595 lock
: Mutex
::new(false),
596 cvar
: Condvar
::new(),
601 /// Atomically makes the handle's token available if it is not already.
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();
609 self.inner
.cvar
.notify_one();
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
)
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
)
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) }
632 ////////////////////////////////////////////////////////////////////////////////
633 // JoinHandle and JoinGuard
634 ////////////////////////////////////////////////////////////////////////////////
636 /// Indicates the manner in which a thread exited.
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>>;
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).
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
>>>>);
656 unsafe impl<T
: Send
> Send
for Packet
<T
> {}
657 unsafe impl<T
: Sync
> Sync
for Packet
<T
> {}
659 /// Inner representation for JoinHandle and JoinGuard
660 struct JoinInner
<T
> {
661 native
: Option
<imp
::Thread
>,
666 impl<T
> JoinInner
<T
> {
667 fn join(&mut self) -> Result
<T
> {
668 self.native
.take().unwrap().join();
670 (*self.packet
.0.get()).take().unwrap()
675 /// An owned permission to join on a thread (block on its termination).
677 /// Unlike a `JoinGuard`, a `JoinHandle` *detaches* the child thread
678 /// when it is dropped, rather than automatically joining on drop.
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
683 #[stable(feature = "rust1", since = "1.0.0")]
684 pub struct JoinHandle
<T
>(JoinInner
<T
>);
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
{
693 /// Waits for the associated thread to finish.
695 /// If the child thread panics, `Err` is returned with the parameter given
697 #[stable(feature = "rust1", since = "1.0.0")]
698 pub fn join(mut self) -> Result
<T
> {
703 /// An RAII-style guard that will block until thread termination when dropped.
705 /// The type `T` is the return type for the thread's main function.
707 /// Joining on drop is necessary to ensure memory safety when stack
708 /// data is shared between a parent and child thread.
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
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
> {
718 _marker
: PhantomData
<&'a T
>,
721 #[stable(feature = "rust1", since = "1.0.0")]
722 unsafe impl<'a
, T
: Send
+ 'a
> Sync
for JoinGuard
<'a
, T
> {}
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
{
731 /// Waits for the associated thread to finish, returning the result of the
732 /// thread's calculation.
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() {
741 Err(_
) => panic
!("child thread {:?} panicked", self.thread()),
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
> {
750 if self.inner
.native
.is_some() && self.inner
.join().is_err() {
751 panic
!("child thread {:?} panicked", self.thread());
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
>();
763 ////////////////////////////////////////////////////////////////////////////////
765 ////////////////////////////////////////////////////////////////////////////////
772 use sync
::mpsc
::{channel, Sender}
;
774 use super::{Builder}
;
780 // !!! These tests are dangerous. If something is buggy, they will hang, !!!
781 // !!! instead of exiting cleanly. This might wedge the buildbots. !!!
784 fn test_unnamed_thread() {
785 thread
::spawn(move|| {
786 assert
!(thread
::current().name().is_none());
787 }).join().ok().unwrap();
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());
798 fn test_run_basic() {
799 let (tx
, rx
) = channel();
800 thread
::spawn(move|| {
801 tx
.send(()).unwrap();
807 fn test_join_success() {
808 assert
!(thread
::scoped(move|| -> String
{
809 "Success!".to_string()
810 }).join() == "Success!");
814 fn test_join_panic() {
815 match thread
::spawn(move|| {
818 result
::Result
::Err(_
) => (),
819 result
::Result
::Ok(()) => panic
!()
824 fn test_scoped_success() {
825 let res
= thread
::scoped(move|| -> String
{
826 "Success!".to_string()
828 assert
!(res
== "Success!");
833 fn test_scoped_panic() {
834 thread
::scoped(|| panic
!()).join();
839 fn test_scoped_implicit_panic() {
840 let _
= thread
::scoped(|| panic
!());
844 fn test_spawn_sched() {
847 let (tx
, rx
) = channel();
849 fn f(i
: i32, tx
: Sender
<()>) {
851 thread
::spawn(move|| {
853 tx
.send(()).unwrap();
865 fn test_spawn_sched_childs_on_default_sched() {
866 let (tx
, rx
) = channel();
868 thread
::spawn(move|| {
869 thread
::spawn(move|| {
870 tx
.send(()).unwrap();
877 fn avoid_copying_the_body
<F
>(spawnfn
: F
) where F
: FnOnce(Thunk
<'
static>) {
878 let (tx
, rx
) = channel();
880 let x
: Box
<_
> = box 1;
881 let x_in_parent
= (&*x
) as *const i32 as usize;
883 spawnfn(Box
::new(move|| {
884 let x_in_child
= (&*x
) as *const i32 as usize;
885 tx
.send(x_in_child
).unwrap();
888 let x_in_child
= rx
.recv().unwrap();
889 assert_eq
!(x_in_parent
, x_in_child
);
893 fn test_avoid_copying_the_body_spawn() {
894 avoid_copying_the_body(|v
| {
895 thread
::spawn(move || v());
900 fn test_avoid_copying_the_body_thread_spawn() {
901 avoid_copying_the_body(|f
| {
902 thread
::spawn(move|| {
909 fn test_avoid_copying_the_body_join() {
910 avoid_copying_the_body(|f
| {
911 let _
= thread
::spawn(move|| {
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|| {
927 thread
::spawn(move|| child_no(x
+1)());
931 thread
::spawn(|| child_no(0)());
935 fn test_simple_newsched_spawn() {
936 thread
::spawn(move || {}
);
940 fn test_try_panic_message_static_str() {
941 match thread
::spawn(move|| {
942 panic
!("static string");
945 type T
= &'
static str;
946 assert
!(e
.is
::<T
>());
947 assert_eq
!(*e
.downcast
::<T
>().unwrap(), "static string");
954 fn test_try_panic_message_owned_str() {
955 match thread
::spawn(move|| {
956 panic
!("owned string".to_string());
960 assert
!(e
.is
::<T
>());
961 assert_eq
!(*e
.downcast
::<T
>().unwrap(), "owned string".to_string());
968 fn test_try_panic_message_any() {
969 match thread
::spawn(move|| {
970 panic
!(box 413u16 as Box
<Any
+ Send
>);
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);
984 fn test_try_panic_message_unit_struct() {
987 match thread
::spawn(move|| {
990 Err(ref e
) if e
.is
::<Juju
>() => {}
991 Err(_
) | Ok(()) => panic
!()
996 fn test_park_timeout_unpark_before() {
998 thread
::current().unpark();
999 thread
::park_timeout_ms(u32::MAX
);
1004 fn test_park_timeout_unpark_not_called() {
1006 thread
::park_timeout_ms(10);
1011 fn test_park_timeout_unpark_called_other_thread() {
1013 let th
= thread
::current();
1015 let _guard
= thread
::spawn(move || {
1016 super::sleep_ms(50);
1020 thread
::park_timeout_ms(u32::MAX
);
1025 fn sleep_ms_smoke() {
1026 thread
::sleep_ms(2);
1029 // NOTE: the corresponding test for stderr is in run-pass/thread-stderr, due
1030 // to the test harness apparently interfering with stderr configuration.