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