Struct atomic_bitvec::AtomicBitVec

pub struct AtomicBitVec { /* fields omitted */ }

AtomicBitVec is build atop a standard Vec, and uses AtomicU64 for its backing store. The ordering for atomic operations is left to the user to decide.

The term "blocks" is used throughout this documentation to refer to the number of atomic integers are stored in the backing storage. All resizing and allocation is done in block-sized units; this means that the bit-length of these bitvecs will always be a multiple of 64.

Implementations

impl AtomicBitVec

pub const fn new() -> Self

Creates an empty AtomicBitVec.

This does not allocate; you'll need to call one of with_bit_capacity, with_capacity, resize_blocks_with, or resize_bits_with to actually allocate memory and initialize the backing store.

Examples

Basic usage:

use atomic_bitvec::AtomicBitVec;
let s = AtomicBitVec::new();

pub fn size_in_mem(&self) -> usize

Returns the size of this bitvec in memory in bytes.

This value is calculated from the size of the allocated backing store and the size of the vector itself. This does not take into account potential reserve overhead; it is based purely on the current length of the bitvec.

pub fn with_bit_capacity(bit_cap: usize) -> Self

Creates a new bitvec with capacity to hold at least bit_cap many bits.

This implementation will allocate as many bits as is necessary to hold a multiple of 64 bits.

pub fn with_capacity(blocks: usize) -> Self

Creates a new bitvec with capacity to hold at least blocks many blocks.

Each block holds 64 bits.

pub fn resize_blocks_with(
    &mut self,
    new_blocks: usize,
    f: impl FnMut() -> AtomicU64
)

Resizes a bitvec to contain new_blocks many blocks, using f to generate new elements if extending the bitvec. If new_blocks is less than block_cnt, this truncates instead.

Examples

let mut s = AtomicBitVec::with_capacity(2);
assert_eq!(s.block_cnt(), 0);
s.resize_blocks_with(4, AtomicU64::default);
assert_eq!(s.block_cnt(), 4);

pub fn resize_bits_with(
    &mut self,
    new_bits: usize,
    f: impl FnMut() -> AtomicU64
)

Resizes a bitvec to contain at least new_bits many bits, using f to generate new blocks if extending the bitvec. If new_bits is less than len, this truncates instead.

This will extend the bitvec to the next multiple of 64 bits if new_bits is not a multiple of 64.

Examples

let mut s = AtomicBitVec::with_bit_capacity(128);
assert_eq!(s.len(), 0);
s.resize_bits_with(200, AtomicU64::default);
// Note that the next multiple of 64 bits was allocated.
assert_eq!(s.block_cnt(), 4);
assert_eq!(s.len(), 256);

pub fn block_cnt(&self) -> usize

Returns the current block count of the bitvec. This is equivalent to the bit-length of the bitvec divided by 64.

Examples

let mut s = AtomicBitVec::with_bit_capacity(128);
s.resize_bits_with(200, AtomicU64::default);
assert_eq!(s.block_cnt(), 4);

pub fn len(&self) -> usize

Returns the current bit-length of the bitvec. This is equivalent to the current block count times 64.

Examples

let mut s = AtomicBitVec::with_bit_capacity(128);
s.resize_bits_with(200, AtomicU64::default);
// Note that the next multiple of 64 bits was allocated.
assert_eq!(s.len(), 256);

pub fn set(&self, idx: usize, value: bool, ordering: Ordering) -> bool

Sets the bit at idx to value, using the atomic ordering provided by ordering. Returns the previous value at the specified bit.

The bit will be set atomically, allowing this bitvec to be used from multiple threads.

Examples

let mut s = AtomicBitVec::with_bit_capacity(128);
s.resize_bits_with(256, AtomicU64::default);
s.set(3, true, Ordering::AcqRel);
assert!(s.get(3, Ordering::Acquire));

Panics

Panics if idx is out of bounds.

pub fn get(&self, idx: usize, ordering: Ordering) -> bool

Returns the bit at the specified index according to the given atomic ordering.

Examples

let mut s = AtomicBitVec::with_bit_capacity(128);
s.resize_bits_with(256, AtomicU64::default);
s.set(3, true, Ordering::AcqRel);
assert!(s.get(3, Ordering::Acquire));

Panics

Panics if idx is out of bounds or if ordering is not valid for AtomicU64::load

pub fn iter<'a>(&'a self, ordering: Ordering) -> impl Iterator<Item = bool> + 'a

Returns an iterator over the bits of this bitvec.

Examples

let mut s = AtomicBitVec::with_bit_capacity(128);
s.resize_bits_with(64, AtomicU64::default);
s.set(3, true, Ordering::AcqRel);
let i = s.iter(Ordering::Acquire);
let v: Vec<bool> = i.take(5).collect();
assert_eq!(v, [false, false, false, true, false]);

Panics

Panics if ordering is not valid for AtomicU64::load

Warning

Because this struct can be updated atomically, if this function is called while other threads are updating this bitvec, the result may not be equivalent to if this function had been called when this thread had unique ownership.

let mut s = AtomicBitVec::with_bit_capacity(128);
s.resize_bits_with(64, AtomicU64::default);
s.set(3, true, Ordering::AcqRel);
let a = Arc::new(s);
let ta = a.clone();
std::thread::spawn(move || ta.set(4, true, Ordering::AcqRel));
let i = a.iter(Ordering::Acquire);
let v: Vec<bool> = i.take(5).collect();
assert_eq!(v, [false, false, false, true, false]); // May or may not panic!

pub fn count_ones(&self, ordering: Ordering) -> u64

Counts all of the set bits in this bitvec.

Examples

let mut s = AtomicBitVec::with_bit_capacity(128);
s.resize_bits_with(64, AtomicU64::default);
s.set(3, true, Ordering::AcqRel);
s.set(5, true, Ordering::AcqRel);
assert_eq!(s.count_ones(Ordering::Acquire), 2);

Panics

Panics if ordering is not valid for AtomicU64::load

Warning

Because this struct can be updated atomically, if this function is called while other threads are updating this bitvec, the result may not be equivalent to if this function had been called when this thread had unique ownership.

let mut s = AtomicBitVec::with_bit_capacity(128);
s.resize_bits_with(64, AtomicU64::default);
s.set(3, true, Ordering::AcqRel);
s.set(5, true, Ordering::AcqRel);
let a = Arc::new(s);
let ta = a.clone();
std::thread::spawn(move || ta.set(5, false, Ordering::AcqRel));
assert_eq!(a.count_ones(Ordering::Acquire), 2); // May or may not panic!

Trait Implementations

impl IntoIterator for AtomicBitVec

type Item = bool

The type of the elements being iterated over.

type IntoIter = Iter<'static, AtomicBitVec>

Which kind of iterator are we turning this into?

pub fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.