Skip to main content

tuwunel_core/utils/future/
bool_ext.rs

1//! Short-circuiting Boolean combinators over concurrently polled futures.
2//!
3//! The fixed-arity forms poll their inputs in the order given, and a pass ends
4//! at the first input to decide the result, leaving those after it unpolled.
5//! An unpolled input runs none of the work its future defers to `poll`, which
6//! for a database read is the pool dispatch and the storage I/O. The elision
7//! needs the deciding input ready on its first poll, since a pending one does
8//! not end the pass. Order the arguments cheapest and likeliest to decide
9//! first; the iterator forms promise no such order.
10
11#![expect(clippy::many_single_char_names, clippy::impl_trait_in_params)]
12
13use futures::{
14	FutureExt, StreamExt,
15	future::{ready, try_join, try_join3, try_join4},
16	stream::FuturesUnordered,
17};
18
19use crate::utils::BoolExt as _;
20
21#[cfg(test)]
22mod tests;
23
24/// Combines Boolean futures with concurrent short-circuit logic.
25///
26/// Conjunction resolves false on the first false output and true only after
27/// every input resolves true. Disjunction resolves true on the first true
28/// output and false only after every input resolves false.
29pub trait BoolExt
30where
31	Self: Future<Output = bool> + Send,
32{
33	/// Computes the disjunction of two Boolean futures.
34	///
35	/// Both futures are polled concurrently. The returned future resolves true
36	/// on the first true output or false after both produce false.
37	fn or<B>(self, b: B) -> impl Future<Output = bool> + Send
38	where
39		B: Future<Output = bool> + Send,
40		Self: Sized;
41
42	/// Computes the conjunction of two Boolean futures.
43	///
44	/// Both futures are polled concurrently. The returned future resolves false
45	/// on the first false output or true after both produce true.
46	fn and<B>(self, b: B) -> impl Future<Output = bool> + Send
47	where
48		B: Future<Output = bool> + Send,
49		Self: Sized;
50
51	/// Computes the conjunction of three Boolean futures.
52	///
53	/// The receiver and both arguments are polled concurrently. The result is
54	/// true only when all three futures produce true.
55	fn and2<B, C>(self, b: B, c: C) -> impl Future<Output = bool> + Send
56	where
57		B: Future<Output = bool> + Send,
58		C: Future<Output = bool> + Send,
59		Self: Sized;
60
61	/// Computes the disjunction of three Boolean futures.
62	///
63	/// The receiver and both arguments are polled concurrently. The result is
64	/// true when any of the three futures produces true.
65	fn or2<B, C>(self, b: B, c: C) -> impl Future<Output = bool> + Send
66	where
67		B: Future<Output = bool> + Send,
68		C: Future<Output = bool> + Send,
69		Self: Sized;
70
71	/// Computes the conjunction of four Boolean futures.
72	///
73	/// The receiver and all three arguments are polled concurrently. The result
74	/// is true only when every future produces true.
75	fn and3<B, C, D>(self, b: B, c: C, d: D) -> impl Future<Output = bool> + Send
76	where
77		B: Future<Output = bool> + Send,
78		C: Future<Output = bool> + Send,
79		D: Future<Output = bool> + Send,
80		Self: Sized;
81
82	/// Computes the disjunction of four Boolean futures.
83	///
84	/// The receiver and all three arguments are polled concurrently. The result
85	/// is true when any future produces true.
86	fn or3<B, C, D>(self, b: B, c: C, d: D) -> impl Future<Output = bool> + Send
87	where
88		B: Future<Output = bool> + Send,
89		C: Future<Output = bool> + Send,
90		D: Future<Output = bool> + Send,
91		Self: Sized;
92}
93
94impl<Fut> BoolExt for Fut
95where
96	Fut: Future<Output = bool> + Send,
97{
98	fn or<B>(self, b: B) -> impl Future<Output = bool> + Send
99	where
100		B: Future<Output = bool> + Send,
101		Self: Sized,
102	{
103		try_join(self.map(test_not), b.map(test_not)).map(|res| res.is_err())
104	}
105
106	fn and<B>(self, b: B) -> impl Future<Output = bool> + Send
107	where
108		B: Future<Output = bool> + Send,
109		Self: Sized,
110	{
111		try_join(self.map(test), b.map(test)).map(|res| res.is_ok())
112	}
113
114	fn and2<B, C>(self, b: B, c: C) -> impl Future<Output = bool> + Send
115	where
116		B: Future<Output = bool> + Send,
117		C: Future<Output = bool> + Send,
118		Self: Sized,
119	{
120		try_join3(self.map(test), b.map(test), c.map(test)).map(|res| res.is_ok())
121	}
122
123	fn or2<B, C>(self, b: B, c: C) -> impl Future<Output = bool> + Send
124	where
125		B: Future<Output = bool> + Send,
126		C: Future<Output = bool> + Send,
127		Self: Sized,
128	{
129		try_join3(self.map(test_not), b.map(test_not), c.map(test_not)).map(|res| res.is_err())
130	}
131
132	fn and3<B, C, D>(self, b: B, c: C, d: D) -> impl Future<Output = bool> + Send
133	where
134		B: Future<Output = bool> + Send,
135		C: Future<Output = bool> + Send,
136		D: Future<Output = bool> + Send,
137		Self: Sized,
138	{
139		try_join4(self.map(test), b.map(test), c.map(test), d.map(test)).map(|res| res.is_ok())
140	}
141
142	fn or3<B, C, D>(self, b: B, c: C, d: D) -> impl Future<Output = bool> + Send
143	where
144		B: Future<Output = bool> + Send,
145		C: Future<Output = bool> + Send,
146		D: Future<Output = bool> + Send,
147		Self: Sized,
148	{
149		try_join4(self.map(test_not), b.map(test_not), c.map(test_not), d.map(test_not))
150			.map(|res| res.is_err())
151	}
152}
153
154/// Computes the conjunction of an iterator of Boolean futures.
155///
156/// The first ready false output wins at any position in the iterator.
157/// Polling all inputs concurrently costs one allocation per input.
158/// An empty iterator resolves to true.
159pub fn and<I, F>(args: I) -> impl Future<Output = bool> + Send
160where
161	I: Iterator<Item = F> + Send,
162	F: Future<Output = bool> + Send,
163{
164	args.collect::<FuturesUnordered<_>>().all(ready)
165}
166
167/// Computes the disjunction of an iterator of Boolean futures.
168///
169/// The first ready true output wins at any position in the iterator.
170/// Polling all inputs concurrently costs one allocation per input.
171/// An empty iterator resolves to false.
172pub fn or<I, F>(args: I) -> impl Future<Output = bool> + Send
173where
174	I: Iterator<Item = F> + Send,
175	F: Future<Output = bool> + Send,
176{
177	args.collect::<FuturesUnordered<_>>().any(ready)
178}
179
180/// Computes the conjunction of four Boolean futures.
181///
182/// All four inputs are polled concurrently. The result is true only when every
183/// future resolves to true.
184pub fn and4(
185	a: impl Future<Output = bool> + Send,
186	b: impl Future<Output = bool> + Send,
187	c: impl Future<Output = bool> + Send,
188	d: impl Future<Output = bool> + Send,
189) -> impl Future<Output = bool> + Send {
190	a.and3(b, c, d)
191}
192
193/// Computes the conjunction of five Boolean futures.
194///
195/// All five inputs are polled concurrently. The result is true only when every
196/// future resolves to true.
197pub fn and5(
198	a: impl Future<Output = bool> + Send,
199	b: impl Future<Output = bool> + Send,
200	c: impl Future<Output = bool> + Send,
201	d: impl Future<Output = bool> + Send,
202	e: impl Future<Output = bool> + Send,
203) -> impl Future<Output = bool> + Send {
204	a.and2(b, c).and2(d, e)
205}
206
207/// Computes the conjunction of six Boolean futures.
208///
209/// All six inputs are polled concurrently. The result is true only when every
210/// future resolves to true.
211pub fn and6(
212	a: impl Future<Output = bool> + Send,
213	b: impl Future<Output = bool> + Send,
214	c: impl Future<Output = bool> + Send,
215	d: impl Future<Output = bool> + Send,
216	e: impl Future<Output = bool> + Send,
217	f: impl Future<Output = bool> + Send,
218) -> impl Future<Output = bool> + Send {
219	a.and3(b, c, d).and2(e, f)
220}
221
222/// Computes the conjunction of seven Boolean futures.
223///
224/// All seven inputs are polled concurrently. The result is true only when every
225/// future resolves to true.
226pub fn and7(
227	a: impl Future<Output = bool> + Send,
228	b: impl Future<Output = bool> + Send,
229	c: impl Future<Output = bool> + Send,
230	d: impl Future<Output = bool> + Send,
231	e: impl Future<Output = bool> + Send,
232	f: impl Future<Output = bool> + Send,
233	g: impl Future<Output = bool> + Send,
234) -> impl Future<Output = bool> + Send {
235	a.and3(b, c, d).and3(e, f, g)
236}
237
238fn test(test: bool) -> crate::Result<(), ()> { test.into_result() }
239
240fn test_not(test: bool) -> crate::Result<(), ()> { test.is_false().into_result() }