class

Nucleoc::Boxcar(T)

Inspired by Rust's boxcar::Vec, adapted for Crystal native concurrency.

A concurrent, append-only vector that supports parallel appends and random access. Uses atomic operations for thread-safe indexing and Crystal's native spawn for parallelism.

Constants

BUCKET_SIZE = 256

Default bucket size (power of two for fast division).

MAX_BUCKETS = 1 << 20

Maximum number of buckets before resizing.

Constructors

new

Creates a new empty Boxcar.

Source

Instance methods

clear

Clear all values (resets size to zero but keeps allocated buckets).

Source

each

Iterate over all initialized values.

Source

get(index : Int64) : T | Nil

Get value at index, or nil if not yet initialized or out of bounds.

Source

get!(index : Int64) : T

Get value at index, raising if not found.

Source

get_entry(index : Int64) : Entry(T) | Nil

Get entry at index, or nil if not yet initialized or out of bounds.

Source

par_snapshot

Create a parallel snapshot that can be processed in parallel.

Source

parallel_map

Process elements in parallel, applying a block to each. Returns an array of results in the same order as elements.

Source

parallel_select_map

Process elements in parallel, applying a block to each and collecting non-nil results.

Source

push(value : T, &fill_columns : T, Array(Utf32String) -> Nil) : Int64

Append a single value with column data.

Source

push(value : T) : Int64

Append a single value without column data (for testing).

Source

push_all(values : Enumerable(T), &fill_columns : T, Array(Utf32String) -> Nil) : Nil

Append multiple values efficiently with column data. Uses native Crystal spawn for parallel appends if beneficial.

Source

push_all(values : Enumerable(T)) : Nil

Append multiple values without column data (for testing).

Source

size

Current logical size (number of elements that have been allocated).

Source

snapshot(start_index : Int64 = 0) : Array(T)

Create an immutable snapshot of current values.

Source

sort_snapshot(start_index : Int64 = 0, &block : T, T -> Int32) : Array(T)

Sort snapshot with comparator.

Source

to_a

Convert to array (skips uninitialized slots).

Source

top_k_snapshot(k : Int32, start_index : Int64 = 0, &block : T, T -> Int32) : Array(T)

Get top K elements from snapshot using comparator. More efficient than full sort when k << n. The comparator should return: negative if a < b zero if a == b positive if a > b For top-k largest elements, use standard <=> comparator. For top-k smallest elements, use reversed comparator.

Source