pub trait Buffer<T>where
Self: Sized,{
type Output;
// Required methods
fn buffer_ptr(&mut self) -> *mut T;
fn buffer_len(&self) -> usize;
unsafe fn assume_init(self, len: usize) -> Self::Output;
// Provided method
fn cursor(self) -> Cursor<T, Self> { ... }
}Expand description
A memory buffer that may be uninitialized.
When a function has a Buffer argument, the type of the argument
determines the return type of the function:
| If you pass a… | You get back a… |
|---|---|
&mut [T] | usize, indicating the number of elements initialized. |
&mut [MaybeUninit<T>] | (&mut [T], &mut [MaybeUninit<T>]), holding the initialized and uninitialized subslices. |
SpareCapacity | usize, indicating the number of elements initialized. And the Vec is extended. |
&mut Cursor<T, B> | usize, indicating the number of elements initialized. And the Cursor is advanced. Be sure to call Cursor::finish when you’re done writing to it. |
§Examples
Passing a &mut [T]:
let mut buf = [0_u8; 64];
let nread = read(fd, &mut buf)?;
// `nread` is the number of bytes read.Passing a &mut [MaybeUninit<T>]:
let mut buf = [MaybeUninit::<u8>::uninit(); 64];
let (init, uninit) = read(fd, &mut buf)?;
// `init` is a `&mut [u8]` with the initialized bytes.
// `uninit` is a `&mut [MaybeUninit<u8>]` with the remaining bytes.Passing a SpareCapacity, via the spare_capacity helper function:
let mut buf = Vec::with_capacity(64);
let nread = read(fd, spare_capacity(&mut buf))?;
// `nread` is the number of bytes read.
// Also, `buf.len()` is now `nread` elements longer than it was before.Passing a &mut Cursor<T, B>:
let mut buf = [0_u8; 64];
let mut cursor = Cursor::new(&mut buf);
let _nread = read(fd, &mut cursor)?;
let _nread = read(fd, &mut cursor)?;
let _nread = read(fd, &mut cursor)?;
let total_nread = cursor.finish();
// `total_nread` is the total number of bytes read.§Guide to error messages
Sometimes code using Buffer can encounter non-obvious error messages.
Here are some we’ve encountered, along with ways to fix them.
If you see errors like
“cannot move out of self which is behind a mutable reference”
and
“move occurs because x has type &mut [u8], which does not implement the Copy trait”,
replace x with &mut *x. See error_buffer_wrapper in
examples/buffer_errors.rs.
If you see errors like
“type annotations needed”
and
“cannot infer type of the type parameter Buf declared on the function read”,
you may need to change a &mut [] to &mut [0_u8; 0]. See
error_empty_slice in examples/buffer_errors.rs.
If you see errors like
“the trait bound [MaybeUninit<u8>; 1]: Buffer<u8> is not satisfied”,
add a &mut to pass the array by reference instead of by value. See
error_array_by_value in examples/buffer_errors.rs.
If you see errors like
“cannot move out of x, a captured variable in an FnMut closure”,
try replacing x with &mut *x, or, if that doesn’t work, try moving a
let into the closure body. See error_retry_closure and
error_retry_indirect_closure in examples/buffer_errors.rs.
If you see errors like
“captured variable cannot escape FnMut closure body”,
use an explicit loop instead of retry_on_intr, assuming you’re using
that. See error_retry_closure_uninit in examples/buffer_errors.rs.
Required Associated Types§
Required Methods§
Sourcefn buffer_ptr(&mut self) -> *mut T
fn buffer_ptr(&mut self) -> *mut T
Return a raw mutable pointer to the underlying buffer.
After using this pointer to initialize some elements, call
assume_init to declare how many were initialized.
Sourcefn buffer_len(&self) -> usize
fn buffer_len(&self) -> usize
Return the length in elements of the underlying buffer.
Sourceunsafe fn assume_init(self, len: usize) -> Self::Output
unsafe fn assume_init(self, len: usize) -> Self::Output
Assert that len elements were written to, and provide a return value.
§Safety
At least the first len elements of the buffer must be initialized.
Provided Methods§
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.