1//! This crate provides a library for high-performance event tracing which is used by
2//! the Rust compiler's unstable `-Z self-profile` feature.
3//!
4//! The output of a tracing session will be an `.mm_profdata` file containing a stream
5//! of events and a string table that allows to decode the `StringId`s in the event stream.
6//!
7//! # Writing event trace files
8//!
9//! The main entry point for writing event trace files is the [`Profiler`] struct.
10//!
11//! To create a [`Profiler`], call the [`Profiler::new()`] function and provide a `Path` with
12//! the directory and file name for the trace files.
13//! Alternatively, call the [`Profiler::with_counter()`] function, to choose the [`Counter`]
14//! the profiler will use for events (whereas [`Profiler::new()`] defaults to `wall-time`).
15//!
16//! For more information on available counters, see the [`counters`] module documentation.
17//!
18//! To record an event, call the [`Profiler::record_instant_event()`] method, passing a few
19//! arguments:
20//! - `event_kind`: a [`StringId`] which assigns an arbitrary category to the event
21//! - `event_id`: a [`StringId`] which specifies the name of the event
22//! - `thread_id`: a `u32` id of the thread which is recording this event
23//!
24//! Alternatively, events can also be recorded via the
25//! [`Profiler::start_recording_interval_event()`] method. This method records a "start" event and
26//! returns a `TimingGuard` object that will automatically record the corresponding "end" event
27//! when it is dropped.
28//!
29//! To create a [`StringId`], call one of the string allocation methods:
30//! - [`Profiler::alloc_string()`]: allocates a string and returns the [`StringId`] that refers
31//! to it
32//!
33//! [`Counter`]: counters::Counter
34#![deny(warnings)]
35
36#[macro_use]
37extern crate log;
38
39pub mod counters;
40pub mod event_id;
41pub mod file_header;
42mod profiler;
43mod raw_event;
44mod serialization;
45pub mod stringtable;
46
47pub mod rustc;
48
49pub use crate::event_id::{EventId, EventIdBuilder};
50pub use crate::profiler::{DetachedTiming, Profiler, TimingGuard};
51pub use crate::raw_event::{RawEvent, MAX_INTERVAL_VALUE, MAX_SINGLE_VALUE};
52pub use crate::serialization::{
53 split_streams, Addr, PageTag, SerializationSink, SerializationSinkBuilder,
54};
55pub use crate::stringtable::{SerializableString, StringComponent, StringId, StringTableBuilder};
56