API Reference

Полный справочник по каждому публичному типу в Flytachi\Winter\Thread. Сигнатуры точно соответствуют исходному коду; для каждого элемента перечислены параметры, возвращаемые значения, исключения и неочевидная семантика.

API с высоты птичьего полёта

Поверхность делится на два уровня. Большинству приложений нужен только публичный API — три типа. Низкоуровневый API нужен для построения собственного пула, планировщика или супервизора прямо на сырых примитивах.

Публичный API — то, что вы используете

Низкоуровневый и расширяющий API — то, на чём вы строите

Четыре интерфейса (Engine, Launcher, Runner, PayloadTransport) — это точки расширения, принимающие вашу собственную реализацию; всё остальное — конкретные типы, которые вы потребляете.

Публичный API

Runnable (interface)

Flytachi\Winter\Thread\Runnable — контракт задачи.

public function run(array $args): void

Поместите свою логику в run(); она выполняется в рабочем процессе.

Возвращает ничего. Сигнализируйте о результате через код возврата (return/нормальное завершение → 0; выброс исключения → ненулевой) или побочные эффекты (файл/БД/очередь).

Контракт: реализующий объект должен быть сериализуемым — никаких живых ресурсов (PDO, сокеты, потоки) в его свойствах; открывайте их внутри run(). Непойманное исключение перехватывается runner’ом, логируется в STDERR со стеком трассировки и превращается в ненулевой код возврата.

Thread (final class)

Flytachi\Winter\Thread\Thread — высокоуровневый фасад над одним процессом. Изменяемый; защищает от конкурентных запусков.

__construct

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

Конструирование ничего не запускает. Заголовок процесса — WinterThread <namespace> -> <name>@<tag> (только там, где существует cli_set_process_title()).

Статические — привязка движка

start

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

Сериализует задачу, запускает процесс и немедленно возвращает управление.

Возвращает int — PID запущенного процесса (в detached-режиме — эфемерный PID launcher’а). Выбрасывает ThreadException, если поток уже жив или процесс не удаётся запустить.

Жизненный цикл и ожидание

Состояние

Сигналы (требуют ext-posix; каждый возвращает false, если не выполняется)

Каждый возвращает bool — true, если сигнал был отправлен. Чтобы отреагировать корректно, задача должна установить обработчик; см. Корректное завершение.

Вывод (непустой только при запуске с outputTarget: null)

Метаданные

Engine (interface)

Flytachi\Winter\Thread\Engine\Engine — корень конфигурации/стратегии, используется только на стороне родителя. У него нет метода для стороны потомка: воркер запускает отдельный AdaptiveRunner. security() родителя передаётся потомку через переменную окружения WINTER_THREAD_SECRET.

AdaptiveEngine (final readonly class, default)

Flytachi\Winter\Thread\Engine\AdaptiveEngine — самонастраивающийся; неизменяемый.

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

Неизменяемый — чтобы изменить один аспект, создайте новый экземпляр.

ManualEngine (final class)

Flytachi\Winter\Thread\Engine\ManualEngine — явный, с чистого листа. Неизменяемые wither-методы (каждый возвращает клон); незаданная обязательная часть выбрасывает ThreadException при обращении ("ManualEngine: <part> is not configured.").

При своём withLauncher(...) transport/binaryPath/runnerPath не обязательны — launcher сам владеет обвязкой. Иначе все три обязательны. security() возвращает null, если секрет не был задан.

Низкоуровневый и расширяющий API

Для пулов, планировщиков и собственных бэкендов. Thread построен ровно на этих частях — вы можете управлять ими напрямую.

Launcher (interface)

Flytachi\Winter\Thread\Launch\Launcher — стратегия порождения процесса на стороне родителя.

public function launch(LaunchSpec $spec): ProcessHandle

Возвращает ProcessHandle. Выбрасывает ThreadException при сбое. Реализуйте его, чтобы запускать по SSH, в контейнере или на удалённом узле.

