dptree/handler/
description.rs

1//! Built-in handler description types.
2
3mod interest_set;
4mod unspecified;
5
6pub use interest_set::{EventKind, InterestSet};
7pub use unspecified::Unspecified;
8
9/// Handler description.
10///
11/// This trait allows information to flow "back up" the tree, allowing a user to
12/// check its structure.
13///
14/// ## Examples
15///
16/// Count how many branches are in the tree:
17///
18/// ```
19/// use dptree::{prelude::DependencyMap, Handler, HandlerDescription};
20///
21/// struct CountBranches(u32);
22///
23/// impl HandlerDescription for CountBranches {
24///     fn entry() -> Self {
25///         Self(0)
26///     }
27///
28///     fn user_defined() -> Self {
29///         Self(0)
30///     }
31///
32///     fn merge_chain(&self, other: &Self) -> Self {
33///         Self(self.0 + other.0)
34///     }
35///
36///     fn merge_branch(&self, other: &Self) -> Self {
37///         Self(self.0 + other.0 + 1)
38///     }
39/// }
40///
41/// #[track_caller]
42/// fn assert_count(count: u32, handler: Handler<(), CountBranches>) {
43///     assert_eq!(handler.description().0, count);
44/// }
45///
46/// assert_count(0, dptree::entry());
47/// assert_count(1, dptree::entry().branch(dptree::inspect(|| ())));
48/// assert_count(
49///     5,
50///     dptree::entry()
51///         .branch(
52///             dptree::entry()
53///                 .branch(dptree::entry().branch(dptree::filter(|| true)))
54///                 .branch(dptree::entry().chain(dptree::filter(|| false))),
55///         )
56///         .branch(dptree::inspect(|| ())),
57/// );
58/// ```
59pub trait HandlerDescription: Sized + Send + Sync + 'static {
60    /// Description for [`entry`](crate::entry).
61    fn entry() -> Self;
62
63    /// Description for a user-defined handler that can do practically
64    /// everything.
65    fn user_defined() -> Self;
66
67    /// Merge descriptions to get a description for a chain handler.
68    fn merge_chain(&self, other: &Self) -> Self;
69
70    /// Merge descriptions to get a description for a branch handler.
71    fn merge_branch(&self, other: &Self) -> Self;
72
73    /// Description for [`map`](crate::map).
74    ///
75    /// ## Default implementation
76    ///
77    /// By default this returns the value from
78    /// [`user_defined`](HandlerDescription::user_defined).
79    #[track_caller]
80    fn map() -> Self {
81        Self::user_defined()
82    }
83
84    /// Description for [`map_async`](crate::map_async).
85    ///
86    /// ## Default implementation
87    ///
88    /// By default this returns the value from
89    /// [`user_defined`](HandlerDescription::user_defined).
90    #[track_caller]
91    fn map_async() -> Self {
92        Self::user_defined()
93    }
94
95    /// Description for [`filter`](crate::filter).
96    ///
97    /// ## Default implementation
98    ///
99    /// By default this returns the value from
100    /// [`user_defined`](HandlerDescription::user_defined).
101    #[track_caller]
102    fn filter() -> Self {
103        Self::user_defined()
104    }
105
106    /// Description for [`filter_async`](crate::filter_async).
107    ///
108    /// ## Default implementation
109    ///
110    /// By default this returns the value from
111    /// [`user_defined`](HandlerDescription::user_defined).
112    #[track_caller]
113    fn filter_async() -> Self {
114        Self::user_defined()
115    }
116
117    /// Description for [`filter_map`](crate::filter_map).
118    ///
119    /// ## Default implementation
120    ///
121    /// By default this returns the value from
122    /// [`user_defined`](HandlerDescription::user_defined).
123    #[track_caller]
124    fn filter_map() -> Self {
125        Self::user_defined()
126    }
127
128    /// Description for [`filter_map_async`](crate::filter_map_async).
129    ///
130    /// ## Default implementation
131    ///
132    /// By default this returns the value from
133    /// [`user_defined`](HandlerDescription::user_defined).
134    #[track_caller]
135    fn filter_map_async() -> Self {
136        Self::user_defined()
137    }
138
139    /// Description for [`inspect`](crate::inspect).
140    ///
141    /// ## Default implementation
142    ///
143    /// By default this returns the value from
144    /// [`user_defined`](HandlerDescription::user_defined).
145    #[track_caller]
146    fn inspect() -> Self {
147        Self::user_defined()
148    }
149
150    /// Description for [`inspect_async`](crate::inspect_async).
151    ///
152    /// ## Default implementation
153    ///
154    /// By default this returns the value from
155    /// [`user_defined`](HandlerDescription::user_defined).
156    #[track_caller]
157    fn inspect_async() -> Self {
158        Self::user_defined()
159    }
160
161    /// Description for [`endpoint`](crate::endpoint).
162    ///
163    /// ## Default implementation
164    ///
165    /// By default this returns the value from
166    /// [`user_defined`](HandlerDescription::user_defined).
167    #[track_caller]
168    fn endpoint() -> Self {
169        Self::user_defined()
170    }
171}
dptree/handler/description.rs

dptree/handler/
description.rs
