indexbus_abi/layouts/
state.rs

1use crate::{caps, IndexbusAtomicU32, IndexbusAtomicU64, LayoutHeader};
2
3/// State stream region base layout (generic over max bytes).
4///
5/// Note: C header generation typically uses a concrete `STATE_MAX` (see `StateLayout256`).
6///
7/// IMPORTANT: This generic layout does not include trailing padding for appended sections.
8/// For C headers and append-only wake sections, prefer a concrete exported layout like
9/// `StateLayout256` which includes explicit 64B padding.
10///
11/// ## Initialization protocol (v1)
12///
13/// Most IndexBus layouts use a cross-process initialization state machine
14/// `initialized: 0 (uninit) / 1 (initializing) / 2 (initialized)`.
15///
16/// The state-stream layout is intentionally different: it uses the `seq` field itself as the
17/// writer protocol (even = stable, odd = write-in-progress). A fresh, initialized region starts
18/// with `seq = 0` (stable). There is no separate `initialized` field in v1.
19#[repr(C)]
20pub struct StateLayout<const STATE_MAX: usize> {
21    /// Common region header (magic/version/capabilities/layout size).
22    pub header: LayoutHeader,
23
24    /// Sequence protocol:
25    /// - even = stable
26    /// - odd  = writer in progress
27    pub seq: IndexbusAtomicU64,
28
29    /// Current payload length in bytes.
30    pub len: IndexbusAtomicU32,
31    /// Padding (reserved).
32    pub pad: IndexbusAtomicU32,
33
34    /// State payload bytes (up to `len`).
35    pub data: [u8; STATE_MAX],
36}
37
38impl<const STATE_MAX: usize> StateLayout<STATE_MAX> {
39    /// Capabilities required for this region to be considered compatible.
40    pub const REQUIRED_CAPS: u32 = caps::INDEXBUS_CAP_SUPPORTS_STATE;
41}
42
43/// Concrete v1 state layout for `STATE_MAX=256` (header generation target).
44#[repr(C, align(64))]
45pub struct StateLayout256 {
46    /// Common region header (magic/version/capabilities/layout size).
47    pub header: LayoutHeader,
48    /// State sequence protocol.
49    pub seq: IndexbusAtomicU64,
50    /// Current payload length in bytes.
51    pub len: IndexbusAtomicU32,
52    /// Padding (reserved).
53    pub pad: IndexbusAtomicU32,
54    /// State payload bytes (up to `len`).
55    pub data: [u8; 256],
56
57    /// 16 + 8 + 4 + 4 + 256 = 288; pad 32 bytes so appended wake starts 64-aligned.
58    pub pad_to_64: [u8; 32],
59}
indexbus_abi/layouts/state.rs

indexbus_abi/layouts/
state.rs