CliLauncher (final readonly class)

Flytachi\Winter\Thread\Launch\CliLauncher — по умолчанию, на основе proc_open.

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

Собирает команду, полностью экранированную через escapeshellarg. Пустой $childEnv → потомок наследует окружение родителя; непустой → сливается поверх унаследованного окружения.

ProcessHandle (final class)

Flytachi\Winter\Thread\Launch\ProcessHandle — низкоуровневый примитив процесса, возвращаемый launcher’ом. Изменяемый; отслеживает состояние процесса/pipe’ов/кода возврата. Не конструируется напрямую — получается из Launcher::launch().

reap(), detach() и __destruct() неблокирующие на живом процессе; блокирующий proc_close выполняется только на уже мёртвом процессе. __destruct() пожинает завершённый процесс либо отсоединяет ещё работающий — он никогда не блокирует родителя.

LaunchSpec (final readonly class)

Flytachi\Winter\Thread\LaunchSpec — неизменяемый набор всех параметров запуска. Постройте его напрямую, чтобы управлять launcher’ом без 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,
)

Все свойства публичные и readonly.

PayloadTransport (interface)

Flytachi\Winter\Thread\Payload\PayloadTransport — доставляет сериализованный payload через границу процессов в две части плюс очистка.

$options в receive() — это array<string, mixed> — разобранные опции CLI потомка.

PipeTransport

…\Payload\PipeTransport — payload через pipe stdin потомка (записывается после запуска). Без расширений. Не безопасен для Swoole (использует pipe fd). По умолчанию в обычном CLI.

TempFileTransport

…\Payload\TempFileTransport — payload через временный файл 0600, помещённый на stdin, удаляемый (unlink) сразу после запуска (потомок сохраняет свой fd). Без расширений. Безопасен для Swoole. Выбрасывает ThreadException, если временный файл не удаётся создать/записать.

ShmTransport

…\Payload\ShmTransport — payload через сегмент System V разделяемой памяти 0600; целочисленный ключ передаётся как --shmkey, а потомок читает, затем удаляет его. Без диска, безопасен для Swoole. Требует ext-shmop — выбрасывает ThreadException ("ShmTransport requires ext-shmop.") как в stage(), так и в receive(), если расширения нет, а также при сбое выделения.

StagedPayload (final readonly class)

Flytachi\Winter\Thread\Payload\StagedPayload — результат stage(); launcher читает его обобщённо.

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

Runner (interface)

Flytachi\Winter\Thread\Runner\Runner — стратегия исполнения на стороне потомка.

public function execute(array $options): int

Возвращает int — код возврата процесса (0 — успех, ненулевой — сбой).

AdaptiveRunner (final readonly class)

Flytachi\Winter\Thread\Runner\AdaptiveRunner — стандартный runner на стороне потомка (управляется wRunner). Он зависит только от провайдера безопасности — не от Engine — так что обе стороны остаются независимыми.

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

Ход execute(): принять payload (--shmkey → shm, иначе STDIN) → проверить + десериализовать через opis/closure (отклоняя пустые, не-Runnable или неподписанные/подделанные payload’ы ненулевым кодом возврата) → опционально fork+setsid (detached) → установить заголовок процесса → run() → код возврата.

Signal (final class)

Flytachi\Winter\Thread\Signal — статические POSIX-хелперы по сырому PID. isProcessRunning() трактует зомби (состояние Z) как не выполняющиеся, как на Linux (/proc/<pid>/status), так и на macOS (ps).

ThreadException (class)

Flytachi\Winter\Thread\ThreadException extends \RuntimeException — единственный тип исключения библиотеки.

Выбрасывается при: сбое запуска (proc_open отклонён или процесс сразу умер), запуске уже работающего Thread, некорректной конфигурации (незаданная часть ManualEngine или ShmTransport без ext-shmop) и сбоях подготовки транспорта (временный файл / выделение shm). Ловите его вокруг start() и настройки движка.