Struct WordBuf 

pub struct WordBuf { /* private fields */ }

A capacity word followed by cap atomic slots.

Implementations

impl WordBuf

pub fn empty() -> *mut WordBuf

The shared empty buffer.

pub fn alloc(cap: usize, fill: u64) -> *mut WordBuf

A new buffer of cap slots, each holding fill.

pub fn alloc_from( cap: usize, prefix: impl IntoIterator<Item = u64>, fill: u64, ) -> *mut WordBuf

A new buffer of cap slots holding the words of prefix (at most cap of them) and then fill, written in one pass.

pub fn try_alloc(cap: usize, fill: u64) -> Result<*mut WordBuf, Layout>

As WordBuf::alloc, but returns the layout the allocator refused instead of aborting.

pub fn try_alloc_from( cap: usize, prefix: impl IntoIterator<Item = u64>, fill: u64, ) -> Result<*mut WordBuf, Layout>

As WordBuf::alloc_from, but returns the layout the allocator refused instead of aborting.

pub unsafe fn init_in_place( p: *mut WordBuf, cap: usize, prefix: impl IntoIterator<Item = u64>, fill: u64, )

Writes a buffer of cap slots holding the words of prefix (at most cap of them) and then fill at p, which is not allocated by this module: containers use it for a buffer embedded in their own heap object. Such a buffer must never be passed to WordBuf::free or release, and it has no written range: it must not be passed to WordBuf::note_written or the functions that follow it.

Safety

p must be valid for writes of 8 * (cap + 1) bytes, 8-aligned, and unpublished.

pub fn from_vec(items: Vec<u64>, fill: u64) -> *mut WordBuf

A buffer holding items (with the vector’s capacity, spare slots holding fill) that takes over the vector’s allocation instead of copying it: the allocation is grown by the header words and the items are moved up within it, so building a large container from a vector does not need memory for two copies.

pub fn try_from_vec(items: Vec<u64>, fill: u64) -> Result<*mut WordBuf, Layout>

As WordBuf::from_vec, but if the allocator refuses, frees the vector and returns the layout it refused instead of aborting.

pub unsafe fn free(p: *mut u8)

Safety

p must come from WordBuf::alloc and be unreachable by any reader.

pub unsafe fn slots<'a>(p: *const WordBuf) -> &'a [AtomicU64]

Safety

p must be a live buffer, loaded with Acquire (or by its only writer); the slice must not be held across a safepoint.

pub unsafe fn cap(p: *const WordBuf) -> usize

Safety

As for WordBuf::slots.

pub unsafe fn range_word(p: *const WordBuf) -> u64

The word before the capacity word: the written range of a buffer this module allocated.

Safety

That word must be readable as an atomic word: p is a live buffer this module allocated, or one written in place after an atomic word of the same object.

pub fn range_covers(r: u64, lo: usize, hi: usize) -> bool

Whether the range word r covers slots lo..hi.

pub unsafe fn note_written(p: *const WordBuf, lo: usize, hi: usize)

Records that slots lo..hi (lo < hi) were written. A load and two compares when the range already covers them, as it does for every container that is still young.

Safety

p must be a live buffer this module allocated (not one written in place), and the caller must have write access to the container that holds it.

pub unsafe fn widen_written(p: *const WordBuf, lo: usize, hi: usize)

The slow path of WordBuf::note_written: widens the range to cover lo..hi.

Safety

As for WordBuf::note_written.

pub unsafe fn copy_written(from: *const WordBuf, to: *const WordBuf)

Gives to, a new buffer holding the contents of from at the same indices, the written range of from.

Safety

As for WordBuf::note_written, for both buffers.

pub unsafe fn take_written(p: *const WordBuf) -> Range<usize>

The slots written since the last call (within the capacity), which it then forgets.

Safety

As for WordBuf::note_written; called by a minor collection of the owning thread.

pub unsafe fn written(p: *const WordBuf) -> Range<usize>

The slots written since the last WordBuf::take_written (within the capacity).

Safety

As for WordBuf::note_written.