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, single access, sequential read.

MemMap : Body in a memory mapped file, ready for efficient and potentially concurrent and random access reading.

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_slice<T>(bytes: T) -> BodyImage where
    T: Into<Bytes>, 

Create new instance from a single byte slice.

pub fn is_ram(&self) -> bool

Return true if in state Ram.

pub fn is_empty(&self) -> bool

Return true if body is empty.

pub fn len(&self) -> u64

Return the current length of body in bytes.

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

Prepare for re-reading. If FsRead, seeks to beginning of file. No-op for other 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. See also try_clone as a means of preserving the original FsRead.

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>

Attempt to clone self and return a new BodyImage. If self is Ram or MemMap, this returns a shallow copy, and will not fail. If self is FsRead the returned clone will be a new MemMap (see rationale below) or will fail with BodyError::Io.

Rationale

FsRead currently uses an un-linked temporary file, so we can't create an independent (i.e. having its own offset or Seek position) file handle by independently opening a path. Rather than sharing the same offset in the clone (via File::try_clone), which would be very surprising for independent reads, we promote the clone to MemMap. The original BodyImage as FsRead, isn't modified by the clone and can still be read normally.

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 in state FsRead, a temporary memory map will be made in order to write without mutating self, using or changing the file position.

Trait Implementations

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.