[−][src]Trait crossbeam_epoch::atomic::Handle

pub unsafe trait Handle: DerefMut {
    const ALIGN: usize;

    fn into_usize(self) -> usize;

    unsafe fn from_usize(_: usize) -> Self;
}

Qualifies word-sized handle types that own T.

DST is very useful in the construction of concurrent data structures. Consider a node in a skiplist. It consists of: key, value, tower. The tower is an array of atomic pointers. To save a level of indirection, it is wise to lay out the entire tower inside the node. Since towers consist of variable number of pointers, skiplist nodes are dynamically sized.

Another example might be arrays backing hash-tables or Chase-Lev deques. They too are dynamically sized so it might make sense to lay out the length together with array's elements. B-tree nodes may likewise be dynamically sized.

However, Crossbeam had not supported DST because it used Box as the representation of atomic pointers. When T is a DST, Box<T> becomes a fat pointer (consisting of the underlying pointer and an integer representing the size), which doesn't support atomic operations (such as compare-and-swap or fetch-and-add) in stable Rust. There are also other reasons why one might want thin pointers with length stored within the object, like performance (cache locality) and memory consumption.

This trait was introduced to support DST by generalizing Box<T>: roughly speaking, what we require for a handle type is that (1) it is represented as a word, and (2) it owns a value of type T. Box<T> indeed satisfies these conditions and it implements Handle<Target=T>. For an example of DST, see Array and ArrayBox.

Safety

When H implements Handle<Target=T>, it should satisfy the following conditions:

  • When an storage object is converted to usize and then back, it should be the same storage object.
  • The result of into_raw() should be properly aligned as a pointer to T.

Associated Constants

const ALIGN: usize

Alignment of the data.

Loading content...

Required methods

fn into_usize(self) -> usize

Converts the storage type to usize.

The result shall be a multiple of ALIGN.

unsafe fn from_usize(_: usize) -> Self

Converts back usize to the storage type.

Safety

The given usize shall be originated from a storage object; otherwise, the behavior is undefined.

Loading content...

Implementations on Foreign Types

impl<T> Handle for Box<T>[src]

Loading content...

Implementors

impl<T> Handle for ArrayBox<T>[src]

Loading content...