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 (default mmap feature)

All states support concurrent reads. BodyImage is Send, Sync, 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 unsafe 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 the returned BodyImage can fail if the file is not open for read.

Safety

Use of this constructor is potentially unsafe when the mmap feature enabled and once mem_map is called:

• The mem_map call will fail if the file is zero length or not open for read.

• Any concurrent writes to the file, or file system modifications while under use in MemMap state may lead to Undefined Behavior (UB).

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

Create new instance from a single byte slice.

pub unsafe 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 the returned BodyImage can fail if the file is not open for read.

Safety

Use of this constructor is potentially unsafe when the mmap feature enabled and once mem_map is called:

• The mem_map call will fail if the file is zero length or not open for read.

• Any concurrent writes to the file, or file system modifications while under use in MemMap state may lead to Undefined Behavior (UB).

pub fn is_ram(&self) -> bool

Return true if in state Ram.

pub fn is_mem_map(&self) -> bool

Return true if in state MemMap.

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 mem_map(&mut self) -> Result<&mut Self, BodyError>

If FsRead, convert to MemMap by memory mapping the file.

Under normal construction via BodySink in FsWrite state, this method is safe, because no other thread or process has access to the underlying file. Note the potential safety requirements via from_file however.

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.

Important traits for BodyReader<'a>

impl<'a> Read for BodyReader<'a>

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 explode(self) -> ExplodedImage

Consume self, exploding into an ExplodedImage variant.

pub fn read_from<R: ?Sized>(
    rin: &mut R,
    len_estimate: u64,
    tune: &Tunables
) -> Result<BodyImage, BodyError> where
    R: Read, 

Given a Read reference, 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).

The Read is passed by reference for backward compatibility with its original non-generic form as &mut dyn Read. C-RW-VALUE prefers pass by value, but this would now be a breaking change.

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

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

The Write is passed by reference for backward compatibility with its original non-generic form as &mut dyn Write. C-RW-VALUE prefers pass by value, but this would now be a breaking change. std::io::copy is presumably in the same position.

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, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for BodyImage

fn default() -> BodyImage

Returns the "default value" for a type.