Struct rune::runtime::Shared

source ·

pub struct Shared<T: ?Sized> { /* private fields */ }

Expand description

A shared value.

Implementations§

source §

impl<T> Shared<T>

source

pub fn new(data: T) -> Result<Self>

Construct a new shared value.

source

pub fn debug(&self) -> SharedDebug<'_, T>

Return a debug formatter, that when printed will display detailed diagnostics of this shared type.

source

pub fn is_readable(&self) -> bool

Test if the value is sharable.

§Examples

use rune::runtime::Shared;

let shared = Shared::new(1u32)?;
assert!(shared.is_readable());

{
    let guard = shared.borrow_ref().unwrap();
    assert!(shared.is_readable()); // Note: still readable.
}

{
    let guard = shared.borrow_mut().unwrap();
    assert!(!shared.is_readable());
}

assert!(shared.is_readable());

§Taking inner value

use rune::runtime::Shared;

let shared = Shared::new(1u32)?;
let shared2 = shared.clone();
assert!(shared.is_readable());
shared.take().unwrap();
assert!(!shared2.is_readable());
assert!(shared2.take().is_err());

source

pub fn is_writable(&self) -> bool

Test if the value is exclusively accessible.

§Examples

use rune::runtime::Shared;

let shared = Shared::new(1u32)?;
assert!(shared.is_writable());

{
    let guard = shared.borrow_ref().unwrap();
    assert!(!shared.is_writable());
}

assert!(shared.is_writable());

source

pub fn take(self) -> Result<T, AccessError>

Take the interior value, if we have exlusive access to it and there are no other live exlusive or shared references.

A value that has been taken can no longer be accessed.

§Examples

use rune::runtime::Shared;

#[derive(Debug)]
struct Foo {
    counter: isize,
}

let a = Shared::new(Foo { counter: 0 })?;
let b = a.clone();

{
    let mut a = a.borrow_mut().unwrap();
    // NB: this is prevented since we have a live reference.
    assert!(b.take().is_err());
    a.counter += 1;
}

let a = a.take().unwrap();
assert_eq!(a.counter, 1);

source

pub fn into_ref(self) -> Result<Ref<T>, AccessError>

Get a reference to the interior value while checking for shared access that holds onto a reference count of the inner value.

This prevents other exclusive accesses from being performed while the guard returned from this function is live.

§Examples

use rune::runtime::Shared;

#[derive(Debug)]
struct Foo {
    counter: isize,
}

let a = Shared::new(Foo { counter: 0 })?;
let b = a.clone();

b.borrow_mut().unwrap().counter += 1;

{
    // Consumes `a`.
    let mut a = a.into_ref().unwrap();
    assert_eq!(a.counter, 1);
    assert!(b.borrow_mut().is_err());
}

let mut b = b.borrow_mut().unwrap();
b.counter += 1;
assert_eq!(b.counter, 2);

source

pub fn into_mut(self) -> Result<Mut<T>, AccessError>

Get a reference to the interior value while checking for exclusive access that holds onto a reference count of the inner value.

This prevents other exclusive and shared accesses from being performed while the guard returned from this function is live.

§Examples

use rune::runtime::Shared;

#[derive(Debug)]
struct Foo {
    counter: isize,
}

let a = Shared::new(Foo { counter: 0 })?;
let b = a.clone();

{
    // Consumes `a`.
    let mut a = a.into_mut().unwrap();
    a.counter += 1;

    assert!(b.borrow_ref().is_err());
}

assert_eq!(b.borrow_ref().unwrap().counter, 1);

source §

impl<T: ?Sized> Shared<T>

source

pub fn borrow_ref(&self) -> Result<BorrowRef<'_, T>, AccessError>

Get a reference to the interior value while checking for shared access.

This prevents other exclusive accesses from being performed while the guard returned from this function is live.

§Examples

use rune::runtime::Shared;

#[derive(Debug)]
struct Foo {
    counter: isize,
}

let a = Shared::new(Foo { counter: 0 })?;

a.borrow_mut().unwrap().counter += 1;

