Trait RcuRef

pub unsafe trait RcuRef<F> {
    type Output;

    // Required method
    unsafe fn take_ownership_unchecked(self) -> Self::Output;

    // Provided methods
    fn take_ownership<C>(self, context: &mut C) -> Self::Output
       where Self: Sized,
             C: RcuContext<Flavor = F> { ... }
    fn defer_cleanup<C>(self, context: &mut C)
       where Self: Sized,
             C: RcuDeferContext<Flavor = F> { ... }
    fn call_cleanup<C>(self, context: &C)
       where Self: Sized + Send + 'static,
             C: RcuReadContext<Flavor = F> + 'static { ... }
    fn safe_cleanup(self)
       where Self: Sized + Send + 'static,
             F: RcuFlavor { ... }
}

This trait defines a RCU reference that can be owned after a RCU grace period.

Safety

• The underlying reference must be cleaned up upon dropping (see below).
• There may be immutable borrows to the underlying reference.
• There must not be any mutable borrows to the underlying reference.

Dropping

An RcuRef should always cleanup when Drop::drop is executed by taking ownership and dropping the underlying value.

• We cannot call RcuContext::rcu_synchronize since we can’t be sure that a RCU read lock is currently held or not¹.

Because an RcuRef can be sent to any thread, we cannot guarantee that a thread executing Drop::drop is properly registered.

• We cannot call RcuDeferContext::rcu_defer since we can’t enforce that the thread is registered with the RCU defer mecanisms¹.
• We cannot call RcuReadContext::rcu_call since we can’t enforce that the thread is registered with the RCU read mecanisms².

The only way to keep the safety guarantees of this crate is to use the custom cleanup thread through RcuRef::safe_cleanup. It is similar to the built-in RcuReadContext::rcu_call, except it doesn’t expect the calling thread to be registered with RCU in any way.

The downside is that it is most likely worst than RcuReadContext::rcu_call in every way. If it is a performance problem, the owner of an RcuRef can alway use RcuRef::defer_cleanup and RcuRef::call_cleanup before Drop::drop is called.

---

1. Unless your RcuRef has a mutable borrow of an RcuContext. ↩

2. Unless your RcuRef has an immutable borrow of an RcuContext. ↩

Required Associated Types

type Output

The output type after taking ownership.

Required Methods

unsafe fn take_ownership_unchecked(self) -> Self::Output

Take ownership of the reference.

Safety

You must wait for the grace period before taking ownership.

Provided Methods

fn take_ownership<C>(self, context: &mut C) -> Self::Output

where Self: Sized, C: RcuContext<Flavor = F>,

Take ownership of the reference.

fn defer_cleanup<C>(self, context: &mut C)

where Self: Sized, C: RcuDeferContext<Flavor = F>,

Configure a cleanup callback to be called after the grace period.

Note

The function might internally call RcuContext::rcu_synchronize and block.

The callback is guaranteed to be executed on the current thread.

fn call_cleanup<C>(self, context: &C)

where Self: Sized + Send + 'static, C: RcuReadContext<Flavor = F> + 'static,

Configure a cleanup callback to be called after the grace period.

Note

The function will internally call RcuReadContext::rcu_read_lock.

The reference must implement Send since the cleanup will be executed in an helper thread.

fn safe_cleanup(self)

where Self: Sized + Send + 'static, F: RcuFlavor,

Implementations on Foreign Types

impl<T0, T1, F> RcuRef<F> for (T0, T1)

where T0: RcuRef<F>, T1: RcuRef<F>,

Safety

It is the responsability of the underlying types to be safe.

type Output = (<T0 as RcuRef<F>>::Output, <T1 as RcuRef<F>>::Output)

unsafe fn take_ownership_unchecked(self) -> Self::Output

impl<T0, T1, T2, F> RcuRef<F> for (T0, T1, T2)

where T0: RcuRef<F>, T1: RcuRef<F>, T2: RcuRef<F>,

Safety

It is the responsability of the underlying types to be safe.

type Output = (<T0 as RcuRef<F>>::Output, <T1 as RcuRef<F>>::Output, <T2 as RcuRef<F>>::Output)

unsafe fn take_ownership_unchecked(self) -> Self::Output

