Struct Asc

pub struct Asc<T: ?Sized, A = System>
where
    A: GlobalAlloc,
{ /* private fields */ }

A thread-safe strong reference-counting pointer. ‘Asc’ stands for ‘Atomic Strong Counted.’

It behaves like std::Sync::Arc except for that this treats only strong pointer; i.e. Asc gives up weak pointer for the performance.

The inherent methods of Asc are all associated funcitons, which means that you have to call them as e.g., Asc::get_mut(&mut value) instead of value.get_mut() . This avoids conflicts with methods of the inner type T .

Thread Safety

Unlike to Sc , Asc uses atomic operations for its reference counting. This means that it is thread-safe. The disadvangate is that atomic operations are more expensive than ordinary memory access.

Implementations

impl<T, A> Asc<T, A>

where A: GlobalAlloc,

pub fn new(val: T, alloc: A) -> Self

Creates a new instance.

Examples

use std::alloc::System;
use counting_pointer::Asc;

let _five = Asc::new(5, System);

pub fn from_slice_alloc(vals: &[T], alloc: A) -> Asc<[T], A>

where T: Clone,

Creates a new instance of Asc<[T], A> .

Examples

use std::alloc::System;
use counting_pointer::Asc;

let vals: [i32; 4] = [0, 1, 2, 3];
let sc = Asc::from_slice_alloc(&vals, System);
assert_eq!(&vals, &*sc);

impl<A> Asc<dyn Any, A>

where A: GlobalAlloc,

pub fn new_any<T>(val: T, alloc: A) -> Self

where T: Any,

Creates Asc<dyn Any> instance.

Examples

use std::alloc::System;
use counting_pointer::Asc;

let _five = Asc::new_any(5, System);

impl<T, A> Asc<T, A>

where A: GlobalAlloc,

pub fn to_any(this: Self) -> Asc<dyn Any, A>

where T: Any,

Consumes this, returning Asc<dyn Any, A>

Examples

use counting_pointer::Asc;

let sc: Asc<i32> = Asc::from(6);
let any = Asc::to_any(sc);

impl<T: ?Sized, A> Asc<T, A>

where A: GlobalAlloc,

pub fn as_ptr(this: &Self) -> *const T

Provides a raw pointer to the data.

The counts are not affected in any way and the Asc is not consumed. The pointer is valid for as long as another Asc instance is pointing to the address.

Examples

use counting_pointer::Asc;

let x: Asc<String> = Asc::from(String::from("Hello"));
let x_ptr = Asc::as_ptr(&x);
assert_eq!("Hello", unsafe { &*x_ptr });

pub fn count(this: &Self) -> usize

Returns the number of Asc pointers pointing to the same address.

Examples

use counting_pointer::Asc;

let five: Asc<i32> = Asc::from(5);
assert_eq!(1, Asc::count(&five));

let _also_five = five.clone();
assert_eq!(2, Asc::count(&five));
assert_eq!(2, Asc::count(&_also_five));

drop(five);
assert_eq!(1, Asc::count(&_also_five));

pub fn get_mut(this: &mut Self) -> Option<&mut T>

Returns a mutable reference into the given Asc , if no other Asc instance is pointing to the same address; otherwise returns None .

See also make_mut , which will clone the inner value when some other Asc instances are.

Examples

use counting_pointer::Asc;

let mut x: Asc<i32> = Asc::from(3);
assert_eq!(3, *x);

*Asc::get_mut(&mut x).unwrap() = 4;
assert_eq!(4, *x);

let _y = x.clone();
let n = Asc::get_mut(&mut x);
assert!(n.is_none());

pub fn ptr_eq(this: &Self, other: &Self) -> bool

Returns true if the two Asc instances point to the same address, or false .

Examples

use counting_pointer::Asc;

let five: Asc<i32> = Asc::from(5);
let same_five = five.clone();
let other_five: Asc<i32> = Asc::from(5);

assert_eq!(true, Asc::ptr_eq(&five, &same_five));
assert_eq!(false, Asc::ptr_eq(&five, &other_five));

pub fn into_raw_alloc(this: Self) -> (*const T, A)

Consumes this , returning the wrapped pointer and the allocator.

To avoid memory leak, the returned pointer must be converted back to an Asc using from_raw_alloc .

Using this function and from_raw_alloc , user can create an Asc<T: ?Sized> instance.

Examples

use counting_pointer::Asc;

