Struct conc::Guard

#[must_use = "You are getting a `conc::Guard` without using it, which means it is potentially unnecessary overhead. Consider replacing the method with something that doesn\'t return a guard."]
pub struct Guard<T: 'static + ?Sized> { /* fields omitted */ }

A RAII guard protecting from garbage collection.

This "guards" the held pointer against garbage collection. First when all guards of said pointer is gone (the data is unreachable), it can be collected.

Methods

impl<T: ?Sized> Guard<T>

fn try_new<F, E>(ptr: F) -> Result<Guard<T>, E> where
    F: FnOnce() -> Result<&'static T, E>, 

Failably create a new guard.

This has all the same restrictions and properties as Guard::new() (please read its documentation before using), with the exception of being failable.

This means that the closure can return and error and abort the creation of the guard.

fn new<F>(ptr: F) -> Guard<T> where
    F: FnOnce() -> &'static T, 

Create a new guard.

Because it must ensure that no garbage collection happens until the pointer is read, it takes a closure, which is evaluated to the pointer the guard will hold. During the span of this closure, garbage collection is ensured to not happen, making it safe to read from an atomic pointer without risking the ABA problem.

Important!

It is very important that this closure does not contain anything which might cause a garbage collection, as garbage collecting inside this closure will cause the current thread to be blocked infinitely (because the hazard is blocked) and stop all other threads from collecting garbage, leading to memory leaks in those — unless it is compiled in debug mode, in which case it will likely panic.

fn maybe_new<F>(ptr: F) -> Option<Guard<T>> where
    F: FnOnce() -> Option<&'static T>, 

Conditionally create a new guard.

This acts try_new, but with Option instead of Result.

fn map<U: ?Sized, F>(self, f: F) -> Guard<U> where
    F: FnOnce(&T) -> &U, 

Map the pointer to another.

This allows one to map a pointer to a pointer e.g. to an object referenced by the old. It is very convenient for creating APIs without the need for creating a wrapper type.

fn try_map<U: ?Sized, E, F>(self, f: F) -> Result<Guard<U>, E> where
    F: FnOnce(&T) -> Result<&U, E>, 

(Failably) map the pointer to another.

This corresponds to map, but when the closure returns Err, this does as well. In other words, the closure can fail.

fn maybe_map<U: ?Sized, F>(self, f: F) -> Option<Guard<U>> where
    F: FnOnce(&T) -> Option<&U>, 

Conditionally map the pointer to another.

This acts try_map, but with Option instead of Result.

fn as_ptr(&self) -> *const T

Get the raw pointer of this guard.

Trait Implementations

impl<T: Debug + 'static + ?Sized> Debug for Guard<T>

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

Formats the value using the given formatter.

impl<T: ?Sized> Deref for Guard<T>

type Target = T

The resulting type after dereferencing

fn deref(&self) -> &T

The method called to dereference a value