{
    let mut a_ref = a.borrow_ref().unwrap();
    assert_eq!(a_ref.counter, 1);
    assert!(a.borrow_mut().is_err());
    assert!(a.borrow_ref().is_ok());
}

let mut a = a.borrow_mut().unwrap();
a.counter += 1;
assert_eq!(a.counter, 2);

source

pub fn borrow_mut(&self) -> Result<BorrowMut<'_, T>, AccessError>

Get a reference to the interior value while checking for exclusive access.

This prevents other shared or exclusive accesses from being performed while the guard returned from this function is live.

§Examples

use rune::runtime::Shared;

#[derive(Debug)]
struct Foo {
    counter: isize,
}

let a = Shared::new(Foo { counter: 0 })?;

{
    let mut a_mut = a.borrow_mut().unwrap();
    a_mut.counter += 1;
    assert_eq!(a_mut.counter, 1);
    assert!(a.borrow_ref().is_err());
}

let a = a.borrow_ref().unwrap();
assert_eq!(a.counter, 1);

source §

impl Shared<AnyObj>

source

pub unsafe fn from_ref<T>(data: &T) -> Result<(Self, SharedPointerGuard)>
where T: Any,

Construct a Shared<Any> from a pointer, that will be “taken” once the returned guard is dropped.

§Safety

The reference must be valid for the duration of the guard.

§Examples

use rune::Any;
use rune::runtime::Shared;

#[derive(Any)]
struct Thing(u32);

let value = Thing(10u32);

unsafe {
    let (shared, guard) = Shared::from_ref(&value)?;
    assert!(shared.downcast_borrow_mut::<Thing>().is_err());
    assert_eq!(10u32, shared.downcast_borrow_ref::<Thing>().unwrap().0);

    drop(guard);

    assert!(shared.downcast_borrow_mut::<Thing>().is_err());
    assert!(shared.downcast_borrow_ref::<Thing>().is_err());
}

source

pub unsafe fn from_mut<T>(data: &mut T) -> Result<(Self, SharedPointerGuard)>
where T: Any,

Construct a Shared<Any> from a mutable pointer, that will be “taken” once the returned guard is dropped.

§Safety

The reference must be valid for the duration of the guard.

§Examples

use rune::Any;
use rune::runtime::Shared;

#[derive(Any)]
struct Thing(u32);

let mut value = Thing(10u32);

unsafe {
    let (shared, guard) = Shared::from_mut(&mut value)?;
    shared.downcast_borrow_mut::<Thing>().unwrap().0 = 20;

    assert_eq!(20u32, shared.downcast_borrow_mut::<Thing>().unwrap().0);
    assert_eq!(20u32, shared.downcast_borrow_ref::<Thing>().unwrap().0);

    drop(guard);

    assert!(shared.downcast_borrow_mut::<Thing>().is_err());
    assert!(shared.downcast_borrow_ref::<Thing>().is_err());
}

source

pub fn take_downcast<T>(self) -> Result<T, AccessError>
where T: Any,

Take the interior value, if we have exlusive access to it and there exist no other references.

source

pub fn downcast_borrow_ref<T>(&self) -> Result<BorrowRef<'_, T>, AccessError>
where T: Any,

Get an shared, downcasted reference to the contained value.

source

pub fn downcast_borrow_mut<T>(&self) -> Result<BorrowMut<'_, T>, AccessError>
where T: Any,

Get an exclusive, downcasted reference to the contained value.

source

pub fn downcast_into_ref<T>(self) -> Result<Ref<T>, AccessError>
where T: Any,

Get a shared value and downcast.

source

pub fn downcast_into_mut<T>(self) -> Result<Mut<T>, AccessError>
where T: Any,

Get an exclusive value and downcast.

Trait Implementations§

source §

impl<T: ?Sized> Clone for Shared<T>

source §

fn clone(&self) -> Self

Returns a copy of the value. Read more

1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

source §

impl<T> Debug for Shared<T>
where T: Debug + ?Sized,

source §

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

Formats the value using the given formatter. Read more

source §

impl<T: ?Sized> Drop for Shared<T>

source §

fn drop(&mut self)

Executes the destructor for this type. Read more

source §