Struct maskerad_object_pool::ArcHandle

pub struct ArcHandle<T: Recyclable>(pub Arc<RwLock<T>>);

A wrapper around a Arc pointer to a RwLock<Poolable> object.

The Poolable object is wrapped by a RwLock, allowing read/write access to the object from multiple threads.

This RwLock is wrapped by an Arc, an atomic reference-counted pointer, allowing the object to be shared between threads.

This wrapper allows a custom Drop implementation: when an ArcHandle is dropped, the contained Poolable object is reinitialized if its strong reference count is equal to two. If it is the case, the object is reinitialized, the inner Arc is dropped and the strong reference count decrease to 1, meaning that the only structure holding a reference is the ArcPool itself.

Methods

impl<T: Recyclable> ArcHandle<T>

fn read(&self) -> LockResult<RwLockReadGuard<T>>

Locks this rwlock with shared read access, blocking the current thread until it can be acquired.

Refer to the RwLock::read method for more information.

Errors

This function will return an error if the RwLock is poisoned. An RwLock is poisoned whenever a writer panics while holding an exclusive lock. The failure will occur immediately after the lock has been acquired.

Panics

This function might panic when called if the lock is already held by the current thread.

Example

use maskerad_object_pool::ArcPool;
let pool = ArcPool::with_capacity(10, || {
    Monster::default()
});

let monster = pool.create_strict()?;
assert_eq!(monster.read().unwrap().level, 10);

fn try_read(&self) -> TryLockResult<RwLockReadGuard<T>>

Attempts to acquire this rwlock with shared read access.

Refer to the RwLock::try_read method for more information.

Errors

This function will return an error if the RwLock is poisoned. An RwLock is poisoned whenever a writer panics while holding an exclusive lock. An error will only be returned if the lock would have otherwise been acquired.

Example

use maskerad_object_pool::ArcPool;
let pool = ArcPool::with_capacity(10, || {
    Monster::default()
});

let monster = pool.create_strict()?;
// The RwLock has not been poisoned yet, there is no writers.
assert!(monster.try_read().is_ok());

fn write(&self) -> LockResult<RwLockWriteGuard<T>>

Locks this rwlock with exclusive write access, blocking the current thread until it can be acquired.

Refer to the RwLock::write method for more information.

Errors

This function will return an error if the RwLock is poisoned. An RwLock is poisoned whenever a writer panics while holding an exclusive lock. An error will be returned when the lock is acquired.

Panics

This function might panic when called if the lock is already held by the current thread.

Example

use maskerad_object_pool::ArcPool;
let pool = ArcPool::with_capacity(10, || {
    Monster::default()
});

let monster = pool.create_strict()?;
monster.write().unwrap().level_up();
assert_eq!(monster.read().unwrap().level, 11);

fn try_write(&self) -> TryLockResult<RwLockWriteGuard<T>>

Attempts to lock this rwlock with exclusive write access.

Refer to the RwLock::try_write method for more information.

Errors

This function will return an error if the RwLock is poisoned. An RwLock is poisoned whenever a writer panics while holding an exclusive lock. An error will only be returned if the lock would have otherwise been acquired.

Example

use maskerad_object_pool::ArcPool;
let pool = ArcPool::with_capacity(10, || {
    Monster::default()
});

let monster = pool.create_strict()?;
let reader = monster.read().unwrap();

// With an RwLock, there can be at any given time, either:
// - multiple readers
// - a single writer
// There is already a reader, try_write will return an error.
assert!(monster.try_write().is_err());

fn is_poisoned(&self) -> bool

Determines whether the lock is poisoned.

Refer to the RwLock::is_poisoned method for more information.

Trait Implementations

impl<T: Debug + Recyclable> Debug for ArcHandle<T>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: Recyclable> AsRef<Arc<RwLock<T>>> for ArcHandle<T>

fn as_ref(&self) -> &Arc<RwLock<T>>

Performs the conversion.

impl<T: Recyclable> Drop for ArcHandle<T>

fn drop(&mut self)

This Drop implementation allow us to reinitialize the Poolable object if the strong reference count of the inner Arc is equal to 2.

If it is the case, T is reinitialized, the inner Arc is dropped and the strong reference count is decreased to 1, meaning that the only structure holding a reference is the ArcPool itself.

impl<T: Recyclable> Clone for ArcHandle<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.