# [−][src]Struct crossbeam_epoch::Shared

    pub struct Shared<'g, T: 'g> { /* fields omitted */ }

A pointer to an object protected by the epoch GC.

The pointer is valid for use only during the lifetime `'g`.

The pointer must be properly aligned. Since it is aligned, a tag can be stored into the unused least significant bits of the address.

## Methods

### `impl<'g, T> Shared<'g, T>`[src]

#### `pub fn null() -> Shared<'g, T>`[src]

Returns a new null pointer.

# Examples

    use crossbeam_epoch::Shared;

    let p = Shared::<i32>::null();
    assert!(p.is_null());

#### `pub fn is_null(&self) -> bool`[src]

Returns `true` if the pointer is null.

# Examples

    use crossbeam_epoch::{self as epoch, Atomic, Owned};
    use std::sync::atomic::Ordering::SeqCst;

    let a = Atomic::null();
    let guard = &epoch::pin();
    assert!(a.load(SeqCst, guard).is_null());
    a.store(Owned::new(1234), SeqCst);
    assert!(!a.load(SeqCst, guard).is_null());

#### `pub fn as_raw(&self) -> *const T`[src]

Converts the pointer to a raw pointer (without the tag).

# Examples

    use crossbeam_epoch::{self as epoch, Atomic, Owned};
    use std::sync::atomic::Ordering::SeqCst;

    let o = Owned::new(1234);
    let raw = &*o as *const _;
    let a = Atomic::from(o);

    let guard = &epoch::pin();
    let p = a.load(SeqCst, guard);
    assert_eq!(p.as_raw(), raw);

####
ⓘImportant traits for &'_ mut W

### Important traits for &'_ mut W

`impl<'_, W> Write for &'_ mut W where
W: Write + ?Sized, impl<'_, R> Read for &'_ mut R where
R: Read + ?Sized, impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
`pub unsafe fn deref(&self) -> &'g T`[src]

Dereferences the pointer.

Returns a reference to the pointee that is valid during the lifetime `'g`.

# Safety

Dereferencing a pointer is unsafe because it could be pointing to invalid memory.

Another concern is the possiblity of data races due to lack of proper synchronization. For example, consider the following scenario:

1. A thread creates a new object: `a.store(Owned::new(10), Relaxed)`
2. Another thread reads it: `*a.load(Relaxed, guard).as_ref().unwrap()`

The problem is that relaxed orderings don't synchronize initialization of the object with the read from the second thread. This is a data race. A possible solution would be to use `Release` and `Acquire` orderings.

# Examples

    use crossbeam_epoch::{self as epoch, Atomic};
    use std::sync::atomic::Ordering::SeqCst;

    let a = Atomic::new(1234);
    let guard = &epoch::pin();
    let p = a.load(SeqCst, guard);
    unsafe {
        assert_eq!(p.deref(), &1234);
    }

####
ⓘImportant traits for &'_ mut W

### Important traits for &'_ mut W

`impl<'_, W> Write for &'_ mut W where
W: Write + ?Sized, impl<'_, R> Read for &'_ mut R where
R: Read + ?Sized, impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
`pub unsafe fn deref_mut(&mut self) -> &'g mut T`[src]

Dereferences the pointer.

Returns a mutable reference to the pointee that is valid during the lifetime `'g`.

# Safety

- There is no guarantee that there are no more threads attempting to read/write from/to the actual object at the same time.

  The user must know that there are no concurrent accesses towards the object itself.

- Other than the above, all safety concerns of `deref()` applies here.

# Examples

    use crossbeam_epoch::{self as epoch, Atomic};
    use std::sync::atomic::Ordering::SeqCst;

    let a = Atomic::new(vec![1, 2, 3, 4]);
    let guard = &epoch::pin();

    let mut p = a.load(SeqCst, guard);
    unsafe {
        assert!(!p.is_null());
        let b = p.deref_mut();
        assert_eq!(b, &vec![1, 2, 3, 4]);
        b.push(5);
        assert_eq!(b, &vec![1, 2, 3, 4, 5]);
    }

    let p = a.load(SeqCst, guard);
    unsafe {
        assert_eq!(p.deref(), &vec![1, 2, 3, 4, 5]);
    }

