[−][src]Struct body_image::BodyImage
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
and supports
low-cost shallow Clone
via internal (atomic) reference
counting. BodyImage
is not Sync
(with the default mmap feature
enabled).
Methods
impl BodyImage
[src]
pub fn empty() -> BodyImage
[src]
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
[src]
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>,
[src]
T: Into<Bytes>,
Create new instance from a single byte slice.
pub unsafe fn from_read_slice(rslice: ReadSlice) -> BodyImage
[src]
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
[src]
Return true if in state Ram
.
pub fn is_mem_map(&self) -> bool
[src]
Return true if in state MemMap
.
pub fn len(&self) -> u64
[src]
Return the current length of body in bytes.
pub fn is_empty(&self) -> bool
[src]
Return true if body is empty.
pub fn mem_map(&mut self) -> Result<&mut Self, BodyError>
[src]
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
[src]
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>pub fn reader(&self) -> BodyReader
[src]
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
[src]
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,
[src]
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,
[src]
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 Default for BodyImage
[src]
impl Clone for BodyImage
[src]
fn clone(&self) -> BodyImage
[src]
fn clone_from(&mut self, source: &Self)
1.0.0[src]
Performs copy-assignment from source
. Read more
impl Debug for BodyImage
[src]
Auto Trait Implementations
Blanket Implementations
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
fn to_owned(&self) -> T
[src]
fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,