API Reference

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

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

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

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

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

Четыре интерфейса (Launcher, ProcessHandle, 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)

Метаданные

Привязка лаунчера

Конфигурация запуска живёт в Launcher — он описан ниже, в разделе низкоуровневого API, потому что это же расширяемая точка. Привязывается один раз при инициализации:

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

Thread::launcher();   // текущий лаунчер; без привязки — AdaptiveLauncher

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

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

Launcher (interface)

Flytachi\Winter\Thread\Launch\Launcher — как порождается процесс. Живёт только на стороне родителя: потомку он не передаётся, там работает отдельный AdaptiveRunner, а секрет доезжает через переменную окружения WINTER_THREAD_SECRET.

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

Вся поверхность — два метода: транспорт, путь к бинарнику и путь к wRunner в интерфейс не входят, это внутреннее дело конкретного бэкенда. Поэтому свой запуск (SSH, контейнер, удалённый узел) реализует ровно то, что ему нужно.

AdaptiveLauncher (final readonly class)

Flytachi\Winter\Thread\Launch\AdaptiveLauncher — используется, если вы ничего не привязали. Держит оба встроенных бэкенда и выбирает один на каждый launch() по рантайму в этот момент: внутри корутины Swoole или при включённых хуках — SwooleLauncher, иначе — CliLauncher.

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 — бэкенд для CLI и FPM, на основе proc_open. Команда собирается полностью экранированной через escapeshellarg.

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

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

SwooleLauncher (final readonly class)

Flytachi\Winter\Thread\Launch\SwooleLauncher — бэкенд для активного рантайма Swoole. Вместо proc_open (портит дескрипторы реактора) и Swoole\Process (запрещён при поднятых async-io потоках) запускает runner фоновой задачей оболочки через 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

Транспорта в сигнатуре нет: доставку он выбирает сам — разделяемая память при ext-shmop, иначе временный файл. Требует ext-swoole в момент запуска и осмыслен только для detached-задач: у корутинного воркера нет родительского пайпа, поэтому его дескриптор работает по PID — живость и сигналы есть, читать и join() нечего.

ProcessHandle (interface)

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

Это интерфейс: свой бэкенд возвращает собственную реализацию. Встроенных две — CliProcessHandle (оборачивает ресурс proc_open, отслеживает состояние процесса, pipe’ов и кода возврата) и SwooleProcessHandle (работает по PID: живость и сигналы есть, читать и join() нечего).

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). Он зависит только от провайдера безопасности — не от лаунчера — так что обе стороны остаются независимыми.

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, некорректной конфигурации (например, ShmTransport без ext-shmop) и сбоях подготовки транспорта (временный файл / выделение shm). Ловите его вокруг start() и настройки лаунчера.