tokio/io/util/async_write_ext.rs
1use crate::io::util::flush::{flush, Flush};
2use crate::io::util::shutdown::{shutdown, Shutdown};
3use crate::io::util::write::{write, Write};
4use crate::io::util::write_all::{write_all, WriteAll};
5use crate::io::util::write_all_buf::{write_all_buf, WriteAllBuf};
6use crate::io::util::write_buf::{write_buf, WriteBuf};
7use crate::io::util::write_int::{WriteF32, WriteF32Le, WriteF64, WriteF64Le};
8use crate::io::util::write_int::{
9 WriteI128, WriteI128Le, WriteI16, WriteI16Le, WriteI32, WriteI32Le, WriteI64, WriteI64Le,
10 WriteI8,
11};
12use crate::io::util::write_int::{
13 WriteU128, WriteU128Le, WriteU16, WriteU16Le, WriteU32, WriteU32Le, WriteU64, WriteU64Le,
14 WriteU8,
15};
16use crate::io::util::write_vectored::{write_vectored, WriteVectored};
17use crate::io::AsyncWrite;
18use std::io::IoSlice;
19
20use bytes::Buf;
21
22cfg_io_util! {
23 /// Defines numeric writer.
24 macro_rules! write_impl {
25 (
26 $(
27 $(#[$outer:meta])*
28 fn $name:ident(&mut self, n: $ty:ty) -> $($fut:ident)*;
29 )*
30 ) => {
31 $(
32 $(#[$outer])*
33 fn $name(&mut self, n: $ty) -> $($fut)*<&mut Self> where Self: Unpin {
34 $($fut)*::new(self, n)
35 }
36 )*
37 }
38 }
39
40 /// Writes bytes to a sink.
41 ///
42 /// Implemented as an extension trait, adding utility methods to all
43 /// [`AsyncWrite`] types. Callers will tend to import this trait instead of
44 /// [`AsyncWrite`].
45 ///
46 /// ```no_run
47 /// # #[cfg(not(target_family = "wasm"))]
48 /// # {
49 /// use tokio::io::{self, AsyncWriteExt};
50 /// use tokio::fs::File;
51 ///
52 /// #[tokio::main]
53 /// async fn main() -> io::Result<()> {
54 /// let data = b"some bytes";
55 ///
56 /// let mut pos = 0;
57 /// let mut buffer = File::create("foo.txt").await?;
58 ///
59 /// while pos < data.len() {
60 /// let bytes_written = buffer.write(&data[pos..]).await?;
61 /// pos += bytes_written;
62 /// }
63 ///
64 /// Ok(())
65 /// }
66 /// # }
67 /// ```
68 ///
69 /// See [module][crate::io] documentation for more details.
70 ///
71 /// [`AsyncWrite`]: AsyncWrite
72 pub trait AsyncWriteExt: AsyncWrite {
73 /// Writes a buffer into this writer, returning how many bytes were
74 /// written.
75 ///
76 /// Equivalent to:
77 ///
78 /// ```ignore
79 /// async fn write(&mut self, buf: &[u8]) -> io::Result<usize>;
80 /// ```
81 ///
82 /// This function will attempt to write the entire contents of `buf`, but
83 /// the entire write may not succeed, or the write may also generate an
84 /// error. A call to `write` represents *at most one* attempt to write to
85 /// any wrapped object.
86 ///
87 /// # Return
88 ///
89 /// If the return value is `Ok(n)` then it must be guaranteed that `n <=
90 /// buf.len()`. A return value of `0` typically means that the
91 /// underlying object is no longer able to accept bytes and will likely
92 /// not be able to in the future as well, or that the buffer provided is
93 /// empty.
94 ///
95 /// # Errors
96 ///
97 /// Each call to `write` may generate an I/O error indicating that the
98 /// operation could not be completed. If an error is returned then no bytes
99 /// in the buffer were written to this writer.
100 ///
101 /// It is **not** considered an error if the entire buffer could not be
102 /// written to this writer.
103 ///
104 /// # Cancel safety
105 ///
106 /// This method is cancel safe. If it is used as a branch in
107 /// [`tokio::select!`](crate::select) and another branch completes
108 /// first, then it is guaranteed that no data was
109 /// written to this `AsyncWrite`.
110 ///
111 /// # Examples
112 ///
113 /// ```no_run
114 /// # #[cfg(not(target_family = "wasm"))]
115 /// # {
116 /// use tokio::io::{self, AsyncWriteExt};
117 /// use tokio::fs::File;
118 ///
119 /// #[tokio::main]
120 /// async fn main() -> io::Result<()> {
121 /// let mut file = File::create("foo.txt").await?;
122 ///
123 /// // Writes some prefix of the byte string, not necessarily all of it.
124 /// file.write(b"some bytes").await?;
125 /// file.flush().await?;
126 /// Ok(())
127 /// }
128 /// # }
129 /// ```
130 fn write<'a>(&'a mut self, src: &'a [u8]) -> Write<'a, Self>
131 where
132 Self: Unpin,
133 {
134 write(self, src)
135 }
136
137 /// Like [`write`], except that it writes from a slice of buffers.
138 ///
139 /// Equivalent to:
140 ///
141 /// ```ignore
142 /// async fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize>;
143 /// ```
144 ///
145 /// See [`AsyncWrite::poll_write_vectored`] for more details.
146 ///
147 /// # Cancel safety
148 ///
149 /// This method is cancel safe. If it is used as a branch in
150 /// [`tokio::select!`](crate::select) and another branch completes
151 /// first, then it is guaranteed that no data was
152 /// written to this `AsyncWrite`.
153 ///
154 /// # Examples
155 ///
156 /// ```no_run
157 /// # #[cfg(not(target_family = "wasm"))]
158 /// # {
159 /// use tokio::io::{self, AsyncWriteExt};
160 /// use tokio::fs::File;
161 /// use std::io::IoSlice;
162 ///
163 /// #[tokio::main]
164 /// async fn main() -> io::Result<()> {
165 /// let mut file = File::create("foo.txt").await?;
166 ///
167 /// let bufs: &[_] = &[
168 /// IoSlice::new(b"hello"),
169 /// IoSlice::new(b" "),
170 /// IoSlice::new(b"world"),
171 /// ];
172 ///
173 /// file.write_vectored(&bufs).await?;
174 /// file.flush().await?;
175 ///
176 /// Ok(())
177 /// }
178 /// # }
179 /// ```
180 ///
181 /// [`write`]: AsyncWriteExt::write
182 fn write_vectored<'a, 'b>(&'a mut self, bufs: &'a [IoSlice<'b>]) -> WriteVectored<'a, 'b, Self>
183 where
184 Self: Unpin,
185 {
186 write_vectored(self, bufs)
187 }
188
189 /// Writes a buffer into this writer, advancing the buffer's internal
190 /// cursor.
191 ///
192 /// Equivalent to:
193 ///
194 /// ```ignore
195 /// async fn write_buf<B: Buf>(&mut self, buf: &mut B) -> io::Result<usize>;
196 /// ```
197 ///
198 /// This function will attempt to write the entire contents of `buf`, but
199 /// the entire write may not succeed, or the write may also generate an
200 /// error. After the operation completes, the buffer's
201 /// internal cursor is advanced by the number of bytes written. A
202 /// subsequent call to `write_buf` using the **same** `buf` value will
203 /// resume from the point that the first call to `write_buf` completed.
204 /// A call to `write_buf` represents *at most one* attempt to write to any
205 /// wrapped object.
206 ///
207 /// # Return
208 ///
209 /// If the return value is `Ok(n)` then it must be guaranteed that `n <=
210 /// buf.len()`. A return value of `0` typically means that the
211 /// underlying object is no longer able to accept bytes and will likely
212 /// not be able to in the future as well, or that the buffer provided is
213 /// empty.
214 ///
215 /// # Errors
216 ///
217 /// Each call to `write` may generate an I/O error indicating that the
218 /// operation could not be completed. If an error is returned then no bytes
219 /// in the buffer were written to this writer.
220 ///
221 /// It is **not** considered an error if the entire buffer could not be
222 /// written to this writer.
223 ///
224 /// # Cancel safety
225 ///
226 /// This method is cancel safe. If it is used as a branch in
227 /// [`tokio::select!`](crate::select) and another branch completes
228 /// first, then it is guaranteed that no data was
229 /// written to this `AsyncWrite`.
230 ///
231 /// # Examples
232 ///
233 /// [`File`] implements [`AsyncWrite`] and [`Cursor`]`<&[u8]>` implements [`Buf`]:
234 ///
235 /// [`File`]: crate::fs::File
236 /// [`Buf`]: bytes::Buf
237 /// [`Cursor`]: std::io::Cursor
238 ///
239 /// ```no_run
240 /// # #[cfg(not(target_family = "wasm"))]
241 /// # {
242 /// use tokio::io::{self, AsyncWriteExt};
243 /// use tokio::fs::File;
244 ///
245 /// use bytes::Buf;
246 /// use std::io::Cursor;
247 ///
248 /// #[tokio::main]
249 /// async fn main() -> io::Result<()> {
250 /// let mut file = File::create("foo.txt").await?;
251 /// let mut buffer = Cursor::new(b"data to write");
252 ///
253 /// // Loop until the entire contents of the buffer are written to
254 /// // the file.
255 /// while buffer.has_remaining() {
256 /// // Writes some prefix of the byte string, not necessarily
257 /// // all of it.
258 /// file.write_buf(&mut buffer).await?;
259 /// }
260 /// file.flush().await?;
261 ///
262 /// Ok(())
263 /// }
264 /// # }
265 /// ```
266 fn write_buf<'a, B>(&'a mut self, src: &'a mut B) -> WriteBuf<'a, Self, B>
267 where
268 Self: Sized + Unpin,
269 B: Buf,
270 {
271 write_buf(self, src)
272 }
273
274 /// Attempts to write an entire buffer into this writer.
275 ///
276 /// Equivalent to:
277 ///
278 /// ```ignore
279 /// async fn write_all_buf(&mut self, buf: impl Buf) -> Result<(), io::Error> {
280 /// while buf.has_remaining() {
281 /// self.write_buf(&mut buf).await?;
282 /// }
283 /// Ok(())
284 /// }
285 /// ```
286 ///
287 /// This method will continuously call [`write`] until
288 /// [`buf.has_remaining()`](bytes::Buf::has_remaining) returns false. This method will not
289 /// return until the entire buffer has been successfully written or an error occurs.
290 /// Errors of kind [`ErrorKind::Interrupted`] are ignored and the write is retried. The first
291 /// other error generated will be returned.
292 ///
293 /// The buffer is advanced after each chunk is successfully written. After failure,
294 /// `src.chunk()` will return the chunk that failed to write.
295 ///
296 /// # Cancel safety
297 ///
298 /// If `write_all_buf` is used as a branch in
299 /// [`tokio::select!`](crate::select) and another branch
300 /// completes first, then the data in the provided buffer may have been
301 /// partially written. However, it is guaranteed that the provided
302 /// buffer has been [advanced] by the amount of bytes that have been
303 /// partially written.
304 ///
305 /// # Examples
306 ///
307 /// [`File`] implements [`AsyncWrite`] and [`Cursor`]`<&[u8]>` implements [`Buf`]:
308 ///
309 /// [`File`]: crate::fs::File
310 /// [`Buf`]: bytes::Buf
311 /// [`Cursor`]: std::io::Cursor
312 /// [advanced]: bytes::Buf::advance
313 ///
314 /// ```no_run
315 /// # #[cfg(not(target_family = "wasm"))]
316 /// # {
317 /// use tokio::io::{self, AsyncWriteExt};
318 /// use tokio::fs::File;
319 ///
320 /// use std::io::Cursor;
321 ///
322 /// #[tokio::main]
323 /// async fn main() -> io::Result<()> {
324 /// let mut file = File::create("foo.txt").await?;
325 /// let mut buffer = Cursor::new(b"data to write");
326 ///
327 /// file.write_all_buf(&mut buffer).await?;
328 /// file.flush().await?;
329 /// Ok(())
330 /// }
331 /// # }
332 /// ```
333 ///
334 /// [`write`]: AsyncWriteExt::write
335 /// [`ErrorKind::Interrupted`]: std::io::ErrorKind::Interrupted
336 fn write_all_buf<'a, B>(&'a mut self, src: &'a mut B) -> WriteAllBuf<'a, Self, B>
337 where
338 Self: Sized + Unpin,
339 B: Buf,
340 {
341 write_all_buf(self, src)
342 }
343
344 /// Attempts to write an entire buffer into this writer.
345 ///
346 /// Equivalent to:
347 ///
348 /// ```ignore
349 /// async fn write_all(&mut self, buf: &[u8]) -> io::Result<()>;
350 /// ```
351 ///
352 /// This method will continuously call [`write`] until there is no more data
353 /// to be written. This method will not return until the entire buffer
354 /// has been successfully written or such an error occurs. Errors of kind
355 /// [`ErrorKind::Interrupted`] are ignored and the write is retried. The first
356 /// other error generated from this method will be returned.
357 ///
358 /// # Cancel safety
359 ///
360 /// This method is not cancel safe. If it is used as a branch in
361 /// [`tokio::select!`](crate::select) and another branch completes
362 /// first, then the provided buffer may have been
363 /// partially written, but future calls to `write_all` will start over
364 /// from the beginning of the buffer.
365 ///
366 /// # Errors
367 ///
368 /// This function will ignore errors of kind [`ErrorKind::Interrupted`] and
369 /// will otherwise return the first error that [`write`] returns.
370 ///
371 /// # Examples
372 ///
373 /// ```no_run
374 /// # #[cfg(not(target_family = "wasm"))]
375 /// # {
376 /// use tokio::io::{self, AsyncWriteExt};
377 /// use tokio::fs::File;
378 ///
379 /// #[tokio::main]
380 /// async fn main() -> io::Result<()> {
381 /// let mut file = File::create("foo.txt").await?;
382 ///
383 /// file.write_all(b"some bytes").await?;
384 /// file.flush().await?;
385 /// Ok(())
386 /// }
387 /// # }
388 /// ```
389 ///
390 /// [`write`]: AsyncWriteExt::write
391 /// [`ErrorKind::Interrupted`]: std::io::ErrorKind::Interrupted
392 fn write_all<'a>(&'a mut self, src: &'a [u8]) -> WriteAll<'a, Self>
393 where
394 Self: Unpin,
395 {
396 write_all(self, src)
397 }
398
399 write_impl! {
400 /// Writes an unsigned 8-bit integer to the underlying writer.
401 ///
402 /// Equivalent to:
403 ///
404 /// ```ignore
405 /// async fn write_u8(&mut self, n: u8) -> io::Result<()>;
406 /// ```
407 ///
408 /// It is recommended to use a buffered writer to avoid excessive
409 /// syscalls.
410 ///
411 /// # Errors
412 ///
413 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
414 ///
415 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
416 ///
417 /// # Examples
418 ///
419 /// Write unsigned 8 bit integers to a `AsyncWrite`:
420 ///
421 /// ```rust
422 /// use tokio::io::{self, AsyncWriteExt};
423 ///
424 /// # #[tokio::main(flavor = "current_thread")]
425 /// # async fn main() -> io::Result<()> {
426 /// let mut writer = Vec::new();
427 ///
428 /// writer.write_u8(2).await?;
429 /// writer.write_u8(5).await?;
430 ///
431 /// assert_eq!(writer, b"\x02\x05");
432 /// Ok(())
433 /// # }
434 /// ```
435 fn write_u8(&mut self, n: u8) -> WriteU8;
436
437 /// Writes a signed 8-bit integer to the underlying writer.
438 ///
439 /// Equivalent to:
440 ///
441 /// ```ignore
442 /// async fn write_i8(&mut self, n: i8) -> io::Result<()>;
443 /// ```
444 ///
445 /// It is recommended to use a buffered writer to avoid excessive
446 /// syscalls.
447 ///
448 /// # Errors
449 ///
450 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
451 ///
452 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
453 ///
454 /// # Examples
455 ///
456 /// Write signed 8 bit integers to a `AsyncWrite`:
457 ///
458 /// ```rust
459 /// use tokio::io::{self, AsyncWriteExt};
460 ///
461 /// # #[tokio::main(flavor = "current_thread")]
462 /// # async fn main() -> io::Result<()> {
463 /// let mut writer = Vec::new();
464 ///
465 /// writer.write_i8(-2).await?;
466 /// writer.write_i8(126).await?;
467 ///
468 /// assert_eq!(writer, b"\xFE\x7E");
469 /// Ok(())
470 /// # }
471 /// ```
472 fn write_i8(&mut self, n: i8) -> WriteI8;
473
474 /// Writes an unsigned 16-bit integer in big-endian order to the
475 /// underlying writer.
476 ///
477 /// Equivalent to:
478 ///
479 /// ```ignore
480 /// async fn write_u16(&mut self, n: u16) -> io::Result<()>;
481 /// ```
482 ///
483 /// It is recommended to use a buffered writer to avoid excessive
484 /// syscalls.
485 ///
486 /// # Errors
487 ///
488 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
489 ///
490 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
491 ///
492 /// # Examples
493 ///
494 /// Write unsigned 16-bit integers to a `AsyncWrite`:
495 ///
496 /// ```rust
497 /// use tokio::io::{self, AsyncWriteExt};
498 ///
499 /// # #[tokio::main(flavor = "current_thread")]
500 /// # async fn main() -> io::Result<()> {
501 /// let mut writer = Vec::new();
502 ///
503 /// writer.write_u16(517).await?;
504 /// writer.write_u16(768).await?;
505 ///
506 /// assert_eq!(writer, b"\x02\x05\x03\x00");
507 /// Ok(())
508 /// # }
509 /// ```
510 fn write_u16(&mut self, n: u16) -> WriteU16;
511
512 /// Writes a signed 16-bit integer in big-endian order to the
513 /// underlying writer.
514 ///
515 /// Equivalent to:
516 ///
517 /// ```ignore
518 /// async fn write_i16(&mut self, n: i16) -> io::Result<()>;
519 /// ```
520 ///
521 /// It is recommended to use a buffered writer to avoid excessive
522 /// syscalls.
523 ///
524 /// # Errors
525 ///
526 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
527 ///
528 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
529 ///
530 /// # Examples
531 ///
532 /// Write signed 16-bit integers to a `AsyncWrite`:
533 ///
534 /// ```rust
535 /// use tokio::io::{self, AsyncWriteExt};
536 ///
537 /// # #[tokio::main(flavor = "current_thread")]
538 /// # async fn main() -> io::Result<()> {
539 /// let mut writer = Vec::new();
540 ///
541 /// writer.write_i16(193).await?;
542 /// writer.write_i16(-132).await?;
543 ///
544 /// assert_eq!(writer, b"\x00\xc1\xff\x7c");
545 /// Ok(())
546 /// # }
547 /// ```
548 fn write_i16(&mut self, n: i16) -> WriteI16;
549
550 /// Writes an unsigned 32-bit integer in big-endian order to the
551 /// underlying writer.
552 ///
553 /// Equivalent to:
554 ///
555 /// ```ignore
556 /// async fn write_u32(&mut self, n: u32) -> io::Result<()>;
557 /// ```
558 ///
559 /// It is recommended to use a buffered writer to avoid excessive
560 /// syscalls.
561 ///
562 /// # Errors
563 ///
564 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
565 ///
566 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
567 ///
568 /// # Examples
569 ///
570 /// Write unsigned 32-bit integers to a `AsyncWrite`:
571 ///
572 /// ```rust
573 /// use tokio::io::{self, AsyncWriteExt};
574 ///
575 /// # #[tokio::main(flavor = "current_thread")]
576 /// # async fn main() -> io::Result<()> {
577 /// let mut writer = Vec::new();
578 ///
579 /// writer.write_u32(267).await?;
580 /// writer.write_u32(1205419366).await?;
581 ///
582 /// assert_eq!(writer, b"\x00\x00\x01\x0b\x47\xd9\x3d\x66");
583 /// Ok(())
584 /// # }
585 /// ```
586 fn write_u32(&mut self, n: u32) -> WriteU32;
587
588 /// Writes a signed 32-bit integer in big-endian order to the
589 /// underlying writer.
590 ///
591 /// Equivalent to:
592 ///
593 /// ```ignore
594 /// async fn write_i32(&mut self, n: i32) -> io::Result<()>;
595 /// ```
596 ///
597 /// It is recommended to use a buffered writer to avoid excessive
598 /// syscalls.
599 ///
600 /// # Errors
601 ///
602 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
603 ///
604 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
605 ///
606 /// # Examples
607 ///
608 /// Write signed 32-bit integers to a `AsyncWrite`:
609 ///
610 /// ```rust
611 /// use tokio::io::{self, AsyncWriteExt};
612 ///
613 /// # #[tokio::main(flavor = "current_thread")]
614 /// # async fn main() -> io::Result<()> {
615 /// let mut writer = Vec::new();
616 ///
617 /// writer.write_i32(267).await?;
618 /// writer.write_i32(1205419366).await?;
619 ///
620 /// assert_eq!(writer, b"\x00\x00\x01\x0b\x47\xd9\x3d\x66");
621 /// Ok(())
622 /// # }
623 /// ```
624 fn write_i32(&mut self, n: i32) -> WriteI32;
625
626 /// Writes an unsigned 64-bit integer in big-endian order to the
627 /// underlying writer.
628 ///
629 /// Equivalent to:
630 ///
631 /// ```ignore
632 /// async fn write_u64(&mut self, n: u64) -> io::Result<()>;
633 /// ```
634 ///
635 /// It is recommended to use a buffered writer to avoid excessive
636 /// syscalls.
637 ///
638 /// # Errors
639 ///
640 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
641 ///
642 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
643 ///
644 /// # Examples
645 ///
646 /// Write unsigned 64-bit integers to a `AsyncWrite`:
647 ///
648 /// ```rust
649 /// use tokio::io::{self, AsyncWriteExt};
650 ///
651 /// # #[tokio::main(flavor = "current_thread")]
652 /// # async fn main() -> io::Result<()> {
653 /// let mut writer = Vec::new();
654 ///
655 /// writer.write_u64(918733457491587).await?;
656 /// writer.write_u64(143).await?;
657 ///
658 /// assert_eq!(writer, b"\x00\x03\x43\x95\x4d\x60\x86\x83\x00\x00\x00\x00\x00\x00\x00\x8f");
659 /// Ok(())
660 /// # }
661 /// ```
662 fn write_u64(&mut self, n: u64) -> WriteU64;
663
664 /// Writes an signed 64-bit integer in big-endian order to the
665 /// underlying writer.
666 ///
667 /// Equivalent to:
668 ///
669 /// ```ignore
670 /// async fn write_i64(&mut self, n: i64) -> io::Result<()>;
671 /// ```
672 ///
673 /// It is recommended to use a buffered writer to avoid excessive
674 /// syscalls.
675 ///
676 /// # Errors
677 ///
678 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
679 ///
680 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
681 ///
682 /// # Examples
683 ///
684 /// Write signed 64-bit integers to a `AsyncWrite`:
685 ///
686 /// ```rust
687 /// use tokio::io::{self, AsyncWriteExt};
688 ///
689 /// # #[tokio::main(flavor = "current_thread")]
690 /// # async fn main() -> io::Result<()> {
691 /// let mut writer = Vec::new();
692 ///
693 /// writer.write_i64(i64::MIN).await?;
694 /// writer.write_i64(i64::MAX).await?;
695 ///
696 /// assert_eq!(writer, b"\x80\x00\x00\x00\x00\x00\x00\x00\x7f\xff\xff\xff\xff\xff\xff\xff");
697 /// Ok(())
698 /// # }
699 /// ```
700 fn write_i64(&mut self, n: i64) -> WriteI64;
701
702 /// Writes an unsigned 128-bit integer in big-endian order to the
703 /// underlying writer.
704 ///
705 /// Equivalent to:
706 ///
707 /// ```ignore
708 /// async fn write_u128(&mut self, n: u128) -> io::Result<()>;
709 /// ```
710 ///
711 /// It is recommended to use a buffered writer to avoid excessive
712 /// syscalls.
713 ///
714 /// # Errors
715 ///
716 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
717 ///
718 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
719 ///
720 /// # Examples
721 ///
722 /// Write unsigned 128-bit integers to a `AsyncWrite`:
723 ///
724 /// ```rust
725 /// use tokio::io::{self, AsyncWriteExt};
726 ///
727 /// # #[tokio::main(flavor = "current_thread")]
728 /// # async fn main() -> io::Result<()> {
729 /// let mut writer = Vec::new();
730 ///
731 /// writer.write_u128(16947640962301618749969007319746179).await?;
732 ///
733 /// assert_eq!(writer, vec![
734 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83,
735 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
736 /// ]);
737 /// Ok(())
738 /// # }
739 /// ```
740 fn write_u128(&mut self, n: u128) -> WriteU128;
741
742 /// Writes an signed 128-bit integer in big-endian order to the
743 /// underlying writer.
744 ///
745 /// Equivalent to:
746 ///
747 /// ```ignore
748 /// async fn write_i128(&mut self, n: i128) -> io::Result<()>;
749 /// ```
750 ///
751 /// It is recommended to use a buffered writer to avoid excessive
752 /// syscalls.
753 ///
754 /// # Errors
755 ///
756 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
757 ///
758 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
759 ///
760 /// # Examples
761 ///
762 /// Write signed 128-bit integers to a `AsyncWrite`:
763 ///
764 /// ```rust
765 /// use tokio::io::{self, AsyncWriteExt};
766 ///
767 /// # #[tokio::main(flavor = "current_thread")]
768 /// # async fn main() -> io::Result<()> {
769 /// let mut writer = Vec::new();
770 ///
771 /// writer.write_i128(i128::MIN).await?;
772 ///
773 /// assert_eq!(writer, vec![
774 /// 0x80, 0, 0, 0, 0, 0, 0, 0,
775 /// 0, 0, 0, 0, 0, 0, 0, 0
776 /// ]);
777 /// Ok(())
778 /// # }
779 /// ```
780 fn write_i128(&mut self, n: i128) -> WriteI128;
781
782 /// Writes an 32-bit floating point type in big-endian order to the
783 /// underlying writer.
784 ///
785 /// Equivalent to:
786 ///
787 /// ```ignore
788 /// async fn write_f32(&mut self, n: f32) -> io::Result<()>;
789 /// ```
790 ///
791 /// It is recommended to use a buffered writer to avoid excessive
792 /// syscalls.
793 ///
794 /// # Errors
795 ///
796 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
797 ///
798 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
799 ///
800 /// # Examples
801 ///
802 /// Write 32-bit floating point type to a `AsyncWrite`:
803 ///
804 /// ```rust
805 /// use tokio::io::{self, AsyncWriteExt};
806 ///
807 /// # #[tokio::main(flavor = "current_thread")]
808 /// # async fn main() -> io::Result<()> {
809 /// let mut writer = Vec::new();
810 ///
811 /// writer.write_f32(f32::MIN).await?;
812 ///
813 /// assert_eq!(writer, vec![0xff, 0x7f, 0xff, 0xff]);
814 /// Ok(())
815 /// # }
816 /// ```
817 fn write_f32(&mut self, n: f32) -> WriteF32;
818
819 /// Writes an 64-bit floating point type in big-endian order to the
820 /// underlying writer.
821 ///
822 /// Equivalent to:
823 ///
824 /// ```ignore
825 /// async fn write_f64(&mut self, n: f64) -> io::Result<()>;
826 /// ```
827 ///
828 /// It is recommended to use a buffered writer to avoid excessive
829 /// syscalls.
830 ///
831 /// # Errors
832 ///
833 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
834 ///
835 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
836 ///
837 /// # Examples
838 ///
839 /// Write 64-bit floating point type to a `AsyncWrite`:
840 ///
841 /// ```rust
842 /// use tokio::io::{self, AsyncWriteExt};
843 ///
844 /// # #[tokio::main(flavor = "current_thread")]
845 /// # async fn main() -> io::Result<()> {
846 /// let mut writer = Vec::new();
847 ///
848 /// writer.write_f64(f64::MIN).await?;
849 ///
850 /// assert_eq!(writer, vec![
851 /// 0xff, 0xef, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
852 /// ]);
853 /// Ok(())
854 /// # }
855 /// ```
856 fn write_f64(&mut self, n: f64) -> WriteF64;
857
858 /// Writes an unsigned 16-bit integer in little-endian order to the
859 /// underlying writer.
860 ///
861 /// Equivalent to:
862 ///
863 /// ```ignore
864 /// async fn write_u16_le(&mut self, n: u16) -> io::Result<()>;
865 /// ```
866 ///
867 /// It is recommended to use a buffered writer to avoid excessive
868 /// syscalls.
869 ///
870 /// # Errors
871 ///
872 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
873 ///
874 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
875 ///
876 /// # Examples
877 ///
878 /// Write unsigned 16-bit integers to a `AsyncWrite`:
879 ///
880 /// ```rust
881 /// use tokio::io::{self, AsyncWriteExt};
882 ///
883 /// # #[tokio::main(flavor = "current_thread")]
884 /// # async fn main() -> io::Result<()> {
885 /// let mut writer = Vec::new();
886 ///
887 /// writer.write_u16_le(517).await?;
888 /// writer.write_u16_le(768).await?;
889 ///
890 /// assert_eq!(writer, b"\x05\x02\x00\x03");
891 /// Ok(())
892 /// # }
893 /// ```
894 fn write_u16_le(&mut self, n: u16) -> WriteU16Le;
895
896 /// Writes a signed 16-bit integer in little-endian order to the
897 /// underlying writer.
898 ///
899 /// Equivalent to:
900 ///
901 /// ```ignore
902 /// async fn write_i16_le(&mut self, n: i16) -> io::Result<()>;
903 /// ```
904 ///
905 /// It is recommended to use a buffered writer to avoid excessive
906 /// syscalls.
907 ///
908 /// # Errors
909 ///
910 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
911 ///
912 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
913 ///
914 /// # Examples
915 ///
916 /// Write signed 16-bit integers to a `AsyncWrite`:
917 ///
918 /// ```rust
919 /// use tokio::io::{self, AsyncWriteExt};
920 ///
921 /// # #[tokio::main(flavor = "current_thread")]
922 /// # async fn main() -> io::Result<()> {
923 /// let mut writer = Vec::new();
924 ///
925 /// writer.write_i16_le(193).await?;
926 /// writer.write_i16_le(-132).await?;
927 ///
928 /// assert_eq!(writer, b"\xc1\x00\x7c\xff");
929 /// Ok(())
930 /// # }
931 /// ```
932 fn write_i16_le(&mut self, n: i16) -> WriteI16Le;
933
934 /// Writes an unsigned 32-bit integer in little-endian order to the
935 /// underlying writer.
936 ///
937 /// Equivalent to:
938 ///
939 /// ```ignore
940 /// async fn write_u32_le(&mut self, n: u32) -> io::Result<()>;
941 /// ```
942 ///
943 /// It is recommended to use a buffered writer to avoid excessive
944 /// syscalls.
945 ///
946 /// # Errors
947 ///
948 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
949 ///
950 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
951 ///
952 /// # Examples
953 ///
954 /// Write unsigned 32-bit integers to a `AsyncWrite`:
955 ///
956 /// ```rust
957 /// use tokio::io::{self, AsyncWriteExt};
958 ///
959 /// # #[tokio::main(flavor = "current_thread")]
960 /// # async fn main() -> io::Result<()> {
961 /// let mut writer = Vec::new();
962 ///
963 /// writer.write_u32_le(267).await?;
964 /// writer.write_u32_le(1205419366).await?;
965 ///
966 /// assert_eq!(writer, b"\x0b\x01\x00\x00\x66\x3d\xd9\x47");
967 /// Ok(())
968 /// # }
969 /// ```
970 fn write_u32_le(&mut self, n: u32) -> WriteU32Le;
971
972 /// Writes a signed 32-bit integer in little-endian order to the
973 /// underlying writer.
974 ///
975 /// Equivalent to:
976 ///
977 /// ```ignore
978 /// async fn write_i32_le(&mut self, n: i32) -> io::Result<()>;
979 /// ```
980 ///
981 /// It is recommended to use a buffered writer to avoid excessive
982 /// syscalls.
983 ///
984 /// # Errors
985 ///
986 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
987 ///
988 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
989 ///
990 /// # Examples
991 ///
992 /// Write signed 32-bit integers to a `AsyncWrite`:
993 ///
994 /// ```rust
995 /// use tokio::io::{self, AsyncWriteExt};
996 ///
997 /// # #[tokio::main(flavor = "current_thread")]
998 /// # async fn main() -> io::Result<()> {
999 /// let mut writer = Vec::new();
1000 ///
1001 /// writer.write_i32_le(267).await?;
1002 /// writer.write_i32_le(1205419366).await?;
1003 ///
1004 /// assert_eq!(writer, b"\x0b\x01\x00\x00\x66\x3d\xd9\x47");
1005 /// Ok(())
1006 /// # }
1007 /// ```
1008 fn write_i32_le(&mut self, n: i32) -> WriteI32Le;
1009
1010 /// Writes an unsigned 64-bit integer in little-endian order to the
1011 /// underlying writer.
1012 ///
1013 /// Equivalent to:
1014 ///
1015 /// ```ignore
1016 /// async fn write_u64_le(&mut self, n: u64) -> io::Result<()>;
1017 /// ```
1018 ///
1019 /// It is recommended to use a buffered writer to avoid excessive
1020 /// syscalls.
1021 ///
1022 /// # Errors
1023 ///
1024 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
1025 ///
1026 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
1027 ///
1028 /// # Examples
1029 ///
1030 /// Write unsigned 64-bit integers to a `AsyncWrite`:
1031 ///
1032 /// ```rust
1033 /// use tokio::io::{self, AsyncWriteExt};
1034 ///
1035 /// # #[tokio::main(flavor = "current_thread")]
1036 /// # async fn main() -> io::Result<()> {
1037 /// let mut writer = Vec::new();
1038 ///
1039 /// writer.write_u64_le(918733457491587).await?;
1040 /// writer.write_u64_le(143).await?;
1041 ///
1042 /// assert_eq!(writer, b"\x83\x86\x60\x4d\x95\x43\x03\x00\x8f\x00\x00\x00\x00\x00\x00\x00");
1043 /// Ok(())
1044 /// # }
1045 /// ```
1046 fn write_u64_le(&mut self, n: u64) -> WriteU64Le;
1047
1048 /// Writes an signed 64-bit integer in little-endian order to the
1049 /// underlying writer.
1050 ///
1051 /// Equivalent to:
1052 ///
1053 /// ```ignore
1054 /// async fn write_i64_le(&mut self, n: i64) -> io::Result<()>;
1055 /// ```
1056 ///
1057 /// It is recommended to use a buffered writer to avoid excessive
1058 /// syscalls.
1059 ///
1060 /// # Errors
1061 ///
1062 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
1063 ///
1064 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
1065 ///
1066 /// # Examples
1067 ///
1068 /// Write signed 64-bit integers to a `AsyncWrite`:
1069 ///
1070 /// ```rust
1071 /// use tokio::io::{self, AsyncWriteExt};
1072 ///
1073 /// # #[tokio::main(flavor = "current_thread")]
1074 /// # async fn main() -> io::Result<()> {
1075 /// let mut writer = Vec::new();
1076 ///
1077 /// writer.write_i64_le(i64::MIN).await?;
1078 /// writer.write_i64_le(i64::MAX).await?;
1079 ///
1080 /// assert_eq!(writer, b"\x00\x00\x00\x00\x00\x00\x00\x80\xff\xff\xff\xff\xff\xff\xff\x7f");
1081 /// Ok(())
1082 /// # }
1083 /// ```
1084 fn write_i64_le(&mut self, n: i64) -> WriteI64Le;
1085
1086 /// Writes an unsigned 128-bit integer in little-endian order to the
1087 /// underlying writer.
1088 ///
1089 /// Equivalent to:
1090 ///
1091 /// ```ignore
1092 /// async fn write_u128_le(&mut self, n: u128) -> io::Result<()>;
1093 /// ```
1094 ///
1095 /// It is recommended to use a buffered writer to avoid excessive
1096 /// syscalls.
1097 ///
1098 /// # Errors
1099 ///
1100 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
1101 ///
1102 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
1103 ///
1104 /// # Examples
1105 ///
1106 /// Write unsigned 128-bit integers to a `AsyncWrite`:
1107 ///
1108 /// ```rust
1109 /// use tokio::io::{self, AsyncWriteExt};
1110 ///
1111 /// # #[tokio::main(flavor = "current_thread")]
1112 /// # async fn main() -> io::Result<()> {
1113 /// let mut writer = Vec::new();
1114 ///
1115 /// writer.write_u128_le(16947640962301618749969007319746179).await?;
1116 ///
1117 /// assert_eq!(writer, vec![
1118 /// 0x83, 0x86, 0x60, 0x4d, 0x95, 0x43, 0x03, 0x00,
1119 /// 0x83, 0x86, 0x60, 0x4d, 0x95, 0x43, 0x03, 0x00,
1120 /// ]);
1121 /// Ok(())
1122 /// # }
1123 /// ```
1124 fn write_u128_le(&mut self, n: u128) -> WriteU128Le;
1125
1126 /// Writes an signed 128-bit integer in little-endian order to the
1127 /// underlying writer.
1128 ///
1129 /// Equivalent to:
1130 ///
1131 /// ```ignore
1132 /// async fn write_i128_le(&mut self, n: i128) -> io::Result<()>;
1133 /// ```
1134 ///
1135 /// It is recommended to use a buffered writer to avoid excessive
1136 /// syscalls.
1137 ///
1138 /// # Errors
1139 ///
1140 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
1141 ///
1142 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
1143 ///
1144 /// # Examples
1145 ///
1146 /// Write signed 128-bit integers to a `AsyncWrite`:
1147 ///
1148 /// ```rust
1149 /// use tokio::io::{self, AsyncWriteExt};
1150 ///
1151 /// # #[tokio::main(flavor = "current_thread")]
1152 /// # async fn main() -> io::Result<()> {
1153 /// let mut writer = Vec::new();
1154 ///
1155 /// writer.write_i128_le(i128::MIN).await?;
1156 ///
1157 /// assert_eq!(writer, vec![
1158 /// 0, 0, 0, 0, 0, 0, 0,
1159 /// 0, 0, 0, 0, 0, 0, 0, 0, 0x80
1160 /// ]);
1161 /// Ok(())
1162 /// # }
1163 /// ```
1164 fn write_i128_le(&mut self, n: i128) -> WriteI128Le;
1165
1166 /// Writes an 32-bit floating point type in little-endian order to the
1167 /// underlying writer.
1168 ///
1169 /// Equivalent to:
1170 ///
1171 /// ```ignore
1172 /// async fn write_f32_le(&mut self, n: f32) -> io::Result<()>;
1173 /// ```
1174 ///
1175 /// It is recommended to use a buffered writer to avoid excessive
1176 /// syscalls.
1177 ///
1178 /// # Errors
1179 ///
1180 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
1181 ///
1182 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
1183 ///
1184 /// # Examples
1185 ///
1186 /// Write 32-bit floating point type to a `AsyncWrite`:
1187 ///
1188 /// ```rust
1189 /// use tokio::io::{self, AsyncWriteExt};
1190 ///
1191 /// # #[tokio::main(flavor = "current_thread")]
1192 /// # async fn main() -> io::Result<()> {
1193 /// let mut writer = Vec::new();
1194 ///
1195 /// writer.write_f32_le(f32::MIN).await?;
1196 ///
1197 /// assert_eq!(writer, vec![0xff, 0xff, 0x7f, 0xff]);
1198 /// Ok(())
1199 /// # }
1200 /// ```
1201 fn write_f32_le(&mut self, n: f32) -> WriteF32Le;
1202
1203 /// Writes an 64-bit floating point type in little-endian order to the
1204 /// underlying writer.
1205 ///
1206 /// Equivalent to:
1207 ///
1208 /// ```ignore
1209 /// async fn write_f64_le(&mut self, n: f64) -> io::Result<()>;
1210 /// ```
1211 ///
1212 /// It is recommended to use a buffered writer to avoid excessive
1213 /// syscalls.
1214 ///
1215 /// # Errors
1216 ///
1217 /// This method returns the same errors as [`AsyncWriteExt::write_all`].
1218 ///
1219 /// [`AsyncWriteExt::write_all`]: AsyncWriteExt::write_all
1220 ///
1221 /// # Examples
1222 ///
1223 /// Write 64-bit floating point type to a `AsyncWrite`:
1224 ///
1225 /// ```rust
1226 /// use tokio::io::{self, AsyncWriteExt};
1227 ///
1228 /// # #[tokio::main(flavor = "current_thread")]
1229 /// # async fn main() -> io::Result<()> {
1230 /// let mut writer = Vec::new();
1231 ///
1232 /// writer.write_f64_le(f64::MIN).await?;
1233 ///
1234 /// assert_eq!(writer, vec![
1235 /// 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xef, 0xff
1236 /// ]);
1237 /// Ok(())
1238 /// # }
1239 /// ```
1240 fn write_f64_le(&mut self, n: f64) -> WriteF64Le;
1241 }
1242
1243 /// Flushes this output stream, ensuring that all intermediately buffered
1244 /// contents reach their destination.
1245 ///
1246 /// Equivalent to:
1247 ///
1248 /// ```ignore
1249 /// async fn flush(&mut self) -> io::Result<()>;
1250 /// ```
1251 ///
1252 /// # Errors
1253 ///
1254 /// It is considered an error if not all bytes could be written due to
1255 /// I/O errors or EOF being reached.
1256 ///
1257 /// # Cancel safety
1258 ///
1259 /// This method is cancel safe.
1260 ///
1261 /// If `flush` is used as a branch in [`tokio::select!`](crate::select)
1262 /// and another branch completes first, then the buffered data in this
1263 /// `AsyncWrite` may have been partially flushed.
1264 /// However, it is guaranteed that the buffer is advanced by the amount of
1265 /// bytes that have been partially flushed.
1266 ///
1267 /// # Examples
1268 ///
1269 /// ```no_run
1270 /// # #[cfg(not(target_family = "wasm"))]
1271 /// # {
1272 /// use tokio::io::{self, BufWriter, AsyncWriteExt};
1273 /// use tokio::fs::File;
1274 ///
1275 /// #[tokio::main]
1276 /// async fn main() -> io::Result<()> {
1277 /// let f = File::create("foo.txt").await?;
1278 /// let mut buffer = BufWriter::new(f);
1279 ///
1280 /// buffer.write_all(b"some bytes").await?;
1281 /// buffer.flush().await?;
1282 /// Ok(())
1283 /// }
1284 /// # }
1285 /// ```
1286 fn flush(&mut self) -> Flush<'_, Self>
1287 where
1288 Self: Unpin,
1289 {
1290 flush(self)
1291 }
1292
1293 /// Shuts down the output stream, ensuring that the value can be dropped
1294 /// cleanly.
1295 ///
1296 /// Equivalent to:
1297 ///
1298 /// ```ignore
1299 /// async fn shutdown(&mut self) -> io::Result<()>;
1300 /// ```
1301 ///
1302 /// Similar to [`flush`], all intermediately buffered content is written to
1303 /// the underlying stream. Once the operation completes, the caller should
1304 /// no longer attempt to write to the stream. For example, the
1305 /// `TcpStream` implementation will issue a `shutdown(Write)` sys call.
1306 ///
1307 /// [`flush`]: fn@crate::io::AsyncWriteExt::flush
1308 ///
1309 /// # Examples
1310 ///
1311 /// ```no_run
1312 /// # #[cfg(not(target_family = "wasm"))]
1313 /// # {
1314 /// use tokio::io::{self, BufWriter, AsyncWriteExt};
1315 /// use tokio::fs::File;
1316 ///
1317 /// #[tokio::main]
1318 /// async fn main() -> io::Result<()> {
1319 /// let f = File::create("foo.txt").await?;
1320 /// let mut buffer = BufWriter::new(f);
1321 ///
1322 /// buffer.write_all(b"some bytes").await?;
1323 /// buffer.shutdown().await?;
1324 /// Ok(())
1325 /// }
1326 /// # }
1327 /// ```
1328 fn shutdown(&mut self) -> Shutdown<'_, Self>
1329 where
1330 Self: Unpin,
1331 {
1332 shutdown(self)
1333 }
1334 }
1335}
1336
1337impl<W: AsyncWrite + ?Sized> AsyncWriteExt for W {}