futures_diagnose/
lib.rs

1// Copyright 2020 Pierre Krieger
2//
3// Permission is hereby granted, free of charge, to any person obtaining a
4// copy of this software and associated documentation files (the "Software"),
5// to deal in the Software without restriction, including without limitation
6// the rights to use, copy, modify, merge, publish, distribute, sublicense,
7// and/or sell copies of the Software, and to permit persons to whom the
8// Software is furnished to do so, subject to the following conditions:
9//
10// The above copyright notice and this permission notice shall be included in
11// all copies or substantial portions of the Software.
12//
13// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
14// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
19// DEALINGS IN THE SOFTWARE.
20
21//! Wraps around futures and profiles them.
22//!
23//! # Usage
24//!
25//! ```
26//! futures::executor::block_on(futures_diagnose::diagnose("task-name", async move {
27//!     // ...
28//! }))
29//! ```
30//!
31//! Wrap all your futures into `futures_diagnose::diagnose`. Then launch your program with
32//! the `PROFILE_DIR` environment variable set to a path name. CPU profiling will automatically
33//! be performed and JSON files written in the target directory.
34//!
35//! You can open the JSON files using the Chrome browser by opening the address
36//! `chrome://tracing`.
37//!
38
39use futures::future::FutureObj;
40use futures::task::{Spawn, SpawnError};
41use std::{borrow::Cow, future::Future};
42
43pub use fut_with_diag::{diagnose, DiagnoseFuture};
44
45mod absolute_time;
46mod ctxt_with_diag;
47mod fut_with_diag;
48mod log_out;
49
50pub mod prelude {
51    pub use crate::FutureExt as _;
52    pub use crate::Future01Ext as _;
53}
54
55/// Extension trait on `Future`s.
56pub trait FutureExt: Future {
57    fn with_diagnostics(self, name: impl Into<Cow<'static, str>>) -> DiagnoseFuture<Self>
58    where
59        Self: Sized,
60    {
61        fut_with_diag::diagnose(name, self)
62    }
63}
64
65impl<T> FutureExt for T where T: Future {}
66
67/// Extension trait on `Future`s.
68pub trait Future01Ext: futures01::Future {
69    fn with_diagnostics(self, name: impl Into<Cow<'static, str>>) -> DiagnoseFuture<Self>
70    where
71        Self: Sized,
72    {
73        fut_with_diag::diagnose(name, self)
74    }
75}
76
77impl<T> Future01Ext for T where T: futures01::Future {}
78
79/// Wraps around a `T` and provides lots of diagnostics about tasks spawned through it.
80pub struct DiagSpawn<T> {
81    inner: T,
82}
83
84impl<T> DiagSpawn<T> {
85    /// Wraps around `inner`.
86    pub fn new(inner: T) -> Self {
87        DiagSpawn { inner }
88    }
89}
90
91impl<T> Spawn for DiagSpawn<T>
92where
93    T: Spawn,
94{
95    fn spawn_obj(&self, future: FutureObj<'static, ()>) -> Result<(), SpawnError> {
96        let wrapped = diagnose("unnamed", future);
97        self.inner.spawn_obj(From::from(Box::pin(wrapped)))
98    }
99
100    fn status(&self) -> Result<(), SpawnError> {
101        self.inner.status()
102    }
103}
futures_diagnose/lib.rs

futures_diagnose/
lib.rs
