iai_callgrind

Struct FlamegraphConfig

source
pub struct FlamegraphConfig(/* private fields */);
Available on crate feature default only.
Expand description

The FlamegraphConfig which allows the customization of the created flamegraphs

Callgrind flamegraphs are very similar to callgrind_annotate output. In contrast to callgrind_annotate text based output, the produced flamegraphs are svg files (located in the target/iai directory) which can be viewed in a browser.

§Experimental

Note the following considerations only affect flamegraphs of multi-threaded/multi-process benchmarks and benchmarks which produce multiple parts with a total over all sub-metrics.

Currently, Iai-Callgrind creates the flamegraphs only for the total over all threads/parts and subprocesses. This leads to complications since the call graph is not be fully recovered just by examining each thread/subprocess separately. So, the total metrics in the flamegraphs might not be the same as the total metrics shown in the terminal output. If in doubt, the terminal output shows the the correct metrics.

§Examples

use iai_callgrind::{LibraryBenchmarkConfig, FlamegraphConfig, main};
main!(
    config = LibraryBenchmarkConfig::default()
                .flamegraph(FlamegraphConfig::default());
    library_benchmark_groups = some_group
);

Implementations§

source§

impl FlamegraphConfig

source

pub fn kind(&mut self, kind: FlamegraphKind) -> &mut Self

Option to change the FlamegraphKind

The default is FlamegraphKind::All.

§Examples

For example, to only create a differential flamegraph:

use iai_callgrind::{FlamegraphConfig, FlamegraphKind};

let config = FlamegraphConfig::default().kind(FlamegraphKind::Differential);
source

pub fn negate_differential(&mut self, negate_differential: bool) -> &mut Self

Negate the differential flamegraph FlamegraphKind::Differential

The default is false.

Instead of showing the differential flamegraph from the viewing angle of what has happened the negated differential flamegraph shows what will happen. Especially, this allows to see vanished event lines (in blue) for example because the underlying code has improved and removed an unnecessary function call.

See also Differential Flame Graphs from Brendan Gregg’s Blog.

§Examples
use iai_callgrind::{FlamegraphConfig, FlamegraphKind};

let config = FlamegraphConfig::default().negate_differential(true);
source

pub fn normalize_differential( &mut self, normalize_differential: bool, ) -> &mut Self

Normalize the differential flamegraph

This’ll make the first profile event count to match the second. This’ll help in situations when everything looks read (or blue) to get a balanced profile with the full red/blue spectrum

§Examples
use iai_callgrind::{FlamegraphConfig, FlamegraphKind};

let config = FlamegraphConfig::default().normalize_differential(true);
source

pub fn event_kinds<T>(&mut self, event_kinds: T) -> &mut Self
where T: IntoIterator<Item = EventKind>,

One or multiple EventKind for which a flamegraph is going to be created.

The default is EventKind::Ir

Currently, flamegraph creation is limited to one flamegraph for each EventKind and there’s no way to merge all event kinds into a single flamegraph.

Note it is an error to specify a EventKind which isn’t recorded by callgrind. See the docs of the variants of EventKind which callgrind option is needed to create a record for it. See also the Callgrind Documentation. The EventKinds recorded by callgrind which are available as long as the cache simulation is turned on with --cache-sim=yes (which is the default):

If the cache simulation is turned on, the following derived EventKinds are also available:

§Examples
use iai_callgrind::{EventKind, FlamegraphConfig};

let config =
    FlamegraphConfig::default().event_kinds([EventKind::EstimatedCycles, EventKind::Ir]);
source

pub fn direction(&mut self, direction: Direction) -> &mut Self

Set the Direction in which the flamegraph should grow.

The default is Direction::TopToBottom.

§Examples

For example to change the default

use iai_callgrind::{Direction, FlamegraphConfig};

let config = FlamegraphConfig::default().direction(Direction::BottomToTop);
source

pub fn title(&mut self, title: String) -> &mut Self

Overwrite the default title of the final flamegraph

§Examples
use iai_callgrind::{Direction, FlamegraphConfig};

let config = FlamegraphConfig::default().title("My flamegraph title".to_owned());
source

pub fn subtitle(&mut self, subtitle: String) -> &mut Self

Overwrite the default subtitle of the final flamegraph

§Examples
use iai_callgrind::FlamegraphConfig;

let config = FlamegraphConfig::default().subtitle("My flamegraph subtitle".to_owned());
source

pub fn min_width(&mut self, min_width: f64) -> &mut Self

Set the minimum width (in pixels) for which event lines are going to be shown.

The default is 0.1

To show all events, set the min_width to 0f64.

§Examples
use iai_callgrind::FlamegraphConfig;

let config = FlamegraphConfig::default().min_width(0f64);

Trait Implementations§

source§

impl AsRef<FlamegraphConfig> for FlamegraphConfig

source§

fn as_ref(&self) -> &InternalFlamegraphConfig

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl Clone for FlamegraphConfig

source§

fn clone(&self) -> FlamegraphConfig

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for FlamegraphConfig

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Default for FlamegraphConfig

source§

fn default() -> FlamegraphConfig

Returns the “default value” for a type. Read more
source§

impl From<&FlamegraphConfig> for InternalFlamegraphConfig

source§

fn from(value: &FlamegraphConfig) -> Self

Converts to this type from the input type.
source§

impl From<&mut FlamegraphConfig> for InternalFlamegraphConfig

source§

fn from(value: &mut FlamegraphConfig) -> Self

Converts to this type from the input type.
source§

impl From<FlamegraphConfig> for InternalFlamegraphConfig

source§

fn from(value: FlamegraphConfig) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

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.