SharedArray

A flat, fixed-stride array written once and read by many processes. One writer fills it and seals it; from then on it is read-only for every process, including the one that made it. The stride is exactly the element size, there is no per-element synchronization word, and the whole span is readable as one slice.

The “baked table many processes read” primitive. Every other array-shaped primitive here gives each element its own synchronization word and rounds its stride up to a cache line, so a reader never sees a half-written element. That is the right trade for something written while it is read, and pure cost for a table baked once and never written again: a 12-byte row costs 64 bytes of file, and a 3.5 MB table lands at 18 MB. Here 1000 elements of 12 bytes occupy 64 + 12,000 bytes on disk, header included.

Constraints (read first):

• One writer, then seal. seal() flushes, sets the flag, and flushes again, so a reader that sees the seal sees the data behind it. Every later write is refused through any handle, in any process.
• A reader attached before the seal sees whatever the writer has reached. There is no per-element version, so there is no torn-read detection; this primitive is for a table read after it is finished.
• The stride is in the header and every attach checks it. A reader using a different element size would read misaligned bytes that look exactly like data, so a disagreement is refused instead.
• Read-only attachments carry no write permission. open_read_only maps without it, so a reader cannot modify the file even through a mistake in its own code.
• Fixed shape at create. len and stride are locked into the header; both must be non-zero.
• create does not truncate. It attaches to an array already at the path when the shape matches, so reopening a baked table does not destroy it.

Table of contents

• What it is
• Operation table
• Errors
• Worked example
• When not to reach for this
• References

What it is

+---------------------------+
| ArrayHeader (64B)         |  magic + stride + len + sealed
+---------------------------+
| element 0                 |  stride bytes, no padding
| element 1                 |
| ...                       |
| element len-1             |
+---------------------------+

Total file size: 64 + len * stride bytes, which is what array_file_size(len, stride) returns. The header is cache-line aligned so the data behind it starts on a line; the elements themselves are not padded.

Operation table

Errors

Worked example

use subetha_cxc::shared_array::SharedArray;

// Bake a table of 12-byte rows: a u64 key and a u32 value.
let mut rows = Vec::new();
for i in 0u64..1000 {
    rows.extend_from_slice(&i.to_le_bytes());
    rows.extend_from_slice(&(i as u32 * 7).to_le_bytes());
}

let mut table = SharedArray::create("/tmp/lookup.bin", 1000, 12)?;
table.fill_from(&rows)?;
table.seal()?;

// Any process reads it without write access, and pays nothing per element.
let reader = SharedArray::open_read_only("/tmp/lookup.bin", 1000, 12)?;
let all = reader.as_slice();
let row = reader.get(37)?;

When not to reach for this

References

• Source: shared_array.rs