Struct RawEntityRef 

pub struct RawEntityRef<T: ?Sized, Metadata = ()> { /* private fields */ }

A RawEntityRef is an unsafe smart pointer type for IR entities allocated in a [Context].

Along with the type of entity referenced, it can be instantiated with extra metadata of any type. For example, UnsafeIntrusiveEntityRef stores an intrusive link in the entity metadata, so that the entity can be added to an intrusive linked list without the entity needing to know about the link - and without violating aliasing rules when navigating the list.

Unlike regular references, no reference to the underlying T is constructed until one is needed, at which point the borrow (whether mutable or immutable) is dynamically checked to ensure that it is valid according to Rust’s aliasing rules.

As a result, a RawEntityRef is not considered an alias, and it is possible to acquire a mutable reference to the underlying data even while other copies of the handle exist. Any attempt to construct invalid aliases (immutable reference while a mutable reference exists, or vice versa), will result in a runtime panic.

This is a tradeoff, as we do not get compile-time guarantees that such panics will not occur, but in exchange we get a much more flexible and powerful IR structure.

SAFETY

Unlike most smart-pointer types, e.g. Rc, [RAwEntityRef] does not provide any protection against the underlying allocation being deallocated (i.e. the arena it points into is dropped). This is by design, as the type is meant to be stored in objects inside the arena, and not dropped when the arena is dropped. This requires care when using it however, to ensure that no RawEntityRef lives longer than the arena that allocated it.

For a safe entity reference, see EntityRef, which binds a RawEntityRef to the lifetime of the arena.

Implementations

impl<T: 'static> RawEntityRef<T, IntrusiveLink>

pub fn new(value: T, arena: &Blink) -> Self

Create a new UnsafeIntrusiveEntityRef by allocating value in arena

SAFETY

This function has the same requirements around safety as RawEntityRef::new.

pub fn new_uninit(arena: &Blink) -> RawEntityRef<MaybeUninit<T>, IntrusiveLink>

impl<T> RawEntityRef<T, IntrusiveLink>

where T: EntityWithParent,

pub fn parent( &self, ) -> Option<UnsafeIntrusiveEntityRef<<T as EntityWithParent>::Parent>>

Returns the parent entity this entity is linked to, if linked.

impl<T> RawEntityRef<T, IntrusiveLink>

where T: EntityWithParent, <T as EntityWithParent>::Parent: EntityWithParent,

pub fn grandparent( &self, ) -> Option<UnsafeIntrusiveEntityRef<<<T as EntityWithParent>::Parent as EntityWithParent>::Parent>>

impl<T> RawEntityRef<T, IntrusiveLink>

pub fn is_linked(&self) -> bool

Returns true if this entity is linked into an intrusive list

pub fn prev(&self) -> Option<Self>

Get the previous entity in the list of T containing the current entity

For example, in a list of Operation in a Block, this would return the handle of the previous operation in the block, or None if there are no other ops before this one.

pub fn next(&self) -> Option<Self>

Get the next entity in the list of T containing the current entity

For example, in a list of Operation in a Block, this would return the handle of the next operation in the block, or None if there are no other ops after this one.

impl<T: 'static, Metadata: 'static> RawEntityRef<T, Metadata>

pub fn new_with_metadata(value: T, metadata: Metadata, arena: &Blink) -> Self

Create a new RawEntityRef by allocating value with metadata in the given arena allocator.

SAFETY

The resulting RawEntityRef must not outlive the arena. This is not enforced statically, it is up to the caller to uphold the invariants of this type.

pub fn new_uninit_with_metadata( metadata: Metadata, arena: &Blink, ) -> RawEntityRef<MaybeUninit<T>, Metadata>

Create a RawEntityRef for an entity which may not be fully initialized, using the provided arena.

SAFETY

The safety rules are much the same as RawEntityRef::new, with the main difference being that the T does not have to be initialized yet. No references to the T will be created directly until RawEntityRef::assume_init is called.

