When a frame comes home — Parallax Sketchbook

SKETCHBOOK / 05 Copper Orchard · 2-week chapter

Page 1 of 4: Commit is a departure

Completion is the return ticket

Commit is a departure

Committing a command buffer schedules work; it does not mean the GPU has consumed your uniforms or finished writing an output. Keep the slot’s CPU-writable ranges unchanged until the corresponding work completes. Metal’s normal retained-resource command-buffer behavior can keep referenced resource objects alive, but that is not permission to overwrite their contents or reset an application allocator. Your application still owns the access schedule.

Use addCompletedHandler to observe completion without blocking every frame. Register the handler before committing. The callback should inspect status/errors and publish a small completion record to a synchronized queue or safe shared state. Do not assume it runs on your UI thread, and do not mutate Cocoa views from it. The main/render thread can consume the record and return the slot to the available pool.

Begin with a bounded number of submissions. If all slots are busy, apply backpressure. This keeps latency and memory growth understandable. A completion record should identify the slot and generation or submission token so the receiver can reject stale notifications rather than treating an index as timeless permission.

LOOK CLOSER

available -> CPU fills slot N -> encode references to slot N
          -> register completion -> commit -> GPU reads slot N
          -> callback publishes (N, generation, status)
          -> owner consumes record -> slot N becomes available

Lifecycle model, not callable code. Completion publication needs a thread-safe implementation and a lifetime that outlasts callbacks.

From the page to your own work

Your studio assignment.

Submit bounded overlapping frames and close the window without stale callbacks or premature range reuse.

A finish line you can see

A slot state diagram, completion trace, and shutdown walkthrough.

Register handlers before commit and check completion status.
Keep callback-owned state valid until every callback finishes.
Return slots through synchronized publication with stable tokens.
Avoid holding a callback-needed lock across completion waits.

Keep the evidence in your weekly notebook ↗

Explain it like an engineer

Try answering aloud before opening the review notes. Use your own implementation as evidence.

Why can a completion handler introduce a use-after-free even when Metal retains its GPU resources?

The handler may capture a separate C++ object whose lifetime Metal does not manage.
Window teardown can destroy that object before callback execution.
Retain suitable small state, synchronize access, and drain pending work before teardown.

These prompts support practice; they are not an automatic assessment of your work.

A tip for this exercise

Treat shutdown as part of the frame protocol from the beginning. Sketch the smallest callback state you need, then give that state an owner whose lifetime covers every pending completion.

Hints, when you need them.

Try a first step, then reveal as much help as you need. Each hint gets a little more specific.

1Hint 1 · Find a starting point

Draw available, submitted, and completed states for one slot. Which captured values must remain alive when the window begins closing?

2Hint 2 · Choose an approach

Register completion handling before commit, use stable slot tokens, and synchronize publication back to the CPU. Keep callback-needed locks out of any blocking completion wait.

3Hint 3 · Check your reasoning

Log bounded overlapping submissions and their completion status, then close the window. Confirm no slot returns early and callback-owned state survives until the final callback finishes.

A small creative variation ↗

Add a visible pending-frame counter whose updates are marshaled to the UI thread.

Optional. Save it for later if this chapter already feels full.

Coming back after a break? ↩

Draw one submitted slot and one completion callback. Name the owner of every captured value.

Books & principles behind this study +

Original Parallax explanations and assignments, with these works for further reading.

YOUR MARGIN NOTES

Leave yourself a good question.

What changed your mind? What would you try next?

Notes for When a frame comes home

Notes are private to this browser and saved as you write.

A CHECKPOINT, NOT A SCORE

Can you explain the idea and try the exercise yourself?

Completion records your own assessment. It does not compile or test your C++.

Companion source 6 files