vendor/tokio/src/io/util/async_write_ext.rs

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