Module mmtk::util::metadata::vo_bit

Valid object bit (VO bit)

The valid object bit, or “VO bit” for short“, is a global per-address metadata. It is set at the address of the ObjectReference of an object when the object is allocated, and cleared when the object is determined to be dead by the GC.

The VO bit metadata serves multiple purposes, including but not limited to:

purpose	happens when
conservative stack scanning	stack scanning
conservative object scanning	tracing
supporting interior pointers	tracing
heap dumping (by tracing)	tracing
heap dumping (by iteration)	before or after tracing
heap iteration (for GC algorithm)	depending on algorithm
heap iteration (for VM API, e.g. JVM-TI)	during mutator time
sanity checking	any time in GC

Among the listed purposes, conservative stack scanning and conservative objects scanning are visible to the VM binding. By default, if the “vo_bit” cargo feature is enabled, the VO bits metadata will be available to the VM binding during stack scanning time. The VM binding can further require the VO bits to be available during tracing (for object scanning) by setting crate::vm::ObjectModel::NEED_VO_BITS_DURING_TRACING to true. mmtk-core does not guarantee the VO bits are available to the VM binding during other time.

Internally, mmtk-core will also make the VO bits available when necessary if mmtk-core needs to implement features that needs VO bits.

When the VO bits are available during tracing, if a plan uses evacuation to reclaim space, then both the from-space copy and the to-space copy of an object will have the VO-bit set.

(Note: There are several reasons behind this semantics. One reason is that a slot may be visited multiple times during GC. If a slot is visited twice, we will see the object reference in the slot pointing to the from-space copy during the first visit, but pointing to the to-space copy during the second visit. We consider an object reference valid if it points to either the from-space or the to-space copy. If each slot is visited only once, and we see a slot happen to hold a pointer into the to-space during its only visit, that must be a dangling pointer, and error should be reported. However, it is hard to guarantee each slot is only visited once during tracing because both the VM and the GC algorithm may break this guarantee. See: crate::plan::PlanConstraints::may_trace_duplicate_edges)

Modules

• helper 🔒
  This module updates of VO bits during GC. It is used for spaces that do not clear the metadata of some dead objects during GC. Currently, only ImmixSpace is affected.

Constants

• VO_BIT_SIDE_METADATA_ADDR
  The base address for VO bit side metadata on 64 bits platforms.
• VO_BIT_SIDE_METADATA_SPEC
  A VO bit is required per min-object-size aligned address, rather than per object, and can only exist as side metadata. This is only publicly available when the feature “vo_bit_access” is enabled. Check the comments on “vo_bit_access” in Cargo.toml before use. Use at your own risk.
• VO_BIT_WORD_TO_REGION 🔒
  How many data memory bytes does 1 word in the VO bit side metadata represents?

Functions

• bcopy_vo_bit_from_mark_bit 🔒
  Bulk copy VO bits from side mark bits. Some VMs require the VO bits to be available during tracing. However, some GC algorithms (such as Immix) cannot clear VO bits for dead objects only. As an alternative, this function copies the mark bits metadata to VO bits. The caller needs to ensure the mark bits are set exactly wherever VO bits need to be set before calling this function.
• bzero_vo_bit 🔒
  Bulk zero the VO bit.
• find_object_from_internal_pointer 🔒
  Find the base reference to the object from a potential internal pointer.
• get_object_ref_for_vo_addr 🔒
  Get the object reference from an aligned address where VO bit is set.
• get_raw_vo_bit_word 🔒
  Bulk check if a VO bit word. Return true if there is any bit set in the word.
• is_internal_ptr 🔒
  Check if the address could be an internal pointer in the object.
• is_internal_ptr_from_vo_bit 🔒
  Check if the address could be an internal pointer based on where VO bit is set.
• is_vo_addr 🔒 ^⚠
  Non-atomically check if the VO bit is set for this address.
• is_vo_bit_set 🔒
  Check if the VO bit is set for an object.
• is_vo_bit_set_for_addr 🔒
  Check if an address can be turned directly into an object reference using the VO bit. If so, return Some(object). Otherwise return None.
• is_vo_bit_set_inner 🔒
• is_vo_bit_set_unsafe 🔒 ^⚠
  Check if an address can be turned directly into an object reference using the VO bit. If so, return Some(object). Otherwise return None. The caller needs to ensure the side metadata for the VO bit for the object is accessed by only one thread.
• set_vo_bit 🔒
  Atomically set the VO bit for an object.
• unset_vo_bit 🔒
  Atomically unset the VO bit for an object.
• unset_vo_bit_nocheck 🔒
  Atomically unset the VO bit for an object, regardless whether the bit is set or not.
• unset_vo_bit_unsafe 🔒 ^⚠
  Non-atomically unset the VO bit for an object. The caller needs to ensure the side metadata for the VO bit for the object is accessed by only one thread.