core::marker::Sync - Rust
Description: API documentation for the Rust `Sync` trait in crate `core`.
Keywords: rust, rustlang, rust-lang, Sync

# Trait core::marker::Sync 1.0.0 [−] [src]

    #[lang = "sync"]
    pub unsafe trait Sync { }

Types for which it is safe to share references between threads.

This trait is automatically implemented when the compiler determines it's appropriate.

The precise definition is: a type `T` is `Sync` if `&T` is `Send`. In other words, if there is no possibility of undefined behavior (including data races) when passing `&T` references between threads.

As one would expect, primitive types like `u8` and `f64` are all `Sync`, and so are simple aggregate types containing them, like tuples, structs and enums. More examples of basic `Sync` types include "immutable" types like `&T`, and those with simple inherited mutability, such as `Box<T>`, `Vec<T>` and most other collection types. (Generic parameters need to be `Sync` for their container to be `Sync`.)

A somewhat surprising consequence of the definition is that `&mut T` is `Sync` (if `T` is `Sync`) even though it seems like that might provide unsynchronized mutation. The trick is that a mutable reference behind a shared reference (that is, `& &mut T`) becomes read-only, as if it were a `& &T`. Hence there is no risk of a data race.

Types that are not `Sync` are those that have "interior mutability" in a non-thread-safe form, such as `cell::Cell` and `cell::RefCell`. These types allow for mutation of their contents even through an immutable, shared reference. For example the `set` method on `Cell<T>` takes `&self`, so it requires only a shared reference `&Cell<T>`. The method performs no synchronization, thus `Cell` cannot be `Sync`.

Another example of a non-`Sync` type is the reference-counting pointer `rc::Rc`. Given any reference `&Rc<T>`, you can clone a new `Rc<T>`, modifying the reference counts in a non-atomic way.

For cases when one does need thread-safe interior mutability, Rust provides atomic data types, as well as explicit locking via `sync::Mutex` and `sync::RwLock`. These types ensure that any mutation cannot cause data races, hence the types are `Sync`. Likewise, `sync::Arc` provides a thread-safe analogue of `Rc`.

Any types with interior mutability must also use the `cell::UnsafeCell` wrapper around the value(s) which can be mutated through a shared reference. Failing to doing this is undefined behavior. For example, `transmute`-ing from `&T` to `&mut T` is invalid.

See the Nomicon for more details about `Sync`.

## Implementors

- [src]
  `impl<T: Sync + ?Sized> Sync for Unique<T>`
- [src]
  `impl<T: ?Sized> !Sync for Shared<T>`
- `impl<T: ?Sized> !Sync for *const T`
- `impl<T: ?Sized> !Sync for *mut T`
- [src]
  `impl Sync for AtomicBool`
- [src]
  `impl<T> Sync for AtomicPtr<T>`
- [src]
  `impl Sync for AtomicI8`
- [src]
  `impl Sync for AtomicU8`
- [src]
  `impl Sync for AtomicI16`
- [src]
  `impl Sync for AtomicU16`
- [src]
  `impl Sync for AtomicI32`
- [src]
  `impl Sync for AtomicU32`
- [src]
  `impl Sync for AtomicI64`
- [src]
  `impl Sync for AtomicU64`
- [src]
  `impl Sync for AtomicIsize`
- [src]
  `impl Sync for AtomicUsize`
- [src]
  `impl<T> !Sync for Cell<T>`
- [src]
  `impl<T: ?Sized> !Sync for RefCell<T>`
- [src]
  `impl<T: ?Sized> !Sync for UnsafeCell<T>`
- [src]
  `impl<'a, T: Sync> Sync for Iter<'a, T>`
- [src]
  `impl<'a, T: Sync> Sync for IterMut<'a, T>`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
↑
  Move up in search results
↓
  Move down in search results
↹
  Switch tab
⏎
  Go to active search result
+ / -
  Collapse/expand all sections

## 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`)