#### `pub unsafe fn as_ref(&self) -> Option<&'g T>`[src]

Converts the pointer to a reference.

Returns `None` if the pointer is null, or else a reference to the object wrapped in `Some`.

# Safety

Dereferencing a pointer is unsafe because it could be pointing to invalid memory.

Another concern is the possiblity of data races due to lack of proper synchronization. For example, consider the following scenario:

1. A thread creates a new object: `a.store(Owned::new(10), Relaxed)`
2. Another thread reads it: `*a.load(Relaxed, guard).as_ref().unwrap()`

The problem is that relaxed orderings don't synchronize initialization of the object with the read from the second thread. This is a data race. A possible solution would be to use `Release` and `Acquire` orderings.

# Examples

    use crossbeam_epoch::{self as epoch, Atomic};
    use std::sync::atomic::Ordering::SeqCst;

    let a = Atomic::new(1234);
    let guard = &epoch::pin();
    let p = a.load(SeqCst, guard);
    unsafe {
        assert_eq!(p.as_ref(), Some(&1234));
    }

#### `pub unsafe fn into_owned(self) -> Owned<T>`[src]

Takes ownership of the pointee.

# Panics

Panics if this pointer is null, but only in debug mode.

# Safety

This method may be called only if the pointer is valid and nobody else is holding a reference to the same object.

# Examples

    use crossbeam_epoch::{self as epoch, Atomic};
    use std::sync::atomic::Ordering::SeqCst;

    let a = Atomic::new(1234);
    unsafe {
        let guard = &epoch::unprotected();
        let p = a.load(SeqCst, guard);
        drop(p.into_owned());
    }

#### `pub fn tag(&self) -> usize`[src]

Returns the tag stored within the pointer.

# Examples

    use crossbeam_epoch::{self as epoch, Atomic, Owned};
    use std::sync::atomic::Ordering::SeqCst;

    let a = Atomic::<u64>::from(Owned::new(0u64).with_tag(2));
    let guard = &epoch::pin();
    let p = a.load(SeqCst, guard);
    assert_eq!(p.tag(), 2);

#### `pub fn with_tag(&self, tag: usize) -> Shared<'g, T>`[src]

Returns the same pointer, but tagged with `tag`. `tag` is truncated to be fit into the unused bits of the pointer to `T`.

# Examples

    use crossbeam_epoch::{self as epoch, Atomic};
    use std::sync::atomic::Ordering::SeqCst;

    let a = Atomic::new(0u64);
    let guard = &epoch::pin();
    let p1 = a.load(SeqCst, guard);
    let p2 = p1.with_tag(2);

    assert_eq!(p1.tag(), 0);
    assert_eq!(p2.tag(), 2);
    assert_eq!(p1.as_raw(), p2.as_raw());

## Trait Implementations

### `impl<'g, T> Pointer<T> for Shared<'g, T>`[src]

#### `fn into_usize(self) -> usize`[src]

Returns the machine representation of the pointer.

#### `unsafe fn from_usize(data: usize) -> Self`[src]

Returns a new pointer pointing to the tagged pointer `data`.

### `impl<'g, T> Eq for Shared<'g, T>`[src]

### `impl<'g, T> Default for Shared<'g, T>`[src]

#### `fn default() -> Self`[src]

Returns the "default value" for a type. Read more

### `impl<'g, T> Clone for Shared<'g, T>`[src]

#### `fn clone(&self) -> Self`[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`1.0.0[src]

Performs copy-assignment from `source`. Read more

