Struct tracy_client::Client

pub struct Client(/* private fields */);

A type representing an enabled Tracy client.

Obtaining a Client is required in order to instrument the application.

Multiple copies of a Client may be live at once. As long as at least one Client value lives, the Tracy client is enabled globally. In addition to collecting information through the instrumentation inserted by you, the Tracy client may automatically collect information about execution of the program while it is enabled. All this information may be stored in memory until a profiler application connects to the client to read the data.

Depending on the build configuration, the client may collect and make available machine and source code of the application as well as other potentially sensitive information.

When all of the Client values are dropped, the underlying Tracy client will be shut down as well. Shutting down the Client will discard any information gathered up to that point that still hasn’t been delivered to the profiler application.

Implementations

impl Client

Instrumentation for global frame indicators.

pub fn frame_mark(&self)

Indicate that rendering of a continuous frame has ended.

Examples

In a traditional rendering scenarios a frame mark should be inserted after a buffer swap.

use tracy_client::Client;
// loop {
//     ...
       swap_buffers();
       Client::running().expect("client must be running").frame_mark();
// }

pub fn secondary_frame_mark(&self, name: FrameName)

Indicate that rendering of a secondary (named) continuous frame has ended.

Examples

Much like with the primary frame mark, the secondary (named) frame mark should be inserted after some continuously repeating operation finishes one iteration of its processing.

use tracy_client::frame_name;
// loop {
//     ...
       physics_tick();
       tracy_client::Client::running()
           .expect("client must be running")
           .secondary_frame_mark(frame_name!("physics"));
// }

pub fn non_continuous_frame(&self, name: FrameName) -> Frame

Indicate that a processing of a non-continuous frame has begun.

Dropping the returned Frame will terminate the non-continuous frame.

Examples

use tracy_client::frame_name;
let _guard = tracy_client::Client::running()
    .expect("client must be running")
    .non_continuous_frame(frame_name!("a frame"));

impl Client

pub fn new_gpu_context( self, name: Option<&str>, ty: GpuContextType, gpu_timestamp: i64, period: f32, ) -> Result<GpuContext, GpuContextCreationError>

Creates a new GPU context.

• name is the name of the context.
• ty is the type (backend) of the context.
• gpu_timestamp is the gpu side timestamp the corresponds (as close as possible) to this call.
• period is the period of the gpu clock in nanoseconds (setting 1.0 means the clock is 1GHz, 1000.0 means 1MHz, etc).

See the type level documentation for more information.

Errors

• If more than 255 contexts were made during the lifetime of the application.

impl Client

Instrumentation for drawing 2D plots.

pub fn plot(&self, plot_name: PlotName, value: f64)

Add a point with an y-axis value of value to the plot named plot_name.

Examples

tracy_client::Client::running()
    .expect("client must be running")
    .plot(tracy_client::plot_name!("temperature"), 37.0);

impl Client

Instrumentation for timed regions, spans or zones of execution.

pub fn span(self, loc: &'static SpanLocation, callstack_depth: u16) -> Span

Start a new Tracy span/zone.

In order to obtain a SpanLocation value to provide to this function use the span_location! macro.

Specifying a non-zero callstack_depth will enable collection of callstack for this message. The number provided will limit the number of call frames collected. Note that enabling callstack collection introduces a non-trivial amount of overhead to this call. On some systems this value may be clamped to a maximum value supported by the target.

The span! macro is a convenience wrapper over this method.

Example

In the following example the span is created with the location at which the span_location! macro appears and will measure the execution of the 100ms long sleep.

use tracy_client::{Client, span_location};
let client = Client::start();
{
    let _span = client.span(span_location!("sleeping"), 100);
    std::thread::sleep(std::time::Duration::from_millis(100));
} // _span ends

pub fn span_alloc( self, name: Option<&str>, function: &str, file: &str, line: u32, callstack_depth: u16, ) -> Span

Start a new Tracy span/zone.

This function allocates the span information on the heap until it is read out by the profiler. Prefer the Client::span as a allocation-free and faster alternative when possible.

Specifying a non-zero callstack_depth will enable collection of callstack for this message. The number provided will limit the number of call frames collected. Note that enabling callstack collection introduces a non-trivial amount of overhead to this call. On some systems this value may be clamped to a maximum value supported by the target.

Example

In the following example the span is created with custom span source data and will measure the execution of the 100ms long sleep.

use tracy_client::Client;
let client = Client::start();
{
    let _span = client.span_alloc(Some("hello"), "my_function", "hello.rs", 42, 100);
    std::thread::sleep(std::time::Duration::from_millis(100));
} // _span ends

impl Client

Client initialization and lifetime management.

pub fn start() -> Self

Start the client.

The client must be started with this function before any instrumentation is invoked anywhere in the process. This function can be called multiple times to obtain multiple Client values.

The underlying client implementation will be started up only if it wasn’t already running yet.

Note that when the manual-lifetime feature is used, it is a responsibility of the user to stop tracy using the sys::___tracy_shutdown_profiler function. Keep in mind that at the time this function is called there can be no other invocations to the tracy profiler, even from other threads (or you may get a crash!)

Example

// fn main() {
    let _client = tracy_client::Client::start();
    // ...
// }

pub fn running() -> Option<Self>

Obtain a client handle, but only if the client is already running.

pub fn is_running() -> bool

Is the client already running?

impl Client

Instrumentation methods for outputting events occurring at a specific instant.

Data provided by this instrumentation can largely be considered to be equivalent to logs.

pub fn message(&self, message: &str, callstack_depth: u16)

Output a message.

Specifying a non-zero callstack_depth will enable collection of callstack for this message. The number provided will limit the number of call frames collected. Note that enabling callstack collection introduces a non-trivial amount of overhead to this call.

pub fn color_message(&self, message: &str, rgba: u32, callstack_depth: u16)

Output a message with an associated color.

Specifying a non-zero callstack_depth will enable collection of callstack for this message. The number provided will limit the number of call frames collected. Note that enabling callstack collection introduces a non-trivial amount of overhead to this call.

The colour shall be provided as RGBA, where the least significant 8 bits represent the alpha component and most significant 8 bits represent the red component.

impl Client

pub fn set_thread_name(&self, name: &str)

Set the current thread name to the provided value.

Panics

This function will panic if the name contains interior null characters.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Self

A cheaper alternative to Client::start or Client::running when there is already a handle handy.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.