API Reference

Complete reference for every public type in Flytachi\Winter\Thread. Signatures match the source exactly; each entry lists parameters, return values, exceptions, and the non-obvious semantics.

API at a glance

The surface splits into two tiers. Most applications only touch the Public API — three types. The low-level API is for building your own pool, scheduler, or supervisor directly on the raw primitives.

Public API — what you use

Low-level & extension API — what you build on

The four interfaces (Engine, Launcher, Runner, PayloadTransport) are the extension points that accept your own implementation; everything else is a concrete type you consume.

Public API

Runnable (interface)

Flytachi\Winter\Thread\Runnable — the task contract.

public function run(array $args): void

Put your logic in run(); it executes in the worker process.

Returns nothing. Signal the outcome via the exit code (return/normal completion → 0; throwing → non-zero) or side effects (file/DB/queue).

Contract: the implementing object must be serializable — no live resources (PDO, sockets, streams) in its properties; open them inside run(). An uncaught exception is caught by the runner, logged to STDERR with a trace, and turned into a non-zero exit.

Thread (final class)

Flytachi\Winter\Thread\Thread — the high-level facade over one process. Mutable; guards against concurrent starts.

__construct

new Thread(
  Runnable $runnable,
  string   $namespace = '',
  ?string  $name = null,
  ?string  $tag = null,
)

Constructing does not start anything. The process title is WinterThread <namespace> -> <name>@<tag> (only where cli_set_process_title() exists).

Static — engine binding

start

start(
  array   $arguments = [],
  bool    $debugMode = false,
  ?string $outputTarget = '/dev/null',
  bool    $detached = false,
): int

Serializes the task, launches the process, and returns immediately.

Returns int — the launched PID (in detached mode, the launcher’s ephemeral PID). Throws ThreadException if the thread is already alive, or the process fails to start.

Lifecycle & waiting

State

Signals (require ext-posix; each returns false if not running)

Each returns bool — true if the signal was sent. To react gracefully, the task must install a handler; see Graceful Shutdown.

Output (non-empty only when started with outputTarget: null)

Metadata

Engine (interface)

Flytachi\Winter\Thread\Engine\Engine — the configuration/strategy root, used parent-side only. It has no child-side method: the worker runs a separate AdaptiveRunner. The parent’s security() is propagated to the child via the WINTER_THREAD_SECRET env var.

AdaptiveEngine (final readonly class, default)

Flytachi\Winter\Thread\Engine\AdaptiveEngine — self-configuring; immutable.

new AdaptiveEngine(
  ?string           $secret = null,
  ?PayloadTransport $transport = null,
  ?string           $binaryPath = null,
  ?string           $runnerPath = null,
  ?Launcher         $launcher = null,
)

Immutable — to change one aspect, construct a new instance.

ManualEngine (final class)

Flytachi\Winter\Thread\Engine\ManualEngine — explicit, clean-slate. Immutable withers (each returns a clone); an unset required part throws ThreadException when accessed ("ManualEngine: <part> is not configured.").

With a custom withLauncher(...), transport/binaryPath/runnerPath are not required — the launcher owns the wiring. Otherwise all three are required. security() returns null when no secret was set.

Low-level & extension API

For pools, schedulers, and custom backends. Thread is built on exactly these pieces — you can drive them directly.

Launcher (interface)

Flytachi\Winter\Thread\Launch\Launcher — parent-side spawn strategy.

public function launch(LaunchSpec $spec): ProcessHandle

Returns ProcessHandle. Throws ThreadException on failure. Implement this to launch over SSH, in a container, or on a remote node.

CliLauncher (final readonly class)

Flytachi\Winter\Thread\Launch\CliLauncher — the default, proc_open-based.

new CliLauncher(
  string           $binaryPath,
  string           $runnerPath,
  PayloadTransport $transport,
  array            $childEnv = [],
)

Builds a fully escapeshellarg-escaped command. Empty $childEnv → the child inherits the parent env; non-empty → merged over the inherited env.

ProcessHandle (final class)

Flytachi\Winter\Thread\Launch\ProcessHandle — the low-level process primitive a launcher returns. Mutable; tracks process/pipes/exit-code state. Not constructed directly — obtained from Launcher::launch().

reap(), detach(), and __destruct() are non-blocking on a live process; the blocking proc_close runs only on an already-dead process. __destruct() reaps a finished process, or detaches a still-running one — it never blocks the parent.

LaunchSpec (final readonly class)

Flytachi\Winter\Thread\LaunchSpec — an immutable bundle of every launch parameter. Build one directly to drive a launcher without a Thread.

new LaunchSpec(
  string  $payload,
  string  $namespace = '',
  string  $name = 'anonymous',
  ?string $tag = null,
  array   $arguments = [],
  bool    $debug = false,
  ?string $output = '/dev/null',
  bool    $detached = false,
)

All properties are public and readonly.

PayloadTransport (interface)

Flytachi\Winter\Thread\Payload\PayloadTransport — delivers the serialized payload across the process boundary in two halves plus a cleanup.

$options in receive() is array<string, mixed> — the parsed child CLI options.

PipeTransport

…\Payload\PipeTransport — payload via the child’s stdin pipe (written after launch). No extension. Not Swoole-safe (uses a pipe fd). The default in plain CLI.

TempFileTransport

…\Payload\TempFileTransport — payload via a 0600 temp file placed on stdin, unlinked right after launch (child keeps its fd). No extension. Swoole-safe. Throws ThreadException if the temp file can’t be created/written.

ShmTransport

…\Payload\ShmTransport — payload via a 0600 System V shared-memory segment; the integer key is passed as --shmkey, and the child reads then deletes it. No disk, Swoole-safe. Requires ext-shmop — throws ThreadException ("ShmTransport requires ext-shmop.") on both stage() and receive() if missing, and on allocation failure.

StagedPayload (final readonly class)

Flytachi\Winter\Thread\Payload\StagedPayload — the result of stage(); the launcher reads it generically.

new StagedPayload(
  array   $stdinSpec,
  array   $cliArgs = [],
  ?string $pipePayload = null,
  ?string $unlinkAfterOpen = null,
  mixed   $ref = null,
)

Runner (interface)

Flytachi\Winter\Thread\Runner\Runner — child-side execution strategy.

public function execute(array $options): int

Returns int — the process exit code (0 success, non-zero failure).

AdaptiveRunner (final readonly class)

Flytachi\Winter\Thread\Runner\AdaptiveRunner — the default child-side runner (driven by wRunner). It depends only on a security provider — not on the Engine — so the two sides stay independent.

new AdaptiveRunner(
  ?DefaultSecurityProvider $security = null,
  mixed                    $errStream = null,
)

execute() flow: receive payload (--shmkey → shm, else STDIN) → verify + deserialize via opis/closure (rejecting empty, non-Runnable, or unsigned/tampered payloads with a non-zero exit) → optional fork+setsid (detached) → set process title → run() → exit code.

Signal (final class)

Flytachi\Winter\Thread\Signal — static POSIX helpers on a raw PID. isProcessRunning() treats zombies (state Z) as not running, on both Linux (/proc/<pid>/status) and macOS (ps).

ThreadException (class)

Flytachi\Winter\Thread\ThreadException extends \RuntimeException — the library’s only exception type.

Thrown on: launch failure (proc_open denied, or the process died immediately), starting an already-running Thread, misconfiguration (an unset ManualEngine part, or ShmTransport without ext-shmop), and transport staging failures (temp file / shm allocation). Catch it around start() and engine setup.