Struct FrameLifecycle 

pub struct FrameLifecycle { /* private fields */ }

Owns the state a commit reconciles: the release ring, the armed-flip tripwire, and whether the scene is suspended.

Implementations

impl FrameLifecycle

pub const fn new() -> Self

A fresh lifecycle with nothing in flight.

pub const fn is_suspended(&self) -> bool

Whether the scene is suspended and short-circuiting commits.

pub const fn has_pending_flip(&self) -> bool

Whether a page-flip event is armed and undispatched.

Invariant 5. Dropping the scene while this is true tears down a framebuffer the flip still references.

pub fn buffers_in_flight(&self) -> usize

How many buffers are held in flight.

pub const fn flip_landed(&mut self)

Record that the armed page-flip event was dispatched.

pub const fn resume(&mut self)

Lift a suspension after the session resumes.

pub fn finalize( &mut self, kind: CommitKind, result: KernelResult, acquisitions: Vec<Acquisition>, report: CommitReport, release_fence: Option<&SyncFence>, wants_fence: impl FnMut(LayerId) -> bool, ) -> FrameOutcome

Reconcile scene state with the kernel’s answer.

The rules, and why each is where it is

• Success on a real commit rotates the release ring and returns the buffers two commits deep — invariant 1.
• Any failure returns this frame’s buffers at once, because no flip is in flight to gate them on — invariant 2.
• Only NotMaster suspends. A non-EACCES rejection drops the frame and heals on the next one; suspending on it would take a recoverable stumble and stop the scene. The C++ states this as an external contract, and self-healing producer rings depend on it.
• A rejected fast-path frame invalidates the cached allocation. Invariant 4’s safety net: the kernel refused a frame whose TEST_ONLY was skipped, so the cache is no longer trustworthy. The frame is dropped but heals — the failure mode is never corruption. A recurring rejection here means a property was misclassified as content, which is why it is worth warning about once.
• A test commit returns its buffers at once and changes nothing else: it applied nothing to hardware.

pub const fn has_warned_fast_path_reject(&self) -> bool

Whether a fast-path rejection has been warned about yet. Set by finalize, which logs the first one and no other.

pub fn release_displaced(&mut self, commit_seq: u64) -> Released

The buffers the flip of real commit commit_seq took off screen, for handing back at that flip rather than at the next commit.

Nothing unless commit_seq names the most recent real commit: after an older one, a newer commit has rotated buffers still on screen into the generation this would release. So a late or repeated call cannot release a buffer still on screen. Port of upstream’s release_displaced (ee90026).

pub fn drain(&mut self) -> Released

Hand back every held buffer, for teardown, pause, or rebind.

Invariant 5. Does not wait on the kernel. Landing an armed flip first is the caller’s job — has_pending_flip says whether one is outstanding.

Trait Implementations

impl Debug for FrameLifecycle

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

Formats the value using the given formatter.

impl Default for FrameLifecycle

fn default() -> Self

Returns the “default value” for a type.