Struct bones_lib::ecs::prelude::Ref

pub struct Ref<'a, T>
where T: ?Sized,
{ /* private fields */ }
Expand description

Wrapper for a borrowed AtomicCell that will released lock on drop.

This type can be dereferenced to &T.

Implements Borrow<T> and AsRef<T> for convenience.

Implements Debug, Display, PartialEq, PartialOrd and Hash by delegating to T.

Implementations§

§

impl<'a, T> Ref<'a, T>
where T: ?Sized,

pub fn new(r: &'a T) -> Ref<'a, T>

Wraps external reference into Ref.

This function’s purpose is to satisfy type requirements where Ref is required but reference does not live in AtomicCell.

§Examples
use atomicell::Ref;

let r = Ref::new(&42);

pub fn with_borrow(r: &'a T, borrow: AtomicBorrow<'a>) -> Ref<'a, T>

Wraps external reference into Ref. And associates it with provided AtomicBorrow

This function is intended to be used by AtomicCell or other abstractions that use AtomicBorrow for locking.

§Examples
use core::sync::atomic::AtomicIsize;
use atomicell::{borrow::{AtomicBorrow, new_lock}, Ref};
let counter = new_lock();
let borrow = AtomicBorrow::try_new(&counter).unwrap();

let r = Ref::with_borrow(&42, borrow);
assert_eq!(*r, 42);

pub fn into_split(r: Ref<'a, T>) -> (NonNull<T>, AtomicBorrow<'a>)

Splits wrapper into two parts. One is reference to the value and the other is AtomicBorrow that guards it from being borrowed mutably.

§Safety

User must ensure NonNull is not dereferenced after AtomicBorrow is dropped.

Also, the NonNull<T> that is returned is still only valid for reads, not writes.

§Examples
use atomicell::{AtomicCell, Ref};

let cell = AtomicCell::new(42);
let r: Ref<'_, i32> = cell.borrow();

unsafe {
    let (r, borrow) = Ref::into_split(r);
    assert_eq!(*r.as_ref(), 42);

    assert!(cell.try_borrow().is_some(), "Must be able to borrow immutably");
    assert!(cell.try_borrow_mut().is_none(), "Must not be able to borrow mutably yet");
    drop(borrow);
    assert!(cell.try_borrow_mut().is_some(), "Must be able to borrow mutably now");
}

pub fn map<F, U>(r: Ref<'a, T>, f: F) -> Ref<'a, U>
where F: FnOnce(&T) -> &U, U: ?Sized,

Makes a new Ref for a component of the borrowed data.

The AtomicCell is already immutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::map(…). A method would interfere with methods of the same name on the contents of a AtomicCell used through Deref.

§Examples
use atomicell::{AtomicCell, Ref};

let c = AtomicCell::new((5, 'b'));
let b1: Ref<(u32, char)> = c.borrow();
let b2: Ref<u32> = Ref::map(b1, |t| &t.0);
assert_eq!(*b2, 5)

pub fn filter_map<U, F>(r: Ref<'a, T>, f: F) -> Result<Ref<'a, U>, Ref<'a, T>>
where F: FnOnce(&T) -> Option<&U>, U: ?Sized,

Makes a new Ref for an optional component of the borrowed data. The original guard is returned as an Err(..) if the closure returns None.

The AtomicCell is already mutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::filter_map(…). A method would interfere with methods of the same name on the contents of a AtomicCell used through Deref.

§Examples
use atomicell::{AtomicCell, Ref};
let c = AtomicCell::new(vec![1, 2, 3]);
let b1: Ref<Vec<u32>> = c.borrow();
let b2: Result<Ref<u32>, _> = Ref::filter_map(b1, |v| v.get(1));
assert_eq!(*b2.unwrap(), 2);

pub fn map_split<U, V, F>(r: Ref<'a, T>, f: F) -> (Ref<'a, U>, Ref<'a, V>)
where F: FnOnce(&T) -> (&U, &V), U: ?Sized, V: ?Sized,

Splits a Ref into multiple Refs for different components of the borrowed data.

The AtomicCell is already immutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::map_split(...). A method would interfere with methods of the same name on the contents of a AtomicCell used through Deref.

§Examples
use atomicell::{Ref, AtomicCell};

let cell = AtomicCell::new([1, 2, 3, 4]);
let borrow = cell.borrow();
let (begin, end) = Ref::map_split(borrow, |slice| slice.split_at(2));
assert_eq!(*begin, [1, 2]);
assert_eq!(*end, [3, 4]);

pub fn leak(r: Ref<'a, T>) -> &'a T

Convert into a reference to the underlying data.

The underlying AtomicCell can never be mutably borrowed from again and will always appear already immutably borrowed. It is not a good idea to leak more than a constant number of references. The AtomicCell can be immutably borrowed again if only a smaller number of leaks have occurred in total.

This is an associated function that needs to be used as Ref::leak(…). A method would interfere with methods of the same name on the contents of a AtomicCell used through Deref.

§Examples
use atomicell::{AtomicCell, Ref};
let cell = AtomicCell::new(0);

let value = Ref::leak(cell.borrow());
assert_eq!(*value, 0);

assert!(cell.try_borrow().is_some());
assert!(cell.try_borrow_mut().is_none());

pub fn as_ref<U>(r: Ref<'a, T>) -> Ref<'a, U>
where T: AsRef<U>, U: ?Sized,

Converts reference and returns result wrapped in the Ref.

The AtomicCell is already immutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::map_split(...). A method would interfere with methods of the same name on the contents of a AtomicCell used through Deref.

§Examples
use atomicell::{AtomicCell, Ref};

let c = AtomicCell::new(String::from("hello"));
let b1: Ref<String> = c.borrow();
let b2: Ref<str> = Ref::as_ref(b1);
assert_eq!(*b2, *"hello")

pub fn as_deref(r: Ref<'a, T>) -> Ref<'a, <T as Deref>::Target>
where T: Deref,

Dereferences and returns result wrapped in the Ref.

The AtomicCell is already immutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::map_split(...). A method would interfere with methods of the same name on the contents of a AtomicCell used through Deref.

§Examples
use atomicell::{AtomicCell, Ref};

let c = AtomicCell::new(String::from("hello"));
let b1: Ref<String> = c.borrow();
let b2: Ref<str> = Ref::as_deref(b1);
assert_eq!(*b2, *"hello")
§

impl<'a, T> Ref<'a, Option<T>>

pub fn transpose(r: Ref<'a, Option<T>>) -> Option<Ref<'a, T>>

Transposes a Ref of an Option into an Option of a Ref. Releases shared lock of AtomicCell if the value is None.

The AtomicCell is already immutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::map_split(...). A method would interfere with methods of the same name on the contents of a AtomicCell used through Deref.

§Examples
use atomicell::{AtomicCell, Ref};

let c = AtomicCell::new(Some(5));
let b1: Ref<Option<i32>> = c.borrow();
let b2: Option<Ref<i32>> = Ref::transpose(b1);
assert!(b2.is_some());

let c = AtomicCell::new(None);
let b1: Ref<Option<i32>> = c.borrow();
let b2: Option<Ref<i32>> = Ref::transpose(b1);
assert!(b2.is_none());
assert!(c.try_borrow_mut().is_some());
§

impl<'a, T> Ref<'a, [T]>

pub fn slice<R>(r: Ref<'a, [T]>, range: R) -> Ref<'a, [T]>
where R: RangeBounds<usize>,

Makes a new Ref for a sub-slice of the borrowed slice.

The AtomicCell is already immutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::map(…). A method would interfere with methods of the same name on the contents of a AtomicCell used through Deref.

§Examples
use atomicell::{AtomicCell, Ref};

let c: &AtomicCell<[i32]> = &AtomicCell::new([1, 2, 3, 4, 5]);
let b1: Ref<[i32]> = c.borrow();
let b2: Ref<[i32]> = Ref::slice(b1, 2..4);
assert_eq!(*b2, [3, 4])

Trait Implementations§

§

impl<'a, T, U> AsRef<U> for Ref<'a, T>
where T: AsRef<U> + ?Sized,

§

fn as_ref(&self) -> &U

Converts this type into a shared reference of the (usually inferred) input type.
§

impl<'a, T> Borrow<T> for Ref<'a, T>

§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
§

impl<'a, T> Clone for Ref<'a, T>
where T: ?Sized,

§

fn clone(&self) -> Ref<'a, T>

Returns a copy of the value. Read more
§

fn clone_from(&mut self, source: &Ref<'a, T>)

Performs copy-assignment from source. Read more
§

impl<'a, T> Debug for Ref<'a, T>
where T: Debug + ?Sized,

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
§

impl<'a, T> Deref for Ref<'a, T>
where T: ?Sized,

§

type Target = T

The resulting type after dereferencing.
§

fn deref(&self) -> &T

Dereferences the value.
§

impl<'a, T> Display for Ref<'a, T>
where T: Display + ?Sized,

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
§

impl<'a, T> Hash for Ref<'a, T>
where T: Hash + ?Sized,

§

fn hash<H>(&self, state: &mut H)
where H: Hasher,

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
§

impl<'a, T, U> PartialEq<U> for Ref<'a, T>
where T: PartialEq<U> + ?Sized,

§

fn eq(&self, other: &U) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
§

impl<'a, T, U> PartialOrd<U> for Ref<'a, T>
where T: PartialOrd<U> + ?Sized,

§

fn partial_cmp(&self, other: &U) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
source§

impl<'a> QueryItem for &'a Ref<'a, UntypedComponentStore>

§

type Iter = UntypedComponentBitsetIterator<'a>

The type of iterator this query item creates
source§

fn apply_bitset(&self, bitset: &mut BitSetVec)

Modify the iteration bitset
source§

fn get_single_with_bitset( self, bitset: Rc<BitSetVec>, ) -> Result<<<&'a Ref<'a, UntypedComponentStore> as QueryItem>::Iter as Iterator>::Item, QuerySingleError>

Return the item that matches the query within the given bitset if there is exactly one entity that matches this query item.
source§

fn iter_with_bitset( self, bitset: Rc<BitSetVec>, ) -> <&'a Ref<'a, UntypedComponentStore> as QueryItem>::Iter

Return an iterator over the provided bitset.
source§

impl<'a, 'q, T> QueryItem for &'a Ref<'q, ComponentStore<T>>
where T: HasSchema,

§

type Iter = Map<UntypedComponentBitsetIterator<'a>, for<'b> fn(_: SchemaRef<'b>) -> &'b T>

The type of iterator this query item creates
source§

fn apply_bitset(&self, bitset: &mut BitSetVec)

Modify the iteration bitset
source§

fn get_single_with_bitset( self, bitset: Rc<BitSetVec>, ) -> Result<<<&'a Ref<'q, ComponentStore<T>> as QueryItem>::Iter as Iterator>::Item, QuerySingleError>

Return the item that matches the query within the given bitset if there is exactly one entity that matches this query item.
source§

fn iter_with_bitset( self, bitset: Rc<BitSetVec>, ) -> <&'a Ref<'q, ComponentStore<T>> as QueryItem>::Iter

Return an iterator over the provided bitset.
source§

impl<'a, T> SystemParam for Ref<'a, ComponentStore<T>>
where T: HasSchema,

§

type State = Arc<AtomicCell<ComponentStore<T>>>

The intermediate state for the parameter, that may be extracted from the world.
§

type Param<'p> = Ref<'p, ComponentStore<T>>

The type of the parameter, ranging over the lifetime of the intermediate state. Read more
source§

fn get_state( world: &World, ) -> <Ref<'a, ComponentStore<T>> as SystemParam>::State

This is called to produce the intermediate state of the system parameter. Read more
source§

fn borrow<'s>( _world: &'s World, state: &'s mut <Ref<'a, ComponentStore<T>> as SystemParam>::State, ) -> <Ref<'a, ComponentStore<T>> as SystemParam>::Param<'s>

This is used create an instance of the system parame, possibly borrowed from the intermediate parameter state.
§

impl<'b, T> Send for Ref<'b, T>
where T: 'b + ?Sized, &'a T: for<'a> Send,

§

impl<'b, T> Sync for Ref<'b, T>
where T: 'b + ?Sized, &'a T: for<'a> Sync,

Auto Trait Implementations§

§

impl<'a, T> Freeze for Ref<'a, T>
where T: ?Sized,

§

impl<'a, T> RefUnwindSafe for Ref<'a, T>
where T: RefUnwindSafe + ?Sized,

§

impl<'a, T> Unpin for Ref<'a, T>
where T: ?Sized,

§

impl<'a, T> UnwindSafe for Ref<'a, T>
where T: RefUnwindSafe + ?Sized,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> RawClone for T
where T: Clone,

source§

unsafe fn raw_clone(src: *const c_void, dst: *mut c_void)

Write the default value of the type to the pointer. Read more
source§

fn raw_clone_cb() -> Unsafe<&'static (dyn Fn(*const c_void, *mut c_void) + Send + Sync)>

Get a callback suitable for [SchemaData].
source§

impl<T> RawDrop for T

source§

unsafe fn raw_drop(ptr: *mut c_void)

Write the default value of the type to the pointer. Read more
source§

fn raw_drop_cb() -> Unsafe<&'static (dyn Fn(*mut c_void) + Send + Sync)>

Get a callback suitable for [SchemaData].
source§

impl<T> RawHash for T
where T: Hash,

source§

unsafe fn raw_hash(ptr: *const c_void) -> u64

Get the hash of the type. Read more
source§

fn raw_hash_cb() -> Unsafe<&'static (dyn Fn(*const c_void) -> u64 + Send + Sync)>

Get a callback suitable for [SchemaData].
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V