Struct more_sync::Carrier

pub struct Carrier<T> { /* private fields */ }

A Carrier that manages the lifetime of an instance of type T.

The carrier owns the instance (the target). References to the target can be obtained by calling the create_ref method. The references returned by the method will be valid as long as the reference is alive.

The carrier can be closed, after which no new references can be obtained. The carrier can also wait for all references it gave out to be dropped. The ownership of target will be returned to the caller after the wait is complete. The caller can then carry out clean-ups or any other type of work that requires an owned instance of type T.

use more_sync::Carrier;

// Create a carrier that holds a mutex.
let carrier = Carrier::new(std::sync::Mutex::new(7usize));

// Ask for a reference to the value held by the carrier.
let ref_one = carrier.create_ref().unwrap();
assert_eq!(*ref_one.lock().unwrap(), 7);

// Reference returned by Carrier can be sent to another thread.
std::thread::spawn(move || *ref_one.lock().unwrap() = 8usize);

// Close the carrier, no new references can be created.
carrier.close();
assert!(carrier.create_ref().is_none());

// Shutdown the carrier and wait for all references to be dropped.
// The value held by carrier is returned.
let mutex_value = carrier.wait();
// Destroy the mutex.
assert!(matches!(mutex_value.into_inner(), Ok(8usize)));

Implementations

impl<T> Carrier<T>

pub fn new(target: T) -> Self

Create a carrier that carries and owns target.

pub fn create_ref(&self) -> Option<CarrierRef<T>>

Creates a reference to the owned instance. Returns None if the carrier has been closed.

pub fn ref_count(&self) -> usize

Returns the number of outstanding references created by this carrier.

The returned value is obsolete as soon as this method returns. The count can change at any time.

pub fn close(&self)

Closes this carrier.

No new references can be created after the carrier is closed. A closed carrier cannot be re-opened again.

pub fn is_closed(&self) -> bool

Returns true if the carrier has been closed, false otherwise.

For the same carrier, once this method returns true it will never return false again.

pub fn wait(self) -> T

Blocks the current thread until all references created by this carrier are dropped.

wait() consumes the carrier and returns the owned instance. It returns immediately if all references have been dropped.

pub fn wait_timeout(self, timeout: Duration) -> Result<T, Self>

Like wait(), but waits for at most timeout.

Returns Ok and the owned instance if the wait was successful. Returns Err(self) if timed out. The reference count can change at any time. It is not guaranteed that the number of references is greater than zero when this method returns.

pub fn shutdown(self) -> T

Closes the carrier and waits for all references to be dropped.

A close() followed by a wait(). See the comments in those two methods.

pub fn shutdown_timeout(self, timeout: Duration) -> Result<T, Self>

Like shutdown(), but waits for at most timeout.

A close() followed by a wait_timeout(). See the comments in those two methods.

Trait Implementations

impl<T> AsRef<T> for Carrier<T>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Debug> Debug for Carrier<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Carrier<T>

fn default() -> Carrier<T>

Returns the “default value” for a type.

impl<T> Deref for Carrier<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.