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