Study guides · Advanced

Confirm completion and reclaim resources: follow used IDs and ownership

Separate publication, notification, used-ring completion, and reclamation so that out-of-order requests release only their own buffers.

Ask Logeia about this articleTry the three questionsReview your answers

Updated

On this page
  1. Goal: distinguish handing work over from reclaiming it
  2. Establish preparation and visibility before publication
  3. Notification is not completion
  4. Map each used ID back to its request
  5. Observe completion before consuming its outputs
  6. An error completion differs from an unfinished request
  7. Exercise: repair early reuse and reclaim out of order
  8. Ask Logeia about this articleCheck your understanding

Goal: distinguish handing work over from reclaiming it

A correct descriptor chain can still be unsafe if the driver overwrites its buffer immediately after notification while the device may still use it. The goal is to separate preparation, publication, notification, device processing, completion recording, and reclamation, then identify which request's resources have returned. Build on block-request structure and split-queue basics. The model fixes a sixteen-sector RAM disk, at most four requests, and sixteen descriptors, with examples that deliberately change completion order.

Ownership here is a contract about who may modify contents, not a claim that memory physically moves. The buffer can remain at the same address while the publishing driver loses permission to reuse it. Record the boundary where confirmed completion permits reclamation. Check matching data, status, and used identity, and also preserve pending-request storage and the other VM's memory. Correct-looking final bytes alone are insufficient if an intermediate reuse violated the lifetime contract or another owner's state was corrupted.

Establish preparation and visibility before publication

The driver prepares header, data and status storage plus descriptors, places the head ID in the available ring, and publishes through the availability index. When the device observes publication, the contents it will reference must already be ready and visible in the required order. The model represents that relation explicitly. It does not claim that one named CPU barrier suffices for every platform. A concrete implementation must also consider the selected transport and DMA-coherency requirements.

A counterexample publishes the head before fixing the header's sector. If the device observes the old sector, repairing the guest variable later does not retroactively change the processed read. Validate structure, including direction, range, and length, separately from publication order. Do not accept an invalid operation sequence merely because the final object looks well formed. Inspecting intermediate states is useful precisely because some lifetime and ordering violations are invisible in the final snapshot, even when a fortunate execution happens to return expected bytes.

Notification is not completion

A notification after publication tells the device that work is available. It does not permit the driver to mark status successful or overwrite data immediately. The device may later read the request, process it, write outputs such as status, and publish completion in the used ring. Keep notification, beginning processing, and finishing processing as distinct logical events. Fast execution of a teaching model is not a reason to merge boundaries that determine safe buffer lifetime.

With notification suppression, there need not be one notification for every request. A masked completion interrupt can also coexist with an already populated used ring. The demonstration exposes both notification state and recorded completion, including inspection by polling. This does not imply that notifications are useless; it establishes that notification is not where completed request contents are stored. Reuse decisions depend on confirmed per-request completion, not on counting notifications or assuming that a quiet interrupt line means the device has done no work.

ObservationEstablished factNot justified
Available publicationDevice may use the requestImmediate buffer reuse
NotificationWork availability was signaledMark every request successful
Observe used IDThat head has completedReclaim other heads
Check status and reclaimResult and resources recoveredClaim durable persistence

Map each used ID back to its request

A split-queue used element identifies the completed chain by its head ID. This lesson does not assume that completion order matches publication order. If heads zero and three were submitted and three finishes first, reclaim three's buffers. Pairing completions with the oldest available request can free zero's still-pending storage. Keep ring slot position, descriptor head, and application request identity as separate concepts even when small examples happen to give them similar numbers.

The example uses a map to recover the owner of head three before head zero. Reordering completion must preserve request-name and data correspondence. Reject unknown used IDs, duplicate reclamation, and completions for heads not yet published. Returned lengths can assist validation, but the per-request status still matters. Resources from a legitimately completed error request can eventually be reclaimed without presenting its data as a successful application result. Reclaiming ownership and reporting successful I/O are related operations with different acceptance conditions.

javascript
const pending = new Map([[0,{name:'A',data:'alpha'}],[3,{name:'B',data:'beta'}]]);
const used = [{id:3,status:0},{id:0,status:0}];
const reclaimed = [];
for (const item of used) {
  const request = pending.get(item.id);
  if (!request) throw Error('unknown or duplicate used id');
  reclaimed.push(`${item.id}:${request.name}:${item.status}`);
  pending.delete(item.id);
}
console.log(reclaimed.join(','));
console.log('pending', pending.size);

Observe completion before consuming its outputs

The device must prepare status and data before publishing the corresponding used completion, and the driver must consume those outputs under the required ordering after observing it. The model exposes that relation as a separate boundary without simulating every effect of a real memory barrier. First resolve used identity to a request, then validate the corresponding status and, for READ, the expected contents in that request's buffer. Do not infer output readiness merely from an unrelated request changing state.

If only one of two requests finishes, an increased used count does not authorize reclamation of both. Retain every pending request's descriptor and buffer lifetime. When reassigning a reclaimed head, maintain the consumption position so that an old completion cannot be replayed against the new request. This bounded model does not cover the complete wraparound behavior of a sixteen-bit ring index. It still tests duplicate consumption on small examples, because that defect does not require a huge queue or a long-running workload to become observable.

An error completion differs from an unfinished request

An I/O-error status is not successful processing, but a valid completion can still permit reclamation when the device no longer owns the buffers under the interface contract. That differs from inventing an error result for a request absent from the used ring and freeing it anyway. A driver-side timeout also does not prove the device stopped referencing memory. Cancellation or reset needs an additional agreement about stopping access and recovering resources; it cannot be inferred merely because the caller stopped waiting.

A completed WRITE to the teaching RAM disk does not establish survival after power loss. Persistence requires further device features and conditions, such as appropriate flushing, beyond this model. Do not merge completion, success, and durability into one saved indicator. The demonstration instead shows which head returned, its status, and the buffers reclaimed. Giving results a precise scope prepares for a real storage implementation while avoiding a claim that a bounded in-memory exercise already provides durable disk semantics.

Exercise: repair early reuse and reclaim out of order

The repair task reuses a READ output buffer immediately after notification. Preserve its lifetime until the corresponding head appears in used and its outputs and status can be checked. Then reverse completion order, reclaiming the second request while the first remains pending. A valid repair maintains calculated ownership and head correspondence rather than replacing a notification message. Include unchanged pending-buffer contents in the acceptance conditions, because correct output from one request does not excuse corrupting another.

The integrated exercise connects this completion to a virtual interrupt. Masking IRQ acceptance can block the guest handler while a used completion still exists, and those observations must remain separate. After unmasking, only the intended VM reclaims the request, leaving other-VM and pending-request data unchanged. Finally test an error status and distinguish reclamation from successful data delivery. Following the same identity and owner from construction through completion ties together the queue, memory lifetime, status, and interrupt lessons into one inspectable path.

Try the interactive model

Virtio block requests and completion

Loading demo checkpoint…

Reading and practice are recorded separately in this browser, for each language.

Choose a learning path