1#![cfg_attr(not(feature = "std"), no_std)]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3#![warn(missing_docs)]
4#![doc = include_str!("../README.md")]
5// disable warning for already-stabilized features.
6// Needed to pass CI, because we deny warnings.
7// We don't immediately remove them to not immediately break older nightlies.
8// When all features are stable, we'll remove them.
9#![cfg_attr(nightly, allow(stable_features, unknown_lints))]
10#![cfg_attr(nightly, feature(async_fn_in_trait, impl_trait_projections))]
11#![allow(async_fn_in_trait)]
12
13#[cfg(feature = "alloc")]
14extern crate alloc;
15
16mod impls;
17
18pub use embedded_io::{
19 Error, ErrorKind, ErrorType, ReadExactError, ReadReady, SeekFrom, WriteReady,
20};
21
22/// Async reader.
23///
24/// This trait is the `embedded-io-async` equivalent of [`std::io::Read`].
25pub trait Read: ErrorType {
26 /// Read some bytes from this source into the specified buffer, returning how many bytes were read.
27 ///
28 /// If no bytes are currently available to read, this function waits until at least one byte is available.
29 ///
30 /// If bytes are available, a non-zero amount of bytes is read to the beginning of `buf`, and the amount
31 /// is returned. It is not guaranteed that *all* available bytes are returned, it is possible for the
32 /// implementation to read an amount of bytes less than `buf.len()` while there are more bytes immediately
33 /// available.
34 ///
35 /// If the reader is at end-of-file (EOF), `Ok(0)` is returned. There is no guarantee that a reader at EOF
36 /// will always be so in the future, for example a reader can stop being at EOF if another process appends
37 /// more bytes to the underlying file.
38 ///
39 /// If `buf.len() == 0`, `read` returns without waiting, with either `Ok(0)` or an error.
40 /// The `Ok(0)` doesn't indicate EOF, unlike when called with a non-empty buffer.
41 ///
42 /// Implementations are encouraged to make this function side-effect-free on cancel (AKA "cancel-safe"), i.e.
43 /// guarantee that if you cancel (drop) a `read()` future that hasn't completed yet, the stream's
44 /// state hasn't changed (no bytes have been read).
45 ///
46 /// This is not a requirement to allow implementations that read into the user's buffer straight from
47 /// the hardware with e.g. DMA.
48 ///
49 /// Implementations should document whether they're actually side-effect-free on cancel or not.
50 async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>;
51
52 /// Read the exact number of bytes required to fill `buf`.
53 ///
54 /// This function calls `read()` in a loop until exactly `buf.len()` bytes have
55 /// been read, waiting if needed.
56 ///
57 /// This function is not side-effect-free on cancel (AKA "cancel-safe"), i.e. if you cancel (drop) a returned
58 /// future that hasn't completed yet, some bytes might have already been read, which will get lost.
59 async fn read_exact(&mut self, mut buf: &mut [u8]) -> Result<(), ReadExactError<Self::Error>> {
60 while !buf.is_empty() {
61 match self.read(buf).await {
62 Ok(0) => break,
63 Ok(n) => buf = &mut buf[n..],
64 Err(e) => return Err(ReadExactError::Other(e)),
65 }
66 }
67 if buf.is_empty() {
68 Ok(())
69 } else {
70 Err(ReadExactError::UnexpectedEof)
71 }
72 }
73}
74
75/// Async buffered reader.
76///
77/// This trait is the `embedded-io-async` equivalent of [`std::io::BufRead`].
78pub trait BufRead: ErrorType {
79 /// Return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.
80 ///
81 /// If no bytes are currently available to read, this function waits until at least one byte is available.
82 ///
83 /// If the reader is at end-of-file (EOF), an empty slice is returned. There is no guarantee that a reader at EOF
84 /// will always be so in the future, for example a reader can stop being at EOF if another process appends
85 /// more bytes to the underlying file.
86 async fn fill_buf(&mut self) -> Result<&[u8], Self::Error>;
87
88 /// Tell this buffer that `amt` bytes have been consumed from the buffer, so they should no longer be returned in calls to `fill_buf`.
89 fn consume(&mut self, amt: usize);
90}
91
92/// Async writer.
93///
94/// This trait is the `embedded-io-async` equivalent of [`std::io::Write`].
95pub trait Write: ErrorType {
96 /// Write a buffer into this writer, returning how many bytes were written.
97 ///
98 /// If the writer is not currently ready to accept more bytes (for example, its buffer is full),
99 /// this function waits until it is ready to accept least one byte.
100 ///
101 /// If it's ready to accept bytes, a non-zero amount of bytes is written from the beginning of `buf`, and the amount
102 /// is returned. It is not guaranteed that *all* available buffer space is filled, i.e. it is possible for the
103 /// implementation to write an amount of bytes less than `buf.len()` while the writer continues to be
104 /// ready to accept more bytes immediately.
105 ///
106 /// Implementations should never return `Ok(0)` when `buf.len() != 0`. Situations where the writer is not
107 /// able to accept more bytes and likely never will are better indicated with errors.
108 ///
109 /// If `buf.len() == 0`, `write` returns without waiting, with either `Ok(0)` or an error.
110 /// The `Ok(0)` doesn't indicate an error.
111 ///
112 /// Implementations are encouraged to make this function side-effect-free on cancel (AKA "cancel-safe"), i.e.
113 /// guarantee that if you cancel (drop) a `write()` future that hasn't completed yet, the stream's
114 /// state hasn't changed (no bytes have been written).
115 ///
116 /// This is not a requirement to allow implementations that write from the user's buffer straight to
117 /// the hardware with e.g. DMA.
118 ///
119 /// Implementations should document whether they're actually side-effect-free on cancel or not.
120 async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>;
121
122 /// Flush this output stream, ensuring that all intermediately buffered contents reach their destination.
123 async fn flush(&mut self) -> Result<(), Self::Error> {
124 Ok(())
125 }
126
127 /// Write an entire buffer into this writer.
128 ///
129 /// This function calls `write()` in a loop until exactly `buf.len()` bytes have
130 /// been written, waiting if needed.
131 ///
132 /// This function is not side-effect-free on cancel (AKA "cancel-safe"), i.e. if you cancel (drop) a returned
133 /// future that hasn't completed yet, some bytes might have already been written.
134 async fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error> {
135 let mut buf = buf;
136 while !buf.is_empty() {
137 match self.write(buf).await {
138 Ok(0) => panic!("write() returned Ok(0)"),
139 Ok(n) => buf = &buf[n..],
140 Err(e) => return Err(e),
141 }
142 }
143 Ok(())
144 }
145}
146
147/// Async seek within streams.
148///
149/// This trait is the `embedded-io-async` equivalent of [`std::io::Seek`].
150pub trait Seek: ErrorType {
151 /// Seek to an offset, in bytes, in a stream.
152 async fn seek(&mut self, pos: SeekFrom) -> Result<u64, Self::Error>;
153
154 /// Rewind to the beginning of a stream.
155 async fn rewind(&mut self) -> Result<(), Self::Error> {
156 self.seek(pos:SeekFrom::Start(0)).await?;
157 Ok(())
158 }
159
160 /// Returns the current seek position from the start of the stream.
161 async fn stream_position(&mut self) -> Result<u64, Self::Error> {
162 self.seek(pos:SeekFrom::Current(0)).await
163 }
164}
165
166impl<T: ?Sized + Read> Read for &mut T {
167 #[inline]
168 async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error> {
169 T::read(self, buf).await
170 }
171}
172
173impl<T: ?Sized + BufRead> BufRead for &mut T {
174 async fn fill_buf(&mut self) -> Result<&[u8], Self::Error> {
175 T::fill_buf(self).await
176 }
177
178 fn consume(&mut self, amt: usize) {
179 T::consume(self, amt);
180 }
181}
182
183impl<T: ?Sized + Write> Write for &mut T {
184 #[inline]
185 async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error> {
186 T::write(self, buf).await
187 }
188
189 #[inline]
190 async fn flush(&mut self) -> Result<(), Self::Error> {
191 T::flush(self).await
192 }
193}
194
195impl<T: ?Sized + Seek> Seek for &mut T {
196 #[inline]
197 async fn seek(&mut self, pos: SeekFrom) -> Result<u64, Self::Error> {
198 T::seek(self, pos).await
199 }
200}
201