[−][src]Crate measureme
This crate provides a library for high-performance event tracing which is used by the Rust compiler's unstable -Z self-profile
feature.
There are two main parts to this library:
- Writing event trace files
- Reading event trace files
The output of a tracing session will be three files:
- A
.events
file which contains all of the traced events. - A
.string_data
file which contains all the strings referenced by events. - A
.string_index
file which mapsStringId
values to offsets into the.string_data
file.
Writing event trace files
The main entry point for writing event trace files is the Profiler
struct.
To create a Profiler
, call the Profiler::new()
function and provide a Path
with the directory and file name for the trace files.
To record an event, call the Profiler::record_event()
method, passing a few arguments:
event_kind
: aStringId
which assigns an arbitrary category to the eventevent_id
: aStringId
which specifies the name of the eventthread_id
: au64
id of the thread which is recording this eventtimestamp_kind
: aTimestampKind
which specifies how this event should be treated bymeasureme
tooling
Alternatively, events can also be recorded via the Profiler::start_recording_interval_event()
method. This
method records a "start" event and returns a TimingGuard
object that will automatically record
the corresponding "end" event when it is dropped.
To create a StringId
, call one of the string allocation methods:
Profiler::alloc_string()
: allocates a string and returns theStringId
that refers to itProfiler::alloc_string_with_reserved_id()
: allocates a string using the specifiedStringId
. It is up to the caller to make sure the specifiedStringId
hasn't already been used.
Reading event trace files
The main entry point for reading trace files is the ProfilingData
struct.
To create a ProfilingData
, call the ProfilingData::new()
function and provide a Path
with the directory and file name for the trace files.
To retrieve an Iterator
of all of the events in the file, call the ProfilingData::iter()
method.
To retrieve an Iterator
of only matching start/stop events, call the ProfilingData::iter_matching_events()
method.
Modules
rustc | This module contains functionality specific to to the measureme integration with rustc |
testing_common |
Structs
Addr | |
Event | |
FileSerializationSink | |
MmapSerializationSink | |
Profiler | |
ProfilerFiles | |
ProfilingData | |
RawEvent | |
StringId | A |
StringRef | |
StringTable | Read-only version of the string table |
StringTableBuilder | Write-only version of the string table |
Timestamp | |
TimingGuard | When dropped, this |
Enums
MatchingEvent | |
TimestampKind |
Traits
SerializableString | Anything that implements |
SerializationSink |