impl<T: 'static> RawEntityRef<T, ()>

pub fn new(value: T, arena: &Blink) -> Self

pub fn new_uninit(arena: &Blink) -> RawEntityRef<MaybeUninit<T>, ()>

impl<T, Metadata> RawEntityRef<MaybeUninit<T>, Metadata>

pub unsafe fn assume_init(self) -> RawEntityRef<T, Metadata>

Converts to RawEntityRef<T>.

Safety

Just like with MaybeUninit::assume_init, it is up to the caller to guarantee that the value really is in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior.

impl<T: ?Sized, Metadata> RawEntityRef<T, Metadata>

pub fn into_raw(this: Self) -> *const T

Convert this handle into a raw pointer to the underlying entity.

This should only be used in situations where the returned pointer will not be used to actually access the underlying entity. Use [get] or [get_mut] for that. RawEntityRef ensures that Rust’s aliasing rules are not violated when using it, but if you use the returned pointer to do so, no such guarantee is provided, and undefined behavior can result.

Safety

The returned pointer must not be used to create a reference to the underlying entity unless you can guarantee that such a reference does not violate Rust’s aliasing rules.

Do not use the pointer to create a mutable reference if other references exist, and do not use the pointer to create an immutable reference if a mutable reference exists or might be created while the immutable reference lives.

pub fn as_ptr(this: &Self) -> *const T

pub unsafe fn from_raw(ptr: *const T) -> Self

Convert a pointer returned by RawEntityRef::into_raw back into a RawEntityRef.

Safety

• It is only valid to call this method on a pointer returned by RawEntityRef::into_raw.
• The pointer must be a valid pointer for T

pub fn borrow<'a, 'b: 'a>(&'a self) -> EntityRef<'b, T>

Get a dynamically-checked immutable reference to the underlying T

pub fn borrow_mut<'a, 'b: 'a>(&'a mut self) -> EntityMut<'b, T>

Get a dynamically-checked mutable reference to the underlying T

pub fn try_borrow_mut<'a, 'b: 'a>(&'a mut self) -> Option<EntityMut<'b, T>>

Try to get a dynamically-checked mutable reference to the underlying T

Returns None if the entity is already borrowed

pub fn ptr_eq(this: &Self, other: &Self) -> bool

impl<From: ?Sized, Metadata: 'static> RawEntityRef<From, Metadata>

pub fn try_downcast<To>( self, ) -> Result<RawEntityRef<To, Metadata>, RawEntityRef<From, Metadata>>

where To: DowncastFromRef<From> + 'static, From: 'static,

Casts this reference to the concrete type T, if the underlying value is a T.

If the cast is not valid for this reference, Err is returned containing the original value.

pub fn try_downcast_ref<To, Obj>(&self) -> Option<RawEntityRef<To, Metadata>>

where To: DowncastFromRef<From> + 'static, From: Is<Obj> + AsAny + 'static, Obj: ?Sized,

Casts this reference to the concrete type T, if the underlying value is a T.

If the cast is not valid for this reference, Err is returned containing the original value.

pub fn downcast<To, Obj>(self) -> RawEntityRef<To, Metadata>

where To: DowncastFromRef<From> + 'static, From: Is<Obj> + AsAny + 'static, Obj: ?Sized,

Casts this reference to the concrete type T, if the underlying value is a T.

Panics if the cast is not valid for this reference.

pub fn downcast_ref<To, Obj>(&self) -> RawEntityRef<To, Metadata>

where To: DowncastFromRef<From> + 'static, From: Is<Obj> + AsAny + 'static, Obj: ?Sized,

Casts this reference to the concrete type T, if the underlying value is a T.

Panics if the cast is not valid for this reference.

impl<To, Metadata: 'static> RawEntityRef<To, Metadata>

pub fn try_downcast_from<From>( from: RawEntityRef<From, Metadata>, ) -> Result<Self, RawEntityRef<From, Metadata>>

