Skip to contents

Timeout and resource-aware external-process supervision

external_process_supervision.Rd

Create deterministic supervision policies and run validated external commands with resource admission, cooperative cancellation boundaries, timeout enforcement, independent output capture, process-tree cleanup, and provenance metadata.

Usage

new_external_process_supervision_policy(
  timeout_seconds = Inf,
  resource_policy = new_execution_resource_policy(),
  label = "default-process-supervision"
)

# S3 method for class 'PopgenVCFExternalProcessSupervisionPolicy'
print(x, ...)

run_supervised_external_command(
  command,
  requirements = new_module_resource_requirements(),
  supervision_policy = new_external_process_supervision_policy(),
  cancellation_token = NULL
)

Arguments

timeout_seconds

Positive maximum elapsed process time in seconds, or Inf.

resource_policy

A PopgenVCFExecutionResourcePolicy.

label

Stable supervision-policy label.

x

A supervision policy.

...

Unused.

command

A validated PopgenVCFExternalCommand.

requirements

Declared process resource requirements.

supervision_policy

An external-process supervision policy.

cancellation_token

Optional execution cancellation token.

Value

new_external_process_supervision_policy() returns a validated policy. run_supervised_external_command() returns a PopgenVCFExternalProcessResult with supervision metadata.

Details

Resource admission and pre-launch cancellation are evaluated before executable resolution and process launch. Execution uses the processx backend with process-tree cleanup enabled. Commands that exceed the elapsed-time limit are terminated together with their descendants and receive the distinct timed_out state and normalized exit status 124.

Cancellation is checked again after process completion. Active asynchronous mid-process cancellation is intentionally deferred to a later supervision layer. The normalized states remain resource_unavailable, cancelled, launch_failed, timed_out, nonzero_exit, and success.

Supervision provenance records the backend, resource admission, timeout policy, cancellation state, termination reason, and whether process-tree cleanup was completed or not required. Timed-out and otherwise unsuccessful commands remain fail-closed and cannot represent accepted scientific output.