Struct futures_bufio::BufWriter

pub struct BufWriter<W> { /* fields omitted */ }

Adds buffering to any writer, similar to the standard BufWriter, but performs non-buffer writes in a thread pool.

All writes are returned as futures.

This writer is most useful for wrapping writers that never block or cannot return EWOULDBLOCK, but are slow. Notably, this is useful for wrapping io::File.

All writes must take and own the BufWriter and the buffer being written for the duration of the write.

Note that unlike the standard BufWriter, this BufWriter is not automatically flushed on drop. Users must call flush_buf and potentially flush_inner to flush contents before dropping.

Examples

let f = io::Cursor::new(vec![]);
let pool = CpuPool::new(1);
let writer = BufWriter::with_pool_and_capacity(pool, 4096, f);

let buf = b"many small writes".to_vec();
let (writer, buf) = writer.write_all(buf).wait().unwrap_or_else(|(_, _, e)| {
    // in real usage, we have the option to deconstruct our BufWriter or reuse buf here
    panic!("unable to read full: {}", e);
});
assert_eq!(&*buf, b"many small writes"); // we can reuse buf

Methods

impl<W: Write + Send + 'static> BufWriter<W>

fn with_pool_and_capacity(pool: CpuPool, cap: usize, inner: W) -> BufWriter<W>

Creates and returns a new BufWriter with an internal buffer of size cap.

Examples

let f = io::Cursor::new(vec![]);
let pool = CpuPool::new(1);
let writer = BufWriter::with_pool_and_capacity(pool, 4<<10, f);

fn with_pool_and_buf(pool: CpuPool, buf: Box<[u8]>, inner: W) -> BufWriter<W>

Creates and returns a new BufWriter with buf as the internal buffer.

Examples

let f = io::Cursor::new(vec![]);
let pool = CpuPool::new(1);
let buf = vec![0; 4096].into_boxed_slice();
let writer = BufWriter::with_pool_and_buf(pool, buf, f);

fn get_ref(&self) -> &W

Gets a reference to the underlying writer.

It is likely invalid to read directly from the underlying writer and then use the BufWriter again.

fn get_mut(&mut self) -> &W

Gets a mutable reference to the underlying writer.

It is likely invalid to read directly from the underlying writer and then use the BufWriter again.

unsafe fn components(self) -> (W, Box<[u8]>, CpuPool)

Returns the internal components of a BufWriter, allowing reuse. This is unsafe because it does not zero the memory of the buffer, meaning the buffer could countain uninitialized memory.

Examples

let f = io::Cursor::new(b"foo text".to_vec());
let pool = CpuPool::new(1);
let writer = BufWriter::with_pool_and_capacity(pool, 4<<10, f);

let (f, buf, pool) = unsafe { writer.components() };
assert_eq!(f.get_ref(), b"foo text");
assert_eq!(buf.len(), 4<<10);

unsafe fn set_pos(&mut self, pos: usize)

Sets the BufWriters internal buffer position to pos.

This is highly unsafe for the following reasons:

• the internal buffer may have uninitialized memory, and advancing the write position will mean writing uninitialized memory

• the pos is not validated, meaning it is possible to move the pos past the end of the internal buffer. This will cause a panic on the next use of write_all or flush_buf.

• it is possible to move before the internal beginning write position, meaning a write or flush may panic due to the beginning of a write being after the end of a write.

This function should only be used for setting up a new BufWriter with a buffer that contains known, existing contents.

Examples

let f = io::Cursor::new(vec![]);
let pool = CpuPool::new(1);
let mut buf = vec![0; 4096].into_boxed_slice();

// copy some known text to uor buffer - note it must be at the beginning
let p = b"pre-existing text";
&mut buf[0..p.len()].copy_from_slice(p);

let mut writer = BufWriter::with_pool_and_buf(pool, buf, f);

// unsafely move the writer's position to the end of our known text, and flush the buffer
unsafe { writer.set_pos(p.len()); }
let writer = writer.flush_buf().wait().unwrap_or_else(|(_, e)| {
    panic!("unable to flush_buf: {}", e);
});

// the underlying writer should be the contents of p
let (f, _, _) = unsafe { writer.components() };
assert_eq!(f.get_ref().as_slice(), p);

fn write_all<B>(
    self,
    buf: B
) -> impl Future<Item = (Self, B), Error = (Self, B, Error)> where
    B: Deref<Target = [u8]> + Send + 'static, 

Writes all of buf to the BufWriter, returning the buffer for potential reuse and any error that occurs.

If used on io::File's, BufWriter could be valuable for performing page-aligned writes.

Examples

let f = io::Cursor::new(vec![]);
let pool = CpuPool::new(1);
let writer = BufWriter::with_pool_and_capacity(pool, 4096, f);

let buf = b"many small writes".to_vec();
let (writer, buf) = writer.write_all(buf).wait().unwrap_or_else(|(_, _, e)| {
    // in real usage, we have the option to deconstruct our BufWriter or reuse buf here
    panic!("unable to read full: {}", e);
});
assert_eq!(&*buf, b"many small writes"); // we can reuse buf

fn flush_buf(self) -> impl Future<Item = Self, Error = (Self, Error)>

Flushes currently buffered data to the inner writer.

Calling flush_buf does not empty the current buffer; instead, a future flush triggered from write_all will be shorter. This is done to keep the full-buffered writes aligned.

Examples

let future = writer.flush_buf();

fn flush_inner(self) -> impl Future<Item = Self, Error = (Self, Error)>

Calls flush on the inner writer.

Examples

let future = writer.flush_inner();