Struct mmtk::util::address::ObjectReference

#[repr(transparent)]
pub struct ObjectReference(NonZeroUsize);

ObjectReference represents address for an object. Compared with Address, operations allowed on ObjectReference are very limited. No address arithmetics are allowed for ObjectReference. The idea is from the paper High-level Low-level Programming (VEE09) and JikesRVM.

A runtime may define its “object references” differently. It may define an object reference as the address of an object, a handle that points to an indirection table entry where a pointer to the object is held, or anything else. Regardless, MMTk expects each object reference to have a pointer to the object (an address) in each object reference, and that address should be used for this ObjectReference type.

We currently do not allow an opaque ObjectReference type for which a binding can define their layout. We now only allow a binding to define their semantics through a set of methods in crate::vm::ObjectModel. Major refactoring is needed in MMTk to allow the opaque ObjectReference type, and we haven’t seen a use case for now.

Note that ObjectReference cannot be null. For the cases where a non-null object reference may or may not exist, (such as the result of crate::vm::edge_shape::Edge::load) Option<ObjectReference> should be used. ObjectReference is backed by NonZeroUsize which cannot be zero, and it has the #[repr(transparent)] attribute. Thanks to null pointer optimization (NPO), Option<ObjectReference> has the same size as NonZeroUsize and usize. For the convenience of passing Option<ObjectReference> to and from native (C/C++) programs, mmtk-core provides crate::util::api_util::NullableObjectReference.

Tuple Fields

0: NonZeroUsize

Implementations

impl ObjectReference

pub fn to_raw_address(self) -> Address

Cast the object reference to its raw address. This method is mostly for the convinience of a binding.

MMTk should not make any assumption on the actual location of the address with the object reference. MMTk should not assume the address returned by this method is in our allocation. For the purposes of setting object metadata, MMTk should use crate::vm::ObjectModel::ref_to_address() or crate::vm::ObjectModel::ref_to_header().

pub fn from_raw_address(addr: Address) -> Option<ObjectReference>

Cast a raw address to an object reference. This method is mostly for the convinience of a binding. This is how a binding creates ObjectReference instances.

If addr is 0, the result is None.

MMTk should not assume an arbitrary address can be turned into an object reference. MMTk can use crate::vm::ObjectModel::address_to_ref() to turn addresses that are from crate::vm::ObjectModel::ref_to_address() back to object.

pub unsafe fn from_raw_address_unchecked(addr: Address) -> ObjectReference

Like from_raw_address, but assume addr is not zero. This can be used to elide a check against zero for performance-critical code.

Safety

This method assumes addr is not zero. It should only be used in cases where we know at compile time that the input cannot be zero. For example, if we compute the address by adding a positive offset to a non-zero address, we know the result must not be zero.

pub fn to_address<VM: VMBinding>(self) -> Address

Get the in-heap address from an object reference. This method is used by MMTk to get an in-heap address for an object reference. This method is syntactic sugar for crate::vm::ObjectModel::ref_to_address. See the comments on crate::vm::ObjectModel::ref_to_address.

pub fn to_header<VM: VMBinding>(self) -> Address

Get the header base address from an object reference. This method is used by MMTk to get a base address for the object header, and access the object header. This method is syntactic sugar for crate::vm::ObjectModel::ref_to_header. See the comments on crate::vm::ObjectModel::ref_to_header.

pub fn to_object_start<VM: VMBinding>(self) -> Address

Get the start of the allocation address for the object. This method is used by MMTk to get the start of the allocation address originally returned from crate::memory_manager::alloc for the object. This method is syntactic sugar for crate::vm::ObjectModel::ref_to_object_start. See comments on crate::vm::ObjectModel::ref_to_object_start.

pub fn from_address<VM: VMBinding>(addr: Address) -> ObjectReference

Get the object reference from an address that is returned from crate::util::address::ObjectReference::to_address or crate::vm::ObjectModel::ref_to_address. This method is syntactic sugar for crate::vm::ObjectModel::address_to_ref. See the comments on crate::vm::ObjectModel::address_to_ref.

pub fn is_reachable<VM: VMBinding>(self) -> bool

Is the object reachable, determined by the policy? Note: Objects in ImmortalSpace may have is_live = true but are actually unreachable.

pub fn is_live<VM: VMBinding>(self) -> bool

Is the object live, determined by the policy?

pub fn is_movable<VM: VMBinding>(self) -> bool

Can the object be moved?

pub fn get_forwarded_object<VM: VMBinding>(self) -> Option<Self>

Get forwarding pointer if the object is forwarded.

pub fn is_in_any_space<VM: VMBinding>(self) -> bool

Is the object in any MMTk spaces?

pub fn is_sane<VM: VMBinding>(self) -> bool

Is the object sane?

Trait Implementations

impl Clone for ObjectReference

fn clone(&self) -> ObjectReference

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ObjectReference

allows Debug format the Address (as upper-case hex value with 0x prefix)

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

Formats the value using the given formatter.

impl Display for ObjectReference

allows Display format the Address (as upper-case hex value with 0x prefix)

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

Formats the value using the given formatter.

impl Finalizable for ObjectReference

This provides an implementation of Finalizable for ObjectReference. Most bindings should be able to use ObjectReference as ReferenceGlue::FinalizableType.

fn get_reference(&self) -> ObjectReference

Load the object reference.

fn set_reference(&mut self, object: ObjectReference)

Store the object reference.

fn keep_alive<E: ProcessEdgesWork>(&mut self, trace: &mut E)

Keep the heap references in the finalizable object alive. For example, the reference itself needs to be traced. However, if the finalizable object includes other heap references, the implementation should trace them as well. Note that trace_object() may move objects so we need to write the new reference in case that it is moved.

impl Hash for ObjectReference

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 LowerHex for ObjectReference

allows print Address as lower-case hex value

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

Formats the value using the given formatter.

impl Ord for ObjectReference

fn cmp(&self, other: &ObjectReference) -> 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 + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for ObjectReference

fn eq(&self, other: &ObjectReference) -> 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 PartialOrd for ObjectReference

fn partial_cmp(&self, other: &ObjectReference) -> 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 UpperHex for ObjectReference

allows print Address as upper-case hex value

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

Formats the value using the given formatter.

impl Copy for ObjectReference

impl Eq for ObjectReference

impl NoUninit for ObjectReference

impl StructuralPartialEq for ObjectReference