where From: ?Sized + 'static, To: DowncastFromRef<From> + 'static,

pub fn try_downcast_from_ref<From, Obj>( from: &RawEntityRef<From, Metadata>, ) -> Option<Self>

where From: ?Sized + Is<Obj> + AsAny + 'static, To: DowncastFromRef<From> + 'static, Obj: ?Sized,

pub fn downcast_from<From, Obj>(from: RawEntityRef<From, Metadata>) -> Self

where From: ?Sized + Is<Obj> + AsAny + 'static, To: DowncastFromRef<From> + 'static, Obj: ?Sized,

pub fn downcast_from_ref<From, Obj>(from: &RawEntityRef<From, Metadata>) -> Self

where From: ?Sized + Is<Obj> + AsAny + 'static, To: DowncastFromRef<From> + 'static, Obj: ?Sized,

impl<From: ?Sized, Metadata: 'static> RawEntityRef<From, Metadata>

pub fn upcast<To>(self) -> RawEntityRef<To, Metadata>

where To: ?Sized, From: Unsize<To> + AsAny + 'static,

Casts this reference to the an unsized type Trait, if From implements Trait

If the cast is not valid for this reference, Err is returned containing the original value.

impl<T: Op> RawEntityRef<T, IntrusiveLink>

pub fn as_operation_ref(self) -> OperationRef

Get a entity ref for the underlying crate::Operation data of an [Op].

impl RawEntityRef<Operation, IntrusiveLink>

Insertion

pub fn insert_at_start(self, block: BlockRef)

pub fn insert_at_end(self, block: BlockRef)

pub fn insert_before(self, before: OperationRef)

pub fn insert_after(self, after: OperationRef)

impl RawEntityRef<Operation, IntrusiveLink>

Read-only Metadata

pub fn name(&self) -> OperationName

pub fn parent_op(&self) -> Option<OperationRef>

Returns a handle to the nearest containing Operation of this operation, if it is attached to one

pub fn parent_region(&self) -> Option<RegionRef>

Returns a handle to the containing Region of this operation, if it is attached to one

pub fn nearest_symbol_table(&self) -> Option<OperationRef>

Returns the nearest SymbolTable from this operation.

Returns None if no parent of this operation is a valid symbol table.

Trait Implementations

impl Borrow<RawEntityRef<dyn Value<Id = ValueId, Use = OpOperandImpl>>> for &ValueOrAlias

fn borrow(&self) -> &ValueRef

Immutably borrows from an owned value.

impl Borrow<RawEntityRef<dyn Value<Id = ValueId, Use = OpOperandImpl>>> for &mut ValueOrAlias

fn borrow(&self) -> &ValueRef

Immutably borrows from an owned value.

impl Borrow<RawEntityRef<dyn Value<Id = ValueId, Use = OpOperandImpl>>> for ValueOrAlias

fn borrow(&self) -> &ValueRef

Immutably borrows from an owned value.

impl<T: ?Sized, Metadata> Clone for RawEntityRef<T, Metadata>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: ?Sized + Debug, Metadata> Debug for RawEntityRef<T, Metadata>

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

Formats the value using the given formatter.

impl<T: ?Sized + Debug + EntityWithId, Metadata> Debug for RawEntityRef<T, Metadata>

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

Formats the value using the given formatter.

impl<T: ?Sized + Display, Metadata> Display for RawEntityRef<T, Metadata>

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

Formats the value using the given formatter.

impl<T: ?Sized + Display + EntityWithId, Metadata> Display for RawEntityRef<T, Metadata>

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

Formats the value using the given formatter.

impl From<RawEntityRef<Block, IntrusiveLink>> for ProgramPoint

Construct a ProgramPoint referring to the point at entry to block

fn from(block: BlockRef) -> Self

Converts to this type from the input type.

impl From<RawEntityRef<Operation, IntrusiveLink>> for ProgramPoint

