Struct tracy_client::Client

source ·
pub struct Client(/* private fields */);
Expand description

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§

source§

impl Client

Instrumentation for global frame indicators.

source

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();
// }
source

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"));
// }
source

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"));
source§

impl Client

source

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.
source§

impl Client

Instrumentation for drawing 2D plots.

source

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);
source§

impl Client

Instrumentation for timed regions, spans or zones of execution.

source

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
source

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
source§

impl Client

Client initialization and lifetime management.

source

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();
    // ...
// }
source

pub fn running() -> Option<Self>

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

source

pub fn is_running() -> bool

Is the client already running?

source§

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.

source

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.

source

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.

source§

impl Client

source

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§

source§

impl Clone for Client

source§

fn clone(&self) -> Self

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

1.0.0 · source§

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

Performs copy-assignment from source. Read more

Auto Trait Implementations§

§

impl Freeze for Client

§

impl RefUnwindSafe for Client

§

impl Send for Client

§

impl Sync for Client

§

impl Unpin for Client

§

impl UnwindSafe for Client

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.