Trait protobuf_native::io::ZeroCopyOutputStream

source ·

pub trait ZeroCopyOutputStream: Sealed {
    // Provided methods
    unsafe fn next(
        self: Pin<&mut Self>
    ) -> Result<&mut [MaybeUninit<u8>], OperationFailedError> { ... }
    fn back_up(self: Pin<&mut Self>, count: usize) { ... }
    fn byte_count(&self) -> i64 { ... }
}

Expand description

Abstract interface similar to an output stream but designed to minimize copying.

§Examples

Copy the contents of infile to outfile, using plain Read for infile but a ZeroCopyOutputStream for outfile:

use std::fs::File;
use std::io::{self, Read, Write};
use protobuf_native::io::{WriterStream, ZeroCopyOutputStream};

let mut infile = File::open("infile")?;
let mut outfile = File::create("outfile")?;
let mut output = WriterStream::new(&mut outfile);

while let Ok(buf) = output.next() {
    // Reading into uninitialized memory requires the unstable `ReadBuf` API.
    // See: https://rust-lang.github.io/rfcs/2930-read-buf.html
    let buf = ReadBuf::uninit(buf);
    infile.read_buf(buf)?;
    output.back_up(buf.remaining());
    if buf.filled().is_empty() {
        break;
    }
}

Provided Methods§

source

unsafe fn next( self: Pin<&mut Self> ) -> Result<&mut [MaybeUninit<u8>], OperationFailedError>

Obtains a buffer into which data can be written.

Any data written into this buffer will eventually (maybe instantly, maybe later on) be written to the output.

§Safety

If this function returns Ok, you must initialize the returned byte slice before you either call next again or drop the slice. You can choose to initialize only a portion of the byte slice by calling back_up.

This is a very unusual invariant to maintain in Rust.

source

fn back_up(self: Pin<&mut Self>, count: usize)

Backs up a number of bytes, so that the end of the last buffer returned by next is not actually written.

This is needed when you finish writing all the data you want to write, but the last buffer was bigger than you needed. You don’t want to write a bunch of garbage after the end of your data, so you use back_up to back up.

source