let asc: Asc<String> = Asc::from("Foo".to_string());
let (ptr, alloc) = Asc::into_raw_alloc(asc);
let _asc: Asc<dyn AsRef<str>> = unsafe { Asc::from_raw_alloc(ptr, alloc) };

pub unsafe fn from_raw_alloc(ptr: *const T, alloc: A) -> Self

Constructs a new instance from a raw pointer and allocator.

The raw pointer must have been previously returned by a call to into_raw_alloc .

Using this function and into_raw_alloc , user can create an Asc<T: ?Sized> instance.

Safety

It may lead to memory unsafety to use improperly, even if the returned value will never be accessed.

Examples

use counting_pointer::Asc;

let asc: Asc<String> = Asc::from("Foo".to_string());
let (ptr, alloc) = Asc::into_raw_alloc(asc);
let _asc: Asc<dyn AsRef<str>> = unsafe { Asc::from_raw_alloc(ptr, alloc) };

impl<T: Clone, A> Asc<T, A>

where A: GlobalAlloc + Clone,

pub fn make_mut(this: &mut Self) -> &mut T

Makes a mutable reference into the given Asc .

If another Asc instance is pointing to the same address, make_mut will clone the inner value to a new allocation to ensure unique ownership.

See also get_mut , which will fail rather than cloning.

Examples

use counting_pointer::Asc;

let mut data: Asc<i32> = Asc::from(5);
assert_eq!(5, *data);

*Asc::make_mut(&mut data) += 1; // Won't clone anything.
assert_eq!(6, *data);

let mut data2 = data.clone();  // Won't clone the inner data.
*Asc::make_mut(&mut data) += 1; // Clones inner data.
assert_eq!(7, *data);
assert_eq!(6, *data2);

impl<A> Asc<dyn Any, A>

where A: GlobalAlloc,

pub fn downcast<T: Any>(self) -> Result<Asc<T, A>, Self>

Attempts to downcast the Asc<dyn Any, A> to a concrete type.

Examples

use std::alloc::System;
use std::any::Any;
use counting_pointer::Asc;

let sc = Asc::new_any(8 as i32, System);

let success = Asc::downcast::<i32>(sc.clone()).unwrap();
assert_eq!(8, *success);

let fail = Asc::downcast::<String>(sc.clone());
assert_eq!(true, fail.is_err());

Trait Implementations

impl<T: ?Sized, A> AsRef<T> for Asc<T, A>

where A: GlobalAlloc,

fn as_ref(&self) -> &T

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

impl<T: ?Sized, A> Borrow<T> for Asc<T, A>

where A: GlobalAlloc,

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: ?Sized, A> Clone for Asc<T, A>

where A: Clone + GlobalAlloc,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: ?Sized, A> Debug for Asc<T, A>

where A: Debug + GlobalAlloc,

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

Formats the value using the given formatter.

impl<T, A> Default for Asc<T, A>

where T: Default, A: Default + GlobalAlloc,

fn default() -> Self

Returns the “default value” for a type.

impl<T: ?Sized, A> Deref for Asc<T, A>

where A: GlobalAlloc,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, A> Display for Asc<T, A>

where T: Display + ?Sized, A: GlobalAlloc,

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

Formats the value using the given formatter.

impl<T: ?Sized, A> Drop for Asc<T, A>

where A: GlobalAlloc,

fn drop(&mut self)

Executes the destructor for this type.

impl<T, A> From<&[T]> for Asc<[T], A>

where T: Clone, A: Default + GlobalAlloc,

fn from(vals: &[T]) -> Self

Converts to this type from the input type.

impl<T, A> From<T> for Asc<T, A>

where A: Default + GlobalAlloc,

fn from(val: T) -> Self

Converts to this type from the input type.

impl<T, A> Hash for Asc<T, A>

where T: Hash + ?Sized, A: GlobalAlloc,

fn hash<H>(&self, hasher: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T, A> Ord for Asc<T, A>

where T: Ord + ?Sized, A: GlobalAlloc,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T, A> PartialEq for Asc<T, A>

where T: PartialEq + ?Sized, A: GlobalAlloc,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, A> PartialOrd for Asc<T, A>

where T: PartialOrd + ?Sized, A: GlobalAlloc,

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

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, A> Eq for Asc<T, A>

where T: Eq + ?Sized, A: GlobalAlloc,

impl<T, A> Send for Asc<T, A>

where T: Send + Sync + ?Sized, A: Send + GlobalAlloc,

impl<T, A> Sync for Asc<T, A>

where T: Send + Sync + ?Sized, A: Sync + GlobalAlloc,