1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
use crate::io::util::flush::{flush, Flush};
use crate::io::util::shutdown::{shutdown, Shutdown};
use crate::io::util::write::{write, Write};
use crate::io::util::write_all::{write_all, WriteAll};
use crate::io::AsyncWrite;
cfg_io_util! {
/// Write bytes to a sink.
///
/// Implemented as an extention trait, adding utility methods to all
/// [`AsyncWrite`] types. Callers will tend to import this trait instead of
/// [`AsyncWrite`].
///
/// As a convenience, this trait may be imported using the [`prelude`]:
///
/// ```no_run
/// use tokio::prelude::*;
/// use tokio::fs::File;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let data = b"some bytes";
///
/// let mut pos = 0;
/// let mut buffer = File::create("foo.txt").await?;
///
/// while pos < data.len() {
/// let bytes_written = buffer.write(&data[pos..]).await?;
/// pos += bytes_written;
/// }
///
/// Ok(())
/// }
/// ```
///
/// See [module][crate::io] documentation for more details.
///
/// [`AsyncWrite`]: AsyncWrite
/// [`prelude`]: crate::prelude
pub trait AsyncWriteExt: AsyncWrite {
/// Write a buffer into this writer, returning how many bytes were
/// written.
///
/// Equivalent to:
///
/// ```ignore
/// async fn write(&mut self, buf: &[u8]) -> io::Result<usize>;
/// ```
///
/// This function will attempt to write the entire contents of `buf`, but
/// the entire write may not succeed, or the write may also generate an
/// error. A call to `write` represents *at most one* attempt to write to
/// any wrapped object.
///
/// If the return value is `Ok(n)` then it must be guaranteed that `n <=
/// buf.len()`. A return value of `0` typically means that the
/// underlying object is no longer able to accept bytes and will likely
/// not be able to in the future as well, or that the buffer provided is
/// empty.
///
/// # Errors
///
/// Each call to `write` may generate an I/O error indicating that the
/// operation could not be completed. If an error is returned then no bytes
/// in the buffer were written to this writer.
///
/// It is **not** considered an error if the entire buffer could not be
/// written to this writer.
///
/// # Examples
///
/// ```no_run
/// use tokio::io::{self, AsyncWriteExt};
/// use tokio::fs::File;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut buffer = File::create("foo.txt").await?;
///
/// // Writes some prefix of the byte string, not necessarily all of it.
/// buffer.write(b"some bytes").await?;
/// Ok(())
/// }
/// ```
fn write<'a>(&'a mut self, src: &'a [u8]) -> Write<'a, Self>
where
Self: Unpin,
{
write(self, src)
}
/// Attempts to write an entire buffer into this writer.
///
/// Equivalent to:
///
/// ```ignore
/// async fn write_all(&mut self, buf: &[u8]) -> io::Result<()>;
/// ```
///
/// This method will continuously call [`write`] until there is no more data
/// to be written. This method will not return until the entire buffer
/// has been successfully written or such an error occurs. The first
/// error generated from this method will be returned.
///
/// # Errors
///
/// This function will return the first error that [`write`] returns.
///
/// # Examples
///
/// ```no_run
/// use tokio::io::{self, AsyncWriteExt};
/// use tokio::fs::File;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let mut buffer = File::create("foo.txt").await?;
///
/// buffer.write_all(b"some bytes").await?;
/// Ok(())
/// }
/// ```
///
/// [`write`]: AsyncWriteExt::write
fn write_all<'a>(&'a mut self, src: &'a [u8]) -> WriteAll<'a, Self>
where
Self: Unpin,
{
write_all(self, src)
}
/// Flush this output stream, ensuring that all intermediately buffered
/// contents reach their destination.
///
/// Equivalent to:
///
/// ```ignore
/// async fn flush(&mut self) -> io::Result<()>;
/// ```
///
/// # Errors
///
/// It is considered an error if not all bytes could be written due to
/// I/O errors or EOF being reached.
///
/// # Examples
///
/// ```no_run
/// use tokio::io::{self, BufWriter, AsyncWriteExt};
/// use tokio::fs::File;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let f = File::create("foo.txt").await?;
/// let mut buffer = BufWriter::new(f);
///
/// buffer.write_all(b"some bytes").await?;
/// buffer.flush().await?;
/// Ok(())
/// }
/// ```
fn flush(&mut self) -> Flush<'_, Self>
where
Self: Unpin,
{
flush(self)
}
/// Shuts down the output stream, ensuring that the value can be dropped
/// cleanly.
///
/// Equivalent to:
///
/// ```ignore
/// async fn shutdown(&mut self) -> io::Result<()>;
/// ```
///
/// Similar to [`flush`], all intermediately buffered is written to the
/// underlying stream. Once the operation completes, the caller should
/// no longer attempt to write to the stream. For example, the
/// `TcpStream` implementation will issue a `shutdown(Write)` sys call.
///
/// # Examples
///
/// ```no_run
/// use tokio::io::{self, BufWriter, AsyncWriteExt};
/// use tokio::fs::File;
///
/// #[tokio::main]
/// async fn main() -> io::Result<()> {
/// let f = File::create("foo.txt").await?;
/// let mut buffer = BufWriter::new(f);
///
/// buffer.write_all(b"some bytes").await?;
/// buffer.shutdown().await?;
/// Ok(())
/// }
/// ```
fn shutdown(&mut self) -> Shutdown<'_, Self>
where
Self: Unpin,
{
shutdown(self)
}
}
}
impl<W: AsyncWrite + ?Sized> AsyncWriteExt for W {}