Expose native reservoir C ABI
This commit is contained in:
parent
b4d50860df
commit
2bf5abbd57
9 changed files with 320 additions and 11 deletions
|
|
@ -6,6 +6,7 @@
|
|||
- `docs/perfect-machine.md` defines the target native machine: one five-second spatiotemporal reservoir, Aquarium-owned dense visual fusion/material/brush rendering, Faust-owned hot audio DSP, OBS-owned broadcast controls, and LocalCastBridge-owned calibration/config/status.
|
||||
- `config/perfect-machine.example.json` declares the contract shape for six cameras, six microphones, reservoir rings, native authorities, outputs, and the demotion of bridge scripts to tooling.
|
||||
- `native/reservoir` is the first native Rust crate. It implements shared-edge five-second reservoir rings and proves that all rings expire against the newest sample, not private per-source clocks.
|
||||
- `native/reservoir/include/localcast_reservoir.h` exposes the Aquarium/Faust C ABI: opaque reservoir create/destroy, sample-handle push, edge/window queries, ring counts, and latest sample lookup by sensor hash. Payload memory remains owned by Aquarium/GPU/Faust; the reservoir owns timing and retention.
|
||||
- Repo-local persistence machinery.
|
||||
- First architecture map.
|
||||
- Example config for one video source plus two audio sources.
|
||||
|
|
@ -75,7 +76,7 @@
|
|||
|
||||
## Next
|
||||
|
||||
1. Add a C ABI and Aquarium-facing binding around `native/reservoir`.
|
||||
1. Add the Aquarium-side binding that loads `localcast_reservoir` and maps GPU/audio buffer handles to `LocalcastSampleHandle`.
|
||||
2. Move camera ingest into native capture workers that append `camera_frame` samples to the reservoir.
|
||||
3. Move feature extraction, flow, cross-view matching, LOD reconciliation, and material fitting into Aquarium GPU compute.
|
||||
4. Move mic alignment, voice separation, room suppression, Ambisonic/HOA spatialization, and stem generation into Faust/native DSP.
|
||||
|
|
|
|||
|
|
@ -157,6 +157,16 @@ five-second reservoir invariant:
|
|||
- evict every ring against the same edge;
|
||||
- query the latest valid sample per sensor.
|
||||
|
||||
This is intentionally below Aquarium and Faust. The crate owns retention and
|
||||
sample-window semantics; Aquarium owns GPU interpretation and rendering, Faust
|
||||
owns DSP interpretation.
|
||||
It now builds as `rlib`, `cdylib`, and `staticlib`, with a small C ABI declared
|
||||
in `native/reservoir/include/localcast_reservoir.h`:
|
||||
|
||||
- create/destroy an opaque `LocalcastReservoir`;
|
||||
- push timestamped sample metadata into a typed ring;
|
||||
- advance/query the shared edge and window start;
|
||||
- query ring length;
|
||||
- query the latest sample for a sensor hash.
|
||||
|
||||
The ABI carries `payload_handle`, not payload bytes. Aquarium owns image,
|
||||
feature, surface, material, and GPU memory interpretation. Faust/native DSP owns
|
||||
audio buffer interpretation. The reservoir owns only retention, ring identity,
|
||||
timestamp order, and the five-second shared-edge invariant.
|
||||
|
|
|
|||
|
|
@ -10,4 +10,22 @@ tests, and offline analysis. It does not own dense live fusion or DSP.
|
|||
- `reservoir`: the first native five-second spatiotemporal reservoir core. It
|
||||
owns shared-edge retention and typed sample rings. Aquarium/Faust integration
|
||||
should build on this invariant instead of copying the deadline bridge cache.
|
||||
It exports `rlib`, `cdylib`, and `staticlib` artifacts plus the C header at
|
||||
`reservoir/include/localcast_reservoir.h`.
|
||||
|
||||
## Reservoir ABI
|
||||
|
||||
The ABI is intentionally small:
|
||||
|
||||
- `LocalcastReservoir` is opaque.
|
||||
- `LocalcastSampleHandle` is sample metadata plus a `payload_handle`.
|
||||
- Ring ids match the Perfect Machine reservoir rings:
|
||||
camera frame, camera feature, scene ray, surface claim, material claim, audio
|
||||
block, phase claim, event claim, and render packet.
|
||||
- The reservoir can create/destroy, push, set/query edge, query window start,
|
||||
count a ring, and fetch the latest sample for a sensor hash.
|
||||
|
||||
Payload handles are owned by the caller. Aquarium should treat them as handles
|
||||
to GPU/native visual memory; Faust/native DSP should treat them as handles to
|
||||
audio buffers. This crate does not interpret those bytes. It is the clocked
|
||||
retention authority, not the renderer or DSP engine in a tiny hat.
|
||||
|
|
|
|||
|
|
@ -5,6 +5,6 @@ edition = "2024"
|
|||
description = "Native five-second spatiotemporal reservoir core for LocalCastBridge"
|
||||
|
||||
[lib]
|
||||
crate-type = ["rlib"]
|
||||
crate-type = ["rlib", "cdylib", "staticlib"]
|
||||
|
||||
[dependencies]
|
||||
|
|
|
|||
56
native/reservoir/include/localcast_reservoir.h
Normal file
56
native/reservoir/include/localcast_reservoir.h
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
#pragma once
|
||||
|
||||
#include <stdbool.h>
|
||||
#include <stdint.h>
|
||||
#include <stddef.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
enum LocalcastRingKind {
|
||||
LOCALCAST_RING_CAMERA_FRAME = 0,
|
||||
LOCALCAST_RING_CAMERA_FEATURE = 1,
|
||||
LOCALCAST_RING_SCENE_RAY = 2,
|
||||
LOCALCAST_RING_SURFACE_CLAIM = 3,
|
||||
LOCALCAST_RING_MATERIAL_CLAIM = 4,
|
||||
LOCALCAST_RING_AUDIO_BLOCK = 5,
|
||||
LOCALCAST_RING_PHASE_CLAIM = 6,
|
||||
LOCALCAST_RING_EVENT_CLAIM = 7,
|
||||
LOCALCAST_RING_RENDER_PACKET = 8
|
||||
};
|
||||
|
||||
typedef struct LocalcastReservoir LocalcastReservoir;
|
||||
|
||||
typedef struct LocalcastSampleHandle {
|
||||
uint64_t sensor_id_hash;
|
||||
uint64_t timestamp_ns;
|
||||
uint64_t arrival_ns;
|
||||
uint64_t sequence;
|
||||
uint64_t payload_handle;
|
||||
} LocalcastSampleHandle;
|
||||
|
||||
LocalcastReservoir *localcast_reservoir_create(uint64_t duration_ns);
|
||||
void localcast_reservoir_destroy(LocalcastReservoir *reservoir);
|
||||
|
||||
bool localcast_reservoir_push(
|
||||
LocalcastReservoir *reservoir,
|
||||
uint32_t ring_kind,
|
||||
LocalcastSampleHandle sample
|
||||
);
|
||||
|
||||
bool localcast_reservoir_set_edge(LocalcastReservoir *reservoir, uint64_t edge_ns);
|
||||
uint64_t localcast_reservoir_edge_ns(const LocalcastReservoir *reservoir);
|
||||
uint64_t localcast_reservoir_window_start_ns(const LocalcastReservoir *reservoir);
|
||||
size_t localcast_reservoir_ring_len(const LocalcastReservoir *reservoir, uint32_t ring_kind);
|
||||
|
||||
bool localcast_reservoir_latest_for_sensor(
|
||||
const LocalcastReservoir *reservoir,
|
||||
uint32_t ring_kind,
|
||||
uint64_t sensor_id_hash,
|
||||
LocalcastSampleHandle *out_sample
|
||||
);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
|
@ -15,6 +15,23 @@ pub enum RingKind {
|
|||
RenderPacket,
|
||||
}
|
||||
|
||||
impl RingKind {
|
||||
fn from_u32(value: u32) -> Option<Self> {
|
||||
match value {
|
||||
0 => Some(Self::CameraFrame),
|
||||
1 => Some(Self::CameraFeature),
|
||||
2 => Some(Self::SceneRay),
|
||||
3 => Some(Self::SurfaceClaim),
|
||||
4 => Some(Self::MaterialClaim),
|
||||
5 => Some(Self::AudioBlock),
|
||||
6 => Some(Self::PhaseClaim),
|
||||
7 => Some(Self::EventClaim),
|
||||
8 => Some(Self::RenderPacket),
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq)]
|
||||
pub struct Sample<T> {
|
||||
pub sensor_id: String,
|
||||
|
|
@ -98,8 +115,9 @@ impl<T> ReservoirRing<T> {
|
|||
|
||||
fn evict_expired(&mut self) {
|
||||
let start_ns = self.window_start_ns();
|
||||
self.samples
|
||||
.retain(|sample| sample.timestamp_ns >= start_ns && sample.timestamp_ns <= self.edge_ns);
|
||||
self.samples.retain(|sample| {
|
||||
sample.timestamp_ns >= start_ns && sample.timestamp_ns <= self.edge_ns
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -158,6 +176,133 @@ impl<T> Default for Reservoir<T> {
|
|||
}
|
||||
}
|
||||
|
||||
#[repr(C)]
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct LocalcastSampleHandle {
|
||||
pub sensor_id_hash: u64,
|
||||
pub timestamp_ns: u64,
|
||||
pub arrival_ns: u64,
|
||||
pub sequence: u64,
|
||||
pub payload_handle: u64,
|
||||
}
|
||||
|
||||
pub struct LocalcastReservoir {
|
||||
inner: Reservoir<LocalcastSampleHandle>,
|
||||
}
|
||||
|
||||
#[unsafe(no_mangle)]
|
||||
pub extern "C" fn localcast_reservoir_create(duration_ns: u64) -> *mut LocalcastReservoir {
|
||||
let duration = if duration_ns == 0 {
|
||||
DEFAULT_RESERVOIR_NS
|
||||
} else {
|
||||
duration_ns
|
||||
};
|
||||
Box::into_raw(Box::new(LocalcastReservoir {
|
||||
inner: Reservoir::new(duration),
|
||||
}))
|
||||
}
|
||||
|
||||
#[unsafe(no_mangle)]
|
||||
pub extern "C" fn localcast_reservoir_destroy(ptr: *mut LocalcastReservoir) {
|
||||
if ptr.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
drop(Box::from_raw(ptr));
|
||||
}
|
||||
}
|
||||
|
||||
#[unsafe(no_mangle)]
|
||||
pub extern "C" fn localcast_reservoir_push(
|
||||
ptr: *mut LocalcastReservoir,
|
||||
ring_kind: u32,
|
||||
sample: LocalcastSampleHandle,
|
||||
) -> bool {
|
||||
let Some(reservoir) = (unsafe { ptr.as_mut() }) else {
|
||||
return false;
|
||||
};
|
||||
let Some(kind) = RingKind::from_u32(ring_kind) else {
|
||||
return false;
|
||||
};
|
||||
reservoir.inner.push(
|
||||
kind,
|
||||
Sample::new(
|
||||
sample.sensor_id_hash.to_string(),
|
||||
sample.timestamp_ns,
|
||||
sample.arrival_ns,
|
||||
sample.sequence,
|
||||
sample,
|
||||
),
|
||||
);
|
||||
true
|
||||
}
|
||||
|
||||
#[unsafe(no_mangle)]
|
||||
pub extern "C" fn localcast_reservoir_set_edge(ptr: *mut LocalcastReservoir, edge_ns: u64) -> bool {
|
||||
let Some(reservoir) = (unsafe { ptr.as_mut() }) else {
|
||||
return false;
|
||||
};
|
||||
reservoir.inner.set_edge(edge_ns);
|
||||
true
|
||||
}
|
||||
|
||||
#[unsafe(no_mangle)]
|
||||
pub extern "C" fn localcast_reservoir_edge_ns(ptr: *const LocalcastReservoir) -> u64 {
|
||||
let Some(reservoir) = (unsafe { ptr.as_ref() }) else {
|
||||
return 0;
|
||||
};
|
||||
reservoir.inner.edge_ns()
|
||||
}
|
||||
|
||||
#[unsafe(no_mangle)]
|
||||
pub extern "C" fn localcast_reservoir_window_start_ns(ptr: *const LocalcastReservoir) -> u64 {
|
||||
let Some(reservoir) = (unsafe { ptr.as_ref() }) else {
|
||||
return 0;
|
||||
};
|
||||
reservoir.inner.window_start_ns()
|
||||
}
|
||||
|
||||
#[unsafe(no_mangle)]
|
||||
pub extern "C" fn localcast_reservoir_ring_len(
|
||||
ptr: *const LocalcastReservoir,
|
||||
ring_kind: u32,
|
||||
) -> usize {
|
||||
let Some(reservoir) = (unsafe { ptr.as_ref() }) else {
|
||||
return 0;
|
||||
};
|
||||
let Some(kind) = RingKind::from_u32(ring_kind) else {
|
||||
return 0;
|
||||
};
|
||||
reservoir.inner.ring(kind).map_or(0, ReservoirRing::len)
|
||||
}
|
||||
|
||||
#[unsafe(no_mangle)]
|
||||
pub extern "C" fn localcast_reservoir_latest_for_sensor(
|
||||
ptr: *const LocalcastReservoir,
|
||||
ring_kind: u32,
|
||||
sensor_id_hash: u64,
|
||||
out_sample: *mut LocalcastSampleHandle,
|
||||
) -> bool {
|
||||
let Some(reservoir) = (unsafe { ptr.as_ref() }) else {
|
||||
return false;
|
||||
};
|
||||
let Some(kind) = RingKind::from_u32(ring_kind) else {
|
||||
return false;
|
||||
};
|
||||
let Some(out) = (unsafe { out_sample.as_mut() }) else {
|
||||
return false;
|
||||
};
|
||||
let Some(ring) = reservoir.inner.ring(kind) else {
|
||||
return false;
|
||||
};
|
||||
let key = sensor_id_hash.to_string();
|
||||
let Some(sample) = ring.latest_for_sensor(&key) else {
|
||||
return false;
|
||||
};
|
||||
*out = sample.payload;
|
||||
true
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
|
@ -208,4 +353,69 @@ mod tests {
|
|||
assert_eq!("a1", latest.payload);
|
||||
assert_eq!(1, latest.sequence);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn c_abi_pushes_and_queries_latest_sample() {
|
||||
let reservoir = localcast_reservoir_create(DEFAULT_RESERVOIR_NS);
|
||||
let pushed = localcast_reservoir_push(
|
||||
reservoir,
|
||||
0,
|
||||
LocalcastSampleHandle {
|
||||
sensor_id_hash: 42,
|
||||
timestamp_ns: 10,
|
||||
arrival_ns: 11,
|
||||
sequence: 7,
|
||||
payload_handle: 99,
|
||||
},
|
||||
);
|
||||
let mut out = LocalcastSampleHandle {
|
||||
sensor_id_hash: 0,
|
||||
timestamp_ns: 0,
|
||||
arrival_ns: 0,
|
||||
sequence: 0,
|
||||
payload_handle: 0,
|
||||
};
|
||||
let found = localcast_reservoir_latest_for_sensor(reservoir, 0, 42, &mut out);
|
||||
|
||||
assert!(pushed);
|
||||
assert!(found);
|
||||
assert_eq!(1, localcast_reservoir_ring_len(reservoir, 0));
|
||||
assert_eq!(99, out.payload_handle);
|
||||
localcast_reservoir_destroy(reservoir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn c_abi_rejects_nulls_and_unknown_ring_kinds() {
|
||||
let sample = LocalcastSampleHandle {
|
||||
sensor_id_hash: 1,
|
||||
timestamp_ns: 2,
|
||||
arrival_ns: 3,
|
||||
sequence: 4,
|
||||
payload_handle: 5,
|
||||
};
|
||||
let mut out = sample;
|
||||
|
||||
assert!(!localcast_reservoir_push(std::ptr::null_mut(), 0, sample));
|
||||
assert!(!localcast_reservoir_set_edge(std::ptr::null_mut(), 10));
|
||||
assert_eq!(0, localcast_reservoir_edge_ns(std::ptr::null()));
|
||||
assert_eq!(0, localcast_reservoir_window_start_ns(std::ptr::null()));
|
||||
assert_eq!(0, localcast_reservoir_ring_len(std::ptr::null(), 0));
|
||||
assert!(!localcast_reservoir_latest_for_sensor(
|
||||
std::ptr::null(),
|
||||
0,
|
||||
1,
|
||||
&mut out,
|
||||
));
|
||||
|
||||
let reservoir = localcast_reservoir_create(0);
|
||||
assert!(!localcast_reservoir_push(reservoir, 99, sample));
|
||||
assert_eq!(0, localcast_reservoir_ring_len(reservoir, 99));
|
||||
assert!(!localcast_reservoir_latest_for_sensor(
|
||||
reservoir,
|
||||
0,
|
||||
1,
|
||||
std::ptr::null_mut(),
|
||||
));
|
||||
localcast_reservoir_destroy(reservoir);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -27,9 +27,9 @@ Ownership:
|
|||
- Faust owns hot audio DSP and program stem generation.
|
||||
- OBS owns broadcast controls.
|
||||
- Python remains tooling, not the stream hot path.
|
||||
- `native/reservoir` is the first native crate. It owns shared-edge five-second sample retention for typed rings and is the seed of the Aquarium/Faust runtime boundary.
|
||||
- `native/reservoir` is the first native crate. It owns shared-edge five-second sample retention for typed rings and exposes the small C ABI in `native/reservoir/include/localcast_reservoir.h`: opaque reservoir lifetime, sample-handle push, edge/window queries, ring counts, and latest-by-sensor lookup.
|
||||
|
||||
Invariant: the five-second spatiotemporal reservoir is the live authority. Producers append, optimizers refine, Aquarium/Faust sample. No private history outlives the reservoir.
|
||||
Invariant: the five-second spatiotemporal reservoir is the live authority. Producers append sample handles, optimizers refine, Aquarium/Faust sample and interpret the pointed-to payloads. No private history outlives the reservoir, and the reservoir does not pretend to own GPU image memory or Faust audio buffers.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ invariants:
|
|||
|
||||
accepted_design:
|
||||
- `docs/perfect-machine.md` and `config/perfect-machine.example.json` define the native target: one five-second spatiotemporal reservoir, Aquarium GPU fusion/rendering, Faust DSP, OBS output controls, and LocalCastBridge tooling.
|
||||
- `native/reservoir` is the first native Rust crate. It implements shared-edge reservoir rings so all sample types expire from the newest live sample rather than private source histories.
|
||||
- `native/reservoir` is the first native Rust crate. It implements shared-edge reservoir rings so all sample types expire from the newest live sample rather than private source histories, and exposes a small C ABI for Aquarium/Faust handle-based integration.
|
||||
- `config/localcast.example.json` defines receiver address, base port, video encode settings, and audio sources.
|
||||
- `scripts/sender-discover.ps1` lists FFmpeg devices, protocols, and encoders.
|
||||
- `scripts/sender-start.ps1` launches one FFmpeg process per enabled source.
|
||||
|
|
@ -42,7 +42,7 @@ accepted_design:
|
|||
- Persistence follows the active repo pattern: map, scratch, evidence, branches, handoff, system map, implementation plan, state helpers.
|
||||
|
||||
active_subgoals:
|
||||
- Implement the Perfect Machine native reservoir contract described by `docs/perfect-machine.md` and `config/perfect-machine.example.json`.
|
||||
- Bind Aquarium/Faust to the native reservoir C ABI described by `native/reservoir/include/localcast_reservoir.h`.
|
||||
- Move dense visual fusion/material fitting/brush generation into Aquarium GPU compute.
|
||||
- Move hot audio DSP/voice separation/room suppression/spatialization into Faust/native runtime.
|
||||
- Validate the actual sender FFmpeg build and capture device names.
|
||||
|
|
|
|||
|
|
@ -30,6 +30,20 @@ class PerfectMachineContractTests(unittest.TestCase):
|
|||
})
|
||||
self.assertIn("dense-feature-extraction", data["bridgeDemotion"]["notPython"])
|
||||
|
||||
def test_native_reservoir_header_exposes_small_c_abi(self):
|
||||
header = (ROOT / "native" / "reservoir" / "include" / "localcast_reservoir.h").read_text(encoding="utf-8")
|
||||
|
||||
self.assertIn("typedef struct LocalcastReservoir LocalcastReservoir;", header)
|
||||
self.assertIn("typedef struct LocalcastSampleHandle", header)
|
||||
self.assertIn("uint64_t payload_handle;", header)
|
||||
self.assertIn("LocalcastReservoir *localcast_reservoir_create", header)
|
||||
self.assertIn("void localcast_reservoir_destroy", header)
|
||||
self.assertIn("bool localcast_reservoir_push", header)
|
||||
self.assertIn("uint64_t localcast_reservoir_edge_ns", header)
|
||||
self.assertIn("uint64_t localcast_reservoir_window_start_ns", header)
|
||||
self.assertIn("size_t localcast_reservoir_ring_len", header)
|
||||
self.assertIn("bool localcast_reservoir_latest_for_sensor", header)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
|
|
|||
Loading…
Reference in a new issue