Struct body_image::BodyImage [−][src]
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
[src]
impl BodyImage
pub fn empty() -> BodyImage
[src]
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
[src]
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>,
[src]
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
[src]
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
[src]
pub fn is_ram(&self) -> bool
Return true if in state Ram
.
pub fn len(&self) -> u64
[src]
pub fn len(&self) -> u64
Return the current length of body in bytes.
pub fn is_empty(&self) -> bool
[src]
pub fn is_empty(&self) -> bool
Return true if body is empty.
pub fn mem_map(&mut self) -> Result<&mut Self, BodyError>
[src]
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
[src]
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 reader(&self) -> BodyReader
[src]
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>
[src]
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>
[src]
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
[src]
impl Clone for BodyImage
fn clone(&self) -> BodyImage
[src]
fn clone(&self) -> BodyImage
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
impl Debug for BodyImage
[src]
impl Debug for BodyImage
fn fmt(&self, f: &mut Formatter) -> Result
[src]
fn fmt(&self, f: &mut Formatter) -> Result
Formats the value using the given formatter. Read more
impl Default for BodyImage
[src]
impl Default for BodyImage