Trait FragileTryContainer

pub trait FragileTryContainer<T: ?Sized> {
    type Ref<'a>: Deref<Target = T>
       where Self: 'a;
    type RefError;

    // Required methods
    fn new_container(t: T) -> Self
       where Self: Sized,
             T: Sized;
    fn into_inner(self) -> Option<T>
       where Self: Sized,
             T: Sized;
    fn try_get_ref(&self) -> Result<Self::Ref<'_>, Self::RefError>;
}

An abstraction over some container which owns a T and can provide immutable references to it, or be consumed to return the inner T (if T is Sized).

This is the base container trait, which places the fewest requirements on implementors.

Fragility: Potential Panics or Deadlocks

Unless a FragileTryContainer is known to also implement TryContainer, it should be treated as fragile.

Errors

The into_inner and try_get_ref methods may be able to fail, depending on the container; a container should clearly document the circumstances in which a None or Err variant may be returned.

Required Associated Types

type Ref<'a>: Deref<Target = T> where Self: 'a

An immutably borrowed value from the container.

May have a nontrivial Drop implementatation, as with the Ref type corresponding to RefCell.

type RefError

An error that might be returned by try_get_ref. This type should implement std::error::Error.

The canonical error to use when try_get_ref can never return an error is Infallible.

Required Methods

fn new_container(t: T) -> Self

where Self: Sized, T: Sized,

Create a new container that owns the provided T.

fn into_inner(self) -> Option<T>

where Self: Sized, T: Sized,

Attempt to retrieve the inner T from the container.

Note for implementors

Given a collection of containers that refer to the same inner T (as with several cloned Rc or Arc containers, or the trivial case of a single container like Box<T>), if into_inner is called on each of those containers, then an implementation should return Some(T) for exactly one of them, unless there is some useful reason for the implementation to do otherwise.

fn try_get_ref(&self) -> Result<Self::Ref<'_>, Self::RefError>

Attempt to immutably access the inner T.

There are no particular constraints imposed on implementations. In particular, depending on the container implementation:

• the function could be infallible,
• the function could panic or deadlock (see below),
• retrying the function in a loop might never succeed.

However, if the container implements FragileContainer<T>, then implementors should usually make try_get_ref infallible as well, unless there is some useful reason to not do so.

Fragility: Potential Panics or Deadlocks

Unless this FragileTryContainer is also a TryContainer, implementations are permitted to panic or deadlock if this method is called from a thread which already has a reference to the inner T of this container.

Read more about fragility.

Errors

Errors are implementation-defined, and should be documented by implementors.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T: ?Sized> FragileTryContainer<T> for Box<T>

fn into_inner(self) -> Option<T>

where T: Sized,

Infallibly get the inner T of this box.

fn try_get_ref(&self) -> Result<Self::Ref<'_>, Self::RefError>

Infallibly get immutable access to the inner T.

type Ref<'a> = &'a T where T: 'a

type RefError = Infallible

fn new_container(t: T) -> Self

where T: Sized,

impl<T: ?Sized> FragileTryContainer<T> for Rc<RefCell<T>>

fn into_inner(self) -> Option<T>

where T: Sized,

Attempt to retrieve the inner T from the container. Behaves identically to Rc::into_inner.

fn try_get_ref(&self) -> Result<Self::Ref<'_>, Self::RefError>

Get immutable access to the inner T.

Uses RefCell::borrow, so this container is fragile.

Panics

Panics if the contract of a fragile container is broken.

type Ref<'a> = Ref<'a, T> where T: 'a

type RefError = Infallible

fn new_container(t: T) -> Self

where T: Sized,

impl<T: ?Sized> FragileTryContainer<T> for Rc<T>

fn into_inner(self) -> Option<T>

where T: Sized,

Attempt to retrieve the inner T from the container.

Uses Rc::into_inner.

fn try_get_ref(&self) -> Result<Self::Ref<'_>, Self::RefError>

Infallibly get immutable access to the inner T.

type Ref<'a> = &'a T where T: 'a

type RefError = Infallible

fn new_container(t: T) -> Self

where T: Sized,

impl<T: ?Sized> FragileTryContainer<T> for Arc<Mutex<T>>

fn into_inner(self) -> Option<T>

where T: Sized,

Attempt to retrieve the inner T from the container. Behaves identically to Arc::into_inner.

Ignores any poison errors.

fn try_get_ref(&self) -> Result<Self::Ref<'_>, Self::RefError>

Get immutable access to the inner T.

Uses Mutex::lock, so this container is fragile.

Panics and Deadlocks

Panics if a poison error is encountered, which can only occur if another thread has already panicked.

May also panic or deadlock if the contract of a fragile container is broken.

type Ref<'a> = MutexGuard<'a, T> where T: 'a

type RefError = Infallible

fn new_container(t: T) -> Self

where T: Sized,

impl<T: ?Sized> FragileTryContainer<T> for Arc<RwLock<T>>

fn into_inner(self) -> Option<T>

where T: Sized,

Attempt to retrieve the inner T from the container. Behaves identically to Arc::into_inner.

Ignores any poison errors.

fn try_get_ref(&self) -> Result<Self::Ref<'_>, Self::RefError>

Get immutable access to the inner T.

Uses RwLock::read, so this container is fragile.

Panics and Deadlocks

Panics if a poison error is encountered, which can only occur if another thread has already panicked.

May also panic or deadlock if the contract of a fragile container is broken.

type Ref<'a> = RwLockReadGuard<'a, T> where T: 'a

type RefError = Infallible

fn new_container(t: T) -> Self

where T: Sized,

impl<T: ?Sized> FragileTryContainer<T> for Arc<ThreadCheckedMutex<T>>

fn into_inner(self) -> Option<T>

where T: Sized,

Attempt to retrieve the inner T from the container. Behaves identically to Arc::into_inner.

Ignores any poison errors.

fn try_get_ref(&self) -> Result<Self::Ref<'_>, Self::RefError>

Attempt to immutably access the inner T.

Errors

This function fails if and only if ThreadCheckedMutex::lock fails.

A poison error is not ignored, nor does it trigger a panic.

type Ref<'a> = ThreadCheckedMutexGuard<'a, T> where T: 'a

type RefError = ErasedLockError

fn new_container(t: T) -> Self

where T: Sized,

impl<T: ?Sized> FragileTryContainer<T> for Arc<T>

fn into_inner(self) -> Option<T>

where T: Sized,

Attempt to retrieve the inner T from the container.

Uses Arc::into_inner.

fn try_get_ref(&self) -> Result<Self::Ref<'_>, Self::RefError>

Infallibly get immutable access to the inner T.

type Ref<'a> = &'a T where T: 'a

type RefError = Infallible

fn new_container(t: T) -> Self

where T: Sized,

Implementors

impl<T: ?Sized> FragileTryContainer<T> for CheckedRcRefCell<T>

type Ref<'a> = Ref<'a, T> where T: 'a

type RefError = BorrowError

impl<T: ?Sized> FragileTryContainer<T> for T

type Ref<'a> = &'a T where T: 'a

type RefError = Infallible