Struct rustc_middle::mir::interpret::allocation::Allocation

pub struct Allocation<Prov = AllocId, Extra = ()> {
    bytes: Box<[u8]>,
    provenance: ProvenanceMap<Prov>,
    init_mask: InitMask,
    pub align: Align,
    pub mutability: Mutability,
    pub extra: Extra,
}

This type represents an Allocation in the Miri/CTFE core engine.

Its public API is rather low-level, working directly with allocation offsets and a custom error type to account for the lack of an AllocId on this level. The Miri/CTFE core engine memory module provides higher-level access.

Fields

bytes: Box<[u8]>

The actual bytes of the allocation. Note that the bytes of a pointer represent the offset of the pointer.

provenance: ProvenanceMap<Prov>

Maps from byte addresses to extra provenance data for each pointer. Only the first byte of a pointer is inserted into the map; i.e., every entry in this map applies to pointer_size consecutive bytes starting at the given offset.

init_mask: InitMask

Denotes which part of this allocation is initialized.

align: Align

The alignment of the allocation to detect unaligned reads. (Align guarantees that this is a power of two.)

mutability: Mutability

true if the allocation is mutable. Also used by codegen to determine if a static should be put into mutable memory, which happens for static mut and static with interior mutability.

extra: Extra

Extra state for the machine.

Implementations

impl<Prov> Allocation<Prov>

pub fn from_bytes<'a>(
    slice: impl Into<Cow<'a, [u8]>>,
    align: Align,
    mutability: Mutability
) -> Self

Creates an allocation initialized by the given bytes

pub fn from_bytes_byte_aligned_immutable<'a>(
    slice: impl Into<Cow<'a, [u8]>>
) -> Self

pub fn uninit<'tcx>(
    size: Size,
    align: Align,
    panic_on_fail: bool
) -> InterpResult<'tcx, Self>

Try to create an Allocation of size bytes, failing if there is not enough memory available to the compiler to do so.

If panic_on_fail is true, this will never return Err.

impl Allocation

pub fn adjust_from_tcx<Prov, Extra, Err>(
    self,
    cx: &impl HasDataLayout,
    extra: Extra,
    adjust_ptr: impl FnMut(Pointer<AllocId>) -> Result<Pointer<Prov>, Err>
) -> Result<Allocation<Prov, Extra>, Err>

Adjust allocation from the ones in tcx to a custom Machine instance with a different Provenance and Extra type.

impl<Prov, Extra> Allocation<Prov, Extra>

Raw accessors. Provide access to otherwise private bytes.

pub fn len(&self) -> usize

pub fn size(&self) -> Size

pub fn inspect_with_uninit_and_ptr_outside_interpreter(
    &self,
    range: Range<usize>
) -> &[u8]

Looks at a slice which may contain uninitialized bytes or provenance. This differs from get_bytes_with_uninit_and_ptr in that it does no provenance checks (even on the edges) at all. This must not be used for reads affecting the interpreter execution.

pub fn init_mask(&self) -> &InitMask

Returns the mask indicating which bytes are initialized.

pub fn provenance(&self) -> &ProvenanceMap<Prov>

Returns the provenance map.

impl<Prov: Provenance, Extra> Allocation<Prov, Extra>

Byte accessors.

pub fn get_bytes_unchecked(&self, range: AllocRange) -> &[u8]

This is the entirely abstraction-violating way to just grab the raw bytes without caring about provenance or initialization.

This function also guarantees that the resulting pointer will remain stable even when new allocations are pushed to the HashMap. mem_copy_repeatedly relies on that.

pub fn get_bytes_strip_provenance(
    &self,
    cx: &impl HasDataLayout,
    range: AllocRange
) -> Result<&[u8], AllocError>

Checks that these bytes are initialized, and then strip provenance (if possible) and return them.

It is the caller’s responsibility to check bounds and alignment beforehand. Most likely, you want to use the PlaceTy and OperandTy-based methods on InterpCx instead.

