Struct TaskMonitorCore

Source

pub struct TaskMonitorCore { /* private fields */ }

Expand description

A non-Clone, non-allocated, static-friendly version of TaskMonitor. See full docs on the TaskMonitor struct.

You should use TaskMonitorCore if you have a known count of monitors that you want to initialize as compile-time static structs.

You can also use TaskMonitorCore if you are already passing around an Arc-wrapped struct that you want to store your monitor in. This way, you can avoid double-Arc’ing it.

For other most other non-static usage, TaskMonitor will be more ergonomic.

§Examples

Static usage:

use tokio_metrics::TaskMonitorCore;

static MONITOR: TaskMonitorCore = TaskMonitorCore::new();

#[tokio::main]
async fn main() {
    assert_eq!(MONITOR.cumulative().first_poll_count, 0);

    MONITOR.instrument(async {}).await;
    assert_eq!(MONITOR.cumulative().first_poll_count, 1);
}

Usage with wrapper struct and TaskMonitorCore::instrument_with:

use std::sync::Arc;
use tokio_metrics::TaskMonitorCore;

#[derive(Clone)]
struct SharedState(Arc<SharedStateInner>);
struct SharedStateInner {
    monitor: TaskMonitorCore,
    other_state: SomeOtherSharedState,
}
/// Imagine: a type that wasn't `Clone` that you want to pass around
/// in a similar way as the monitor
struct SomeOtherSharedState;

impl AsRef<TaskMonitorCore> for SharedState {
    fn as_ref(&self) -> &TaskMonitorCore {
        &self.0.monitor
    }
}

#[tokio::main]
async fn main() {
    let state = SharedState(Arc::new(SharedStateInner {
        monitor: TaskMonitorCore::new(),
        other_state: SomeOtherSharedState,
    }));

    assert_eq!(state.0.monitor.cumulative().first_poll_count, 0);

    TaskMonitorCore::instrument_with(async {}, state.clone()).await;
    assert_eq!(state.0.monitor.cumulative().first_poll_count, 1);
}

Implementations§

Source §

impl TaskMonitorCore

Source

pub const fn builder() -> TaskMonitorCoreBuilder

Returns a const-friendly TaskMonitorCoreBuilder.

Source

pub const fn new() -> TaskMonitorCore

Constructs a new TaskMonitorCore. Refer to the struct documentation for more discussion of benefits compared to TaskMonitor.

Uses TaskMonitor::DEFAULT_SLOW_POLL_THRESHOLD as the threshold at which polls will be considered ‘slow’.

Uses TaskMonitor::DEFAULT_LONG_DELAY_THRESHOLD as the threshold at which scheduling will be considered ‘long’.

Source

pub const fn with_slow_poll_threshold( slow_poll_cut_off: Duration, ) -> TaskMonitorCore

Constructs a new task monitor with a given threshold at which polls are considered ‘slow’.

Refer to TaskMonitor::with_slow_poll_threshold for examples.

Source

pub fn slow_poll_threshold(&self) -> Duration

Produces the duration greater-than-or-equal-to at which polls are categorized as slow.

Refer to TaskMonitor::slow_poll_threshold for examples.

Source

pub fn long_delay_threshold(&self) -> Duration

Produces the duration greater-than-or-equal-to at which scheduling delays are categorized as long.

Source

pub fn instrument<F>(&'static self, task: F) -> Instrumented<F, &'static Self> ⓘ

Produces an instrumented façade around a given async task.

§Examples

use tokio_metrics::TaskMonitorCore;

static MONITOR: TaskMonitorCore = TaskMonitorCore::new();

#[tokio::main]
async fn main() {
    assert_eq!(MONITOR.cumulative().first_poll_count, 0);

    MONITOR.instrument(async {}).await;
    assert_eq!(MONITOR.cumulative().first_poll_count, 1);
}

Source

pub fn instrument_with<F, M: AsRef<TaskMonitorCore> + Send + Sync + 'static>( task: F, monitor: M, ) -> Instrumented<F, M> ⓘ

Produces an instrumented façade around a given async task, with an explicit monitor.

Use this when you have a non-static monitor reference, such as an Arc<TaskMonitorCore>.

§Examples

use std::sync::Arc;
use tokio_metrics::TaskMonitorCore;

#[derive(Clone)]
struct SharedState(Arc<SharedStateInner>);
struct SharedStateInner {
    monitor: TaskMonitorCore,
    other_state: SomeOtherSharedState,
}
/// Imagine: a type that wasn't `Clone` that you want to pass around
/// in a similar way as the monitor
struct SomeOtherSharedState;

impl AsRef<TaskMonitorCore> for SharedState {
    fn as_ref(&self) -> &TaskMonitorCore {
        &self.0.monitor
    }
}

#[tokio::main]
async fn main() {
    let state = SharedState(Arc::new(SharedStateInner {
        monitor: TaskMonitorCore::new(),
        other_state: SomeOtherSharedState,
    }));

    assert_eq!(state.0.monitor.cumulative().first_poll_count, 0);

    TaskMonitorCore::instrument_with(async {}, state.clone()).await;
    assert_eq!(state.0.monitor.cumulative().first_poll_count, 1);
}

Source

pub fn cumulative(&self) -> TaskMetrics

Produces TaskMetrics for the tasks instrumented by this TaskMonitorCore, collected since the construction of TaskMonitorCore.

§See also

TaskMonitorCore::intervals: produces TaskMetrics for user-defined sampling intervals, instead of cumulatively

See TaskMonitor::cumulative for examples.

Source

pub fn intervals<Monitor: AsRef<TaskMonitorCore> + Send + Sync + 'static>( monitor: Monitor, ) -> TaskIntervals<Monitor> ⓘ

Produces an unending iterator of metric sampling intervals.

Each sampling interval is defined by the time elapsed between advancements of the iterator produced by TaskMonitorCore::intervals. The item type of this iterator is TaskMetrics, which is a bundle of task metrics that describe only events occurring within that sampling interval.

§Examples

The below example demonstrates construction of TaskIntervals with TaskMonitorCore.

See TaskMonitor::intervals for more usage examples.

use std::sync::Arc;

fn main() {
    let metrics_monitor = Arc::new(tokio_metrics::TaskMonitorCore::new());

    let mut _intervals = tokio_metrics::TaskMonitorCore::intervals(metrics_monitor);
}