PtcRunner.Sandbox (PtcRunner v0.9.0)

Copy Markdown View Source

Executes programs in isolated BEAM processes with resource limits.

Spawns isolated processes with configurable timeout and memory limits, ensuring safe program execution.

Resource Limits

ResourceDefaultOption
Timeout1,000 ms:timeout
Max Heap~10 MB (1,250,000 words):max_heap

Configuration

Limits can be set per-call:

PtcRunner.Lisp.run(program, timeout: 5000, max_heap: 5_000_000)

Or as application-level defaults in config.exs:

config :ptc_runner,
  default_timeout: 2000,
  default_max_heap: 2_500_000

Summary

Types

eval_fn()

Evaluator function that takes AST and context and returns result with memory.

metrics()

Execution metrics for a program run.

Functions

execute(ast, context, opts \\ [])

Executes an AST in an isolated sandbox process.

Types

eval_fn()

@type eval_fn() :: (any(), PtcRunner.Context.t() ->
                {:ok, any(), map()}
                | {:error, {atom(), String.t()} | {atom(), String.t(), any()}})

Evaluator function that takes AST and context and returns result with memory.

metrics()

@type metrics() :: %{duration_ms: integer(), memory_bytes: integer()}

Execution metrics for a program run.

Functions

execute(ast, context, opts \\ [])

@spec execute(any(), PtcRunner.Context.t(), keyword()) ::
  {:ok, any(), metrics(), map()}
  | {:error,
     {atom(), non_neg_integer()}
     | {atom(), String.t()}
     | {atom(), String.t(), any()}}

Executes an AST in an isolated sandbox process.

Arguments

  • ast: The AST to execute
  • context: The execution context
  • opts: Options (timeout, max_heap, eval_fn)
    • :eval_fn - Evaluator function (required)
    • :timeout - Timeout in milliseconds (default: 1000, configurable via :default_timeout)
    • :max_heap - Max heap size in words (default: 1_250_000, configurable via :default_max_heap)

Returns

  • {:ok, result, metrics, memory} on success
  • {:error, reason} on failure