pub fn get_bytes_mut(
    &mut self,
    cx: &impl HasDataLayout,
    range: AllocRange
) -> Result<&mut [u8], AllocError>

Just calling this already marks everything as defined and removes provenance, so be sure to actually put data there!

It is the caller’s responsibility to check bounds and alignment beforehand. Most likely, you want to use the PlaceTy and OperandTy-based methods on InterpCx instead.

pub fn get_bytes_mut_ptr(
    &mut self,
    cx: &impl HasDataLayout,
    range: AllocRange
) -> Result<*mut [u8], AllocError>

A raw pointer variant of get_bytes_mut that avoids invalidating existing aliases into this memory.

impl<Prov: Provenance, Extra> Allocation<Prov, Extra>

Reading and writing.

pub fn read_scalar(
    &self,
    cx: &impl HasDataLayout,
    range: AllocRange,
    read_provenance: bool
) -> Result<Scalar<Prov>, AllocError>

Reads a non-ZST scalar.

If read_provenance is true, this will also read provenance; otherwise (if the machine supports that) provenance is entirely ignored.

ZSTs can’t be read because in order to obtain a Pointer, we need to check for ZSTness anyway due to integer pointers being valid for ZSTs.

It is the caller’s responsibility to check bounds and alignment beforehand. Most likely, you want to call InterpCx::read_scalar instead of this method.

pub fn write_scalar(
    &mut self,
    cx: &impl HasDataLayout,
    range: AllocRange,
    val: Scalar<Prov>
) -> Result<(), AllocError>

Writes a non-ZST scalar.

ZSTs can’t be read because in order to obtain a Pointer, we need to check for ZSTness anyway due to integer pointers being valid for ZSTs.

It is the caller’s responsibility to check bounds and alignment beforehand. Most likely, you want to call InterpCx::write_scalar instead of this method.

pub fn write_uninit(
    &mut self,
    cx: &impl HasDataLayout,
    range: AllocRange
) -> Result<(), AllocError>

Write “uninit” to the given memory range.

impl<Prov: Copy, Extra> Allocation<Prov, Extra>

Provenance.

fn range_get_provenance(
    &self,
    cx: &impl HasDataLayout,
    range: AllocRange
) -> &[(Size, Prov)]

Returns all provenance overlapping with the given pointer-offset pair.

fn offset_get_provenance(
    &self,
    cx: &impl HasDataLayout,
    offset: Size
) -> Option<Prov>

Get the provenance of a single byte.

pub fn range_has_provenance(
    &self,
    cx: &impl HasDataLayout,
    range: AllocRange
) -> bool

Returns whether this allocation has progrnance overlapping with the given range.

Note: this function exists to allow range_get_provenance to be private, in order to somewhat limit access to provenance outside of the Allocation abstraction.

fn clear_provenance(
    &mut self,
    cx: &impl HasDataLayout,
    range: AllocRange
) -> Result<(), AllocError>where
    Prov: Provenance,

Removes all provenance inside the given range. If there is provenance overlapping with the edges, it are removed as well and the bytes they cover are marked as uninitialized. This is a somewhat odd “spooky action at a distance”, but it allows strictly more code to run than if we would just error immediately in that case.

impl<Prov: Copy, Extra> Allocation<Prov, Extra>

pub fn prepare_provenance_copy(
    &self,
    cx: &impl HasDataLayout,
    src: AllocRange,
    dest: Size,
    count: u64
) -> AllocationProvenance<Prov>

pub fn mark_provenance_range(&mut self, provenance: AllocationProvenance<Prov>)

Applies a provenance copy. The affected range, as defined in the parameters to prepare_provenance_copy is expected to be clear of provenance.

This is dangerous to use as it can violate internal Allocation invariants! It only exists to support an efficient implementation of mem_copy_repeatedly.

impl<Prov: Copy, Extra> Allocation<Prov, Extra>

Uninitialized bytes.

fn is_init(&self, range: AllocRange) -> Result<(), AllocRange>

Checks whether the given range is entirely initialized.

