Skip to content

Commit

Permalink
Rollup merge of rust-lang#41982 - gamazeps:thread-yield-now, r=Guilla…
Browse files Browse the repository at this point in the history
…umeGomez

[Doc] Explain why `thread::yield_now` could be used.

Part of rust-lang#29378.

r? @steveklabnik
  • Loading branch information
Mark-Simulacrum authored May 16, 2017
2 parents 7a9cf92 + a9cb094 commit efe285e
Showing 1 changed file with 23 additions and 0 deletions.
23 changes: 23 additions & 0 deletions src/libstd/thread/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -468,13 +468,36 @@ pub fn current() -> Thread {

/// Cooperatively gives up a timeslice to the OS scheduler.
///
/// This is used when the programmer knows that the thread will have nothing
/// to do for some time, and thus avoid wasting computing time.
///
/// For example when polling on a resource, it is common to check that it is
/// available, and if not to yield in order to avoid busy waiting.
///
/// Thus the pattern of `yield`ing after a failed poll is rather common when
/// implementing low-level shared resources or synchronization primitives.
///
/// However programmers will usualy prefer to use, [`channel`]s, [`Condvar`]s,
/// [`Mutex`]es or [`join`] for their synchronisation routines, as they avoid
/// thinking about thread schedulling.
///
/// Note that [`channel`]s for example are implemented using this primitive.
/// Indeed when you call `send` or `recv`, which are blocking, they will yield
/// if the channel is not available.
///
/// # Examples
///
/// ```
/// use std::thread;
///
/// thread::yield_now();
/// ```
///
/// [`channel`]: ../../std/sync/mpsc/index.html
/// [`spawn`]: ../../std/thread/fn.spawn.html
/// [`join`]: ../../std/thread/struct.JoinHandle.html#method.join
/// [`Mutex`]: ../../std/sync/struct.Mutex.html
/// [`Condvar`]: ../../std/sync/struct.Condvar.html
#[stable(feature = "rust1", since = "1.0.0")]
pub fn yield_now() {
imp::Thread::yield_now()
Expand Down

0 comments on commit efe285e

Please sign in to comment.