Struct kernel::revocable::AsyncRevocable

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

An object that can become inaccessible at runtime.

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

Unlike Revocable, AsyncRevocable does not wait for concurrent users of the wrapped object to finish before AsyncRevocable::revoke completes – thus the async qualifier. This has the advantage of not requiring RCU locks or waits of any kind.

Examples

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

fn add_two(v: &AsyncRevocable<Example>) -> Option<u32> {
    let guard = v.try_access()?;
    Some(guard.a + guard.b)
}

let v = AsyncRevocable::new(Example { a: 10, b: 20 });
assert_eq!(add_two(&v), Some(30));
v.revoke();
assert_eq!(add_two(&v), None);

Example where revocation happens while there is a user:

use core::sync::atomic::{AtomicBool, Ordering};

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

static DROPPED: AtomicBool = AtomicBool::new(false);

impl Drop for Example {
    fn drop(&mut self) {
        DROPPED.store(true, Ordering::Relaxed);
    }
}

fn add_two(v: &AsyncRevocable<Example>) -> Option<u32> {
    let guard = v.try_access()?;
    Some(guard.a + guard.b)
}

let v = AsyncRevocable::new(Example { a: 10, b: 20 });
assert_eq!(add_two(&v), Some(30));

let guard = v.try_access().unwrap();
assert!(!v.is_revoked());
assert!(!DROPPED.load(Ordering::Relaxed));
v.revoke();
assert!(!DROPPED.load(Ordering::Relaxed));
assert!(v.is_revoked());
assert!(v.try_access().is_none());
assert_eq!(guard.a + guard.b, 30);
drop(guard);
assert!(DROPPED.load(Ordering::Relaxed));

Implementations

impl<T> AsyncRevocable<T>

pub fn new(data: T) -> Self

Creates a new asynchronously revocable instance of the given data.

pub fn try_access(&self) -> Option<AsyncRevocableGuard<'_, T>>

Tries to access the [revocable] wrapped object.

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.

pub fn revoke(&self) -> bool

Revokes access to the protected object.

Returns true if access has been revoked, or false when the object has already been revoked by a previous call to AsyncRevocable::revoke.

This call is non-blocking, that is, no new users of the revocable object will be allowed, but potential current users are able to continue to use it and the thread won’t wait for them to finish. In such cases, the object will be dropped when the last user completes.

pub fn is_revoked(&self) -> bool

Returns whether access to the object has been revoked.

Trait Implementations

impl<T> Drop for AsyncRevocable<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Send> Send for AsyncRevocable<T>

impl<T: Sync + Send> Sync for AsyncRevocable<T>