Struct octopus::atomic::Pointer

pub struct Pointer<T>(_);

A pointer to an object stored in an AtomicPtr

Methods

impl<T> Pointer<T>

pub fn new(value: T) -> Pointer<T>

Allocates value on the heap and returns a new pointer pointing to it.

Examples

use octopus::atomic::Pointer;

let ptr = Pointer::new("foo");

pub fn null() -> Pointer<T>

Creates and returns a new null pointer.

Examples

use octopus::atomic::Pointer;

let ptr = Pointer::<&str>::null();

pub fn inner(self) -> *mut T

Returns the inner raw pointer.

Examples

use octopus::atomic::Pointer;
use std::ptr;

let ptr = Pointer::<&str>::null();

assert_eq!(ptr.inner(), ptr::null_mut());

pub fn is_null(self) -> bool

Returns true if the pointer is null.

Examples

use octopus::atomic::Pointer;

let ptr = Pointer::<&str>::null();

assert!(ptr.is_null());

pub unsafe fn as_ref<'a>(self) -> Option<&'a T>

Converts the pointer to a reference.

Returns None if the pointer is null, or else a reference to the object wrapped in Some. The returned reference is valid for the lifetime 'a.

Safety

Dereferencing a pointer is unsafe because it could be pointing to invalid memory.

Another concern is possibly of data races due to lack of proper synchronization. For example, consider the following scenario:

1. A thread creates a new object: a_ptr.store(10, Ordering::Relaxed)
2. Another thread reads it: *a.load(Relaxed).as_ref().unwrap()

The problem is that relaxed orderings don't synchronize initialization of the object with the read from the second thread. This is a data race. A possible solution would be to use Release and Acquire orderings.

Examples

use octopus::AtomicPtr;
use std::sync::atomic::Ordering;

let a_ptr = AtomicPtr::new("foo");
let ptr = a_ptr.load(Ordering::SeqCst);

unsafe {
    assert_eq!(ptr.as_ref(), Some(&"foo"));
}

pub unsafe fn deref<'a>(self) -> &'a T

Dereferences the pointer

Returns a reference to the pointer that is valid during the lifetime 'a.

Safety

Dereferencing a pointer is unsafe because it could be pointing to invalid memory.

Another concern is possibly of data races due to lack of proper synchronization. For example, consider the following scenario:

1. A thread creates a new object: a_ptr.store(10, Ordering::Relaxed)
2. Another thread reads it: *a.load(Relaxed).deref()

The problem is that relaxed orderings don't synchronize initialization of the object with the read from the second thread. This is a data race. A possible solution would be to use Release and Acquire orderings.

Examples

use octopus::AtomicPtr;
use std::sync::atomic::Ordering;

let a_ptr = AtomicPtr::new("foo");
let ptr = a_ptr.load(Ordering::SeqCst);

unsafe {
    assert_eq!(ptr.deref(), &"foo");
}

pub unsafe fn drop_inner(self)

Drops the pointer's inner value.

Warning: don't use this function unless you are sure that you won't use the pointer or any pointer pointing to the same data, ever.

Examples

use octopus::AtomicPtr;
use std::sync::atomic::Ordering;

let a_ptr = AtomicPtr::new("foo");
let ptr = a_ptr.load(Ordering::SeqCst);

unsafe {
    ptr.drop_inner();
}

Trait Implementations

impl<T: PartialEq> PartialEq for Pointer<T>

fn eq(&self, other: &Pointer<T>) -> bool

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

fn ne(&self, other: &Pointer<T>) -> bool

This method tests for !=.

impl<T: Eq> Eq for Pointer<T>

impl<T: Debug> Debug for Pointer<T>

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

Formats the value using the given formatter.

impl<T> From<*mut T> for Pointer<T>

fn from(ptr: *mut T) -> Self

Performs the conversion.

impl<T> From<T> for Pointer<T>

fn from(value: T) -> Self

Performs the conversion.

impl<T> From<Option<T>> for Pointer<T>

fn from(value: Option<T>) -> Self

Performs the conversion.

impl<T> Clone for Pointer<T>

fn clone(&self) -> Pointer<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Copy for Pointer<T>

impl<T> Deref for Pointer<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.