futures_polling/lib.rs
1/**************************************************************************************************
2 * *
3 * This Source Code Form is subject to the terms of the Mozilla Public *
4 * License, v. 2.0. If a copy of the MPL was not distributed with this *
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. *
6 * *
7 **************************************************************************************************/
8
9// ======================================== Documentation ======================================= \\
10
11//! An enum similar to [`Poll`], but containing a [future] in its `Pending` variant.
12//!
13//! ## Example
14//!
15//! ```rust
16//! use futures_lite::future;
17//! use futures_polling::{FuturePollingExt, Polling};
18//!
19//! # future::block_on(async {
20//! #
21//! let mut polling = async {
22//! future::yield_now().await;
23//! 42
24//! }.polling();
25//!
26//! assert_eq!(polling.is_pending(), true);
27//!
28//! // Poll just once.
29//! polling.polling_once().await;
30//! assert_eq!(polling.is_pending(), true);
31//!
32//! // Poll until the inner future is ready.
33//! assert_eq!(polling.await, 42);
34//! #
35//! # });
36//! ```
37//!
38//! [future]: core::future::Future
39
40// =========================================== Imports ========================================== \\
41
42use core::future::Future;
43use core::mem;
44use core::pin::Pin;
45use core::task::{Context, Poll};
46
47// ============================================ Types =========================================== \\
48
49#[derive(Hash, Ord, PartialOrd, Eq, PartialEq, Copy, Clone, Debug)]
50/// An enum similar to [`Poll`], but containing a [future] in its `Pending` variant.
51///
52/// ## Example
53///
54/// ```rust
55/// use futures_lite::future;
56/// use futures_polling::{FuturePollingExt, Polling};
57///
58/// # future::block_on(async {
59/// #
60/// let mut polling = async {
61/// future::yield_now().await;
62/// 42
63/// }.polling();
64///
65/// assert_eq!(polling.is_pending(), true);
66///
67/// // Poll just once.
68/// polling.polling_once().await;
69/// assert_eq!(polling.is_pending(), true);
70///
71/// // Poll until the inner future is ready.
72/// assert_eq!(polling.await, 42);
73/// #
74/// # });
75/// ```
76///
77/// [future]: core::future::Future
78pub enum Polling<Fut: Future> {
79 /// Contains the [future's output] once it has returned it (like [`Poll::Ready`]).
80 ///
81 /// ## Example
82 ///
83 /// ```rust
84 /// # use futures_lite::future;
85 /// use futures_polling::{FuturePollingExt, Polling};
86 ///
87 /// # future::block_on(async {
88 /// #
89 /// let mut polling = async { 42i32 }.polling();
90 /// polling.polling_once().await;
91 ///
92 /// if let Polling::Ready(out) = polling {
93 /// assert_eq!(out, 42);
94 /// } else {
95 /// unreachable!();
96 /// }
97 ///
98 /// // or
99 ///
100 /// assert_eq!(polling.into_ready(), Some(42));
101 /// #
102 /// # });
103 /// ```
104 ///
105 /// [future's output]: core::future::Future::Output
106 Ready(Fut::Output),
107 /// Contains the pending [future].
108 ///
109 /// ## Example
110 ///
111 /// ```rust
112 /// use futures_lite::future;
113 /// use futures_polling::{FuturePollingExt, Polling};
114 ///
115 /// # future::block_on(async {
116 /// #
117 /// let mut polling = async {
118 /// future::yield_now().await;
119 /// 42i32
120 /// }.polling();
121 ///
122 /// if let Polling::Pending(_) = polling {
123 /// // -> future::yield_now().await;
124 /// polling.polling_once().await;
125 /// } else {
126 /// unreachable!();
127 /// }
128 ///
129 /// if let Polling::Pending(_) = polling {
130 /// // 42
131 /// polling.polling_once().await;
132 /// } else {
133 /// unreachable!();
134 /// }
135 ///
136 /// assert_eq!(polling.into_ready(), Some(42));
137 /// #
138 /// # });
139 /// ```
140 ///
141 /// [future]: core::future::Future
142 Pending(Fut),
143 /// The [future] has already returned an [output], but it has already been [extracted] out of
144 /// `Polling`.
145 ///
146 /// ## Example
147 ///
148 /// ```rust
149 /// # use futures_lite::future;
150 /// use futures_polling::{FuturePollingExt, Polling};
151 ///
152 /// # future::block_on(async {
153 /// #
154 /// let mut polling = async { 42i32 }.polling();
155 /// polling.polling_once().await;
156 ///
157 /// assert_eq!(polling.take_ready(), Some(42));
158 /// assert_eq!(polling.is_done(), true);
159 /// #
160 /// # });
161 /// ```
162 ///
163 /// [future]: core::future::Future
164 /// [output]: core::future::Future::Output
165 /// [extracted]: Polling::take_ready()
166 Done,
167}
168
169// ========================================= Interfaces ========================================= \\
170
171/// Extension trait to easily convert a [`Future`] into a [`Polling`].
172pub trait FuturePollingExt: Future {
173 /// Returns [`Polling::Pending(self)`], consuming `self`.
174 ///
175 /// ## Example
176 ///
177 /// ```rust
178 /// use core::task::Poll;
179 /// # use futures_lite::future;
180 /// use futures_polling::FuturePollingExt;
181 ///
182 /// # future::block_on(async {
183 /// #
184 /// let mut polling = async { 42 }.polling();
185 /// assert_eq!(polling.poll_once().await, Poll::Ready(42));
186 /// #
187 /// # });
188 /// ```
189 fn polling(self) -> Polling<Self>
190 where
191 Self: Sized,
192 {
193 Polling::Pending(self)
194 }
195}
196
197impl<Fut: Future> FuturePollingExt for Fut {}
198
199// =========================================== Polling ========================================== \\
200
201impl<Fut: Future> Polling<Fut> {
202 // ===================================== Destructors ==================================== \\
203
204 /// | `self` | return |
205 /// |:---------------------:|:-----------:|
206 /// | `Polling::Ready(out)` | `Some(out)` |
207 /// | `Polling::Pending(_)` | `None` |
208 /// | `Polling::Done` | `None` |
209 ///
210 /// ## Example
211 ///
212 /// ```rust
213 /// use futures_lite::future::{self, Ready};
214 /// use futures_polling::Polling;
215 ///
216 /// let polling = Polling::<Ready<i32>>::Ready(42);
217 /// assert_eq!(polling.into_ready(), Some(42));
218 ///
219 /// let polling = Polling::<Ready<i32>>::Pending(future::ready(42));
220 /// assert_eq!(polling.into_ready(), None);
221 ///
222 /// let polling = Polling::<Ready<i32>>::Done;
223 /// assert_eq!(polling.into_ready(), None);
224 /// ```
225 ///
226 /// [`Polling::Ready(out)`]: Polling::Ready
227 /// [`Some(out)`]: core::option::Option::Some
228 /// [`as_ready()`]: Polling::as_ready()
229 /// [`as_ready_mut()`]: Polling::as_ready_mut()
230 pub fn into_ready(self) -> Option<Fut::Output> {
231 if let Polling::Ready(out) = self {
232 Some(out)
233 } else {
234 None
235 }
236 }
237
238 /// | `self` | return |
239 /// |:-----------------------:|:-----------:|
240 /// | `Polling::Ready(_)` | `None` |
241 /// | `Polling::Pending(fut)` | `Some(fut)` |
242 /// | `Polling::Done` | `None` |
243 ///
244 /// ## Example
245 ///
246 /// ```rust
247 /// use futures_lite::future::{self, Ready};
248 /// use futures_polling::Polling;
249 ///
250 /// let polling = Polling::<Ready<i32>>::Ready(42);
251 /// assert_eq!(polling.into_pending().is_some(), false);
252 ///
253 /// let polling = Polling::<Ready<i32>>::Pending(future::ready(42));
254 /// # future::block_on(async {
255 /// assert_eq!(polling.into_pending().unwrap().await, 42);
256 /// # });
257 ///
258 /// let polling = Polling::<Ready<i32>>::Done;
259 /// assert_eq!(polling.into_pending().is_some(), false);
260 /// ```
261 ///
262 /// [`Polling::Pending(fut)`]: Polling::Pending
263 /// [`Some(fut)`]: core::option::Option::Some
264 /// [`as_pending()`]: Polling::as_pending()
265 /// [`as_pending_mut()`]: Polling::as_pending_mut()
266 pub fn into_pending(self) -> Option<Fut> {
267 if let Polling::Pending(fut) = self {
268 Some(fut)
269 } else {
270 None
271 }
272 }
273
274 /// | `self` | return |
275 /// |:---------------------:|:------------------:|
276 /// | `Polling::Ready(out)` | `Poll::Ready(out)` |
277 /// | `Polling::Pending(_)` | `Poll::Pending` |
278 /// | `Polling::Done` | `Poll::Pending` |
279 ///
280 /// ## Example
281 ///
282 /// ```rust
283 /// use core::task::Poll;
284 /// use futures_lite::future::{self, Ready};
285 /// use futures_polling::Polling;
286 ///
287 /// let polling = Polling::<Ready<i32>>::Ready(42);
288 /// assert_eq!(polling.into_poll(), Poll::Ready(42));
289 ///
290 /// let polling = Polling::<Ready<i32>>::Pending(future::ready(42));
291 /// assert_eq!(polling.into_poll(), Poll::Pending);
292 ///
293 /// let polling = Polling::<Ready<i32>>::Done;
294 /// assert_eq!(polling.into_poll(), Poll::Pending);
295 /// ```
296 ///
297 /// [`Polling::Ready(out)`]: Polling::Ready
298 /// [`Poll::Ready(out)`]: core::task::Poll::Ready
299 /// [`as_poll()`]: Polling::as_poll()
300 /// [`as_poll_mut()`]: Polling::as_poll_mut()
301 pub fn into_poll(self) -> Poll<Fut::Output> {
302 if let Polling::Ready(out) = self {
303 Poll::Ready(out)
304 } else {
305 Poll::Pending
306 }
307 }
308
309 // ======================================== Read ======================================== \\
310
311 /// Returns [`true`] is `self` is [`Polling::Ready(_)`].
312 ///
313 /// ## Example
314 ///
315 /// ```rust
316 /// use futures_lite::future::{self, Ready};
317 /// use futures_polling::Polling;
318 ///
319 /// let polling = Polling::<Ready<i32>>::Ready(42);
320 /// assert_eq!(polling.is_ready(), true);
321 ///
322 /// let polling = Polling::<Ready<i32>>::Pending(future::ready(42));
323 /// assert_eq!(polling.is_ready(), false);
324 ///
325 /// let polling = Polling::<Ready<i32>>::Done;
326 /// assert_eq!(polling.is_ready(), false);
327 /// ```
328 ///
329 /// [`Polling::Ready(_)`]: Polling::Ready
330 pub fn is_ready(&self) -> bool {
331 if let Polling::Ready(_) = self {
332 true
333 } else {
334 false
335 }
336 }
337
338 /// Returns [`true`] is `self` is [`Polling::Pending(_)`].
339 ///
340 /// ## Example
341 ///
342 /// ```rust
343 /// use futures_lite::future::{self, Ready};
344 /// use futures_polling::Polling;
345 ///
346 /// let polling = Polling::<Ready<i32>>::Ready(42);
347 /// assert_eq!(polling.is_pending(), false);
348 ///
349 /// let polling = Polling::<Ready<i32>>::Pending(future::ready(42));
350 /// assert_eq!(polling.is_pending(), true);
351 ///
352 /// let polling = Polling::<Ready<i32>>::Done;
353 /// assert_eq!(polling.is_pending(), false);
354 /// ```
355 ///
356 /// [`Polling::Pending(_)`]: Polling::Pending
357 pub fn is_pending(&self) -> bool {
358 if let Polling::Pending(_) = self {
359 true
360 } else {
361 false
362 }
363 }
364
365 /// Returns [`true`] is `self` is [`Polling::Done`].
366 ///
367 /// ## Example
368 ///
369 /// ```rust
370 /// use futures_lite::future::{self, Ready};
371 /// use futures_polling::Polling;
372 ///
373 /// let polling = Polling::<Ready<i32>>::Ready(42);
374 /// assert_eq!(polling.is_done(), false);
375 ///
376 /// let polling = Polling::<Ready<i32>>::Pending(future::ready(42));
377 /// assert_eq!(polling.is_done(), false);
378 ///
379 /// let polling = Polling::<Ready<i32>>::Done;
380 /// assert_eq!(polling.is_done(), true);
381 /// ```
382 pub fn is_done(&self) -> bool {
383 if let Polling::Done = self {
384 true
385 } else {
386 false
387 }
388 }
389
390 /// | `&self` | return |
391 /// |:---------------------:|:------------:|
392 /// | `Polling::Ready(out)` | `Some(&out)` |
393 /// | `Polling::Pending(_)` | `None` |
394 /// | `Polling::Done` | `None` |
395 ///
396 /// ## Example
397 ///
398 /// ```rust
399 /// use futures_lite::future::{self, Ready};
400 /// use futures_polling::Polling;
401 ///
402 /// let polling = Polling::<Ready<i32>>::Ready(42);
403 /// assert_eq!(polling.as_ready(), Some(&42));
404 ///
405 /// let polling = Polling::<Ready<i32>>::Pending(future::ready(42));
406 /// assert_eq!(polling.as_ready(), None);
407 ///
408 /// let polling = Polling::<Ready<i32>>::Done;
409 /// assert_eq!(polling.as_ready(), None);
410 /// ```
411 ///
412 /// [`Polling::Ready(out)`]: Polling::Ready
413 /// [`Some(&out)`]: core::option::Option::Some
414 /// [`as_ready_mut()`]: Polling::as_ready_mut()
415 /// [`into_ready()`]: Polling::into_ready()
416 pub fn as_ready(&self) -> Option<&Fut::Output> {
417 if let Polling::Ready(out) = self {
418 Some(out)
419 } else {
420 None
421 }
422 }
423
424 /// | `&self` | return |
425 /// |:-----------------------:|:------------:|
426 /// | `Polling::Ready(_)` | `None` |
427 /// | `Polling::Pending(fut)` | `Some(&fut)` |
428 /// | `Polling::Done` | `None` |
429 ///
430 /// ## Example
431 ///
432 /// ```rust
433 /// use futures_lite::future::{self, Ready};
434 /// use futures_polling::Polling;
435 ///
436 /// let polling = Polling::<Ready<i32>>::Ready(42);
437 /// assert_eq!(polling.as_pending().is_some(), false);
438 ///
439 /// let polling = Polling::<Ready<i32>>::Pending(future::ready(42));
440 /// assert_eq!(polling.as_pending().is_some(), true);
441 ///
442 /// let polling = Polling::<Ready<i32>>::Done;
443 /// assert_eq!(polling.as_pending().is_some(), false);
444 /// ```
445 ///
446 /// [`Polling::Pending(fut)`]: Polling::Pending
447 /// [`Some(&fut)`]: core::option::Option::Some
448 /// [`as_pending_mut()`]: Polling::as_pending_mut()
449 /// [`into_pending()`]: Polling::into_pending()
450 pub fn as_pending(&self) -> Option<&Fut> {
451 if let Polling::Pending(fut) = self {
452 Some(fut)
453 } else {
454 None
455 }
456 }
457
458 /// | `&self` | return |
459 /// |:---------------------:|:-------------------:|
460 /// | `Polling::Ready(out)` | `Poll::Ready(&out)` |
461 /// | `Polling::Pending(_)` | `Poll::Pending` |
462 /// | `Polling::Done` | `Poll::Pending` |
463 ///
464 /// ## Example
465 ///
466 /// ```rust
467 /// use core::task::Poll;
468 /// use futures_lite::future::{self, Ready};
469 /// use futures_polling::Polling;
470 ///
471 /// let polling = Polling::<Ready<i32>>::Ready(42);
472 /// assert_eq!(polling.as_poll(), Poll::Ready(&42));
473 ///
474 /// let polling = Polling::<Ready<i32>>::Pending(future::ready(42));
475 /// assert_eq!(polling.as_poll(), Poll::Pending);
476 ///
477 /// let polling = Polling::<Ready<i32>>::Done;
478 /// assert_eq!(polling.as_poll(), Poll::Pending);
479 /// ```
480 ///
481 /// [`Polling::Ready(out)`]: Polling::Ready
482 /// [`Poll::Ready(&out)`]: core::task::Poll::Ready
483 /// [`as_poll_mut()`]: Polling::as_poll_mut()
484 /// [`into_poll()`]: Polling::into_poll()
485 pub fn as_poll(&self) -> Poll<&Fut::Output> {
486 if let Polling::Ready(out) = self {
487 Poll::Ready(out)
488 } else {
489 Poll::Pending
490 }
491 }
492
493 /// | `&mut self` | return |
494 /// |:---------------------:|:----------------:|
495 /// | `Polling::Ready(out)` | `Some(&mut out)` |
496 /// | `Polling::Pending(_)` | `None` |
497 /// | `Polling::Done` | `None` |
498 ///
499 /// ## Example
500 ///
501 /// ```rust
502 /// use futures_lite::future::{self, Ready};
503 /// use futures_polling::Polling;
504 ///
505 /// let mut polling = Polling::<Ready<i32>>::Ready(42);
506 /// if let Some(out) = polling.as_ready_mut() {
507 /// assert_eq!(*out, 42);
508 /// *out = 0;
509 /// } else {
510 /// unreachable!();
511 /// }
512 /// assert_eq!(polling.as_ready(), Some(&0));
513 ///
514 /// let mut polling = Polling::<Ready<i32>>::Pending(future::ready(42));
515 /// assert_eq!(polling.as_ready_mut(), None);
516 ///
517 /// let mut polling = Polling::<Ready<i32>>::Done;
518 /// assert_eq!(polling.as_ready_mut(), None);
519 /// ```
520 ///
521 /// [`Polling::Ready(out)`]: Polling::Ready
522 /// [`Some(&mut out)`]: core::option::Option::Some
523 /// [`as_ready()`]: Polling::as_ready()
524 /// [`into_ready()`]: Polling::into_ready()
525 pub fn as_ready_mut(&mut self) -> Option<&mut Fut::Output> {
526 if let Polling::Ready(out) = self {
527 Some(out)
528 } else {
529 None
530 }
531 }
532
533 /// | `&mut self` | return |
534 /// |:-----------------------:|:----------------:|
535 /// | `Polling::Ready(_)` | `None` |
536 /// | `Polling::Pending(fut)` | `Some(&mut fut)` |
537 /// | `Polling::Done` | `None` |
538 ///
539 /// ## Example
540 ///
541 /// ```rust
542 /// use futures_lite::future::{self, Ready};
543 /// use futures_polling::Polling;
544 ///
545 /// let mut polling = Polling::<Ready<i32>>::Ready(42);
546 /// assert_eq!(polling.as_pending_mut().is_some(), false);
547 ///
548 /// let mut polling = Polling::<Ready<i32>>::Pending(future::ready(42));
549 /// # future::block_on(async {
550 /// assert_eq!(polling.as_pending_mut().unwrap().await, 42);
551 /// # });
552 ///
553 /// let mut polling = Polling::<Ready<i32>>::Done;
554 /// assert_eq!(polling.as_pending_mut().is_some(), false);
555 /// ```
556 ///
557 /// [`Polling::Pending(fut)`]: Polling::Pending
558 /// [`Some(&mut fut)`]: core::option::Option::Some
559 /// [`as_pending()`]: Polling::as_pending()
560 /// [`into_pending()`]: Polling::into_pending()
561 pub fn as_pending_mut(&mut self) -> Option<&mut Fut> {
562 if let Polling::Pending(fut) = self {
563 Some(fut)
564 } else {
565 None
566 }
567 }
568
569 /// | `&mut self` | return |
570 /// |:---------------------:|:-----------------------:|
571 /// | `Polling::Ready(out)` | `Poll::Ready(&mut out)` |
572 /// | `Polling::Pending(_)` | `Poll::Pending` |
573 /// | `Polling::Done` | `Poll::Pending` |
574 ///
575 /// ## Example
576 ///
577 /// ```rust
578 /// use core::task::Poll;
579 /// use futures_lite::future::{self, Ready};
580 /// use futures_polling::Polling;
581 ///
582 /// let mut polling = Polling::<Ready<i32>>::Ready(42);
583 /// if let Poll::Ready(out) = polling.as_poll_mut() {
584 /// *out = 0;
585 /// } else {
586 /// unreachable!();
587 /// }
588 /// assert_eq!(polling.as_poll(), Poll::Ready(&0));
589 ///
590 /// let mut polling = Polling::<Ready<i32>>::Pending(future::ready(42));
591 /// assert_eq!(polling.as_poll_mut(), Poll::Pending);
592 ///
593 /// let mut polling = Polling::<Ready<i32>>::Done;
594 /// assert_eq!(polling.as_poll_mut(), Poll::Pending);
595 /// ```
596 ///
597 /// [`Polling::Ready(out)`]: Polling::Ready
598 /// [`Poll::Ready(&out)`]: core::task::Poll::Ready
599 /// [`as_poll_mut()`]: Polling::as_poll_mut()
600 /// [`into_poll()`]: Polling::into_poll()
601 pub fn as_poll_mut(&mut self) -> Poll<&mut Fut::Output> {
602 if let Polling::Ready(out) = self {
603 Poll::Ready(out)
604 } else {
605 Poll::Pending
606 }
607 }
608
609 // ===================================== Read+Write ===================================== \\
610
611 /// Moves `with` into `&mut self` and returns the previous `self`.
612 ///
613 /// ## Example
614 ///
615 /// ```rust
616 /// use futures_lite::future::{self, Ready};
617 /// use futures_polling::Polling;
618 ///
619 /// let mut p1 = Polling::<Ready<i32>>::Ready(42);
620 /// let p2 = Polling::<Ready<i32>>::Ready(24);
621 ///
622 /// let p3 = p1.replace(p2);
623 ///
624 /// assert_eq!(p1.as_ready(), Some(&24));
625 /// assert_eq!(p3.as_ready(), Some(&42));
626 /// ```
627 pub fn replace(&mut self, with: Self) -> Self {
628 mem::replace(self, with)
629 }
630
631 /// Takes the output or future out of `self`, leaving [`Polling::Done`] in its place.
632 ///
633 /// ## Example
634 ///
635 /// ```rust
636 /// use futures_lite::future::{self, Ready};
637 /// use futures_polling::Polling;
638 ///
639 /// let mut polling = Polling::<Ready<i32>>::Ready(42);
640 /// assert_eq!(polling.take().into_ready(), Some(42));
641 /// assert_eq!(polling.into_ready(), None);
642 ///
643 /// let mut polling = Polling::<Ready<i32>>::Pending(future::ready(42));
644 /// # future::block_on(async {
645 /// assert_eq!(polling.take().into_pending().unwrap().await, 42);
646 /// # });
647 /// assert_eq!(polling.into_pending().is_some(), false);
648 ///
649 /// let mut polling = Polling::<Ready<i32>>::Done;
650 /// assert_eq!(polling.take().is_done(), true);
651 /// assert_eq!(polling.is_done(), true);
652 /// ```
653 pub fn take(&mut self) -> Polling<Fut> {
654 mem::replace(self, Polling::Done)
655 }
656
657 /// | `&mut self` | new `self` value | return |
658 /// |:-----------------------:|:-----------------------:|:-----------:|
659 /// | `Polling::Ready(out)` | `Polling::Done` | `Some(out)` |
660 /// | `Polling::Pending(fut)` | `Polling::Pending(fut)` | `None` |
661 /// | `Polling::Done` | `Polling::Done` | `None` |
662 ///
663 /// ## Example
664 ///
665 /// ```rust
666 /// use futures_lite::future::{self, Ready};
667 /// use futures_polling::Polling;
668 ///
669 /// let mut polling = Polling::<Ready<i32>>::Ready(42);
670 /// assert_eq!(polling.take_ready(), Some(42));
671 /// assert_eq!(polling.into_ready(), None);
672 ///
673 /// let mut polling = Polling::<Ready<i32>>::Pending(future::ready(42));
674 /// assert_eq!(polling.take_ready(), None);
675 /// # future::block_on(async {
676 /// assert_eq!(polling.into_pending().unwrap().await, 42);
677 /// # });
678 ///
679 /// let mut polling = Polling::<Ready<i32>>::Done;
680 /// assert_eq!(polling.take_ready(), None);
681 /// assert_eq!(polling.is_done(), true);
682 /// ```
683 ///
684 /// [`Polling::Ready(out)`]: Polling::Ready
685 /// [`Some(out)`]: core::option::Option::Some
686 pub fn take_ready(&mut self) -> Option<Fut::Output> {
687 if self.is_ready() {
688 self.take().into_ready()
689 } else {
690 None
691 }
692 }
693
694 /// | `&mut self` | new `self` value | return |
695 /// |:-----------------------:|:---------------------:|:-----------:|
696 /// | `Polling::Ready(out)` | `Polling::Ready(out)` | `None` |
697 /// | `Polling::Pending(fut)` | `Polling::Done` | `Some(fut)` |
698 /// | `Polling::Done` | `Polling::Done` | `None` |
699 ///
700 /// ## Example
701 ///
702 /// ```rust
703 /// use futures_lite::future::{self, Ready};
704 /// use futures_polling::Polling;
705 ///
706 /// let mut polling = Polling::<Ready<i32>>::Ready(42);
707 /// assert_eq!(polling.take_pending().is_some(), false);
708 /// assert_eq!(polling.into_ready(), Some(42));
709 ///
710 /// let mut polling = Polling::<Ready<i32>>::Pending(future::ready(42));
711 /// # future::block_on(async {
712 /// assert_eq!(polling.take_pending().unwrap().await, 42);
713 /// # });
714 /// assert_eq!(polling.into_pending().is_some(), false);
715 ///
716 /// let mut polling = Polling::<Ready<i32>>::Done;
717 /// assert_eq!(polling.take_pending().is_some(), false);
718 /// assert_eq!(polling.is_done(), true);
719 /// ```
720 ///
721 /// [`Polling::Pending(fut)`]: Polling::Pending
722 /// [`Some(fut)`]: core::option::Option::Some
723 pub fn take_pending(&mut self) -> Option<Fut> {
724 if self.is_pending() {
725 self.take().into_pending()
726 } else {
727 None
728 }
729 }
730
731 /// | `&mut self` | new `self` value | return |
732 /// |:-----------------------:|:-----------------------:|:------------------:|
733 /// | `Polling::Ready(out)` | `Polling::Done` | `Poll::Ready(out)` |
734 /// | `Polling::Pending(fut)` | `Polling::Pending(fut)` | `Poll::Pending` |
735 /// | `Polling::Done` | `Polling::Done` | `Poll::Pending` |
736 ///
737 /// ## Example
738 ///
739 /// ```rust
740 /// use core::task::Poll;
741 /// use futures_lite::future::{self, Ready};
742 /// use futures_polling::Polling;
743 ///
744 /// let mut polling = Polling::<Ready<i32>>::Ready(42);
745 /// assert_eq!(polling.take_poll(), Poll::Ready(42));
746 /// assert_eq!(polling.into_ready(), None);
747 ///
748 /// let mut polling = Polling::<Ready<i32>>::Pending(future::ready(42));
749 /// assert_eq!(polling.take_poll(), Poll::Pending);
750 /// # future::block_on(async {
751 /// assert_eq!(polling.into_pending().unwrap().await, 42);
752 /// # });
753 ///
754 /// let mut polling = Polling::<Ready<i32>>::Done;
755 /// assert_eq!(polling.take_poll(), Poll::Pending);
756 /// assert_eq!(polling.is_done(), true);
757 /// ```
758 ///
759 /// [`Polling::Ready(out)`]: Polling::Ready
760 /// [`Some(out)`]: core::option::Option::Some
761 pub fn take_poll(&mut self) -> Poll<Fut::Output> {
762 if self.is_ready() {
763 self.take().into_poll()
764 } else {
765 Poll::Pending
766 }
767 }
768
769 /// | `&mut self` | `fut.poll(_)` | new `self` value | return |
770 /// |:-----------------------:|:------------------:|:-----------------------:|:------------------:|
771 /// | `Polling::Ready(out)` | x | `Polling::Done` | `Poll::Ready(out)` |
772 /// | `Polling::Pending(fut)` | `Poll::Ready(out)` | `Polling::Done` | `Poll::Ready(out)` |
773 /// | `Polling::Pending(fut)` | `Poll::Pending` | `Polling::Pending(fut)` | `Poll::Pending` |
774 /// | `Polling::Done` | x | panic!() | panic!() |
775 ///
776 /// ## Example
777 ///
778 /// ```rust
779 /// use core::task::Poll;
780 /// use futures_lite::future::{self, Pending, Ready};
781 /// use futures_polling::Polling;
782 ///
783 /// # future::block_on(async {
784 /// #
785 /// let mut polling = Polling::<Ready<i32>>::Ready(42);
786 /// assert_eq!(polling.poll_once().await, Poll::Ready(42));
787 /// assert_eq!(polling.is_done(), true);
788 ///
789 /// let mut polling = Polling::<Ready<i32>>::Pending(future::ready(42));
790 /// assert_eq!(polling.poll_once().await, Poll::Ready(42));
791 /// assert_eq!(polling.is_done(), true);
792 ///
793 /// let mut polling = Polling::<Pending<i32>>::Pending(future::pending());
794 /// assert_eq!(polling.poll_once().await, Poll::Pending);
795 /// assert_eq!(polling.is_done(), false);
796 /// #
797 /// # });
798 /// ```
799 ///
800 /// [`Polling::Pending(fut)`]: Polling::Pending
801 /// [polls]: core::future::Future::poll
802 /// [output]: core::future::Future::Output
803 /// [`Polling::Ready(out)`]: Polling::Ready
804 /// [`Poll::Ready(out)`]: core::task::Poll::Ready
805 pub async fn poll_once(&mut self) -> Poll<Fut::Output> {
806 self.polling_once().await;
807 self.take_poll()
808 }
809
810 /// | `&mut self` | `fut.poll(_)` | new `self` value |
811 /// |:-----------------------:|:------------------:|:-----------------------:|
812 /// | `Polling::Ready(out)` | x | `Polling::Ready(out)` |
813 /// | `Polling::Pending(fut)` | `Poll::Ready(out)` | `Polling::Ready(out)` |
814 /// | `Polling::Pending(fut)` | `Poll::Pending` | `Polling::Pending(fut)` |
815 /// | `Polling::Done` | x | panic!() |
816 ///
817 /// ## Example
818 ///
819 /// ```rust
820 /// use core::task::Poll;
821 /// use futures_lite::future::{self, Pending, Ready};
822 /// use futures_polling::Polling;
823 ///
824 /// # future::block_on(async {
825 /// #
826 /// let mut polling = Polling::<Ready<i32>>::Ready(42);
827 /// polling.polling_once().await;
828 /// assert_eq!(polling.take_poll(), Poll::Ready(42));
829 ///
830 /// let mut polling = Polling::<Ready<i32>>::Pending(future::ready(42));
831 /// polling.polling_once().await;
832 /// assert_eq!(polling.take_poll(), Poll::Ready(42));
833 ///
834 /// let mut polling = Polling::<Pending<i32>>::Pending(future::pending());
835 /// polling.polling_once().await;
836 /// assert_eq!(polling.is_pending(), true);
837 /// #
838 /// # });
839 /// ```
840 ///
841 /// [`Polling::Pending(fut)`]: Polling::Pending
842 /// [polls]: core::future::Future::poll
843 /// [`Polling::Ready(out)`]: Polling::Ready
844 /// [`Poll::Ready(out)`]: core::task::Poll::Ready
845 /// [`Polling::Ready(_)`]: Polling::Ready
846 pub async fn polling_once(&mut self) -> &mut Self {
847 if self.is_ready() {
848 return self;
849 } else if self.is_done() {
850 panic!("output already extracted");
851 }
852
853 struct PollingOnce<'polling, Fut: Future> {
854 polling: &'polling mut Polling<Fut>,
855 }
856
857 impl<Fut: Future> Future for PollingOnce<'_, Fut> {
858 type Output = ();
859
860 fn poll(self: Pin<&mut Self>, ctx: &mut Context) -> Poll<Self::Output> {
861 let this = unsafe { self.get_unchecked_mut() };
862 if let Polling::Pending(fut) = this.polling {
863 if let Poll::Ready(out) = unsafe { Pin::new_unchecked(fut) }.poll(ctx) {
864 this.polling.replace(Polling::Ready(out));
865 }
866
867 Poll::Ready(())
868 } else {
869 unreachable!();
870 }
871 }
872 }
873
874 PollingOnce { polling: self }.await;
875 self
876 }
877}
878
879impl<T, E, Fut: Future<Output = Result<T, E>>> Polling<Fut> {
880 // ===================================== Destructors ==================================== \\
881
882 /// | `self` | return |
883 /// |:--------------------------:|:--------------:|
884 /// | `Polling::Ready(Ok(ok))` | `Ok(Some(ok))` |
885 /// | `Polling::Ready(Err(err))` | `Err(err)` |
886 /// | `Polling::Pending(_)` | `Ok(None)` |
887 /// | `Polling::Done` | `Ok(None)` |
888 ///
889 /// ## Example
890 ///
891 /// ```rust
892 /// use futures_lite::future::{self, Ready};
893 /// use futures_polling::Polling;
894 ///
895 /// let polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
896 /// assert_eq!(polling.try_into_ready(), Ok(Some(42)));
897 ///
898 /// let polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
899 /// assert_eq!(polling.try_into_ready(), Err(42));
900 ///
901 /// let polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
902 /// assert_eq!(polling.try_into_ready(), Ok(None));
903 ///
904 /// let polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
905 /// assert_eq!(polling.try_into_ready(), Ok(None));
906 ///
907 /// let polling = Polling::<Ready<Result<i32, i32>>>::Done;
908 /// assert_eq!(polling.try_into_ready(), Ok(None));
909 /// ```
910 pub fn try_into_ready(self) -> Result<Option<T>, E> {
911 self.into_ready().transpose()
912 }
913
914 /// | `self` | return |
915 /// |:--------------------------:|:---------------------:|
916 /// | `Polling::Ready(Ok(ok))` | `Ok(Poll::Ready(ok))` |
917 /// | `Polling::Ready(Err(err))` | `Err(err)` |
918 /// | `Polling::Pending(_)` | `Ok(Poll::Pending)` |
919 /// | `Polling::Done` | `Ok(Poll::Pending)` |
920 ///
921 /// ## Example
922 ///
923 /// ```rust
924 /// use core::task::Poll;
925 /// use futures_lite::future::{self, Ready};
926 /// use futures_polling::Polling;
927 ///
928 /// let polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
929 /// assert_eq!(polling.try_into_poll(), Ok(Poll::Ready(42)));
930 ///
931 /// let polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
932 /// assert_eq!(polling.try_into_poll(), Err(42));
933 ///
934 /// let polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
935 /// assert_eq!(polling.try_into_poll(), Ok(Poll::Pending));
936 ///
937 /// let polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
938 /// assert_eq!(polling.try_into_poll(), Ok(Poll::Pending));
939 ///
940 /// let polling = Polling::<Ready<Result<i32, i32>>>::Done;
941 /// assert_eq!(polling.try_into_poll(), Ok(Poll::Pending));
942 /// ```
943 pub fn try_into_poll(self) -> Result<Poll<T>, E> {
944 match self.into_poll() {
945 Poll::Ready(Ok(ok)) => Ok(Poll::Ready(ok)),
946 Poll::Ready(Err(err)) => Err(err),
947 Poll::Pending => Ok(Poll::Pending),
948 }
949 }
950
951 // ======================================== Read ======================================== \\
952
953 /// | `&self` | return |
954 /// |:--------------------------:|:---------------:|
955 /// | `Polling::Ready(Ok(ok))` | `Ok(Some(&ok))` |
956 /// | `Polling::Ready(Err(Err))` | `Err(&err)` |
957 /// | `Polling::Pending(_)` | `Ok(None)` |
958 /// | `Polling::Done` | `Ok(None)` |
959 ///
960 /// ## Example
961 ///
962 /// ```rust
963 /// use futures_lite::future::{self, Ready};
964 /// use futures_polling::Polling;
965 ///
966 /// let polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
967 /// assert_eq!(polling.try_as_ready(), Ok(Some(&42)));
968 ///
969 /// let polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
970 /// assert_eq!(polling.try_as_ready(), Err(&42));
971 ///
972 /// let polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
973 /// assert_eq!(polling.try_as_ready(), Ok(None));
974 ///
975 /// let polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
976 /// assert_eq!(polling.try_as_ready(), Ok(None));
977 ///
978 /// let polling = Polling::<Ready<Result<i32, i32>>>::Done;
979 /// assert_eq!(polling.try_as_ready(), Ok(None));
980 /// ```
981 pub fn try_as_ready(&self) -> Result<Option<&T>, &E> {
982 self.as_ready().map(Result::as_ref).transpose()
983 }
984
985 /// | `&self` | return |
986 /// |:--------------------------:|:----------------------:|
987 /// | `Polling::Ready(Ok(ok))` | `Ok(Poll::Ready(&ok))` |
988 /// | `Polling::Ready(Err(Err))` | `Err(&mut err)` |
989 /// | `Polling::Pending(_)` | `Ok(Poll::Pending)` |
990 /// | `Polling::Done` | `Ok(Poll::Pending)` |
991 ///
992 /// ## Example
993 ///
994 /// ```rust
995 /// use core::task::Poll;
996 /// use futures_lite::future::{self, Ready};
997 /// use futures_polling::Polling;
998 ///
999 /// let polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
1000 /// assert_eq!(polling.try_as_poll(), Ok(Poll::Ready(&42)));
1001 ///
1002 /// let polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
1003 /// assert_eq!(polling.try_as_poll(), Err(&42));
1004 ///
1005 /// let polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
1006 /// assert_eq!(polling.try_as_poll(), Ok(Poll::Pending));
1007 ///
1008 /// let polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
1009 /// assert_eq!(polling.try_as_poll(), Ok(Poll::Pending));
1010 ///
1011 /// let polling = Polling::<Ready<Result<i32, i32>>>::Done;
1012 /// assert_eq!(polling.try_as_poll(), Ok(Poll::Pending));
1013 /// ```
1014 pub fn try_as_poll(&self) -> Result<Poll<&T>, &E> {
1015 match self.as_poll() {
1016 Poll::Ready(Ok(ok)) => Ok(Poll::Ready(ok)),
1017 Poll::Ready(Err(err)) => Err(err),
1018 Poll::Pending => Ok(Poll::Pending),
1019 }
1020 }
1021
1022 /// | `&mut self` | return |
1023 /// |:--------------------------:|:-------------------:|
1024 /// | `Polling::Ready(Ok(ok))` | `Ok(Some(&mut ok))` |
1025 /// | `Polling::Ready(Err(Err))` | `Err(&mut err)` |
1026 /// | `Polling::Pending(_)` | `Ok(None)` |
1027 /// | `Polling::Done` | `Ok(None)` |
1028 ///
1029 /// ## Example
1030 ///
1031 /// ```rust
1032 /// use futures_lite::future::{self, Ready};
1033 /// use futures_polling::Polling;
1034 ///
1035 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
1036 /// if let Ok(Some(ok)) = polling.try_as_ready_mut() {
1037 /// assert_eq!(*ok, 42);
1038 /// *ok = 0;
1039 /// } else {
1040 /// unreachable!();
1041 /// }
1042 /// assert_eq!(polling.try_as_ready(), Ok(Some(&0)));
1043 ///
1044 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
1045 /// if let Err(err) = polling.try_as_ready_mut() {
1046 /// assert_eq!(*err, 42);
1047 /// *err = 0;
1048 /// } else {
1049 /// unreachable!();
1050 /// }
1051 /// assert_eq!(polling.try_as_ready(), Err(&0));
1052 ///
1053 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
1054 /// assert_eq!(polling.try_as_ready_mut(), Ok(None));
1055 ///
1056 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
1057 /// assert_eq!(polling.try_as_ready_mut(), Ok(None));
1058 ///
1059 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Done;
1060 /// assert_eq!(polling.try_as_ready_mut(), Ok(None));
1061 /// ```
1062 pub fn try_as_ready_mut(&mut self) -> Result<Option<&mut T>, &mut E> {
1063 self.as_ready_mut().map(Result::as_mut).transpose()
1064 }
1065
1066 /// | `&mut self` | return |
1067 /// |:--------------------------:|:--------------------------:|
1068 /// | `Polling::Ready(Ok(ok))` | `Ok(Poll::Ready(&mut ok))` |
1069 /// | `Polling::Ready(Err(Err))` | `Err(&mut err)` |
1070 /// | `Polling::Pending(_)` | `Ok(Poll::Pending)` |
1071 /// | `Polling::Done` | `Ok(Poll::Pending)` |
1072 ///
1073 /// ## Example
1074 ///
1075 /// ```rust
1076 /// use core::task::Poll;
1077 /// use futures_lite::future::{self, Ready};
1078 /// use futures_polling::Polling;
1079 ///
1080 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
1081 /// if let Ok(Poll::Ready(ok)) = polling.try_as_poll_mut() {
1082 /// assert_eq!(*ok, 42);
1083 /// *ok = 0;
1084 /// } else {
1085 /// unreachable!();
1086 /// }
1087 /// assert_eq!(polling.try_as_poll(), Ok(Poll::Ready(&0)));
1088 ///
1089 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
1090 /// if let Err(err) = polling.try_as_poll_mut() {
1091 /// assert_eq!(*err, 42);
1092 /// *err = 0;
1093 /// } else {
1094 /// unreachable!();
1095 /// }
1096 /// assert_eq!(polling.try_as_poll(), Err(&0));
1097 ///
1098 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
1099 /// assert_eq!(polling.try_as_poll_mut(), Ok(Poll::Pending));
1100 ///
1101 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
1102 /// assert_eq!(polling.try_as_poll_mut(), Ok(Poll::Pending));
1103 ///
1104 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Done;
1105 /// assert_eq!(polling.try_as_poll_mut(), Ok(Poll::Pending));
1106 /// ```
1107 pub fn try_as_poll_mut(&mut self) -> Result<Poll<&mut T>, &mut E> {
1108 match self.as_poll_mut() {
1109 Poll::Ready(Ok(ok)) => Ok(Poll::Ready(ok)),
1110 Poll::Ready(Err(err)) => Err(err),
1111 Poll::Pending => Ok(Poll::Pending),
1112 }
1113 }
1114
1115 // ===================================== Read+Write ===================================== \\
1116
1117 /// | `&mut self` | new `self` value | return |
1118 /// |:--------------------------:|:-----------------------:|:--------------:|
1119 /// | `Polling::Ready(Ok(ok))` | `Polling::Done` | `Ok(Some(ok))` |
1120 /// | `Polling::Ready(Err(err))` | `Polling::Done` | `Err(err)` |
1121 /// | `Polling::Pending(fut)` | `Polling::Pending(fut)` | `Ok(None)` |
1122 /// | `Polling::Done` | `Polling::Done` | `Ok(None)` |
1123 ///
1124 /// ## Example
1125 ///
1126 /// ```rust
1127 /// use futures_lite::future::{self, Ready};
1128 /// use futures_polling::Polling;
1129 ///
1130 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
1131 /// assert_eq!(polling.try_take_ready(), Ok(Some(42)));
1132 /// assert_eq!(polling.try_into_ready(), Ok(None));
1133 ///
1134 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
1135 /// assert_eq!(polling.try_take_ready(), Err(42));
1136 /// assert_eq!(polling.try_into_ready(), Ok(None));
1137 ///
1138 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
1139 /// assert_eq!(polling.try_take_ready(), Ok(None));
1140 ///
1141 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
1142 /// assert_eq!(polling.try_take_ready(), Ok(None));
1143 ///
1144 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Done;
1145 /// assert_eq!(polling.try_take_ready(), Ok(None));
1146 /// ```
1147 pub fn try_take_ready(&mut self) -> Result<Option<T>, E> {
1148 self.take_ready().transpose()
1149 }
1150
1151 /// | `&mut self` | new `self` value | return |
1152 /// |:--------------------------:|:-----------------------:|:---------------------:|
1153 /// | `Polling::Ready(Ok(ok))` | `Polling::Done` | `Ok(Poll::Ready(ok))` |
1154 /// | `Polling::Ready(Err(err))` | `Polling::Done` | `Err(err)` |
1155 /// | `Polling::Pending(fut)` | `Polling::Pending(fut)` | `Ok(Poll::Pending)` |
1156 /// | `Polling::Done` | `Polling::Done` | `Ok(Poll::Pending)` |
1157 ///
1158 /// ## Example
1159 ///
1160 /// ```rust
1161 /// use core::task::Poll;
1162 /// use futures_lite::future::{self, Ready};
1163 /// use futures_polling::Polling;
1164 ///
1165 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
1166 /// assert_eq!(polling.try_take_poll(), Ok(Poll::Ready(42)));
1167 /// assert_eq!(polling.try_into_ready(), Ok(None));
1168 ///
1169 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
1170 /// assert_eq!(polling.try_take_poll(), Err(42));
1171 /// assert_eq!(polling.try_into_ready(), Ok(None));
1172 ///
1173 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
1174 /// assert_eq!(polling.try_take_poll(), Ok(Poll::Pending));
1175 ///
1176 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
1177 /// assert_eq!(polling.try_take_poll(), Ok(Poll::Pending));
1178 ///
1179 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Done;
1180 /// assert_eq!(polling.try_take_poll(), Ok(Poll::Pending));
1181 /// ```
1182 pub fn try_take_poll(&mut self) -> Result<Poll<T>, E> {
1183 match self.take_poll() {
1184 Poll::Ready(Ok(ok)) => Ok(Poll::Ready(ok)),
1185 Poll::Ready(Err(err)) => Err(err),
1186 Poll::Pending => Ok(Poll::Pending),
1187 }
1188 }
1189
1190 /// | `&mut self` | `fut.poll(ctx)` | new `self` value | return |
1191 /// |:--------------------------:|:-----------------------:|:-----------------------:|:---------------------:|
1192 /// | `Polling::Ready(Ok(ok))` | x | `Polling::Done` | `Ok(Poll:Ready(ok))` |
1193 /// | `Polling::Ready(Err(err))` | x | `Polling::Done` | `Err(err)` |
1194 /// | `Polling::Pending(fut)` | `Poll::Ready(Ok(ok))` | `Polling::Done` | `Ok(Poll::Ready(ok))` |
1195 /// | `Polling::Pending(fut)` | `Poll::Ready(Err(err))` | `Polling::Done` | `Err(err)` |
1196 /// | `Polling::Pending(fut)` | `Poll::Pending` | `Polling::Pending(fut)` | `Ok(Poll::Pending)` |
1197 /// | `Polling::Done` | x | panic!() | panic!() |
1198 ///
1199 /// ## Example
1200 ///
1201 /// ```rust
1202 /// use core::pin::Pin;
1203 /// use core::task::Poll;
1204 /// use futures_lite::future::{self, Pending, Ready};
1205 /// use futures_polling::Polling;
1206 ///
1207 /// # future::block_on(future::poll_fn(|ctx| {
1208 /// #
1209 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
1210 /// assert_eq!(Pin::new(&mut polling).try_poll(ctx), Ok(Poll::Ready(42)));
1211 /// assert_eq!(polling.is_done(), true);
1212 ///
1213 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
1214 /// assert_eq!(Pin::new(&mut polling).try_poll(ctx), Err(42));
1215 /// assert_eq!(polling.is_done(), true);
1216 ///
1217 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
1218 /// assert_eq!(Pin::new(&mut polling).try_poll(ctx), Ok(Poll::Ready(42)));
1219 /// assert_eq!(polling.is_done(), true);
1220 ///
1221 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
1222 /// assert_eq!(Pin::new(&mut polling).try_poll(ctx), Err(42));
1223 /// assert_eq!(polling.is_done(), true);
1224 ///
1225 /// let mut polling = Polling::<Pending<Result<i32, i32>>>::Pending(future::pending());
1226 /// assert_eq!(Pin::new(&mut polling).try_poll(ctx), Ok(Poll::Pending));
1227 /// assert_eq!(polling.is_done(), false);
1228 /// #
1229 /// # Poll::Ready(()) }));
1230 /// ```
1231 pub fn try_poll(self: Pin<&mut Self>, ctx: &mut Context) -> Result<Poll<T>, E> {
1232 match self.poll(ctx) {
1233 Poll::Ready(Ok(ok)) => Ok(Poll::Ready(ok)),
1234 Poll::Ready(Err(err)) => Err(err),
1235 Poll::Pending => Ok(Poll::Pending),
1236 }
1237 }
1238
1239 /// | `&mut self` | `fut.poll(_)` | new `self` value | return |
1240 /// |:--------------------------:|:-----------------------:|:-----------------------:|:---------------------:|
1241 /// | `Polling::Ready(Ok(ok))` | x | `Polling::Done` | `Ok(Poll:Ready(ok))` |
1242 /// | `Polling::Ready(Err(err))` | x | `Polling::Done` | `Err(err)` |
1243 /// | `Polling::Pending(fut)` | `Poll::Ready(Ok(ok))` | `Polling::Done` | `Ok(Poll::Ready(ok))` |
1244 /// | `Polling::Pending(fut)` | `Poll::Ready(Err(err))` | `Polling::Done` | `Err(err)` |
1245 /// | `Polling::Pending(fut)` | `Poll::Pending` | `Polling::Pending(fut)` | `Ok(Poll::Pending)` |
1246 /// | `Polling::Done` | x | panic!() | panic!() |
1247 ///
1248 /// ## Example
1249 ///
1250 /// ```rust
1251 /// use core::task::Poll;
1252 /// use futures_lite::future::{self, Pending, Ready};
1253 /// use futures_polling::Polling;
1254 ///
1255 /// # future::block_on(async {
1256 /// #
1257 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Ok(42));
1258 /// assert_eq!(polling.try_poll_once().await, Ok(Poll::Ready(42)));
1259 /// assert_eq!(polling.is_done(), true);
1260 ///
1261 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Ready(Err(42));
1262 /// assert_eq!(polling.try_poll_once().await, Err(42));
1263 /// assert_eq!(polling.is_done(), true);
1264 ///
1265 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Ok(42)));
1266 /// assert_eq!(polling.try_poll_once().await, Ok(Poll::Ready(42)));
1267 /// assert_eq!(polling.is_done(), true);
1268 ///
1269 /// let mut polling = Polling::<Ready<Result<i32, i32>>>::Pending(future::ready(Err(42)));
1270 /// assert_eq!(polling.try_poll_once().await, Err(42));
1271 /// assert_eq!(polling.is_done(), true);
1272 ///
1273 /// let mut polling = Polling::<Pending<Result<i32, i32>>>::Pending(future::pending());
1274 /// assert_eq!(polling.try_poll_once().await, Ok(Poll::Pending));
1275 /// assert_eq!(polling.is_done(), false);
1276 /// #
1277 /// # });
1278 /// ```
1279 pub async fn try_poll_once(&mut self) -> Result<Poll<T>, E> {
1280 self.polling_once().await;
1281 self.try_take_poll()
1282 }
1283}
1284
1285// ========================================= impl Future ======================================== \\
1286
1287impl<Fut: Future> Future for Polling<Fut> {
1288 type Output = Fut::Output;
1289
1290 fn poll(self: Pin<&mut Self>, ctx: &mut Context) -> Poll<Self::Output> {
1291 let this = unsafe { self.get_unchecked_mut() };
1292 match this {
1293 Polling::Ready(_) => this.take().into_poll(),
1294 Polling::Pending(fut) => {
1295 let poll = unsafe { Pin::new_unchecked(fut) }.poll(ctx);
1296 if poll.is_ready() {
1297 this.take();
1298 }
1299
1300 poll
1301 },
1302 Polling::Done => panic!("output already extracted"),
1303 }
1304 }
1305}
1306
1307// ========================================== impl From ========================================= \\
1308
1309impl<Fut: Future> From<Fut> for Polling<Fut> {
1310 fn from(fut: Fut) -> Self {
1311 Polling::Pending(fut)
1312 }
1313}