async_inspect/
lib.rs

1//! # async-inspect 🔍
2//!
3//! > X-ray vision for async Rust
4
5// Allow some clippy lints that are too pedantic for this crate
6#![allow(clippy::must_use_candidate)]
7#![allow(clippy::cast_precision_loss)]
8#![allow(clippy::cast_possible_truncation)]
9#![allow(clippy::cast_lossless)]
10#![allow(clippy::cast_sign_loss)]
11#![allow(clippy::use_self)]
12#![allow(clippy::missing_errors_doc)]
13#![allow(clippy::missing_panics_doc)]
14#![allow(clippy::module_name_repetitions)]
15#![allow(clippy::needless_pass_by_value)]
16#![allow(clippy::similar_names)]
17#![allow(clippy::too_many_lines)]
18#![allow(clippy::unnested_or_patterns)]
19#![allow(clippy::unused_self)]
20#![allow(clippy::format_in_format_args)]
21#![allow(clippy::doc_markdown)]
22#![allow(clippy::return_self_not_must_use)]
23#![allow(clippy::redundant_closure)]
24#![allow(clippy::float_cmp)]
25#![allow(clippy::manual_range_contains)]
26#![allow(clippy::into_iter_on_ref)]
27#![allow(clippy::map_unwrap_or)]
28#![allow(clippy::format_push_string)]
29//!
30//! **async-inspect** visualizes and inspects async state machines in Rust.
31//! See exactly what your futures are doing, where they're stuck, and why.
32//!
33//! ## Quick Start
34//!
35//! ```rust,ignore
36//! use async_inspect::prelude::*;
37//!
38//! #[async_inspect::trace]
39//! async fn fetch_user(id: u64) -> User {
40//!     let profile = fetch_profile(id).await;
41//!     let posts = fetch_posts(id).await;
42//!     User { profile, posts }
43//! }
44//! ```
45//!
46//! ## Features
47//!
48//! - 🔍 **State Machine Inspection** - See current state and variables
49//! - ⏱️ **Execution Timeline** - Visualize async execution
50//! - 💀 **Deadlock Detection** - Find circular dependencies
51//! - 📊 **Performance Analysis** - Identify bottlenecks
52
53#![warn(missing_docs)]
54#![warn(clippy::all)]
55#![warn(clippy::pedantic)]
56
57// Re-export proc macros
58pub use async_inspect_macros::{inspect, trace};
59
60/// Production configuration
61pub mod config;
62
63/// Core inspection types and traits
64pub mod inspector;
65
66/// State machine introspection
67///
68/// State machine analysis and visualization
69pub mod state_machine {}
70
71/// Task tracking and monitoring
72pub mod task;
73
74/// Timeline and execution history
75pub mod timeline;
76
77/// Deadlock detection
78pub mod deadlock;
79
80/// Performance profiling
81pub mod profile;
82
83/// Runtime integration hooks
84pub mod runtime;
85
86/// Instrumentation and tracing
87pub mod instrument;
88
89/// Reporting and output
90pub mod reporter;
91
92/// Export functionality
93pub mod export;
94
95/// Task relationship graph
96pub mod graph;
97
98/// Ecosystem integrations
99pub mod integrations;
100
101/// Tracked synchronization primitives
102///
103/// Drop-in replacements for `tokio::sync::Mutex`, `RwLock`, and `Semaphore`
104/// with automatic contention tracking and deadlock detection integration.
105#[cfg(feature = "tokio")]
106pub mod sync;
107
108/// Tracked channel primitives
109///
110/// Drop-in replacements for `tokio::sync::mpsc`, `oneshot`, and `broadcast`
111/// channels with automatic message flow tracking.
112#[cfg(feature = "tokio")]
113pub mod channel;
114
115/// Terminal User Interface
116#[cfg(feature = "cli")]
117pub mod tui;
118
119/// Web Dashboard for real-time monitoring
120#[cfg(feature = "dashboard")]
121pub mod dashboard;
122
123/// Language Server Protocol (LSP) integration
124#[cfg(feature = "lsp")]
125pub mod lsp;
126
127/// Usage telemetry
128///
129/// Anonymous usage analytics to help improve async-inspect.
130/// Can be disabled via `ASYNC_INSPECT_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`.
131pub mod telemetry;
132
133/// Error types
134///
135/// Error definitions
136pub mod error {
137
138    use thiserror::Error;
139
140    /// Main error type for async-inspect
141    #[derive(Error, Debug)]
142    pub enum Error {
143        /// Inspection error
144        #[error("Inspection error: {0}")]
145        Inspection(String),
146
147        /// Runtime error
148        #[error("Runtime error: {0}")]
149        Runtime(String),
150
151        /// Serialization error
152        #[error("Serialization error: {0}")]
153        Serialization(#[from] serde_json::Error),
154
155        /// IO error
156        #[error("IO error: {0}")]
157        Io(#[from] std::io::Error),
158    }
159
160    /// Result type alias
161    pub type Result<T> = std::result::Result<T, Error>;
162}
163
164/// Prelude for convenient imports
165///
166/// Convenient re-exports
167///
168/// ```rust
169/// use async_inspect::prelude::*;
170/// ```
171pub mod prelude {
172
173    pub use crate::error::{Error, Result};
174    pub use crate::inspector::{Inspector, InspectorStats};
175    pub use crate::instrument::{InspectContext, TaskGuard};
176    pub use crate::reporter::html::HtmlReporter;
177    pub use crate::reporter::Reporter;
178    #[cfg(feature = "tokio")]
179    pub use crate::sync::{LockMetrics, Mutex, MutexGuard, RwLock, Semaphore};
180    pub use crate::task::{
181        sort_tasks, SortDirection, TaskFilter, TaskId, TaskInfo, TaskSortBy, TaskState,
182    };
183    pub use crate::timeline::{Event, EventKind};
184
185    // Re-export macros
186    pub use crate::{
187        inspect_point, inspect_task_complete, inspect_task_failed, inspect_task_start,
188    };
189}
190
191// Re-exports
192pub use error::{Error, Result};
193pub use inspector::Inspector;
194
195#[cfg(test)]
196mod tests {
197
198    #[test]
199    fn test_placeholder() {
200        // Placeholder test
201        assert_eq!(2 + 2, 4);
202    }
203}
async_inspect/lib.rs

async_inspect/
lib.rs
