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}