Construct a ProgramPoint referring to the point at entry to op

fn from(op: OperationRef) -> Self

Converts to this type from the input type.

impl From<RawEntityRef<dyn Value<Id = ValueId, Use = OpOperandImpl>>> for Callable

fn from(value: ValueRef) -> Self

Converts to this type from the input type.

impl From<RawEntityRef<dyn Value<Id = ValueId, Use = OpOperandImpl>>> for ValueOrAlias

fn from(value: ValueRef) -> Self

Converts to this type from the input type.

impl<const N: usize> FromIterator<RawEntityRef<BlockArgument>> for ValueRange<'static, N>

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = BlockArgumentRef>,

Creates a value from an iterator.

impl<const N: usize> FromIterator<RawEntityRef<OpOperandImpl, IntrusiveLink>> for ValueRange<'static, N>

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = OpOperand>,

Creates a value from an iterator.

impl<const N: usize> FromIterator<RawEntityRef<OpResult>> for ValueRange<'static, N>

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = OpResultRef>,

Creates a value from an iterator.

impl FromIterator<RawEntityRef<SymbolUse, IntrusiveLink>> for SymbolUseRefsIter

fn from_iter<T: IntoIterator<Item = SymbolUseRef>>(iter: T) -> Self

Creates a value from an iterator.

impl FromIterator<RawEntityRef<SymbolUse, IntrusiveLink>> for SymbolUsesIter

fn from_iter<T: IntoIterator<Item = SymbolUseRef>>(iter: T) -> Self

Creates a value from an iterator.

impl<T: EntityListItem> FromIterator<RawEntityRef<T, IntrusiveLink>> for EntityList<T>

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = UnsafeIntrusiveEntityRef<T>>,

Creates a value from an iterator.

impl<const N: usize> FromIterator<RawEntityRef<dyn Value<Id = ValueId, Use = OpOperandImpl>>> for ValueRange<'static, N>

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = ValueRef>,

Creates a value from an iterator.

impl<T: ?Sized, Metadata> Hash for RawEntityRef<T, Metadata>

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: ?Sized + EntityWithId, Metadata> Ord for RawEntityRef<T, Metadata>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<RawEntityRef<dyn Value<Id = ValueId, Use = OpOperandImpl>>> for ValueOrAlias

fn eq(&self, other: &ValueRef) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T: ?Sized, Metadata> PartialEq for RawEntityRef<T, Metadata>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T: ?Sized + EntityWithId, Metadata> PartialOrd for RawEntityRef<T, Metadata>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<T: ?Sized, Metadata> Pointer for RawEntityRef<T, Metadata>

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

Formats the value using the given formatter.

impl<T: ?Sized + PrettyPrint, Metadata> PrettyPrint for RawEntityRef<T, Metadata>

fn render(&self) -> Document

The core of the PrettyPrint functionality.

fn to_pretty_string(&self) -> String

Produce a String containing the results of pretty-printing this object.

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

Pretty-print this object to the given core::fmt::Formatter.

impl<T: ?Sized + Spanned, Metadata> Spanned for RawEntityRef<T, Metadata>

fn span(&self) -> SourceSpan

impl<T: ?Sized + StorableEntity, Metadata> StorableEntity for RawEntityRef<T, Metadata>

fn index(&self) -> usize

Get the absolute index of this entity in its container.

unsafe fn set_index(&mut self, index: usize)

Set the absolute index of this entity in its container.

fn unlink(&mut self)

Called when this entity is removed from EntityStorage

impl<T, U, Metadata> CoerceUnsized<RawEntityRef<U, Metadata>> for RawEntityRef<T, Metadata>

where T: ?Sized + Unsize<U>, U: ?Sized,

impl<T: ?Sized, Metadata> Copy for RawEntityRef<T, Metadata>

impl<T: ?Sized, Metadata> Eq for RawEntityRef<T, Metadata>