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 (Launcher, ProcessHandle, 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 — launcher 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

Binding a launcher

Launch configuration lives in a Launcher — documented below, under the low-level API, because it is also the extension point. Bind it once at bootstrap:

Thread::bindLauncher(CliLauncher::adaptive(secret: '…'));

Thread::launcher();   // the current launcher; an AdaptiveLauncher when none is bound

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 — how a process is spawned. It lives parent-side only: it is never shipped to the child, where a separate AdaptiveRunner runs, and the secret travels through the WINTER_THREAD_SECRET env var.

interface Launcher
{
  public function launch(LaunchSpec $spec): ProcessHandle;
  public function security(): ?DefaultSecurityProvider;
}

Two methods is the entire surface: transport, binary path and runner path are not part of it — they are a concrete backend’s own business. So your own way of launching (SSH, a container, a remote node) implements exactly what it needs.

AdaptiveLauncher (final readonly class)

Flytachi\Winter\Thread\Launch\AdaptiveLauncher — what is used when you bind nothing. It holds both built-in backends and picks one per launch() from the runtime at that moment: SwooleLauncher inside a Swoole coroutine or with runtime hooks enabled, CliLauncher everywhere else.

new AdaptiveLauncher(CliLauncher $cli, SwooleLauncher $swoole)

AdaptiveLauncher::adaptive(
  ?string $secret = null,
  ?string $binaryPath = null,
  ?string $runnerPath = null,
): AdaptiveLauncher

CliLauncher (final readonly class)

Flytachi\Winter\Thread\Launch\CliLauncher — the CLI and FPM backend, proc_open-based. The command is built fully escapeshellarg-escaped.

new CliLauncher(
  string            $binaryPath,
  string            $runnerPath,
  ?PayloadTransport $transport = null,
  ?string           $secret = null,
)

CliLauncher::adaptive(
  ?string           $secret = null,
  ?PayloadTransport $transport = null,
  ?string           $binaryPath = null,
  ?string           $runnerPath = null,
): CliLauncher

Immutable — to change one part, construct a new one.

SwooleLauncher (final readonly class)

Flytachi\Winter\Thread\Launch\SwooleLauncher — the backend for an active Swoole runtime. Instead of proc_open (which corrupts the reactor’s descriptors) or Swoole\Process (forbidden while async-io threads are up), it starts the runner as a shell background job through Swoole\Coroutine\System::exec().

new SwooleLauncher(string $binaryPath, string $runnerPath, ?string $secret = null)

SwooleLauncher::adaptive(
  ?string $secret = null,
  ?string $binaryPath = null,
  ?string $runnerPath = null,
): SwooleLauncher

There is no transport in the signature: it picks delivery itself — shared memory with ext-shmop, a temp file otherwise. It requires ext-swoole at launch time and is meaningful only for detached tasks: a coroutine worker has no parent pipe, so its handle is PID-based — liveness and signalling work, but there is nothing to read or join().

ProcessHandle (interface)

Flytachi\Winter\Thread\Launch\ProcessHandle — the low-level process-control primitive a launcher returns. Not constructed directly — obtained from Launcher::launch().

It is an interface: your own backend returns its own implementation. Two ship with the package — CliProcessHandle (wraps the proc_open resource and tracks process, pipe and exit-code state) and SwooleProcessHandle (PID-based: liveness and signalling work, there is nothing to read or join()).

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 launcher — 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 (for example ShmTransport without ext-shmop), and transport staging failures (temp file / shm allocation). Catch it around start() and launcher setup.