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 {}