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