Skip to main content

orbit_events/
layout.rs

1//! Physical geometry of one event ring.
2//!
3//! The default layout is the fleet's own ring. A second layout names another
4//! ring kind with its own capacity and frame size, so an embedding runtime
5//! can keep, say, small service events and large application events apart
6//! without the two competing for one retained window.
7
8use std::marker::PhantomData;
9
10use orbit_core::{OrbitTyped, RingSpec, RingTopology};
11
12use crate::{Error, HEADER_LEN, Result};
13
14/// Event frame payload limit for the default ring. This is the event lane's
15/// own SHM payload capacity; non-Unix keeps the same contract so callers do
16/// not accidentally rely on unbounded in-memory frames.
17pub const EVENT_RING_CAPACITY: usize = orbit_core::compile::usize_from_env(
18    option_env!("ORBIT_EVENT_RING_CAPACITY"),
19    1_024,
20);
21pub const EVENT_RING_PAYLOAD_CAPACITY: usize =
22    orbit_core::compile::usize_from_env(
23        option_env!("ORBIT_EVENT_RING_PAYLOAD_CAPACITY"),
24        512,
25    );
26pub const EVENT_RING_SPEC: RingSpec =
27    RingSpec::per_node(EVENT_RING_CAPACITY, EVENT_RING_PAYLOAD_CAPACITY);
28pub const EVENT_PAYLOAD_MAX: usize = EVENT_RING_SPEC.payload_capacity;
29pub const EVENT_RING_KIND: u8 = 220;
30
31const _: () = assert!(EVENT_RING_CAPACITY.is_power_of_two());
32const _: () = assert!(EVENT_RING_PAYLOAD_CAPACITY >= HEADER_LEN);
33const _: () = assert!(EVENT_RING_PAYLOAD_CAPACITY <= u32::MAX as usize);
34
35/// The Orbit ring one event bus publishes into and polls from.
36pub trait EventLayout: Send + Sync + 'static {
37    /// Kind of the per-node event ring.
38    const RING_KIND: u8;
39    /// Lane capacity and frame size of that ring.
40    const RING_SPEC: RingSpec;
41}
42
43/// The fleet's default event ring: kind 220, geometry from
44/// `ORBIT_EVENT_RING_CAPACITY` and `ORBIT_EVENT_RING_PAYLOAD_CAPACITY`.
45#[derive(Clone, Copy, Debug, Default)]
46pub struct DefaultEventLayout;
47
48impl EventLayout for DefaultEventLayout {
49    const RING_KIND: u8 = EVENT_RING_KIND;
50    const RING_SPEC: RingSpec = EVENT_RING_SPEC;
51}
52
53pub(crate) struct EventRecord<L>(PhantomData<L>);
54
55impl<L> Clone for EventRecord<L> {
56    fn clone(&self) -> Self {
57        Self(PhantomData)
58    }
59}
60
61impl<L: EventLayout> OrbitTyped for EventRecord<L> {
62    // Hand-picked V0 kinds. Build-time KIND allocation will replace
63    // these manual values later.
64    const KIND: u8 = L::RING_KIND;
65    const RING_SPEC: RingSpec = RingSpec::per_node(
66        L::RING_SPEC.capacity,
67        L::RING_SPEC.payload_capacity,
68    );
69}
70
71pub(crate) fn validate<L: EventLayout>() -> Result<()> {
72    if L::RING_SPEC.topology != RingTopology::PerNode {
73        return Err(Error::InvalidLayout(
74            "the event ring must use per-node lanes",
75        ));
76    }
77    if L::RING_SPEC.capacity == 0 || !L::RING_SPEC.capacity.is_power_of_two() {
78        return Err(Error::InvalidLayout(
79            "event-ring capacity must be a non-zero power of two",
80        ));
81    }
82    if L::RING_SPEC.payload_capacity < HEADER_LEN {
83        return Err(Error::InvalidLayout(
84            "event-ring payload cannot fit an event header",
85        ));
86    }
87    if L::RING_SPEC.payload_capacity > u32::MAX as usize {
88        return Err(Error::InvalidLayout(
89            "event-ring payload exceeds the frame length field",
90        ));
91    }
92    Ok(())
93}