use super::{GpuRingBuffer, RingBufferConfig, WriteHandle};
use crate::device::WgpuDevice;
use crate::error::{BarracudaError, Result};
use bytes::Bytes;
use std::collections::VecDeque;
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Instant;
#[derive(Debug, Clone)]
pub struct UnidirectionalConfig {
pub input_bandwidth_fraction: f64,
pub input_buffer_size: usize,
pub output_buffer_size: usize,
pub target_input_bandwidth: Option<u64>,
pub target_output_bandwidth: Option<u64>,
pub strict_mode: bool,
}
const DEFAULT_INPUT_BUFFER_BYTES: usize = 128 * 1024 * 1024;
const DEFAULT_OUTPUT_BUFFER_BYTES: usize = 16 * 1024 * 1024;
const DEFAULT_INPUT_BW_FRACTION: f64 = 0.9;
const BYTES_PER_MB: usize = 1024 * 1024;
#[cfg(test)]
const LARGE_INPUT_BUFFER_MB: usize = 256;
#[cfg(test)]
const LARGE_OUTPUT_BUFFER_MB: usize = 32;
#[cfg(test)]
const THROTTLE_TEST_BPS: u64 = 1000;
impl Default for UnidirectionalConfig {
fn default() -> Self {
Self {
input_bandwidth_fraction: DEFAULT_INPUT_BW_FRACTION,
input_buffer_size: DEFAULT_INPUT_BUFFER_BYTES,
output_buffer_size: DEFAULT_OUTPUT_BUFFER_BYTES,
target_input_bandwidth: None,
target_output_bandwidth: None,
strict_mode: false,
}
}
}
impl UnidirectionalConfig {
#[must_use]
pub fn with_sizes(input_mb: usize, output_mb: usize) -> Self {
Self {
input_buffer_size: input_mb * BYTES_PER_MB,
output_buffer_size: output_mb * BYTES_PER_MB,
..Default::default()
}
}
#[must_use]
pub fn with_throttling(mut self, input_bps: u64, output_bps: u64) -> Self {
self.target_input_bandwidth = Some(input_bps);
self.target_output_bandwidth = Some(output_bps);
self
}
#[must_use]
pub fn strict(mut self) -> Self {
self.strict_mode = true;
self
}
}
#[derive(Debug, Clone)]
pub struct WorkUnit {
pub id: u64,
pub data: Bytes,
pub submitted_at: Instant,
}
#[derive(Debug, Clone)]
pub struct WorkHandle {
pub id: u64,
pub write_handle: WriteHandle,
pub submitted_at: Instant,
}
#[derive(Debug)]
pub struct CompletedWork {
pub id: u64,
pub data: Bytes,
pub latency: std::time::Duration,
}
#[derive(Debug, Clone, Default)]
pub struct PipelineStats {
pub submitted: u64,
pub completed: u64,
pub input_bytes: u64,
pub output_bytes: u64,
pub avg_latency_ns: u64,
pub max_latency_ns: u64,
pub input_throughput: f64,
pub output_throughput: f64,
pub throttle_delay_ns: u64,
}
struct BandwidthThrottler {
target_bps: u64,
window_bytes: u64,
window_start: Instant,
window_duration: std::time::Duration,
}
const DEFAULT_THROTTLE_WINDOW_SECS: u64 = 1;
impl BandwidthThrottler {
fn new(target_bps: u64) -> Self {
Self {
target_bps,
window_bytes: 0,
window_start: Instant::now(),
window_duration: std::time::Duration::from_secs(DEFAULT_THROTTLE_WINDOW_SECS),
}
}
fn check(&mut self, bytes: u64) -> Option<std::time::Duration> {
let now = Instant::now();
let elapsed = now.duration_since(self.window_start);
if elapsed >= self.window_duration {
self.window_bytes = 0;
self.window_start = now;
return None;
}
if self.window_bytes + bytes > self.target_bps {
let remaining = self.window_duration.saturating_sub(elapsed);
Some(remaining)
} else {
None
}
}
fn record(&mut self, bytes: u64) {
self.window_bytes += bytes;
}
}
pub struct UnidirectionalPipeline {
device: Arc<WgpuDevice>,
input_buffer: GpuRingBuffer,
output_buffer: GpuRingBuffer,
config: UnidirectionalConfig,
next_id: AtomicU64,
in_flight: VecDeque<(u64, Instant)>,
stats: PipelineStats,
input_throttler: Option<BandwidthThrottler>,
#[expect(
dead_code,
reason = "phase 5+: parity with input_throttler for bandwidth simulation"
)]
output_throttler: Option<BandwidthThrottler>,
start_time: Instant,
}
impl UnidirectionalPipeline {
pub fn new(device: Arc<WgpuDevice>, config: UnidirectionalConfig) -> Result<Self> {
let input_config = RingBufferConfig::new(config.input_buffer_size)
.for_input()
.with_label("UnidirectionalInput");
let output_config = RingBufferConfig::new(config.output_buffer_size)
.for_output()
.with_label("UnidirectionalOutput");
let input_buffer = GpuRingBuffer::new(device.clone(), input_config)?;
let output_buffer = GpuRingBuffer::new(device.clone(), output_config)?;
let input_throttler = config.target_input_bandwidth.map(BandwidthThrottler::new);
let output_throttler = config.target_output_bandwidth.map(BandwidthThrottler::new);
tracing::info!(
"Created unidirectional pipeline: input={}MB, output={}MB, strict={}",
config.input_buffer_size / (1024 * 1024),
config.output_buffer_size / (1024 * 1024),
config.strict_mode
);
Ok(Self {
device,
input_buffer,
output_buffer,
config,
next_id: AtomicU64::new(1),
in_flight: VecDeque::new(),
stats: PipelineStats::default(),
input_throttler,
output_throttler,
start_time: Instant::now(),
})
}
pub fn submit(&mut self, data: &[u8]) -> Result<WorkHandle> {
let id = self.next_id.fetch_add(1, Ordering::Relaxed);
let now = Instant::now();
if let Some(throttler) = &mut self.input_throttler {
if let Some(delay) = throttler.check(data.len() as u64) {
if self.config.strict_mode {
return Err(BarracudaError::execution_failed(format!(
"Strict mode: input bandwidth exceeded, would need {}ms delay",
delay.as_millis()
)));
}
self.stats.throttle_delay_ns += delay.as_nanos() as u64;
tracing::trace!(
"Input throttle: {}ms delay for {} bytes",
delay.as_millis(),
data.len()
);
}
throttler.record(data.len() as u64);
}
let write_handle = self.input_buffer.write(data)?;
self.in_flight.push_back((id, now));
self.stats.submitted += 1;
self.stats.input_bytes += data.len() as u64;
self.update_throughput();
Ok(WorkHandle {
id,
write_handle,
submitted_at: now,
})
}
pub fn try_submit(&mut self, data: &[u8]) -> Option<WorkHandle> {
let id = self.next_id.fetch_add(1, Ordering::Relaxed);
let now = Instant::now();
if let Some(throttler) = &mut self.input_throttler {
if throttler.check(data.len() as u64).is_some() {
return None; }
throttler.record(data.len() as u64);
}
let write_handle = self.input_buffer.try_write(data)?;
self.in_flight.push_back((id, now));
self.stats.submitted += 1;
self.stats.input_bytes += data.len() as u64;
Some(WorkHandle {
id,
write_handle,
submitted_at: now,
})
}
pub fn mark_input_consumed(&mut self, bytes: usize) {
self.input_buffer.advance_read(bytes);
}
pub fn mark_completed(&mut self, id: u64, output_size: usize) -> Option<std::time::Duration> {
if let Some(pos) = self.in_flight.iter().position(|(wid, _)| *wid == id) {
let (_, submitted_at) = self.in_flight.remove(pos)?;
let latency = submitted_at.elapsed();
self.stats.completed += 1;
self.stats.output_bytes += output_size as u64;
let latency_ns = latency.as_nanos() as u64;
if self.stats.completed == 1 {
self.stats.avg_latency_ns = latency_ns;
} else {
let n = self.stats.completed;
self.stats.avg_latency_ns = (self.stats.avg_latency_ns * (n - 1) + latency_ns) / n;
}
self.stats.max_latency_ns = self.stats.max_latency_ns.max(latency_ns);
self.update_throughput();
Some(latency)
} else {
tracing::warn!("Unknown work ID {} marked complete", id);
None
}
}
pub fn stats(&self) -> &PipelineStats {
&self.stats
}
pub fn input_gpu_buffer(&self) -> &wgpu::Buffer {
self.input_buffer.gpu_buffer()
}
pub fn output_gpu_buffer(&self) -> &wgpu::Buffer {
self.output_buffer.gpu_buffer()
}
pub fn input_available(&self) -> usize {
self.input_buffer.available_write()
}
pub fn output_available(&self) -> usize {
self.output_buffer.available_read()
}
pub fn advance_output(&mut self, bytes: usize) {
self.output_buffer.advance_write(bytes);
}
pub async fn poll_results(&mut self, max: Option<usize>) -> Result<Vec<CompletedWork>> {
let available = self.output_buffer.available_read();
if available == 0 || self.in_flight.is_empty() {
return Ok(Vec::new());
}
let data = self.output_buffer.read(Some(available)).await?;
if data.is_empty() {
return Ok(Vec::new());
}
let limit = max
.unwrap_or(self.in_flight.len())
.min(self.in_flight.len());
let mut results = Vec::with_capacity(limit);
let chunk_size = data.len().checked_div(limit).unwrap_or(0);
for i in 0..limit {
if let Some((id, submitted_at)) = self.in_flight.pop_front() {
let start = i * chunk_size;
let end = if i + 1 == limit {
data.len()
} else {
(i + 1) * chunk_size
};
let chunk = data.slice(start..end);
let latency = submitted_at.elapsed();
let latency_ns = latency.as_nanos() as u64;
self.stats.completed += 1;
self.stats.output_bytes += chunk.len() as u64;
if self.stats.completed == 1 {
self.stats.avg_latency_ns = latency_ns;
} else {
let n = self.stats.completed;
self.stats.avg_latency_ns =
(self.stats.avg_latency_ns * (n - 1) + latency_ns) / n;
}
self.stats.max_latency_ns = self.stats.max_latency_ns.max(latency_ns);
results.push(CompletedWork {
id,
data: chunk,
latency,
});
}
}
self.update_throughput();
Ok(results)
}
pub fn in_flight_count(&self) -> usize {
self.in_flight.len()
}
pub fn reset(&mut self) {
self.input_buffer.reset();
self.output_buffer.reset();
self.in_flight.clear();
self.stats = PipelineStats::default();
self.start_time = Instant::now();
tracing::info!("Unidirectional pipeline reset");
}
pub fn config(&self) -> &UnidirectionalConfig {
&self.config
}
pub fn device(&self) -> &Arc<WgpuDevice> {
&self.device
}
fn update_throughput(&mut self) {
let elapsed = self.start_time.elapsed().as_secs_f64();
if elapsed > 0.0 {
self.stats.input_throughput = self.stats.input_bytes as f64 / elapsed;
self.stats.output_throughput = self.stats.output_bytes as f64 / elapsed;
}
}
}
impl std::fmt::Debug for UnidirectionalPipeline {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("UnidirectionalPipeline")
.field("input_buffer", &self.input_buffer)
.field("output_buffer", &self.output_buffer)
.field("in_flight", &self.in_flight.len())
.field("stats", &self.stats)
.finish()
}
}
#[cfg(test)]
mod tests {
#![expect(clippy::unwrap_used, reason = "tests")]
use super::*;
use crate::device::test_pool::get_test_device_if_gpu_available;
use std::sync::Arc;
#[test]
fn test_config_defaults() {
let config = UnidirectionalConfig::default();
assert_eq!(config.input_bandwidth_fraction, 0.9);
assert!(!config.strict_mode);
}
#[test]
fn test_config_with_sizes() {
let config =
UnidirectionalConfig::with_sizes(LARGE_INPUT_BUFFER_MB, LARGE_OUTPUT_BUFFER_MB);
assert_eq!(
config.input_buffer_size,
LARGE_INPUT_BUFFER_MB * BYTES_PER_MB
);
assert_eq!(
config.output_buffer_size,
LARGE_OUTPUT_BUFFER_MB * BYTES_PER_MB
);
}
#[test]
fn test_config_throttling() {
let gbps_10 = 10_000_000_000u64; let gbps_1 = 1_000_000_000u64;
let config = UnidirectionalConfig::default().with_throttling(gbps_10, gbps_1);
assert_eq!(config.target_input_bandwidth, Some(gbps_10));
assert_eq!(config.target_output_bandwidth, Some(gbps_1));
}
#[test]
fn test_bandwidth_throttler() {
let mut throttler = BandwidthThrottler::new(THROTTLE_TEST_BPS);
assert!(throttler.check(500).is_none());
throttler.record(500);
assert!(throttler.check(400).is_none());
throttler.record(400);
assert!(throttler.check(200).is_some());
}
#[tokio::test]
async fn test_unidirectional_pipeline_new_requires_gpu() {
let Some(device) = get_test_device_if_gpu_available().await else {
return;
};
let config = UnidirectionalConfig::with_sizes(4, 2);
let pipeline = UnidirectionalPipeline::new(Arc::clone(&device), config).unwrap();
assert_eq!(pipeline.in_flight_count(), 0);
}
#[tokio::test]
async fn test_unidirectional_pipeline_submit_try_submit() {
let Some(device) = get_test_device_if_gpu_available().await else {
return;
};
let config = UnidirectionalConfig::with_sizes(4, 2);
let mut pipeline = UnidirectionalPipeline::new(Arc::clone(&device), config).unwrap();
let handle = pipeline.submit(b"hello").unwrap();
assert_eq!(handle.id, 1);
assert_eq!(handle.write_handle.size, 5);
let handle2 = pipeline.try_submit(b"world").unwrap();
assert_eq!(handle2.id, 2);
assert_eq!(pipeline.in_flight_count(), 2);
}
#[tokio::test]
async fn test_unidirectional_pipeline_mark_completed() {
let Some(device) = get_test_device_if_gpu_available().await else {
return;
};
let config = UnidirectionalConfig::with_sizes(4, 2);
let mut pipeline = UnidirectionalPipeline::new(Arc::clone(&device), config).unwrap();
let handle = pipeline.submit(b"hello").unwrap();
let latency = pipeline.mark_completed(handle.id, 5);
assert!(latency.is_some());
assert_eq!(pipeline.in_flight_count(), 0);
assert_eq!(pipeline.stats().completed, 1);
}
#[tokio::test]
async fn test_unidirectional_pipeline_mark_completed_unknown_id_returns_none() {
let Some(device) = get_test_device_if_gpu_available().await else {
return;
};
let config = UnidirectionalConfig::with_sizes(4, 2);
let mut pipeline = UnidirectionalPipeline::new(Arc::clone(&device), config).unwrap();
let result = pipeline.mark_completed(999, 0);
assert!(result.is_none());
}
#[tokio::test]
async fn test_unidirectional_pipeline_mark_input_consumed_reset() {
let Some(device) = get_test_device_if_gpu_available().await else {
return;
};
let config = UnidirectionalConfig::with_sizes(4, 2);
let mut pipeline = UnidirectionalPipeline::new(Arc::clone(&device), config).unwrap();
pipeline.submit(b"hello").unwrap();
pipeline.mark_input_consumed(5);
pipeline.reset();
assert_eq!(pipeline.in_flight_count(), 0);
}
#[tokio::test]
async fn test_unidirectional_pipeline_stats() {
let Some(device) = get_test_device_if_gpu_available().await else {
return;
};
let config = UnidirectionalConfig::with_sizes(4, 2);
let mut pipeline = UnidirectionalPipeline::new(Arc::clone(&device), config).unwrap();
pipeline.submit(b"hello").unwrap();
let stats = pipeline.stats();
assert_eq!(stats.submitted, 1);
assert_eq!(stats.input_bytes, 5);
}
#[tokio::test]
async fn test_unidirectional_pipeline_debug() {
let Some(device) = get_test_device_if_gpu_available().await else {
return;
};
let config = UnidirectionalConfig::with_sizes(4, 2);
let pipeline = UnidirectionalPipeline::new(Arc::clone(&device), config).unwrap();
let s = format!("{pipeline:?}");
assert!(s.contains("UnidirectionalPipeline"));
}
}