### `impl<'g, T> PartialOrd<Shared<'g, T>> for Shared<'g, T>`[src]

#### `fn partial_cmp(&self, other: &Self) -> Option<Ordering>`[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `#[must_use] fn lt(&self, other: &Rhs) -> bool` 1.0.0[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `#[must_use] fn le(&self, other: &Rhs) -> bool` 1.0.0[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `#[must_use] fn gt(&self, other: &Rhs) -> bool` 1.0.0[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `#[must_use] fn ge(&self, other: &Rhs) -> bool` 1.0.0[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl<'g, T> PartialEq<Shared<'g, T>> for Shared<'g, T>`[src]

#### `fn eq(&self, other: &Self) -> bool`[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

#### `#[must_use] fn ne(&self, other: &Rhs) -> bool` 1.0.0[src]

This method tests for `!=`.

### `impl<'g, T> Ord for Shared<'g, T>`[src]

#### `fn cmp(&self, other: &Self) -> Ordering`[src]

This method returns an `Ordering` between `self` and `other`. Read more

#### `fn max(self, other: Self) -> Self` 1.21.0[src]

Compares and returns the maximum of two values. Read more

#### `fn min(self, other: Self) -> Self` 1.21.0[src]

Compares and returns the minimum of two values. Read more

#### `fn clamp(self, min: Self, max: Self) -> Self`[src]

🔬 This is a nightly-only experimental API. (`clamp`)

Restrict a value to a certain interval. Read more

### `impl<'g, T> From<Shared<'g, T>> for Atomic<T>`[src]

#### `fn from(ptr: Shared<'g, T>) -> Self`[src]

Returns a new atomic pointer pointing to `ptr`.

# Examples

    use crossbeam_epoch::{Atomic, Shared};

    let a = Atomic::<i32>::from(Shared::<i32>::null());

### `impl<'g, T> From<*const T> for Shared<'g, T>`[src]

#### `fn from(raw: *const T) -> Self`[src]

Returns a new pointer pointing to `raw`.

# Panics

Panics if `raw` is not properly aligned.

# Examples

    use crossbeam_epoch::Shared;

    let p = unsafe { Shared::from(Box::into_raw(Box::new(1234)) as *const _) };
    assert!(!p.is_null());

### `impl<'g, T> Copy for Shared<'g, T>`[src]

### `impl<'g, T> Debug for Shared<'g, T>`[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`[src]

Formats the value using the given formatter. Read more

### `impl<'g, T> Pointer for Shared<'g, T>`[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`[src]

Formats the value using the given formatter.

## Auto Trait Implementations

### `impl<'g, T> !Send for Shared<'g, T>`

### `impl<'g, T> Unpin for Shared<'g, T>`

### `impl<'g, T> !Sync for Shared<'g, T>`

### `impl<'g, T> UnwindSafe for Shared<'g, T> where
T: RefUnwindSafe,`

### `impl<'g, T> RefUnwindSafe for Shared<'g, T> where
T: RefUnwindSafe,`

## Blanket Implementations

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `fn to_owned(&self) -> T`[src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `fn clone_into(&self, target: &mut T)`[src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into`)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `fn into(self) -> U`[src]

Performs the conversion.

### `impl<T> From<T> for T`[src]

#### `fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

####
ⓘImportant traits for &'_ mut W

### Important traits for &'_ mut W

`impl<'_, W> Write for &'_ mut W where
W: Write + ?Sized, impl<'_, R> Read for &'_ mut R where
R: Read + ?Sized, impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
`fn borrow_mut(&mut self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

####
ⓘImportant traits for &'_ mut W

### Important traits for &'_ mut W

`impl<'_, W> Write for &'_ mut W where
W: Write + ?Sized, impl<'_, R> Read for &'_ mut R where
R: Read + ?Sized, impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
`fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `fn type_id(&self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

# 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
`+`
  Expand all sections
`-`
  Collapse 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`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)