futures_util/io/
mod.rs

1//! IO
2//!
3//! This module contains a number of functions for working with
4//! `AsyncRead` and `AsyncWrite` types, including the
5//! `AsyncReadExt` and `AsyncWriteExt` traits which add methods
6//! to the `AsyncRead` and `AsyncWrite` types.
7
8
9use std::vec::Vec;
10
11pub use futures_io::{AsyncRead, AsyncWrite, IoVec};
12
13pub use self::allow_std::AllowStdIo;
14pub use self::copy_into::CopyInto;
15pub use self::flush::Flush;
16pub use self::read::Read;
17pub use self::read_exact::ReadExact;
18pub use self::read_to_end::ReadToEnd;
19pub use self::close::Close;
20pub use self::split::{ReadHalf, WriteHalf};
21pub use self::window::Window;
22pub use self::write_all::WriteAll;
23
24// Temporarily removed until AsyncBufRead is implemented
25// pub use io::lines::{lines, Lines};
26// pub use io::read_until::{read_until, ReadUntil};
27// mod lines;
28// mod read_until;
29
30mod allow_std;
31mod copy_into;
32mod flush;
33mod read;
34mod read_exact;
35mod read_to_end;
36mod close;
37mod split;
38mod window;
39mod write_all;
40
41/// An extension trait which adds utility methods to `AsyncRead` types.
42pub trait AsyncReadExt: AsyncRead {
43    /// Creates a future which copies all the bytes from one object to another.
44    ///
45    /// The returned future will copy all the bytes read from this `AsyncRead` into the
46    /// `writer` specified. This future will only complete once the `reader` has hit
47    /// EOF and all bytes have been written to and flushed from the `writer`
48    /// provided.
49    ///
50    /// On success the number of bytes is returned and this `AsyncRead` and `writer` are
51    /// consumed. On error the error is returned and the I/O objects are consumed as
52    /// well.
53    fn copy_into<W>(self, writer: W) -> CopyInto<Self, W>
54        where W: AsyncWrite,
55              Self: Sized,
56    {
57        copy_into::copy_into(self, writer)
58    }
59
60    /// Tries to read some bytes directly into the given `buf` in asynchronous
61    /// manner, returning a future type.
62    ///
63    /// The returned future will resolve to both the I/O stream and the buffer
64    /// as well as the number of bytes read once the read operation is completed.
65    fn read<T>(self, buf: T) -> Read<Self, T>
66        where T: AsMut<[u8]>,
67              Self: Sized,
68    {
69        read::read(self, buf)
70    }
71
72
73    /// Creates a future which will read exactly enough bytes to fill `buf`,
74    /// returning an error if EOF is hit sooner.
75    ///
76    /// The returned future will resolve to both the I/O stream as well as the
77    /// buffer once the read operation is completed.
78    ///
79    /// In the case of an error the buffer and the object will be discarded, with
80    /// the error yielded. In the case of success the object will be destroyed and
81    /// the buffer will be returned, with all data read from the stream appended to
82    /// the buffer.
83    fn read_exact<T>(self, buf: T) -> ReadExact<Self, T>
84        where T: AsMut<[u8]>,
85              Self: Sized,
86    {
87        read_exact::read_exact(self, buf)
88    }
89
90    /// Creates a future which will read all the bytes from this `AsyncRead`.
91    ///
92    /// In the case of an error the buffer and the object will be discarded, with
93    /// the error yielded. In the case of success the object will be destroyed and
94    /// the buffer will be returned, with all data read from the stream appended to
95    /// the buffer.
96    fn read_to_end(self, buf: Vec<u8>) -> ReadToEnd<Self>
97        where Self: Sized,
98    {
99        read_to_end::read_to_end(self, buf)
100    }
101
102    /// Helper method for splitting this read/write object into two halves.
103    ///
104    /// The two halves returned implement the `Read` and `Write` traits,
105    /// respectively.
106    fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>)
107        where Self: AsyncWrite + Sized,
108    {
109        split::split(self)
110    }
111}
112
113impl<T: AsyncRead + ?Sized> AsyncReadExt for T {}
114
115/// An extension trait which adds utility methods to `AsyncWrite` types.
116pub trait AsyncWriteExt: AsyncWrite {
117    /// Creates a future which will entirely flush this `AsyncWrite` and then return `self`.
118    ///
119    /// This function will consume `self` if an error occurs.
120    fn flush(self) -> Flush<Self>
121        where Self: Sized,
122    {
123        flush::flush(self)
124    }
125
126    /// Creates a future which will entirely close this `AsyncWrite` and then return `self`.
127    ///
128    /// This function will consume the object provided if an error occurs.
129    fn close(self) -> Close<Self>
130        where Self: Sized,
131    {
132        close::close(self)
133    }
134
135    /// Write a `Buf` into this value, returning how many bytes were written.
136    /// Creates a future that will write the entire contents of the buffer `buf` into
137    /// this `AsyncWrite`.
138    ///
139    /// The returned future will not complete until all the data has been written.
140    /// The future will resolve to a tuple of `self` and `buf`
141    /// (so the buffer can be reused as needed).
142    ///
143    /// Any error which happens during writing will cause both the stream and the
144    /// buffer to be destroyed.
145    ///
146    /// The `buf` parameter here only requires the `AsRef<[u8]>` trait, which should
147    /// be broadly applicable to accepting data which can be converted to a slice.
148    /// The `Window` struct is also available in this crate to provide a different
149    /// window into a slice if necessary.
150    fn write_all<T>(self, buf: T) -> WriteAll<Self, T>
151        where T: AsRef<[u8]>,
152              Self: Sized,
153    {
154        write_all::write_all(self, buf)
155    }
156}
157
158impl<T: AsyncWrite + ?Sized> AsyncWriteExt for T {}
futures_util/io/mod.rs

futures_util/io/
mod.rs
