Struct ListObj 

pub struct ListObj {
    pub header: Header,
    /* private fields */
}

A list: header, length, a pointer to a backing array, and room for a few elements inline.

Reads never lock, even on shared lists. The length and buffer pointer are atomic words, and a reader bounds-checks against the buffer it loaded, so it sees some consistent-enough state and never reads out of bounds. A writer (the owner, or a thread holding a shared list’s lock) that outgrows the buffer copies it into a new one and swaps the pointer; the old buffer is retired to the collector, which frees it only once the world is stopped and no reader can hold it.

Small lists keep their elements in the object itself: inline is a WordBuf embedded at the end of the object (its slots follow the struct), and buf points at it. Readers do not tell the two cases apart; they load buf as always. A list that outgrows its inline slots moves to an out-of-line buffer exactly as above, and never moves back, so the inline slots are never written again. A racing reader that loaded the inline pointer before the move reads values the list held then, from memory that lives as long as the list does, so the inline buffer needs no retiring. It is never freed on its own: it goes with the object.

Fields

header: Header

Implementations

impl ListObj

pub const INLINE_MAX: usize = 7

Most elements a new list keeps inline (a 96-byte object). Odd, so the object fills its size class. Chosen by measurement (issue #104).

pub const INLINE_MIN: usize = 3

Inline capacity of a new empty (or one-element) list.

pub fn inline_cap_for(cap: usize) -> usize

The inline capacity of a new list that should have room for cap elements, or 0 if they belong out of line. Rounded up to odd: an even count would leave a word of the size-class slot unused.

pub fn size_for(icap: usize) -> usize

The allocation size of a list with inline capacity icap.

pub fn is_inline(&self) -> bool

Whether the elements are currently stored in the object itself.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn get(&self, i: usize) -> Option<Value>

The item at i, if in bounds. Safe against concurrent writers; the caller must still have passed the ownership read check.

pub fn get_local(&self, i: usize) -> Option<Value>

As ListObj::get for a list owned by this thread or frozen, where nothing races.

pub fn to_vec(&self) -> Vec<Value>

A snapshot of the items.

pub fn try_to_vec(&self) -> RtResult<Vec<Value>>

As ListObj::to_vec, raising a MemoryError if the vector cannot be had.

pub fn capacity(&self) -> usize

pub unsafe fn set(&self, i: usize, v: Value) -> bool

Safety

See above.

pub unsafe fn push(&self, v: Value, access: Access)

Safety

See above.

pub unsafe fn try_push(&self, v: Value, access: Access) -> Result<(), Layout>

As ListObj::push, but if the allocator refuses to grow the list, returns the refused layout and leaves the list as it was.

Safety

See above.

pub unsafe fn pop(&self) -> Option<Value>

Safety

See above.

pub unsafe fn replace(&self, items: &[Value], access: Access)

Replaces the contents with items, reusing the buffer when it is large enough.

Safety

See above.

pub unsafe fn try_replace( &self, items: &[Value], access: Access, ) -> Result<(), Layout>

As ListObj::replace, but if the allocator refuses a larger buffer, returns the refused layout and leaves the list as it was.

Safety

See above.

pub unsafe fn modify<R>( &self, access: Access, f: impl FnOnce(&mut Vec<Value>) -> R, ) -> R

Runs f on a copy of the items and writes the result back.

Safety

See above.

pub unsafe fn try_modify<R>( &self, access: Access, f: impl FnOnce(&mut Vec<Value>) -> R, ) -> Result<R, Layout>

As ListObj::modify, but if the allocator refuses a larger buffer for the result, returns the refused layout and leaves the list as it was.

Safety

See above.