# Struct crossbeam::Scope [−] [src]

    pub struct Scope<'a> {
        // some fields omitted
    }

## Methods

### `impl<'a> Scope<'a>`

#### `fn defer<F>(&self, f: F) where F: FnOnce() + 'a`

Schedule code to be executed when exiting the scope.

This is akin to having a destructor on the stack, except that it is guaranteed to be run.

#### `fn spawn<F, T>(&self, f: F) -> ScopedJoinHandle<T> where F: FnOnce() -> T + Send + 'a, T: Send + 'a`

Create a scoped thread.

`spawn` is similar to the `spawn` function in Rust's standard library. The difference is that this thread is scoped, meaning that it's guaranteed to terminate before the current stack frame goes away, allowing you to reference the parent stack frame directly. This is ensured by having the parent thread join on the child thread before the scope exits.

# Examples

A basic scoped thread:

    crossbeam::scope(|scope| {
        scope.spawn(|| {
            println!("Hello from a scoped thread!");
        });
    });

When writing concurrent Rust programs, you'll sometimes see a pattern like this, using `std::thread::spawn`:

    let array = [1, 2, 3];
    let mut guards = vec![];

    for i in &array {
        let guard = std::thread::spawn(move || {
            println!("element: {}", i);
        });

        guards.push(guard);
    }

    for guard in guards {
        guard.join().unwrap();
    }

The basic pattern is:

1. Iterate over some collection.
2. Spin up a thread to operate on each part of the collection.
3. Join all the threads.

However, this code actually gives an error:

    error: `array` does not live long enough
    for i in &array {
              ^~~~~
    in expansion of for loop expansion
    note: expansion site
    note: reference must be valid for the static lifetime...
    note: ...but borrowed value is only valid for the block suffix following statement 0 at ...
        let array = [1, 2, 3];
        let mut guards = vec![];

        for i in &array {
            let guard = std::thread::spawn(move || {
                println!("element: {}", i);
    ...
    error: aborting due to previous error

Because `std::thread::spawn` doesn't know about this scope, it requires a `'static` lifetime. One way of giving it a proper lifetime is to use an `Arc`:

    use std::sync::Arc;

    let array = Arc::new([1, 2, 3]);
    let mut guards = vec![];

    for i in (0..array.len()) {
        let a = array.clone();

        let guard = std::thread::spawn(move || {
            println!("element: {}", a[i]);
        });

        guards.push(guard);
    }

    for guard in guards {
        guard.join().unwrap();
    }

But this introduces unnecessary allocation, as `Arc<T>` puts its data on the heap, and we also end up dealing with reference counts. We know that we're joining the threads before our function returns, so just taking a reference should be safe. Rust can't know that, though.

Enter scoped threads. Here's our original example, using `spawn` from crossbeam rather than from `std::thread`:

    let array = [1, 2, 3];

    crossbeam::scope(|scope| {
        for i in &array {
            scope.spawn(move || {
                println!("element: {}", i);
            });
        }
    });

Much more straightforward.

## Trait Implementations

### `impl<'a> Drop for Scope<'a>`

#### `fn drop(&mut self)`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)