PtcRunner.Kernel.BoundedCapture (PtcRunner v0.15.0)

Copy Markdown View Source

One-shot owner-scoped capture under a heap limit and an absolute deadline.

A snapshot owner reads a source once, at start, and must not grow its own heap doing so. The work therefore runs in a separate monitored process with :max_heap_size set to kill, and the calling owner waits on three things at once: the reply, the worker's death, and the death of the process the capture belongs to.

The outcome is reported in one vocabulary — :owner_down, :heap_exceeded, :worker_failed, :deadline_exceeded — and each caller maps it onto the codes its own source contract publishes. A capture's own return value is handed back wrapped in {:ok, …}, so a capture that answers {:error, …} is never confused with a failure of the capture machinery itself.

Whatever ends the wait, the worker does not outlive it: a deadline or a dead owner kills the worker and reaps its :DOWN before returning, so no capture keeps reading a source nobody is waiting for.

Summary

Functions

Runs capture for :owner, returning {:ok, capture_result} or a failure.

Types

failure()

@type failure() :: :owner_down | :heap_exceeded | :worker_failed | :deadline_exceeded

Functions

for_owner(capture, opts)

@spec for_owner(
  (-> term()),
  keyword()
) :: {:ok, term()} | {:error, failure()}

Runs capture for :owner, returning {:ok, capture_result} or a failure.

:owner_ref must be a monitor the caller already holds on :owner, so the owner's death is observed rather than polled. :deadline_ms is an absolute System.monotonic_time(:millisecond) value, not a duration, so a deadline already spent yields no work rather than a fresh budget.