Returns Ok(()) if it’s initialized. Otherwise returns the range of byte indexes of the first contiguous uninitialized access.

fn check_init(&self, range: AllocRange) -> Result<(), AllocError>

Checks that a range of bytes is initialized. If not, returns the InvalidUninitBytes error which will report the first range of bytes which is uninitialized.

fn mark_init(&mut self, range: AllocRange, is_init: bool)

impl<Prov, Extra> Allocation<Prov, Extra>

Transferring the initialization mask to other allocations.

pub fn compress_uninit_range(&self, range: AllocRange) -> InitMaskCompressed

Creates a run-length encoding of the initialization mask; panics if range is empty.

This is essentially a more space-efficient version of InitMask::range_as_init_chunks(...).collect::<Vec<_>>().

pub fn mark_compressed_init_range(
    &mut self,
    defined: &InitMaskCompressed,
    range: AllocRange,
    repeat: u64
)

Applies multiple instances of the run-length encoding to the initialization mask.

This is dangerous to use as it can violate internal Allocation invariants! It only exists to support an efficient implementation of mem_copy_repeatedly.

Trait Implementations

impl<'tcx> ArenaAllocatable<'tcx, IsNotCopy> for Allocation

fn allocate_on<'a>(self, arena: &'a Arena<'tcx>) -> &'a mut Self

fn allocate_from_iter<'a>(
    arena: &'a Arena<'tcx>,
    iter: impl IntoIterator<Item = Self>
) -> &'a mut [Self]

impl<'tcx> Borrow<Allocation<AllocId, ()>> for InternedInSet<'tcx, Allocation>

fn borrow<'a>(&'a self) -> &'a Allocation

Immutably borrows from an owned value.

impl<Prov: Clone, Extra: Clone> Clone for Allocation<Prov, Extra>

fn clone(&self) -> Allocation<Prov, Extra>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Prov: Debug, Extra: Debug> Debug for Allocation<Prov, Extra>

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

Formats the value using the given formatter.

impl<'tcx, Prov, Extra, __D: TyDecoder<I = TyCtxt<'tcx>>> Decodable<__D> for Allocation<Prov, Extra>where
    Prov: Decodable<__D>,
    Extra: Decodable<__D>,

fn decode(__decoder: &mut __D) -> Self

impl<'tcx, Prov, Extra, __E: TyEncoder<I = TyCtxt<'tcx>>> Encodable<__E> for Allocation<Prov, Extra>where
    Prov: Encodable<__E>,
    Extra: Encodable<__E>,

fn encode(&self, __encoder: &mut __E)

impl Hash for Allocation

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,

Feeds a slice of this type into the given Hasher.

impl<'__ctx, Prov, Extra> HashStable<StableHashingContext<'__ctx>> for Allocation<Prov, Extra>where
    Prov: HashStable<StableHashingContext<'__ctx>>,
    Extra: HashStable<StableHashingContext<'__ctx>>,

fn hash_stable(
    &self,
    __hcx: &mut StableHashingContext<'__ctx>,
    __hasher: &mut StableHasher
)

impl<Prov: Ord, Extra: Ord> Ord for Allocation<Prov, Extra>

fn cmp(&self, other: &Allocation<Prov, Extra>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: PartialOrd<Self>,

Restrict a value to a certain interval.

impl<Prov: PartialEq, Extra: PartialEq> PartialEq<Allocation<Prov, Extra>> for Allocation<Prov, Extra>

fn eq(&self, other: &Allocation<Prov, Extra>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Prov: PartialOrd, Extra: PartialOrd> PartialOrd<Allocation<Prov, Extra>> for Allocation<Prov, Extra>

fn partial_cmp(&self, other: &Allocation<Prov, Extra>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Prov: Eq, Extra: Eq> Eq for Allocation<Prov, Extra>

impl<Prov, Extra> StructuralEq for Allocation<Prov, Extra>

impl<Prov, Extra> StructuralPartialEq for Allocation<Prov, Extra>

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.