pub struct BenchSession { /* private fields */ }Expand description
Guard for a single, explicitly finalized benchmark run.
Dropping an unfinished session performs best-effort finalization but discards
errors. Gate integrations should always call Self::finish.
§Examples
use std::num::NonZeroUsize;
use ailloli_ui_bench::{BenchSession, RunMetadata};
let session = BenchSession::start(
"artifacts/bench/run.jsonl",
RunMetadata::default(),
NonZeroUsize::new(4096).unwrap(),
)?;
let completed = session.finish()?;
assert_eq!(completed.sha256.len(), 64);Implementations§
Source§impl BenchSession
impl BenchSession
Sourcepub fn start(
path: impl AsRef<Path>,
metadata: RunMetadata,
capacity: NonZeroUsize,
) -> Result<Self, BenchInitError>
pub fn start( path: impl AsRef<Path>, metadata: RunMetadata, capacity: NonZeroUsize, ) -> Result<Self, BenchInitError>
Starts a local session which does not replace the global compatibility sink.
The destination must not exist. Parent directories are created, while a
unique .partial-<run-id> file is created exclusively. capacity bounds
pending writer messages and cannot be zero by type.
§Errors
Returns BenchInitError for invalid/non-finite metadata, invalid or
occupied paths, filesystem failures, initial write failure, or thread
spawn failure.
§Examples
use std::num::NonZeroUsize;
use ailloli_ui_bench::{BenchSession, RunMetadata};
let session = BenchSession::start(
"artifacts/bench/local.jsonl",
RunMetadata::default(),
NonZeroUsize::new(128).unwrap(),
)?;Sourcepub fn record(&self, event: Event) -> Result<EventId, BenchWriteError>
pub fn record(&self, event: Event) -> Result<EventId, BenchWriteError>
Records an uncorrelated payload, returning its assigned event identifier.
§Errors
Returns Closed, QueueFull, WriterStopped, NonFiniteValue, or a
serialization error. Queue/full-value rejection invalidates the run.
§Examples
use ailloli_ui_bench::{BenchSession, Event};
fn mark(session: &BenchSession) -> Result<(), ailloli_ui_bench::BenchWriteError> {
let id = session.record(Event::Marker { ts_ms: 1, name: "ready".into() })?;
assert_eq!(id.get(), 1);
Ok(())
}Sourcepub fn record_with_context(
&self,
event: Event,
context: EventContext,
) -> Result<EventId, BenchWriteError>
pub fn record_with_context( &self, event: Event, context: EventContext, ) -> Result<EventId, BenchWriteError>
Records a payload and its provider-neutral correlation context.
Accepted event IDs are allocated in on-disk order, starting at one.
§Errors
Returns the same validation, queue, lifecycle, and serialization errors
as Self::record.
§Examples
use ailloli_ui_bench::{BenchSession, Event, EventContext, FrameId};
fn mark(session: &BenchSession) -> Result<(), ailloli_ui_bench::BenchWriteError> {
session.record_with_context(
Event::Marker { ts_ms: 1, name: "paint".into() },
EventContext::default().with_frame(FrameId::new(1)),
)?;
Ok(())
}Sourcepub fn update_metadata(
&self,
metadata: RunMetadata,
) -> Result<(), BenchWriteError>
pub fn update_metadata( &self, metadata: RunMetadata, ) -> Result<(), BenchWriteError>
Publishes a partial metadata update discovered after startup.
None fields do not erase prior metadata when read back.
§Errors
Rejects non-finite scale metadata and propagates queue/lifecycle errors.
§Examples
use ailloli_ui_bench::{BenchSession, RunMetadata};
fn update(session: &BenchSession) -> Result<(), ailloli_ui_bench::BenchWriteError> {
let mut metadata = RunMetadata::default();
metadata.gpu = Some("adapter".into());
session.update_metadata(metadata)
}Sourcepub fn allocate_frame_id(&self) -> FrameId
pub fn allocate_frame_id(&self) -> FrameId
Allocates a frame identifier unique within this run.
IDs start at one and allocation itself does not write a record.
§Examples
use ailloli_ui_bench::{BenchSession, FrameId};
fn allocate(session: &BenchSession) -> FrameId {
session.allocate_frame_id()
}Sourcepub fn path(&self) -> &Path
pub fn path(&self) -> &Path
Returns the final path. It does not exist until successful finalization.
§Examples
use ailloli_ui_bench::BenchSession;
fn path(session: &BenchSession) -> &std::path::Path { session.path() }Sourcepub fn staging_path(&self) -> &Path
pub fn staging_path(&self) -> &Path
Returns the diagnostic staging path.
The staging file exists during the run and is retained on an invalid
run. Successful publication renames it to Self::path.
§Examples
use ailloli_ui_bench::BenchSession;
fn path(session: &BenchSession) -> &std::path::Path { session.staging_path() }Sourcepub fn run_id(&self) -> &RunId
pub fn run_id(&self) -> &RunId
Returns this session’s run identifier.
§Examples
use ailloli_ui_bench::{BenchSession, RunId};
fn id(session: &BenchSession) -> &RunId { session.run_id() }Sourcepub fn finish(self) -> Result<CompletedRun, BenchWriteError>
pub fn finish(self) -> Result<CompletedRun, BenchWriteError>
Flushes, syncs, and atomically publishes the run.
The method consumes the session, stops acceptance, writes a terminal record, joins the writer, and renames the partial file only when no record was dropped. The destination is never overwritten.
§Errors
Returns typed writer/join/flush/sync/invalid-run/destination/publication errors. Invalid runs retain their staging path.
§Examples
use ailloli_ui_bench::{BenchSession, CompletedRun};
fn finish(session: BenchSession) -> Result<CompletedRun, ailloli_ui_bench::BenchWriteError> {
session.finish()
}