Struct GcStatusWord 

pub(crate) struct GcStatusWord(AtomicUsize);

A lock-free, atomic encoding of GcStatus. This packs the variant tag into the low bits of a usize and, for GcStatus::Disabled, the nesting depth into the remaining high bits, so the whole status fits in a single machine word and can be updated with atomic operations instead of behind a Mutex<GcStatus>.

GcStatus is a state machine: only a handful of transitions between its variants are legal. Every legal transition is exposed here as its own method, each performing its own compare-and-swap retry loop and asserting that the transition is legal for the status it finds. Do not add a generic “set the status to X” method: doing so would make it possible to bypass the state machine’s invariants.

Tuple Fields

0: AtomicUsize

Implementations

impl GcStatusWord

const TAG_BITS: u32 = 3u32

Number of bits used to encode the variant tag. 3 bits is enough to distinguish the 6 variants, leaving the rest of the word for Disabled’s nesting depth.

const TAG_MASK: usize = 7usize

fn encode(status: GcStatus) -> usize

fn decode(bits: usize) -> GcStatus

pub(crate) fn new(status: GcStatus) -> Self

pub(crate) fn load(&self) -> GcStatus

Read the current status.

fn transition_inner<F: FnMut(GcStatus) -> GcStatus>(&self, f: F) -> GcStatus

Inner implementation of Self::transition, handling encoding, decoding, and atomic RMW operation.

fn transition<F: FnMut(GcStatus) -> GcStatus>(&self, f: F) -> GcStatus

Attempt to atomically transition the GC status using function f. Return the status atomically transitioned from (not the new status). It will retry f if the status is modified concurrently.

Note: Returning the old status (rather than the new one) lets a caller tell whether it “won” the race when multiple threads concurrently drive the same transition: only the thread whose CAS actually moved the status away from a given old value can be sure it is the one responsible for that transition, so it is the one that should perform any side effect that must happen exactly once (e.g. notifying the scheduler). If transition returned the new status instead, every racing thread would observe the same new status and none could tell which of them caused it. f may be invoked more than once under contention.

fn try_transition_inner<F: FnMut(GcStatus) -> Option<GcStatus>>( &self, f: F, ) -> Result<GcStatus, GcStatus>

Inner implementation of Self::try_transition, handling encoding, decoding, and atomic RMW operation.

fn try_transition<F: FnMut(GcStatus) -> Option<GcStatus>>( &self, f: F, ) -> Result<GcStatus, GcStatus>

Attempt to atomically transition the GC status using function f. Return Ok(old_status) if f returns Some(new_status), in which case it has atomically transitioned the state from old_state to new_state. Return Err(old_status) if f returns None, in which case old_status is the status passed to the last invocation of f. It will retry f if f returns Some but the underlying status is modified concurrently.

pub(crate) fn is_initialized(&self) -> bool

pub(crate) fn is_disabled(&self) -> bool

pub(crate) fn set_initialized(&self)

Uninitialized -> NotInGC.

pub(crate) fn set_uninitialized(&self)

Any status other than Uninitialized -> Uninitialized.

pub(crate) fn set_in_pause(&self)

PauseRequested -> InPause.

pub(crate) fn set_in_concurrent_gc(&self)

InPause -> InConcurrentGC, e.g. once a GC pause has finished but concurrent work (such as concurrent marking) was scheduled to continue after mutators resume.

pub(crate) fn set_not_in_gc(&self)

InPause -> NotInGC, e.g. once a GC pause has finished and no concurrent work remains.

pub(crate) fn set_disabled(&self) -> Result<bool, GcStatus>

NotInGC/Disabled(depth) -> Disabled(depth + 1). Leaves the status unchanged if collection cannot be disabled from the current status (e.g. a GC is in progress or has been requested), and returns Err with the status that blocked the transition.

On success, returns Ok(true) if this call actually switched collection from enabled to disabled (i.e. it was the outermost NotInGC -> Disabled(1) transition), Ok(false) if it only increased the nesting depth of an already-disabled status. Mirrors the meaning of GcStatusWord::set_enabled’s return value.

pub(crate) fn set_enabled(&self) -> bool

Disabled(depth) -> Disabled(depth - 1), or Disabled(1) -> NotInGC. If collection is not currently disabled, this is a no-op (the status is left unchanged). Returns true if this call actually re-enabled collection (i.e. it was the outermost Disabled(1) -> NotInGC transition), false if it only decremented the nesting depth, or if collection was already enabled.

pub(crate) fn try_request_pause(&self) -> Result<(), GcStatus>

NotInGC/InConcurrentGC -> PauseRequested, unless collection is disabled, MMTk is not yet initialized, or a pause has already been requested, in which case Err is returned with the status that prevented the transition (Disabled(_), Uninitialized, or PauseRequested respectively).