pub struct Mapping { /* private fields */ }
Expand description
A safe wrapper around a mapped region of memory.
Note: this type implements Deref
/DerefMut
to the SharedBuffer
type, which allows reading/writing from the underlying memory.
Aside from creation and the Drop
impl, all of the interesting
functionality of this type is offered via SharedBuffer
.
Create a Mapping
and map it in the root address space.
Returns the VMO that was mapped.
The resulting VMO will not be resizeable.
Create a Mapping
and map it in the root address space.
Returns the VMO that was mapped.
The resulting VMO will not be resizeable.
Create a Mapping
from an existing VMO.
Requires that the VMO was not created with the RESIZABLE
option, and returns ZX_ERR_NOT_SUPPORTED
otherwise.
Return the size of the mapping.
Read bytes from the buffer.
Read up to dst.len()
bytes from the buffer, returning how many bytes
were read. The only thing that can cause fewer bytes to be read than
requested is if dst
is larger than the buffer itself.
A call to read
is only guaranteed to happen after an operation in
another thread or process if the mechanism used to signal the other
process has well-defined memory ordering semantics. Otherwise, the
acquire_writes
method must be called before read
and after receiving
a signal from the other process in order to provide such ordering
guarantees. In practice, this means that acquire_writes
should be the
first read operation that happens after receiving a signal from another
process that the memory may be read. See the acquire_writes
documentation for more details.
Read bytes from the buffer at an offset.
Read up to dst.len()
bytes starting at offset
into the buffer,
returning how many bytes were read. The only thing that can cause fewer
bytes to be read than requested is if there are fewer than dst.len()
bytes available starting at offset
within the buffer.
A call to read_at
is only guaranteed to happen after an operation in
another thread or process if the mechanism used to signal the other
process has well-defined memory ordering semantics. Otherwise, the
acquire_writes
method must be called before read_at
and after
receiving a signal from the other process in order to provide such
ordering guarantees. In practice, this means that acquire_writes
should be the first read operation that happens after receiving a signal
from another process that the memory may be read. See the
acquire_writes
documentation for more details.
read_at
panics if offset
is greater than the length of the buffer.
Write bytes to the buffer.
Write up to src.len()
bytes into the buffer, returning how many bytes
were written. The only thing that can cause fewer bytes to be written
than requested is if src
is larger than the buffer itself.
A call to write
is only guaranteed to happen before an operation in
another thread or process if the mechanism used to signal the other
process has well-defined memory ordering semantics. Otherwise, the
release_writes
method must be called after write
and before
signalling the other process in order to provide such ordering
guarantees. In practice, this means that release_writes
should be the
last write operation that happens before signalling another process that
the memory may be read. See the release_writes
documentation for more
details.
Write bytes to the buffer at an offset.
Write up to src.len()
bytes starting at offset
into the buffer,
returning how many bytes were written. The only thing that can cause
fewer bytes to be written than requested is if there are fewer than
src.len()
bytes available starting at offset
within the buffer.
A call to write_at
is only guaranteed to happen before an operation in
another thread or process if the mechanism used to signal the other
process has well-defined memory ordering semantics. Otherwise, the
release_writes
method must be called after write_at
and before
signalling the other process in order to provide such ordering
guarantees. In practice, this means that release_writes
should be the
last write operation that happens before signalling another process that
the memory may be read. See the release_writes
documentation for more
details.
write_at
panics if offset
is greater than the length of the buffer.
Acquire all writes performed by the other process.
On some systems (such as Fuchsia, currently), the communication
mechanism used for signalling a process that memory is readable does not
have well-defined synchronization semantics. On those systems, this
method MUST be called after receiving such a signal, or else writes
performed before that signal are not guaranteed to be observed by this
process.
acquire_writes
acquires any writes performed on this buffer or any
slice within the buffer.
Zircon, the Fuchsia kernel, will likely eventually have well-defined
semantics around the synchronization behavior of various syscalls. Once
that happens, calling this method in Fuchsia programs may become
optional. This work is tracked in fxbug.dev/32098.
Release all writes performed so far.
On some systems (such as Fuchsia, currently), the communication
mechanism used for signalling the other process that memory is readable
does not have well-defined synchronization semantics. On those systems,
this method MUST be called before such signalling, or else writes
performed before that signal are not guaranteed to be observed by the
other process.
release_writes
releases any writes performed on this buffer or any
slice within the buffer.
Zircon, the Fuchsia kernel, will likely eventually have well-defined
semantics around the synchronization behavior of various syscalls. Once
that happens, calling this method in Fuchsia programs may become
optional. This work is tracked in fxbug.dev/32098.
The number of bytes in this SharedBuffer
.
Create a slice of the original SharedBuffer
.
Just like the slicing operation on array and slice references, slice
constructs a SharedBufferSlice
which points to the same memory as the
original SharedBuffer
, but starting and index from
(inclusive) and
ending at index to
(exclusive).
slice
panics if range
is out of bounds of self
or if range
is
nonsensical (its lower bound is larger than its upper bound).
Create a mutable slice of the original SharedBuffer
.
Just like the mutable slicing operation on array and slice references,
slice_mut
constructs a SharedBufferSliceMut
which points to the same
memory as the original SharedBuffer
, but starting and index from
(inclusive) and ending at index to
(exclusive).
slice_mut
panics if range
is out of bounds of self
or if range
is nonsensical (its lower bound is larger than its upper bound).
Create two non-overlapping slices of the original SharedBuffer
.
Just like the split_at
method on array and slice references,
split_at
constructs one SharedBufferSlice
which represents bytes
[0, idx)
, and one which represents bytes [idx, len)
, where len
is
the length of the buffer.
split_at
panics if idx > self.len()
.
Create two non-overlapping mutable slices of the original SharedBuffer
.
Just like the split_at_mut
method on array and slice references,
split_at_miut
constructs one SharedBufferSliceMut
which represents
bytes [0, idx)
, and one which represents bytes [idx, len)
, where
len
is the length of the buffer.
split_at_mut
panics if idx > self.len()
.
Get the buffer pointer and length so that the memory can be freed.
This method is an alternative to calling consume
if relinquishing
ownership of the object is infeasible (for example, when the object is a
struct field and thus can’t be moved out of the struct). Since it allows
the object to continue existing, it must be used with care (see the
“Safety” section below).
The returned pointer must only be used to free the memory. Since the
memory is shared by another process, using it as a normal raw pointer to
normal memory owned by this process is unsound.
If the pointer is used for this purpose, then the caller must ensure
that no methods will be called on the object after the call to
as_ptr_len
. The only scenario in which the object may be used again is
if the caller does nothing at all with the return value of this method
(although that would be kind of pointless…).
Formats the value using the given formatter.
Read more
The resulting type after dereferencing.
Dereferences the value.
Mutably dereferences the value.
Executes the destructor for this type.
Read more
Immutably borrows from an owned value.
Read more
Mutably borrows from an owned value.
Read more
Returns the argument unchanged.
Calls U::from(self)
.
That is, this conversion is whatever the implementation of
From<T> for U
chooses to do.
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.