impl<T0, T1, T2, T3, F> RcuRef<F> for (T0, T1, T2, T3)

where T0: RcuRef<F>, T1: RcuRef<F>, T2: RcuRef<F>, T3: RcuRef<F>,

Safety

It is the responsability of the underlying types to be safe.

type Output = (<T0 as RcuRef<F>>::Output, <T1 as RcuRef<F>>::Output, <T2 as RcuRef<F>>::Output, <T3 as RcuRef<F>>::Output)

unsafe fn take_ownership_unchecked(self) -> Self::Output

impl<T0, T1, T2, T3, T4, F> RcuRef<F> for (T0, T1, T2, T3, T4)

where T0: RcuRef<F>, T1: RcuRef<F>, T2: RcuRef<F>, T3: RcuRef<F>, T4: RcuRef<F>,

Safety

It is the responsability of the underlying types to be safe.

type Output = (<T0 as RcuRef<F>>::Output, <T1 as RcuRef<F>>::Output, <T2 as RcuRef<F>>::Output, <T3 as RcuRef<F>>::Output, <T4 as RcuRef<F>>::Output)

unsafe fn take_ownership_unchecked(self) -> Self::Output

impl<T0, T1, T2, T3, T4, T5, F> RcuRef<F> for (T0, T1, T2, T3, T4, T5)

where T0: RcuRef<F>, T1: RcuRef<F>, T2: RcuRef<F>, T3: RcuRef<F>, T4: RcuRef<F>, T5: RcuRef<F>,

Safety

It is the responsability of the underlying types to be safe.

type Output = (<T0 as RcuRef<F>>::Output, <T1 as RcuRef<F>>::Output, <T2 as RcuRef<F>>::Output, <T3 as RcuRef<F>>::Output, <T4 as RcuRef<F>>::Output, <T5 as RcuRef<F>>::Output)

unsafe fn take_ownership_unchecked(self) -> Self::Output

impl<T0, T1, T2, T3, T4, T5, T6, F> RcuRef<F> for (T0, T1, T2, T3, T4, T5, T6)

where T0: RcuRef<F>, T1: RcuRef<F>, T2: RcuRef<F>, T3: RcuRef<F>, T4: RcuRef<F>, T5: RcuRef<F>, T6: RcuRef<F>,

Safety

It is the responsability of the underlying types to be safe.

type Output = (<T0 as RcuRef<F>>::Output, <T1 as RcuRef<F>>::Output, <T2 as RcuRef<F>>::Output, <T3 as RcuRef<F>>::Output, <T4 as RcuRef<F>>::Output, <T5 as RcuRef<F>>::Output, <T6 as RcuRef<F>>::Output)

unsafe fn take_ownership_unchecked(self) -> Self::Output

impl<T, F> RcuRef<F> for Option<T>

where T: RcuRef<F>,

Safety

It is the responsability of the underlying type to be safe.

type Output = Option<<T as RcuRef<F>>::Output>

unsafe fn take_ownership_unchecked(self) -> Self::Output

impl<T, F> RcuRef<F> for Vec<T>

where T: RcuRef<F>,

Safety

It is the responsability of the underlying type to be safe.

type Output = Vec<<T as RcuRef<F>>::Output>

unsafe fn take_ownership_unchecked(self) -> Self::Output

Implementors

impl<K, V, F> RcuRef<F> for urcu::collections::hashmap::Ref<K, V, F>

where K: Send, V: Send, F: RcuFlavor,

Safety

The memory reclamation upon dropping is properly deferred after the RCU grace period.

type Output = RefOwned<K, V>

impl<T, F> RcuRef<F> for urcu::collections::boxed::Ref<T, F>

where T: Send, F: RcuFlavor,

Safety

• The reference is cleaned up upon dropping.
• The reference does not expose mutable borrows.

type Output = Box<T>

impl<T, F> RcuRef<F> for RcuRefBox<T, F>

where T: Send, F: RcuFlavor,

Safety

• The underlying reference is cleaned up upon dropping.
• There may be immutable borrows to the underlying reference.
• There cannot be mutable borrows to the underlying reference.

type Output = BoxRefOwned<T>