Struct Mutex

Source

pub struct Mutex<'this, 'handle, T>where
    'handle: 'this,
    T: Debug,
{ /* private fields */ }

Expand description

Represents a POSIX mutex which can be created by the MutexBuilder.

§Example

For a detailed builder example, see MutexBuilder.

use iceoryx2_bb_posix::mutex::*;
use core::time::Duration;

let handle = MutexHandle::<i32>::new();
let mutex = MutexBuilder::new().create(5, &handle)
    .expect("Failed to create mutex");

{
    let guard = mutex.lock().expect("failed to lock mutex");
    println!("current mutex value is: {}", *guard);
}

match mutex.try_lock().expect("failed to lock") {
    Some(mut guard) => *guard = 123, // set mutex value to 123
    None => println!("unable to acquire lock"),
};

match mutex.timed_lock(Duration::from_secs(1)).expect("failed to lock") {
    Some(guard) => println!("New mutex value is: {}", *guard),
    None => println!("Timeout occurred while trying to get lock.")
};

Implementations§

Source §

impl<'this, 'handle, T> Mutex<'this, 'handle, T>
where 'handle: 'this, T: Debug,

Source

pub unsafe fn from_handle( handle: &'handle MutexHandle<T>, ) -> Mutex<'this, 'handle, T>

Instantiates a Mutex from an already initialized MutexHandle. Useful for inter-process usage where the MutexHandle was created by MutexBuilder in another process.

§Safety

handle must have been successfully initialized by the MutexBuilder.

Source

pub fn lock( &'this self, ) -> Result<MutexGuard<'handle, T>, MutexLockError<'handle, T>>

Blocks until the ownership of the lock could be acquired. If it was successful it returns a MutexGuard to allow access to the underlying value. If the previously owning thread has died and MutexThreadTerminationBehavior::ReleaseWhenLocked was set it returns the error MutexLockError::LockAcquiredButOwnerDied which contains also the MutexGuard. The new owner now has the responsibility to either repair the underlying value of the mutex and call Mutex::make_consistent() when it is repaired or to undertake other measures when it is unrepairable.

Source

pub fn try_lock( &'this self, ) -> Result<Option<MutexGuard<'handle, T>>, MutexLockError<'handle, T>>

Tries to acquire the ownership of the lock. If it was successful it returns a MutexGuard packed inside an Option, if the lock is already owned by someone else it returns None. If the previously owning thread has died and MutexThreadTerminationBehavior::ReleaseWhenLocked was set it returns the error MutexLockError::LockAcquiredButOwnerDied which contains also the MutexGuard. The new owner now has the responsibility to either repair the underlying value of the mutex and call Mutex::make_consistent() when it is repaired or to undertake other measures when it is unrepairable.

Source

pub fn timed_lock( &'this self, duration: Duration, ) -> Result<Option<MutexGuard<'handle, T>>, MutexTimedLockError<'handle, T>>

Tries to acquire the ownership of the lock until the provided timeout has elapsed. If it was successful it returns a MutexGuard packed inside an Option, if the could not be acquired lock when the timeout passed it returns None. If the previously owning thread has died and MutexThreadTerminationBehavior::ReleaseWhenLocked was set it returns the error MutexTimedLockError::MutexLockError which contains also the MutexGuard. The new owner now has the responsibility to either repair the underlying value of the mutex and call Mutex::make_consistent() when it is repaired or to undertake other measures when it is unrepairable.

Source

pub fn make_consistent(&self)

If the previously owning thread has died and MutexThreadTerminationBehavior::ReleaseWhenLocked was set it returns the error MutexLockError::LockAcquiredButOwnerDied which contains also the MutexGuard. The new owner now has the responsibility to either repair the underlying value of the mutex and call Mutex::make_consistent() when it is repaired or to undertake other measures when it is unrepairable.