Struct chromium::StableVec

#[repr(C)]
pub struct StableVec<T> where
    T: StableLayout,  { /* fields omitted */ }

A struct for the parts of a Vec with a stable layout.

Unsafety

Because this type is primarily intended to help unsafe Rust we should discuss the precise guarantees offered:

• Validity Invariants
  • The data layout is a *mut T, usize, usize.
• Soundness Invariants
  • The *mut T must point to the start of a valid Vec<T> allocation.
  • The first usize must be the correct length of that valid Vec<T>.
  • The second usize must be the correct capacity of that valid Vec<T>.
  • The memory is owned by the StableVec and is allocated from Rust's Global Allocator.
    • You must not turn this type back into a Vec in a Rust runtime with a different global allocator than the one is was created with. At the moment (2020-03-06) it happens to be the case that the default Rust global allocator is process-wide on Windows / Mac / Linux.

If you drop a StableVec without turning it back into a Vec then the memory leaks.

When you use this type with the C ABI, remember that the C ABI does not support generic types or repr(Rust) types!

If you select a particular type for T that is compatible with the C ABI, such as u8 or i32, then that particular monomorphization of SharedSlice will be C ABI compatible as well. For example, if your element type were u8 then it would be equivalent layout to the following C declaration:

#include <stdint.h>
// Identical layout to `StableVec<u8>`
typedef struct {
  uint8_t *ptr;
  uintptr_t len;
  uintptr_t cap;
} StableVec_u8;

Trait Implementations

impl<T: Debug> Debug for StableVec<T> where
    T: StableLayout, 

fn fmt(&self, f: &mut Formatter) -> Result

Debug prints as a slice would.

impl<T> Default for StableVec<T> where
    T: StableLayout, 

fn default() -> Self

Defaults to an empty vec.

let sv: StableVec<i32> = StableVec::default();
assert_eq!(sv.len(), 0);

impl<T> Deref for StableVec<T> where
    T: StableLayout, 

type Target = [T]

The resulting type after dereferencing.

fn deref(&self) -> &[T]

Dereferences the value.

impl<T> DerefMut for StableVec<T> where
    T: StableLayout, 

fn deref_mut(&mut self) -> &mut [T]

Mutably dereferences the value.

impl<T> From<StableVec<T>> for Vec<T> where
    T: StableLayout, 

fn from(sv: StableVec<T>) -> Self

Performs the conversion.

impl<T> From<Vec<T>> for StableVec<T> where
    T: StableLayout, 

fn from(vec: Vec<T>) -> Self

Performs the conversion.

impl<T: StableLayout> StableLayout for StableVec<T>