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