futures_test/io/read/
mod.rs

1//! Additional combinators for testing async readers.
2
3use futures_io::AsyncRead;
4
5pub use super::limited::Limited;
6pub use crate::assert_unmoved::AssertUnmoved;
7pub use crate::interleave_pending::InterleavePending;
8
9/// Additional combinators for testing async readers.
10pub trait AsyncReadTestExt: AsyncRead {
11    /// Asserts that the given is not moved after being polled.
12    ///
13    /// A check for movement is performed each time the reader is polled
14    /// and when `Drop` is called.
15    ///
16    /// Aside from keeping track of the location at which the reader was first
17    /// polled and providing assertions, this reader adds no runtime behavior
18    /// and simply delegates to the child reader.
19    fn assert_unmoved(self) -> AssertUnmoved<Self>
20    where
21        Self: Sized,
22    {
23        AssertUnmoved::new(self)
24    }
25
26    /// Introduces an extra [`Poll::Pending`](futures_core::task::Poll::Pending)
27    /// in between each read of the reader.
28    ///
29    /// # Examples
30    ///
31    /// ```
32    /// use core::pin::pin;
33    ///
34    /// use futures::task::Poll;
35    /// use futures::io::{AsyncRead, Cursor};
36    /// use futures_test::task::noop_context;
37    /// use futures_test::io::AsyncReadTestExt;
38    ///
39    /// let reader = Cursor::new(&[1, 2, 3]).interleave_pending();
40    /// let mut reader = pin!(reader);
41    ///
42    /// let mut cx = noop_context();
43    ///
44    /// let mut buf = [0, 0];
45    ///
46    /// assert_eq!(reader.as_mut().poll_read(&mut cx, &mut buf[..])?, Poll::Pending);
47    /// assert_eq!(reader.as_mut().poll_read(&mut cx, &mut buf[..])?, Poll::Ready(2));
48    /// assert_eq!(buf, [1, 2]);
49    /// assert_eq!(reader.as_mut().poll_read(&mut cx, &mut buf[..])?, Poll::Pending);
50    /// assert_eq!(reader.as_mut().poll_read(&mut cx, &mut buf[..])?, Poll::Ready(1));
51    /// assert_eq!(buf, [3, 2]);
52    /// assert_eq!(reader.as_mut().poll_read(&mut cx, &mut buf[..])?, Poll::Pending);
53    /// assert_eq!(reader.as_mut().poll_read(&mut cx, &mut buf[..])?, Poll::Ready(0));
54    ///
55    /// # Ok::<(), std::io::Error>(())
56    /// ```
57    ///
58    /// ## `AsyncBufRead`
59    ///
60    /// The returned reader will also implement `AsyncBufRead` if the underlying reader does.
61    ///
62    /// ```
63    /// use core::pin::pin;
64    ///
65    /// use futures::task::Poll;
66    /// use futures::io::{AsyncBufRead, Cursor};
67    /// use futures_test::task::noop_context;
68    /// use futures_test::io::AsyncReadTestExt;
69    ///
70    /// let reader = Cursor::new(&[1, 2, 3]).interleave_pending();
71    /// let mut reader = pin!(reader);
72    ///
73    /// let mut cx = noop_context();
74    ///
75    /// assert_eq!(reader.as_mut().poll_fill_buf(&mut cx)?, Poll::Pending);
76    /// assert_eq!(reader.as_mut().poll_fill_buf(&mut cx)?, Poll::Ready(&[1, 2, 3][..]));
77    /// reader.as_mut().consume(2);
78    /// assert_eq!(reader.as_mut().poll_fill_buf(&mut cx)?, Poll::Pending);
79    /// assert_eq!(reader.as_mut().poll_fill_buf(&mut cx)?, Poll::Ready(&[3][..]));
80    /// reader.as_mut().consume(1);
81    /// assert_eq!(reader.as_mut().poll_fill_buf(&mut cx)?, Poll::Pending);
82    /// assert_eq!(reader.as_mut().poll_fill_buf(&mut cx)?, Poll::Ready(&[][..]));
83    ///
84    /// # Ok::<(), std::io::Error>(())
85    /// ```
86    fn interleave_pending(self) -> InterleavePending<Self>
87    where
88        Self: Sized,
89    {
90        InterleavePending::new(self)
91    }
92
93    /// Limit the number of bytes allowed to be read on each call to `poll_read`.
94    ///
95    /// # Examples
96    ///
97    /// ```
98    /// use core::pin::pin;
99    ///
100    /// use futures::task::Poll;
101    /// use futures::io::{AsyncRead, Cursor};
102    /// use futures_test::task::noop_context;
103    /// use futures_test::io::AsyncReadTestExt;
104    ///
105    /// let reader = Cursor::new(&[1, 2, 3, 4, 5]).limited(2);
106    /// let mut reader = pin!(reader);
107    ///
108    /// let mut cx = noop_context();
109    ///
110    /// let mut buf = [0; 10];
111    ///
112    /// assert_eq!(reader.as_mut().poll_read(&mut cx, &mut buf)?, Poll::Ready(2));
113    /// assert_eq!(&buf[..2], &[1, 2]);
114    /// assert_eq!(reader.as_mut().poll_read(&mut cx, &mut buf)?, Poll::Ready(2));
115    /// assert_eq!(&buf[..2], &[3, 4]);
116    /// assert_eq!(reader.as_mut().poll_read(&mut cx, &mut buf)?, Poll::Ready(1));
117    /// assert_eq!(&buf[..1], &[5]);
118    ///
119    /// # Ok::<(), std::io::Error>(())
120    /// ```
121    fn limited(self, limit: usize) -> Limited<Self>
122    where
123        Self: Sized,
124    {
125        Limited::new(self, limit)
126    }
127}
128
129impl<R> AsyncReadTestExt for R where R: AsyncRead {}
futures_test/io/read/mod.rs

futures_test/io/read/
mod.rs
