ailloli_ui_bench/session.rs
1//! Bounded asynchronous benchmark sessions and atomic JSONL publication.
2//!
3//! Producers never block on file I/O: records enter a bounded `sync_channel`
4//! with `try_send`. Queue overflow permanently invalidates the run. A dedicated
5//! writer periodically flushes staging data, then finalization writes `run_end`,
6//! syncs, and renames the staging file without overwriting a destination.
7
8use std::fs::{create_dir_all, rename, File, OpenOptions};
9use std::io::{BufWriter, Write};
10use std::num::NonZeroUsize;
11use std::path::{Path, PathBuf};
12use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
13use std::sync::mpsc::{self, RecvTimeoutError, SyncSender, TrySendError};
14use std::sync::{Arc, Mutex, Weak};
15use std::thread::{self, JoinHandle};
16use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
17
18use once_cell::sync::Lazy;
19use sha2::{Digest, Sha256};
20use thiserror::Error;
21
22use crate::model::{
23 BenchEventRecord, Event, EventContext, EventId, FrameId, MetadataUpdateRecord, RunEndRecord,
24 RunId, RunMetadata, RunStartRecord, WireRecord, SCHEMA_VERSION,
25};
26
27/// Process-local sequence mixed into generated run identifiers.
28static RUN_SEQUENCE: AtomicU64 = AtomicU64::new(1);
29
30/// Bounds the amount of valid staging data held only in userspace buffers.
31///
32/// The flush runs exclusively on the dedicated writer thread, so it never
33/// extends an instrumented producer span. Durability (`sync_all`) remains a
34/// finalization concern immediately before atomic publication.
35const WRITER_FLUSH_INTERVAL: Duration = Duration::from_millis(250);
36
37/// Result of environment-driven benchmark initialization.
38///
39/// # Examples
40///
41/// ```
42/// use ailloli_ui_bench::BenchInit;
43/// let init = BenchInit::Disabled;
44/// assert!(init.path().is_none());
45/// ```
46#[derive(Debug)]
47pub enum BenchInit {
48 /// Benchmark collection was not requested.
49 Disabled,
50 /// Benchmark collection is active. Keep the session alive for the whole run.
51 Enabled(BenchSession),
52}
53
54impl BenchInit {
55 /// Finishes an enabled session. Disabled collection returns `Ok(None)`.
56 ///
57 /// # Errors
58 ///
59 /// Propagates writer, flush, sync, validity, and publication failures from
60 /// an enabled session.
61 ///
62 /// # Examples
63 ///
64 /// ```
65 /// use ailloli_ui_bench::BenchInit;
66 /// assert_eq!(BenchInit::Disabled.finish()?, None);
67 /// # Ok::<(), ailloli_ui_bench::BenchWriteError>(())
68 /// ```
69 pub fn finish(self) -> Result<Option<CompletedRun>, BenchWriteError> {
70 match self {
71 Self::Disabled => Ok(None),
72 Self::Enabled(session) => session.finish().map(Some),
73 }
74 }
75
76 /// Returns the final output path when collection is enabled.
77 ///
78 /// # Examples
79 ///
80 /// ```
81 /// use ailloli_ui_bench::BenchInit;
82 /// assert!(BenchInit::Disabled.path().is_none());
83 /// ```
84 pub fn path(&self) -> Option<&Path> {
85 match self {
86 Self::Disabled => None,
87 Self::Enabled(session) => Some(session.path()),
88 }
89 }
90
91 /// Borrows the active session when collection is enabled.
92 ///
93 /// # Examples
94 ///
95 /// ```
96 /// use ailloli_ui_bench::BenchInit;
97 /// assert!(BenchInit::Disabled.session().is_none());
98 /// ```
99 pub fn session(&self) -> Option<&BenchSession> {
100 match self {
101 Self::Disabled => None,
102 Self::Enabled(session) => Some(session),
103 }
104 }
105}
106
107/// Failure while creating a benchmark session.
108///
109/// # Examples
110///
111/// ```
112/// let error = ailloli_ui_bench::BenchInitError::InvalidOutputPath;
113/// assert!(error.to_string().contains("must name a file"));
114/// ```
115#[derive(Debug, Error)]
116#[non_exhaustive]
117pub enum BenchInitError {
118 #[error("benchmark output path must name a file")]
119 /// Output path has no UTF-8 file name component.
120 InvalidOutputPath,
121 #[error("benchmark metadata field {0} must be finite")]
122 /// Initial floating-point metadata was invalid.
123 InvalidMetadata(&'static str),
124 #[error("benchmark destination already exists: {0}")]
125 /// Final destination existed before session creation.
126 DestinationExists(PathBuf),
127 #[error("benchmark staging file already exists: {0}")]
128 /// Collision with the generated partial-file path.
129 StagingExists(PathBuf),
130 #[error("another global benchmark recorder is already active")]
131 /// Global initialization would replace another session or legacy recorder.
132 AlreadyInitialized,
133 #[error("failed to create benchmark output directory")]
134 /// Parent directory creation failed.
135 CreateDirectory(#[source] std::io::Error),
136 #[error("failed to create benchmark staging file")]
137 /// Exclusive staging-file creation failed.
138 CreateStaging(#[source] std::io::Error),
139 #[error("failed to serialize or write run_start")]
140 /// Initial `run_start` serialization or write failed.
141 WriteRunStart(#[source] BenchWriteError),
142 #[error("failed to spawn benchmark writer")]
143 /// Dedicated writer thread could not be spawned.
144 SpawnWriter(#[source] std::io::Error),
145}
146
147/// Failure while recording or finalizing a benchmark run.
148///
149/// Queue overflow and non-finite input increment `dropped_records`, so the
150/// staging artifact remains diagnostic but cannot be published as gate-valid.
151///
152/// # Examples
153///
154/// ```
155/// let error = ailloli_ui_bench::BenchWriteError::QueueFull;
156/// assert!(error.to_string().contains("run is invalid"));
157/// ```
158#[derive(Debug, Error)]
159#[non_exhaustive]
160pub enum BenchWriteError {
161 #[error("benchmark session is closed")]
162 /// The session no longer accepts records or was already finished.
163 Closed,
164 #[error("benchmark writer queue is full; the run is invalid")]
165 /// Nonblocking enqueue found the bounded queue full.
166 QueueFull,
167 #[error("benchmark writer stopped before accepting the record")]
168 /// Writer channel disconnected or the writer previously failed.
169 WriterStopped,
170 #[error("benchmark numeric field {field} must be finite; the run is invalid")]
171 /// A finite-number invariant failed before JSON serialization.
172 NonFiniteValue {
173 /// Stable field path identifying the invalid value.
174 field: &'static str,
175 },
176 #[error("failed to serialize a benchmark record")]
177 /// JSON serialization failed.
178 Serialize(#[source] serde_json::Error),
179 #[error("failed to write benchmark data")]
180 /// Staging-file write failed.
181 Write(#[source] std::io::Error),
182 #[error("failed to flush benchmark data")]
183 /// Periodic or final buffer flush failed.
184 Flush(#[source] std::io::Error),
185 #[error("failed to sync benchmark data")]
186 /// Final staging-file `sync_all` failed.
187 Sync(#[source] std::io::Error),
188 #[error("benchmark writer thread panicked")]
189 /// Joining the writer observed a panic.
190 WriterPanicked,
191 #[error("benchmark destination appeared before publication: {0}")]
192 /// Another actor created the destination during the run.
193 DestinationExists(PathBuf),
194 #[error("failed to publish benchmark output atomically")]
195 /// Final staging-file rename failed.
196 Publish(#[source] std::io::Error),
197 /// One or more records were dropped, so only the diagnostic staging artifact remains.
198 #[error("benchmark run is invalid because {dropped_records} record(s) were dropped; diagnostics remain at {staging_path}")]
199 InvalidRun {
200 /// Partial artifact retained for diagnostics.
201 staging_path: PathBuf,
202 /// Total queue drops plus a missing finish message.
203 dropped_records: u64,
204 },
205}
206
207/// Successfully published benchmark artifact.
208///
209/// # Examples
210///
211/// ```
212/// use ailloli_ui_bench::{CompletedRun, RunId};
213/// let run = CompletedRun {
214/// path: "run.jsonl".into(),
215/// run_id: RunId::new("run"),
216/// sha256: "00".repeat(32),
217/// records_written: 2,
218/// };
219/// assert_eq!(run.sha256.len(), 64);
220/// ```
221#[derive(Debug, Clone, PartialEq, Eq)]
222pub struct CompletedRun {
223 /// Final atomically published artifact path.
224 pub path: PathBuf,
225 /// Run identifier serialized into every wire record.
226 pub run_id: RunId,
227 /// Lowercase SHA-256 of every published JSONL byte, including newlines.
228 pub sha256: String,
229 /// Total wire records including `run_start` and `run_end`.
230 pub records_written: u64,
231}
232
233/// Shared producer state retained by the session and global weak reference.
234#[derive(Debug)]
235struct SessionCore {
236 /// Stable identity shared by all wire records.
237 run_id: RunId,
238 /// Reserved final destination.
239 path: PathBuf,
240 /// Unique diagnostic partial-file path.
241 staging_path: PathBuf,
242 /// Monotonic origin for record `elapsed_us`.
243 started: Instant,
244 /// Bounded nonblocking producer channel.
245 sender: SyncSender<WriterMessage>,
246 /// Serializes identifier allocation with queue insertion so the on-disk
247 /// event sequence is deterministic even when producers run concurrently.
248 record_order: Mutex<()>,
249 /// Next event ID; starts at one and uses atomic fetch-add.
250 next_event_id: AtomicU64,
251 /// Next frame ID; starts at one and uses atomic fetch-add.
252 next_frame_id: AtomicU64,
253 /// Rejected records that make publication invalid.
254 dropped_records: AtomicU64,
255 /// Whether producers may still enqueue work.
256 accepting: AtomicBool,
257 /// Sticky signal that the writer failed or disconnected.
258 writer_failed: AtomicBool,
259}
260
261impl SessionCore {
262 /// Validates, identifies, serializes, and nonblockingly queues one event.
263 ///
264 /// Identifier allocation and enqueue are serialized across producers so
265 /// accepted records remain sequential on disk.
266 ///
267 /// # Errors
268 ///
269 /// Returns [`BenchWriteError::Closed`] after finalization,
270 /// [`BenchWriteError::NonFiniteValue`] for invalid numeric event data,
271 /// [`BenchWriteError::Serialize`] for JSON conversion failure, or the queue
272 /// capacity/disconnection errors documented by [`Self::enqueue`].
273 fn record(&self, event: Event, context: EventContext) -> Result<EventId, BenchWriteError> {
274 let _order = self
275 .record_order
276 .lock()
277 .unwrap_or_else(std::sync::PoisonError::into_inner);
278 if !self.accepting.load(Ordering::Acquire) {
279 return Err(BenchWriteError::Closed);
280 }
281 if let Some(field) = non_finite_event_field(&event) {
282 self.dropped_records.fetch_add(1, Ordering::Relaxed);
283 return Err(BenchWriteError::NonFiniteValue { field });
284 }
285 let event_id = EventId::new(self.next_event_id.fetch_add(1, Ordering::Relaxed));
286 let event = serde_json::to_value(event).map_err(BenchWriteError::Serialize)?;
287 let record = BenchEventRecord {
288 schema_version: SCHEMA_VERSION,
289 run_id: self.run_id.clone(),
290 event_id,
291 elapsed_us: self.started.elapsed().as_micros(),
292 context,
293 event,
294 };
295 self.enqueue(WireRecord::Event(record))?;
296 Ok(event_id)
297 }
298
299 /// Validates and queues a sparse metadata overlay in producer order.
300 ///
301 /// # Errors
302 ///
303 /// Returns [`BenchWriteError::Closed`] after finalization,
304 /// [`BenchWriteError::NonFiniteValue`] for invalid numeric metadata, or the
305 /// queue capacity/disconnection errors documented by [`Self::enqueue`].
306 fn update_metadata(&self, metadata: RunMetadata) -> Result<(), BenchWriteError> {
307 let _order = self
308 .record_order
309 .lock()
310 .unwrap_or_else(std::sync::PoisonError::into_inner);
311 if !self.accepting.load(Ordering::Acquire) {
312 return Err(BenchWriteError::Closed);
313 }
314 if let Some(field) = non_finite_metadata_field(&metadata) {
315 self.dropped_records.fetch_add(1, Ordering::Relaxed);
316 return Err(BenchWriteError::NonFiniteValue { field });
317 }
318 let record = MetadataUpdateRecord {
319 schema_version: SCHEMA_VERSION,
320 run_id: self.run_id.clone(),
321 elapsed_us: self.started.elapsed().as_micros(),
322 metadata,
323 };
324 self.enqueue(WireRecord::MetadataUpdate(record))
325 }
326
327 /// Allocates a run-local frame identifier without queueing a record.
328 fn allocate_frame_id(&self) -> FrameId {
329 FrameId::new(self.next_frame_id.fetch_add(1, Ordering::Relaxed))
330 }
331
332 /// Attempts one nonblocking queue insertion and records sticky failures.
333 ///
334 /// # Errors
335 ///
336 /// Returns [`BenchWriteError::Closed`] when producers are no longer accepted,
337 /// [`BenchWriteError::WriterStopped`] after writer failure/disconnection, or
338 /// [`BenchWriteError::QueueFull`] when the bounded channel has no capacity.
339 fn enqueue(&self, record: WireRecord) -> Result<(), BenchWriteError> {
340 if !self.accepting.load(Ordering::Acquire) {
341 return Err(BenchWriteError::Closed);
342 }
343 if self.writer_failed.load(Ordering::Acquire) {
344 return Err(BenchWriteError::WriterStopped);
345 }
346
347 match self
348 .sender
349 .try_send(WriterMessage::Record(Box::new(record)))
350 {
351 Ok(()) => Ok(()),
352 Err(TrySendError::Full(_)) => {
353 self.dropped_records.fetch_add(1, Ordering::Relaxed);
354 Err(BenchWriteError::QueueFull)
355 }
356 Err(TrySendError::Disconnected(_)) => {
357 self.writer_failed.store(true, Ordering::Release);
358 Err(BenchWriteError::WriterStopped)
359 }
360 }
361 }
362}
363
364/// Commands accepted by the dedicated writer thread.
365#[derive(Debug)]
366enum WriterMessage {
367 /// Serialize one boxed record in channel order.
368 Record(Box<WireRecord>),
369 /// Write the terminal record, sync, and publish.
370 Finish,
371}
372
373/// Guard for a single, explicitly finalized benchmark run.
374///
375/// Dropping an unfinished session performs best-effort finalization but discards
376/// errors. Gate integrations should always call [`Self::finish`].
377///
378/// # Examples
379///
380/// ```no_run
381/// use std::num::NonZeroUsize;
382/// use ailloli_ui_bench::{BenchSession, RunMetadata};
383/// let session = BenchSession::start(
384/// "artifacts/bench/run.jsonl",
385/// RunMetadata::default(),
386/// NonZeroUsize::new(4096).unwrap(),
387/// )?;
388/// let completed = session.finish()?;
389/// assert_eq!(completed.sha256.len(), 64);
390/// # Ok::<(), Box<dyn std::error::Error>>(())
391/// ```
392#[derive(Debug)]
393pub struct BenchSession {
394 /// Shared producer state; global registration retains only a weak reference.
395 core: Arc<SessionCore>,
396 /// Join handle consumed exactly once during finalization.
397 worker: Option<JoinHandle<Result<CompletedRun, BenchWriteError>>>,
398}
399
400impl BenchSession {
401 /// Starts a local session which does not replace the global compatibility sink.
402 ///
403 /// The destination must not exist. Parent directories are created, while a
404 /// unique `.partial-<run-id>` file is created exclusively. `capacity` bounds
405 /// pending writer messages and cannot be zero by type.
406 ///
407 /// # Errors
408 ///
409 /// Returns [`BenchInitError`] for invalid/non-finite metadata, invalid or
410 /// occupied paths, filesystem failures, initial write failure, or thread
411 /// spawn failure.
412 ///
413 /// # Examples
414 ///
415 /// ```no_run
416 /// use std::num::NonZeroUsize;
417 /// use ailloli_ui_bench::{BenchSession, RunMetadata};
418 /// let session = BenchSession::start(
419 /// "artifacts/bench/local.jsonl",
420 /// RunMetadata::default(),
421 /// NonZeroUsize::new(128).unwrap(),
422 /// )?;
423 /// # session.finish()?;
424 /// # Ok::<(), Box<dyn std::error::Error>>(())
425 /// ```
426 pub fn start(
427 path: impl AsRef<Path>,
428 metadata: RunMetadata,
429 capacity: NonZeroUsize,
430 ) -> Result<Self, BenchInitError> {
431 Self::start_inner(path.as_ref(), metadata, capacity)
432 }
433
434 /// Starts a session and installs a weak reference in the process-global sink.
435 ///
436 /// # Errors
437 ///
438 /// Returns [`BenchInitError::AlreadyInitialized`] when the global slot is
439 /// active, poisoned, or changes during initialization. Otherwise propagates
440 /// every path, metadata, filesystem, initial-write, or writer-spawn failure
441 /// documented by [`Self::start`].
442 ///
443 /// # Examples
444 ///
445 /// ```no_run
446 /// // Environment-driven initialization uses the same exclusive global slot.
447 /// let init = ailloli_ui_bench::try_init_from_env("run.jsonl")?;
448 /// let _ = init.path();
449 /// # Ok::<(), ailloli_ui_bench::BenchInitError>(())
450 /// ```
451 pub(crate) fn start_global(
452 path: impl AsRef<Path>,
453 metadata: RunMetadata,
454 capacity: NonZeroUsize,
455 ) -> Result<Self, BenchInitError> {
456 {
457 let mut global = GLOBAL
458 .lock()
459 .map_err(|_| BenchInitError::AlreadyInitialized)?;
460 global.clear_dead_session();
461 if global.is_active() {
462 return Err(BenchInitError::AlreadyInitialized);
463 }
464 *global = GlobalSink::Initializing;
465 }
466
467 let session = match Self::start_inner(path.as_ref(), metadata, capacity) {
468 Ok(session) => session,
469 Err(error) => {
470 if let Ok(mut global) = GLOBAL.lock() {
471 if matches!(*global, GlobalSink::Initializing) {
472 *global = GlobalSink::Empty;
473 }
474 }
475 return Err(error);
476 }
477 };
478 let mut global = GLOBAL
479 .lock()
480 .map_err(|_| BenchInitError::AlreadyInitialized)?;
481 if !matches!(*global, GlobalSink::Initializing) {
482 return Err(BenchInitError::AlreadyInitialized);
483 }
484 *global = GlobalSink::Session(Arc::downgrade(&session.core));
485 Ok(session)
486 }
487
488 /// Validates paths/metadata, writes `run_start`, and spawns the writer.
489 ///
490 /// # Errors
491 ///
492 /// Returns the matching [`BenchInitError`] for non-finite metadata, an
493 /// invalid/existing destination or staging path, directory/file creation,
494 /// initial-record serialization/write, or writer-thread spawn failure.
495 fn start_inner(
496 path: &Path,
497 metadata: RunMetadata,
498 capacity: NonZeroUsize,
499 ) -> Result<Self, BenchInitError> {
500 if let Some(field) = non_finite_metadata_field(&metadata) {
501 return Err(BenchInitError::InvalidMetadata(field));
502 }
503 let path = path.to_path_buf();
504 let Some(file_name) = path.file_name().and_then(|name| name.to_str()) else {
505 return Err(BenchInitError::InvalidOutputPath);
506 };
507 if path.exists() {
508 return Err(BenchInitError::DestinationExists(path));
509 }
510 if let Some(parent) = path
511 .parent()
512 .filter(|parent| !parent.as_os_str().is_empty())
513 {
514 create_dir_all(parent).map_err(BenchInitError::CreateDirectory)?;
515 }
516
517 let run_id = generate_run_id();
518 let staging_path = path.with_file_name(format!("{file_name}.partial-{}", run_id.as_str()));
519 if staging_path.exists() {
520 return Err(BenchInitError::StagingExists(staging_path));
521 }
522
523 let file = OpenOptions::new()
524 .create_new(true)
525 .write(true)
526 .open(&staging_path)
527 .map_err(BenchInitError::CreateStaging)?;
528 let mut writer = BufWriter::new(file);
529 let mut hasher = Sha256::new();
530 let run_start = WireRecord::RunStart(RunStartRecord {
531 schema_version: SCHEMA_VERSION,
532 run_id: run_id.clone(),
533 started_unix_ms: unix_time_ms(),
534 metadata,
535 });
536 write_wire_record(&mut writer, &mut hasher, &run_start)
537 .map_err(BenchInitError::WriteRunStart)?;
538
539 let (sender, receiver) = mpsc::sync_channel(capacity.get());
540 let core = Arc::new(SessionCore {
541 run_id: run_id.clone(),
542 path: path.clone(),
543 staging_path: staging_path.clone(),
544 started: Instant::now(),
545 sender,
546 record_order: Mutex::new(()),
547 next_event_id: AtomicU64::new(1),
548 next_frame_id: AtomicU64::new(1),
549 dropped_records: AtomicU64::new(0),
550 accepting: AtomicBool::new(true),
551 writer_failed: AtomicBool::new(false),
552 });
553 let worker_core = Arc::clone(&core);
554 let worker = thread::Builder::new()
555 .name("ailloli-ui-bench-writer".to_string())
556 .spawn(move || {
557 let result = writer_loop(writer, hasher, receiver, &worker_core);
558 if result.is_err() {
559 worker_core.writer_failed.store(true, Ordering::Release);
560 }
561 result
562 })
563 .map_err(BenchInitError::SpawnWriter)?;
564
565 Ok(Self {
566 core,
567 worker: Some(worker),
568 })
569 }
570
571 /// Records an uncorrelated payload, returning its assigned event identifier.
572 ///
573 /// # Errors
574 ///
575 /// Returns `Closed`, `QueueFull`, `WriterStopped`, `NonFiniteValue`, or a
576 /// serialization error. Queue/full-value rejection invalidates the run.
577 ///
578 /// # Examples
579 ///
580 /// ```no_run
581 /// use ailloli_ui_bench::{BenchSession, Event};
582 /// fn mark(session: &BenchSession) -> Result<(), ailloli_ui_bench::BenchWriteError> {
583 /// let id = session.record(Event::Marker { ts_ms: 1, name: "ready".into() })?;
584 /// assert_eq!(id.get(), 1);
585 /// Ok(())
586 /// }
587 /// ```
588 pub fn record(&self, event: Event) -> Result<EventId, BenchWriteError> {
589 self.record_with_context(event, EventContext::default())
590 }
591
592 /// Records a payload and its provider-neutral correlation context.
593 ///
594 /// Accepted event IDs are allocated in on-disk order, starting at one.
595 ///
596 /// # Errors
597 ///
598 /// Returns the same validation, queue, lifecycle, and serialization errors
599 /// as [`Self::record`].
600 ///
601 /// # Examples
602 ///
603 /// ```no_run
604 /// use ailloli_ui_bench::{BenchSession, Event, EventContext, FrameId};
605 /// fn mark(session: &BenchSession) -> Result<(), ailloli_ui_bench::BenchWriteError> {
606 /// session.record_with_context(
607 /// Event::Marker { ts_ms: 1, name: "paint".into() },
608 /// EventContext::default().with_frame(FrameId::new(1)),
609 /// )?;
610 /// Ok(())
611 /// }
612 /// ```
613 pub fn record_with_context(
614 &self,
615 event: Event,
616 context: EventContext,
617 ) -> Result<EventId, BenchWriteError> {
618 self.core.record(event, context)
619 }
620
621 /// Publishes a partial metadata update discovered after startup.
622 ///
623 /// `None` fields do not erase prior metadata when read back.
624 ///
625 /// # Errors
626 ///
627 /// Rejects non-finite scale metadata and propagates queue/lifecycle errors.
628 ///
629 /// # Examples
630 ///
631 /// ```no_run
632 /// use ailloli_ui_bench::{BenchSession, RunMetadata};
633 /// fn update(session: &BenchSession) -> Result<(), ailloli_ui_bench::BenchWriteError> {
634 /// let mut metadata = RunMetadata::default();
635 /// metadata.gpu = Some("adapter".into());
636 /// session.update_metadata(metadata)
637 /// }
638 /// ```
639 pub fn update_metadata(&self, metadata: RunMetadata) -> Result<(), BenchWriteError> {
640 self.core.update_metadata(metadata)
641 }
642
643 /// Allocates a frame identifier unique within this run.
644 ///
645 /// IDs start at one and allocation itself does not write a record.
646 ///
647 /// # Examples
648 ///
649 /// ```no_run
650 /// use ailloli_ui_bench::{BenchSession, FrameId};
651 /// fn allocate(session: &BenchSession) -> FrameId {
652 /// session.allocate_frame_id()
653 /// }
654 /// ```
655 pub fn allocate_frame_id(&self) -> FrameId {
656 self.core.allocate_frame_id()
657 }
658
659 /// Returns the final path. It does not exist until successful finalization.
660 ///
661 /// # Examples
662 ///
663 /// ```no_run
664 /// use ailloli_ui_bench::BenchSession;
665 /// fn path(session: &BenchSession) -> &std::path::Path { session.path() }
666 /// ```
667 pub fn path(&self) -> &Path {
668 &self.core.path
669 }
670
671 /// Returns the diagnostic staging path.
672 ///
673 /// The staging file exists during the run and is retained on an invalid
674 /// run. Successful publication renames it to [`Self::path`].
675 ///
676 /// # Examples
677 ///
678 /// ```no_run
679 /// use ailloli_ui_bench::BenchSession;
680 /// fn path(session: &BenchSession) -> &std::path::Path { session.staging_path() }
681 /// ```
682 pub fn staging_path(&self) -> &Path {
683 &self.core.staging_path
684 }
685
686 /// Returns this session's run identifier.
687 ///
688 /// # Examples
689 ///
690 /// ```no_run
691 /// use ailloli_ui_bench::{BenchSession, RunId};
692 /// fn id(session: &BenchSession) -> &RunId { session.run_id() }
693 /// ```
694 pub fn run_id(&self) -> &RunId {
695 &self.core.run_id
696 }
697
698 /// Flushes, syncs, and atomically publishes the run.
699 ///
700 /// The method consumes the session, stops acceptance, writes a terminal
701 /// record, joins the writer, and renames the partial file only when no record
702 /// was dropped. The destination is never overwritten.
703 ///
704 /// # Errors
705 ///
706 /// Returns typed writer/join/flush/sync/invalid-run/destination/publication
707 /// errors. Invalid runs retain their staging path.
708 ///
709 /// # Examples
710 ///
711 /// ```no_run
712 /// use ailloli_ui_bench::{BenchSession, CompletedRun};
713 /// fn finish(session: BenchSession) -> Result<CompletedRun, ailloli_ui_bench::BenchWriteError> {
714 /// session.finish()
715 /// }
716 /// ```
717 pub fn finish(mut self) -> Result<CompletedRun, BenchWriteError> {
718 self.finish_inner()
719 }
720
721 /// Shared explicit/drop finalization path; may be called only once.
722 ///
723 /// # Errors
724 ///
725 /// Returns [`BenchWriteError::Closed`] after the worker was already taken,
726 /// [`BenchWriteError::WriterPanicked`] if it unwinds,
727 /// [`BenchWriteError::WriterStopped`] if finish delivery fails before an
728 /// otherwise successful worker result, or the worker's flush/publication error.
729 fn finish_inner(&mut self) -> Result<CompletedRun, BenchWriteError> {
730 let Some(worker) = self.worker.take() else {
731 return Err(BenchWriteError::Closed);
732 };
733 let finish_sent = {
734 let _order = self
735 .core
736 .record_order
737 .lock()
738 .unwrap_or_else(std::sync::PoisonError::into_inner);
739 self.core.accepting.store(false, Ordering::Release);
740 clear_global_session(&self.core);
741 self.core.sender.send(WriterMessage::Finish).is_ok()
742 };
743 let result = worker.join().map_err(|_| BenchWriteError::WriterPanicked)?;
744 if !finish_sent && result.is_ok() {
745 return Err(BenchWriteError::WriterStopped);
746 }
747 result
748 }
749}
750
751impl Drop for BenchSession {
752 fn drop(&mut self) {
753 if self.worker.is_some() {
754 let _ = self.finish_inner();
755 }
756 }
757}
758
759/// Drains records, periodically flushes, writes `run_end`, and publishes.
760///
761/// A disconnected channel without `Finish` counts as one dropped record. Counts
762/// saturate rather than wrap. `sync_all` precedes the non-overwriting rename;
763/// invalid runs return with staging data intact.
764///
765/// # Errors
766///
767/// Returns the matching [`BenchWriteError`] for record serialization/write,
768/// periodic/final flush, file synchronization, dropped records, an existing
769/// final destination, or atomic publication rename failure.
770fn writer_loop(
771 mut writer: BufWriter<File>,
772 mut hasher: Sha256,
773 receiver: mpsc::Receiver<WriterMessage>,
774 core: &SessionCore,
775) -> Result<CompletedRun, BenchWriteError> {
776 let mut records_written = 1_u64;
777 let mut received_finish = false;
778 let mut dirty = true;
779 let mut last_flush = Instant::now();
780
781 loop {
782 let wait = WRITER_FLUSH_INTERVAL.saturating_sub(last_flush.elapsed());
783 match receiver.recv_timeout(wait) {
784 Ok(WriterMessage::Record(record)) => {
785 write_wire_record(&mut writer, &mut hasher, &record)?;
786 records_written = records_written.saturating_add(1);
787 dirty = true;
788 if last_flush.elapsed() >= WRITER_FLUSH_INTERVAL {
789 writer.flush().map_err(BenchWriteError::Flush)?;
790 dirty = false;
791 last_flush = Instant::now();
792 }
793 }
794 Ok(WriterMessage::Finish) => {
795 received_finish = true;
796 break;
797 }
798 Err(RecvTimeoutError::Timeout) => {
799 if dirty {
800 writer.flush().map_err(BenchWriteError::Flush)?;
801 dirty = false;
802 }
803 last_flush = Instant::now();
804 }
805 Err(RecvTimeoutError::Disconnected) => break,
806 }
807 }
808
809 let dropped_records =
810 core.dropped_records.load(Ordering::Acquire) + u64::from(!received_finish);
811 let valid = dropped_records == 0;
812 let total_records = records_written.saturating_add(1);
813 let run_end = WireRecord::RunEnd(RunEndRecord {
814 schema_version: SCHEMA_VERSION,
815 run_id: core.run_id.clone(),
816 elapsed_us: core.started.elapsed().as_micros(),
817 valid,
818 dropped_records,
819 records_written: total_records,
820 });
821 write_wire_record(&mut writer, &mut hasher, &run_end)?;
822 writer.flush().map_err(BenchWriteError::Flush)?;
823 writer.get_ref().sync_all().map_err(BenchWriteError::Sync)?;
824 drop(writer);
825
826 if !valid {
827 return Err(BenchWriteError::InvalidRun {
828 staging_path: core.staging_path.clone(),
829 dropped_records,
830 });
831 }
832 if core.path.exists() {
833 return Err(BenchWriteError::DestinationExists(core.path.clone()));
834 }
835 rename(&core.staging_path, &core.path).map_err(BenchWriteError::Publish)?;
836
837 Ok(CompletedRun {
838 path: core.path.clone(),
839 run_id: core.run_id.clone(),
840 sha256: hex_digest(hasher.finalize().as_slice()),
841 records_written: total_records,
842 })
843}
844
845/// Serializes one compact JSON object plus newline, then hashes identical bytes.
846///
847/// # Errors
848///
849/// Returns [`BenchWriteError::Serialize`] when JSON encoding fails or
850/// [`BenchWriteError::Write`] when the complete encoded line cannot be written.
851fn write_wire_record(
852 writer: &mut BufWriter<File>,
853 hasher: &mut Sha256,
854 record: &WireRecord,
855) -> Result<(), BenchWriteError> {
856 let mut bytes = serde_json::to_vec(record).map_err(BenchWriteError::Serialize)?;
857 bytes.push(b'\n');
858 writer.write_all(&bytes).map_err(BenchWriteError::Write)?;
859 hasher.update(&bytes);
860 Ok(())
861}
862
863/// Encodes arbitrary bytes as two lowercase hexadecimal characters each.
864fn hex_digest(bytes: &[u8]) -> String {
865 /// Lowercase hexadecimal digit table.
866 const HEX: &[u8; 16] = b"0123456789abcdef";
867 let mut output = String::with_capacity(bytes.len() * 2);
868 for byte in bytes {
869 output.push(HEX[(byte >> 4) as usize] as char);
870 output.push(HEX[(byte & 0x0f) as usize] as char);
871 }
872 output
873}
874
875/// Generates a process/time/sequence run ID unique within practical process use.
876///
877/// The sequence prevents collisions within one process at identical nanoseconds;
878/// wall clocks before the epoch contribute zero.
879fn generate_run_id() -> RunId {
880 let sequence = RUN_SEQUENCE.fetch_add(1, Ordering::Relaxed);
881 let nanos = SystemTime::now()
882 .duration_since(UNIX_EPOCH)
883 .unwrap_or_default()
884 .as_nanos();
885 RunId::new(format!("{}-{nanos}-{sequence}", std::process::id()))
886}
887
888/// Returns wall-clock milliseconds since Unix epoch, mapping pre-epoch to zero.
889fn unix_time_ms() -> u128 {
890 SystemTime::now()
891 .duration_since(UNIX_EPOCH)
892 .unwrap_or_default()
893 .as_millis()
894}
895
896/// Returns the first invalid floating-point metadata field.
897///
898/// Requested scale rejects non-finite values; observed scale additionally must
899/// be strictly positive.
900fn non_finite_metadata_field(metadata: &RunMetadata) -> Option<&'static str> {
901 if metadata
902 .scale_factor
903 .is_some_and(|value| !value.is_finite())
904 {
905 return Some("scale_factor");
906 }
907 metadata
908 .observed_scale_factor
909 .is_some_and(|value| !value.is_finite() || value <= 0.0)
910 .then_some("observed_scale_factor")
911}
912
913/// Returns the first event field that would serialize as non-finite JSON.
914fn non_finite_event_field(event: &Event) -> Option<&'static str> {
915 match event {
916 Event::Metric { value, .. } if !value.is_finite() => Some("metric.value"),
917 Event::IsolatedCompositorFrame {
918 pool_reuse_ratio, ..
919 } if !pool_reuse_ratio.is_finite() => Some("isolated_compositor.pool_reuse_ratio"),
920 _ => None,
921 }
922}
923
924#[derive(Debug)]
925/// Mutable state protected by [`Recorder`]'s mutex.
926///
927/// # Examples
928///
929/// ```no_run
930/// // Public callers access this state through the locking `Recorder` facade.
931/// let recorder = ailloli_ui_bench::Recorder::new("legacy.jsonl")?;
932/// assert_eq!(recorder.path(), std::path::PathBuf::from("legacy.jsonl"));
933/// # Ok::<(), std::io::Error>(())
934/// ```
935pub(crate) struct RecorderInner {
936 /// Append-only destination path.
937 path: PathBuf,
938 /// Buffered append writer.
939 writer: BufWriter<File>,
940}
941
942/// Legacy append-only JSONL writer.
943///
944/// This compatibility type is intentionally non-gating: record/flush/lock
945/// failures are discarded, events have no run envelope or correlation IDs, and
946/// existing files are appended rather than protected from overwrite.
947///
948/// # Examples
949///
950/// ```no_run
951/// use ailloli_ui_bench::Recorder;
952/// let recorder = Recorder::new("artifacts/bench/legacy.jsonl")?;
953/// assert!(recorder.path().ends_with("legacy.jsonl"));
954/// # Ok::<(), std::io::Error>(())
955/// ```
956#[derive(Debug)]
957pub struct Recorder {
958 /// Serialized writer, path, schema, and frame-correlation state.
959 inner: Mutex<RecorderInner>,
960}
961
962impl Recorder {
963 /// Opens or creates `path` for append.
964 ///
965 /// Parent directories are created when needed.
966 ///
967 /// # Errors
968 ///
969 /// Propagates directory creation or append-open failures.
970 ///
971 /// # Examples
972 ///
973 /// ```no_run
974 /// let recorder = ailloli_ui_bench::Recorder::new("artifacts/bench/legacy.jsonl")?;
975 /// let _ = recorder.path();
976 /// # Ok::<(), std::io::Error>(())
977 /// ```
978 pub fn new(path: impl AsRef<Path>) -> std::io::Result<Self> {
979 let path = path.as_ref().to_path_buf();
980 if let Some(parent) = path
981 .parent()
982 .filter(|parent| !parent.as_os_str().is_empty())
983 {
984 create_dir_all(parent)?;
985 }
986 let file = OpenOptions::new().create(true).append(true).open(&path)?;
987 Ok(Self {
988 inner: Mutex::new(RecorderInner {
989 path,
990 writer: BufWriter::new(file),
991 }),
992 })
993 }
994
995 /// Appends one legacy event. Errors remain non-gating for compatibility.
996 ///
997 /// A successful event is immediately newline-terminated and flushed.
998 ///
999 /// # Examples
1000 ///
1001 /// ```no_run
1002 /// use ailloli_ui_bench::{Event, Recorder};
1003 /// let recorder = Recorder::new("legacy.jsonl")?;
1004 /// recorder.record(&Event::Marker { ts_ms: 1, name: "ready".into() });
1005 /// # Ok::<(), std::io::Error>(())
1006 /// ```
1007 pub fn record(&self, event: &Event) {
1008 let Ok(mut inner) = self.inner.lock() else {
1009 return;
1010 };
1011 if serde_json::to_writer(&mut inner.writer, event).is_ok() {
1012 let _ = inner.writer.write_all(b"\n");
1013 let _ = inner.writer.flush();
1014 }
1015 }
1016
1017 /// Output file path.
1018 ///
1019 /// Returns an empty path if the mutex is poisoned.
1020 ///
1021 /// # Examples
1022 ///
1023 /// ```no_run
1024 /// let recorder = ailloli_ui_bench::Recorder::new("legacy.jsonl")?;
1025 /// assert_eq!(recorder.path(), std::path::PathBuf::from("legacy.jsonl"));
1026 /// # Ok::<(), std::io::Error>(())
1027 /// ```
1028 pub fn path(&self) -> PathBuf {
1029 self.inner
1030 .lock()
1031 .map(|inner| inner.path.clone())
1032 .unwrap_or_default()
1033 }
1034}
1035
1036/// Process-global recorder lifecycle state protected by [`GLOBAL`].
1037#[derive(Debug, Default)]
1038enum GlobalSink {
1039 #[default]
1040 /// No global recorder is installed.
1041 Empty,
1042 /// A global session is being created outside the mutex.
1043 Initializing,
1044 /// Weak reference that does not keep a gating session alive.
1045 Session(Weak<SessionCore>),
1046 /// Historical append-only recorder.
1047 Legacy(Recorder),
1048}
1049
1050impl GlobalSink {
1051 /// Reclaims a session slot whose last strong reference was dropped.
1052 fn clear_dead_session(&mut self) {
1053 if matches!(self, Self::Session(session) if session.strong_count() == 0) {
1054 *self = Self::Empty;
1055 }
1056 }
1057
1058 /// Returns whether any initialization/session/legacy state owns the slot.
1059 fn is_active(&self) -> bool {
1060 !matches!(self, Self::Empty)
1061 }
1062}
1063
1064/// Single process-global recorder slot.
1065static GLOBAL: Lazy<Mutex<GlobalSink>> = Lazy::new(|| Mutex::new(GlobalSink::Empty));
1066
1067/// Installs the append-only compatibility recorder if the global slot is empty.
1068///
1069/// # Errors
1070///
1071/// Returns [`BenchInitError::AlreadyInitialized`] when a session/legacy recorder
1072/// already owns the global slot or its mutex is poisoned.
1073///
1074/// # Examples
1075///
1076/// ```no_run
1077/// #![allow(deprecated)]
1078/// // `init_from_env` creates and installs the same legacy sink when enabled.
1079/// let _path = ailloli_ui_bench::init_from_env("legacy.jsonl");
1080/// ```
1081pub(crate) fn install_legacy(recorder: Recorder) -> Result<(), BenchInitError> {
1082 let mut global = GLOBAL
1083 .lock()
1084 .map_err(|_| BenchInitError::AlreadyInitialized)?;
1085 global.clear_dead_session();
1086 if global.is_active() {
1087 return Err(BenchInitError::AlreadyInitialized);
1088 }
1089 *global = GlobalSink::Legacy(recorder);
1090 Ok(())
1091}
1092
1093/// Dispatches an event to the active gating session or legacy/global no-op.
1094///
1095/// # Errors
1096///
1097/// Returns [`BenchWriteError::WriterStopped`] if the global slot is poisoned, or
1098/// propagates [`BenchWriteError::NonFiniteValue`], `Closed`, `QueueFull`, and
1099/// `WriterStopped` from the active gating session. No active or legacy-only sink
1100/// returns `Ok(None)`.
1101///
1102/// # Examples
1103///
1104/// ```no_run
1105/// use ailloli_ui_bench::{try_record, Event, EventContext};
1106/// let _id = try_record(
1107/// Event::Marker { ts_ms: 1, name: "ready".into() },
1108/// EventContext::default(),
1109/// )?;
1110/// # Ok::<(), ailloli_ui_bench::BenchWriteError>(())
1111/// ```
1112pub(crate) fn record_global(
1113 event: Event,
1114 context: EventContext,
1115) -> Result<Option<EventId>, BenchWriteError> {
1116 /// Owned dispatch decision used after releasing the global mutex.
1117 enum Sink {
1118 /// Active gating session.
1119 Session(Arc<SessionCore>),
1120 /// A legacy recorder already accepted the event.
1121 Legacy,
1122 /// No active correlation-capable sink.
1123 Empty,
1124 }
1125
1126 let sink = {
1127 let mut global = GLOBAL.lock().map_err(|_| BenchWriteError::WriterStopped)?;
1128 global.clear_dead_session();
1129 match &*global {
1130 GlobalSink::Session(session) => session.upgrade().map_or(Sink::Empty, Sink::Session),
1131 GlobalSink::Legacy(recorder) => {
1132 recorder.record(&event);
1133 Sink::Legacy
1134 }
1135 GlobalSink::Initializing | GlobalSink::Empty => Sink::Empty,
1136 }
1137 };
1138
1139 match sink {
1140 Sink::Session(session) => session.record(event, context).map(Some),
1141 Sink::Legacy | Sink::Empty => Ok(None),
1142 }
1143}
1144
1145/// Queues a metadata overlay on the active global gating session.
1146///
1147/// # Errors
1148///
1149/// Returns [`BenchWriteError::WriterStopped`] when the global slot or active
1150/// writer is unavailable, [`BenchWriteError::Closed`] when the session stopped
1151/// accepting updates, [`BenchWriteError::NonFiniteValue`] for invalid metadata,
1152/// or [`BenchWriteError::QueueFull`] when the bounded queue cannot accept it.
1153///
1154/// # Examples
1155///
1156/// ```no_run
1157/// let accepted = ailloli_ui_bench::try_update_metadata(
1158/// ailloli_ui_bench::RunMetadata::default(),
1159/// )?;
1160/// let _ = accepted;
1161/// # Ok::<(), ailloli_ui_bench::BenchWriteError>(())
1162/// ```
1163pub(crate) fn update_global_metadata(metadata: RunMetadata) -> Result<bool, BenchWriteError> {
1164 let session = active_global_session()?;
1165 match session {
1166 Some(session) => {
1167 session.update_metadata(metadata)?;
1168 Ok(true)
1169 }
1170 None => Ok(false),
1171 }
1172}
1173
1174/// Allocates a frame ID from the active global gating session.
1175///
1176/// # Errors
1177///
1178/// Returns [`BenchWriteError::WriterStopped`] when the global sink mutex is
1179/// poisoned. An absent, legacy, initializing, or expired session is not an
1180/// error and returns `Ok(None)`.
1181///
1182/// # Examples
1183///
1184/// ```no_run
1185/// let id: Option<ailloli_ui_bench::FrameId> =
1186/// ailloli_ui_bench::try_allocate_frame_id()?;
1187/// let _ = id;
1188/// # Ok::<(), ailloli_ui_bench::BenchWriteError>(())
1189/// ```
1190pub(crate) fn allocate_global_frame_id() -> Result<Option<FrameId>, BenchWriteError> {
1191 Ok(active_global_session()?.map(|session| session.allocate_frame_id()))
1192}
1193
1194/// Upgrades and returns the active global session without holding the mutex.
1195///
1196/// # Errors
1197///
1198/// Returns [`BenchWriteError::WriterStopped`] when the global sink mutex is
1199/// poisoned. Missing, initializing, legacy, or expired sessions return `Ok(None)`.
1200fn active_global_session() -> Result<Option<Arc<SessionCore>>, BenchWriteError> {
1201 let mut global = GLOBAL.lock().map_err(|_| BenchWriteError::WriterStopped)?;
1202 global.clear_dead_session();
1203 match &*global {
1204 GlobalSink::Session(session) => Ok(session.upgrade()),
1205 GlobalSink::Legacy(_) | GlobalSink::Initializing | GlobalSink::Empty => Ok(None),
1206 }
1207}
1208
1209/// Clears the global slot only when it still points to `core`.
1210fn clear_global_session(core: &Arc<SessionCore>) {
1211 let Ok(mut global) = GLOBAL.lock() else {
1212 return;
1213 };
1214 let should_clear = match &*global {
1215 GlobalSink::Session(session) => session
1216 .upgrade()
1217 .is_some_and(|active| Arc::ptr_eq(&active, core)),
1218 _ => false,
1219 };
1220 if should_clear {
1221 *global = GlobalSink::Empty;
1222 }
1223}
1224
1225#[cfg(test)]
1226/// Verifies digest/run IDs plus queue and non-finite invalidation behavior.
1227mod tests {
1228 use super::*;
1229
1230 #[test]
1231 fn hex_digest_is_lowercase() {
1232 assert_eq!(hex_digest(&[0x00, 0xab, 0xff]), "00abff");
1233 }
1234
1235 #[test]
1236 fn generated_run_ids_are_unique() {
1237 assert_ne!(generate_run_id(), generate_run_id());
1238 }
1239
1240 #[test]
1241 fn full_queue_marks_the_run_invalid_without_blocking() {
1242 let (sender, _receiver) = mpsc::sync_channel(1);
1243 let core = SessionCore {
1244 run_id: RunId::new("queue-test"),
1245 path: PathBuf::from("unused.jsonl"),
1246 staging_path: PathBuf::from("unused.partial"),
1247 started: Instant::now(),
1248 sender,
1249 record_order: Mutex::new(()),
1250 next_event_id: AtomicU64::new(1),
1251 next_frame_id: AtomicU64::new(1),
1252 dropped_records: AtomicU64::new(0),
1253 accepting: AtomicBool::new(true),
1254 writer_failed: AtomicBool::new(false),
1255 };
1256 core.record(
1257 Event::Marker {
1258 ts_ms: 1,
1259 name: "accepted".to_string(),
1260 },
1261 EventContext::default(),
1262 )
1263 .unwrap();
1264 let error = core
1265 .record(
1266 Event::Marker {
1267 ts_ms: 2,
1268 name: "dropped".to_string(),
1269 },
1270 EventContext::default(),
1271 )
1272 .unwrap_err();
1273 assert!(matches!(error, BenchWriteError::QueueFull));
1274 assert_eq!(core.dropped_records.load(Ordering::Relaxed), 1);
1275 }
1276
1277 #[test]
1278 fn non_finite_metric_marks_the_run_invalid_before_json_serialization() {
1279 let (sender, _receiver) = mpsc::sync_channel(1);
1280 let core = SessionCore {
1281 run_id: RunId::new("finite-test"),
1282 path: PathBuf::from("unused.jsonl"),
1283 staging_path: PathBuf::from("unused.partial"),
1284 started: Instant::now(),
1285 sender,
1286 record_order: Mutex::new(()),
1287 next_event_id: AtomicU64::new(1),
1288 next_frame_id: AtomicU64::new(1),
1289 dropped_records: AtomicU64::new(0),
1290 accepting: AtomicBool::new(true),
1291 writer_failed: AtomicBool::new(false),
1292 };
1293 let error = core
1294 .record(
1295 Event::Metric {
1296 ts_ms: 1,
1297 name: "bad".to_string(),
1298 value: f64::NAN,
1299 role: crate::MetricRole::Diagnostic,
1300 },
1301 EventContext::default(),
1302 )
1303 .unwrap_err();
1304 assert!(matches!(
1305 error,
1306 BenchWriteError::NonFiniteValue {
1307 field: "metric.value"
1308 }
1309 ));
1310 assert_eq!(core.dropped_records.load(Ordering::Relaxed), 1);
1311 }
1312}