Struct kernel::sync::Revocable

pub struct Revocable<F: LockFactory, T> { /* private fields */ }

Revocable synchronisation primitive.

That is, it wraps synchronisation primitives so that access to their contents can be revoked at runtime, rendering them inacessible.

Once access is revoked and all concurrent users complete (i.e., all existing instances of RevocableGuard are dropped), the wrapped object is also dropped.

For better ergonomics, we advise the use of specialisations of this struct, for example, super::RevocableMutex and super::RevocableRwSemaphore. Callers that do not need to sleep while holding on to a guard should use crate::revocable::Revocable instead, which is more efficient as it uses RCU to keep objects alive.

Examples

struct Example {
    a: u32,
    b: u32,
}

fn add_two(v: &Revocable<Mutex<()>, Example>) -> Option<u32> {
    let mut guard = v.try_write()?;
    guard.a += 2;
    guard.b += 2;
    Some(guard.a + guard.b)
}

// SAFETY: We call `revocable_init` immediately below.
let mut v = unsafe { Revocable::<Mutex<()>, Example>::new(Example { a: 10, b: 20 }) };
// SAFETY: We never move out of `v`.
let pinned = unsafe { Pin::new_unchecked(&mut v) };
revocable_init!(pinned, "example::v");
assert_eq!(add_two(&v), Some(34));
v.revoke();
assert_eq!(add_two(&v), None);

Implementations

impl<F: LockFactory, T> Revocable<F, T>

pub unsafe fn new(data: T) -> Self

Creates a new revocable instance of the given lock.

Safety

The caller must call Revocable::init before using the revocable synch primitive.

impl<F: LockFactory, T> Revocable<F, T>where
    F::LockedType<Inner<T>>: Lock<Inner = Inner<T>>,

pub fn revoke(&self)

Revokes access to and drops the wrapped object.

Revocation and dropping happen after ongoing accessors complete.

pub fn try_write(&self) -> Option<RevocableGuard<'_, F, T, WriteLock>>

Tries to lock the [revocable] wrapped object in write (exclusive) mode.

Returns None if the object has been revoked and is therefore no longer accessible.

Returns a guard that gives access to the object otherwise; the object is guaranteed to remain accessible while the guard is alive. Callers are allowed to sleep while holding on to the returned guard.

impl<F: LockFactory, T> Revocable<F, T>where
    F::LockedType<Inner<T>>: Lock<ReadLock, Inner = Inner<T>>,

pub fn try_read(&self) -> Option<RevocableGuard<'_, F, T, ReadLock>>

Tries to lock the [revocable] wrapped object in read (shared) mode.

Returns None if the object has been revoked and is therefore no longer accessible.

Returns a guard that gives access to the object otherwise; the object is guaranteed to remain accessible while the guard is alive. Callers are allowed to sleep while holding on to the returned guard.

Trait Implementations

impl<F: LockFactory, T> NeedsLockClass for Revocable<F, T>where
    F::LockedType<Inner<T>>: NeedsLockClass,

fn init(
    self: Pin<&mut Self>,
    name: &'static CStr,
    key1: &'static LockClassKey,
    key2: &'static LockClassKey
)

Initialises the type instance so that it can be safely used.