Struct body_image::BodyImage

pub struct BodyImage { /* fields omitted */ }

A logical buffer of bytes, which may or may not be RAM resident.

Besides a few immediate/convenience constructors found here, use BodySink for the incremental or stream-oriented collection of bytes to produce a BodyImage.

A BodyImage is always in one of the following states, as a buffering strategy:

Ram : A vector of zero, one, or many discontinuous (AKA scattered) byte buffers in Random Access Memory. This state is also used to represent an empty body (without allocation).

FsRead : Body in a (temporary) file, ready for position based, sequential read.

MemMap : Body in a memory mapped file, ready for random access read (optional feature memmap)

All states support concurrent reads. BodyImage is Sync and Send, and supports low-cost shallow Clone via internal (atomic) reference counting.

Methods

impl BodyImage

pub fn empty() -> BodyImage

Create new empty instance with no allocation. The state is Ram with a zero-capacity vector.

pub fn from_file(file: File, length: u64) -> BodyImage

Create a new FsRead instance based on an existing File. The fixed length is used to report BodyImage::len and may be obtained using File::metadata. If the provided length is zero, this returns as per BodyImage::empty() instead. Attempts to read from or mem_map the returned BodyImage can fail if the file is not open for read or is zero length.

pub fn from_slice<T>(bytes: T) -> BodyImage where
    T: Into<Bytes>, 

Create new instance from a single byte slice.

pub fn from_read_slice(rslice: ReadSlice) -> BodyImage

Create a new instance based on a ReadSlice. The BodyImage::len will be as per ReadSlice::len, and if zero, this returns as per BodyImage::empty(). Attempts to read from or mem_map the returned BodyImage can fail if the file is not open for read or is zero length.

pub fn is_ram(&self) -> bool

Return true if in state Ram.

pub fn len(&self) -> u64

Return the current length of body in bytes.

pub fn is_empty(&self) -> bool

Return true if body is empty.

pub fn prepare(&mut self) -> Result<&mut Self, BodyError>

Deprecated

Formerly, this rewound 'FsRead', but now is an unnecessary no-op. The reader method always returns a Read from the start of the BodyImage for all states.

pub fn mem_map(&mut self) -> Result<&mut Self, BodyError>

If FsRead, convert to MemMap by memory mapping the file. No-op for other states.

pub fn gather(&mut self) -> &mut Self

If Ram with 2 or more buffers, gather by copying into a single contiguous buffer with the same total length. No-op for other states. Buffers are eagerly dropped as they are copied. Possibly in combination with mem_map, this can be used to ensure Cursor (and &[u8] slice) access via reader, at the cost of the copy.

pub fn try_clone(&self) -> Result<BodyImage, BodyError>

Deprecated

Clone self by shallow copy, returning a new BodyImage. This is currently infallible and deprecated in favor of clone.

pub fn reader(&self) -> BodyReader

Return a new BodyReader enum over self. The enum provides a consistent Read reference, or can be destructured for access to the specific concrete types.

pub fn read_from(
    r: &mut Read,
    len_estimate: u64,
    tune: &Tunables
) -> Result<BodyImage, BodyError>

Given a Read object, a length estimate in bytes, and Tunables read and prepare a new BodyImage. Tunables, the estimate and actual length read will determine which buffering strategy is used. The length estimate provides a hint to use the file system from the start, which is more optimal than writing out accumulated Ram buffers later. If the length can't be estimated, use zero (0).

pub fn write_to(&self, out: &mut Write) -> Result<u64, BodyError>

Write self to out and return length. If FsRead this is performed using std::io::copy with ReadPos as input.

Trait Implementations

impl Clone for BodyImage

fn clone(&self) -> BodyImage

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BodyImage

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for BodyImage

fn default() -> BodyImage

Returns the "default value" for a type.