feagi_npu_burst_engine/
parameter_update_queue.rs

1// Copyright 2025 Neuraville Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4/*!
5Asynchronous parameter update queue for cortical areas.
6
7This queue allows non-blocking parameter updates that are applied between burst cycles,
8preventing lock contention and ensuring zero impact on burst timing even at ultra-high
9frequencies (100Hz+) with GPU acceleration.
10
11Copyright 2025 Neuraville Inc.
12Licensed under the Apache License, Version 2.0
13*/
14
15use serde_json::Value;
16use std::collections::VecDeque;
17use std::sync::{Arc, Mutex};
18
19/// A single parameter update command
20#[derive(Debug, Clone)]
21pub struct ParameterUpdate {
22    /// Cortical area index
23    pub cortical_idx: u32,
24    /// Cortical area ID (for logging)
25    pub cortical_id: String,
26    /// Parameter name
27    pub parameter_name: String,
28    /// New value
29    pub value: Value,
30    /// Optional cortical area dimensions (for spatial gradient updates)
31    pub dimensions: Option<(u32, u32, u32)>, // (width, height, depth)
32    /// Optional neurons_per_voxel (for spatial gradient updates)
33    pub neurons_per_voxel: Option<u32>,
34    /// Optional base_threshold (for spatial gradient updates)
35    pub base_threshold: Option<f32>,
36}
37
38/// Thread-safe queue for parameter updates
39///
40/// ARCHITECTURE:
41/// - API thread: Pushes updates (non-blocking, just mutex on queue)
42/// - Burst thread: Consumes updates between bursts (when NPU is free)
43///
44/// PERFORMANCE:
45/// - Queue operations: ~1-2µs (fast mutex, no contention)
46/// - Zero impact on burst timing
47/// - Works at any frequency (100Hz+, 1000Hz+)
48pub struct ParameterUpdateQueue {
49    queue: Arc<Mutex<VecDeque<ParameterUpdate>>>,
50}
51
52impl ParameterUpdateQueue {
53    pub fn new() -> Self {
54        Self {
55            queue: Arc::new(Mutex::new(VecDeque::with_capacity(100))),
56        }
57    }
58
59    /// Push a parameter update (non-blocking, called from API thread)
60    pub fn push(&self, update: ParameterUpdate) {
61        self.queue.lock().unwrap().push_back(update);
62    }
63
64    /// Drain all pending updates (called from burst thread between bursts)
65    pub fn drain_all(&self) -> Vec<ParameterUpdate> {
66        self.queue.lock().unwrap().drain(..).collect()
67    }
68
69    /// Get queue size (for monitoring)
70    pub fn len(&self) -> usize {
71        self.queue.lock().unwrap().len()
72    }
73
74    /// Check if queue is empty
75    pub fn is_empty(&self) -> bool {
76        self.queue.lock().unwrap().is_empty()
77    }
78}
79
80impl Default for ParameterUpdateQueue {
81    fn default() -> Self {
82        Self::new()
83    }
84}
85
86impl Clone for ParameterUpdateQueue {
87    fn clone(&self) -> Self {
88        Self {
89            queue: Arc::clone(&self.queue),
90        }
91    }
92}
feagi_npu_burst_engine/parameter_update_queue.rs

feagi_npu_burst_engine/
parameter_update_queue.rs
