EN
apps/winzik / src / Work / WorkerPool.php · commit 6576d6f
<?phpnamespace App\Work;/** * (From the JumPHP IDE's JumPHP\Ide\Async\WorkerPool, for WinZik's helper processes: the tags, lengths and covers of the * songs read beside the interface, which stays free.) * * Helper processes of the IDE, one per core (the desktop only): CPU work spread over the whole computer while the IDE's own frame * stays free (the first indexing of a project and of its libraries: 16 s on one core for JumPHP's repository). * * Why processes and not threads: the IDE runs on the desktop runtime (PHP 8.5 NTS, and StaticPHP's micro once exported), which has * no threads; TrueAsync's threads need the async runtime (PHP 8.6 ZTS). A process of the same PHP works on every desktop, crashes * alone, and needs nothing shared. Each one runs Worker::serve(): jobs as JSON lines on its stdin, an answer per line on its stdout. * * Never a crash, never a frozen IDE: *  - submit() never blocks: a job waits in a queue, a worker gets a few at a time (its pipe never fills); *  - poll() reads what came back for at most its budget, settles the Deferreds (on the IDE's thread, between frames); *  - an error in a job comes back as a rejected Deferred (WorkerError), the worker goes on; *  - a worker that dies (fatal error, killed) or that hangs past its job's timeout is stopped and started again; its jobs are tried *    once more, then rejected; too many deaths and the pool closes itself: every caller then does the work itself (the fallback); *  - a worker that does not say it is ready within $startTimeout (an executable too old to run it, a missing PHP) closes the pool. * The users of the pool always keep their single-thread path: a rejected job is done by the caller (Index). */final class WorkerPool implements JobPool{    /** @var array<int, array{proc: int, buffer: string, ready: bool, started: float, jobs: array<int, true>, busySince: ?float, alive: bool}> */    private array $workers = [];    /** @var array<int, array{type: string, payload: array<string, mixed>, deferred: Deferred, tries: int, worker: ?int, sent: ?float, timeout: float}> */    private array $jobs = [];    /** @var list<int> job ids not yet given to a worker */    private array $queue = [];    private int $nextJob = 1;    private int $nextWorker = 1;    private bool $closed = false;    private ?string $closedWhy = null;    /** @var list<float> when workers died (the last minute's count closes the pool) */    private array $deaths = [];    private int $done = 0;    private int $failed = 0;    private int $retried = 0;    private int $restarts = 0;    private const PER_WORKER = 8;    private const MAX_DEATHS_PER_MINUTE = 6;    /**     * @param list<string> $command the program and its arguments (WorkerPool::command())     * @param array<string, string> $env     */    public function __construct(        private array $command,        private array $env = [],        private int $size = 2,        private float $startTimeout = 15.0,        private ?Processes $processes = null,    ) {        $this->processes ??= new Processes();        $this->size = max(1, $size);    }    /**     * How to start a worker from this IDE: this PHP and the worker script, or the exported IDE's own executable when its stub knows     * how (tools/standalone-stub.php defines JUMPHP_STUB_WORKERS); null when neither (an older executable: no pool, the IDE works alone).     *     * @return array{0: list<string>, 1: array<string, string>}|null     */    public static function command(): ?array    {        $script = realpath(dirname(__DIR__, 2) . '/bin/winzik-worker.php');        if ($script === false) {            return null;        }        if (defined('JUMPHP_EXECUTABLE')) {            // the exported WinZik: its own executable runs the script (tools/standalone-stub.php, JUMPHP_WORKER_SCRIPT)            return defined('JUMPHP_STUB_WORKERS') ? [[(string)constant('JUMPHP_EXECUTABLE')], ['JUMPHP_WORKER_SCRIPT' => $script]] : null;        }        if (!is_file(PHP_BINARY)) {            return null;        }        return [[PHP_BINARY, '-d', 'memory_limit=512M', $script], []];    }    /** The computer's cores (1 when it cannot tell). */    public static function cores(): int    {        $n = 0;        if (PHP_OS_FAMILY === 'Windows') {            $n = (int)getenv('NUMBER_OF_PROCESSORS');        } elseif (is_readable('/proc/cpuinfo')) {            $n = substr_count((string)@file_get_contents('/proc/cpuinfo'), "\nprocessor") + (str_starts_with((string)@file_get_contents('/proc/cpuinfo', length: 9), 'processor') ? 1 : 0);        }        if ($n <= 0 && PHP_OS_FAMILY === 'Darwin') {            $n = (int)@shell_exec('sysctl -n hw.ncpu 2>/dev/null');        }        return max(1, $n);    }    /** A job: its answer (a plain value) or a WorkerError. Never blocks; a closed pool rejects at once. */    public function submit(string $type, array $payload = [], float $timeout = 60.0): Deferred    {        $deferred = new Deferred();        if ($this->closed) {            $deferred->reject(new WorkerError('the workers are off: ' . ($this->closedWhy ?? 'closed')));            return $deferred;        }        $id = $this->nextJob++;        $this->jobs[$id] = ['type' => $type, 'payload' => $payload, 'deferred' => $deferred, 'tries' => 0, 'worker' => null, 'sent' => null, 'timeout' => $timeout];        $this->queue[] = $id;        $this->spawn();        return $deferred;    }    /**     * Whether a worker said it is ready: callers give jobs only then (a worker that never starts would hold their work up to     * $startTimeout), and do the work themselves meanwhile. The first call starts the workers.     */    public function ready(): bool    {        if ($this->closed) {            return false;        }        foreach ($this->workers as $w) {            if ($w['alive'] && $w['ready']) {                return true;            }        }        $this->spawn($this->size);        return false;    }    /** Whether it can take jobs (false once it closed itself: callers do the work themselves). */    public function available(): bool    {        return !$this->closed;    }    /** Jobs not answered yet. */    public function pending(): int    {        return count($this->jobs);    }    /** How many more jobs it is worth giving now (the queue kept short: answers come in order of submission anyway). */    public function room(): int    {        return $this->closed ? 0 : max(0, $this->size * self::PER_WORKER * 2 - count($this->jobs));    }    /** Reads the answers for at most $budget seconds, settles their Deferreds, supervises the workers. */    public function poll(float $budget = 0.004): void    {        if ($this->jobs === [] && $this->processes->count() === 0) {            return;        }        if ($this->workers === [] && $this->jobs === []) {            $this->processes->poll();        // only workers let go, ending            return;        }        $start = microtime(true);        $this->processes->poll();        $now = microtime(true);        foreach ($this->workers as $wid => &$w) {            if (!$w['alive']) {                continue;            }            while (($nl = strpos($w['buffer'], "\n")) !== false) {                $line = substr($w['buffer'], 0, $nl);                $w['buffer'] = (string)substr($w['buffer'], $nl + 1);                $this->answer($wid, $w, $line);                if (microtime(true) - $start > $budget) {                    break 2;                }            }            if (!$w['ready'] && $now - $w['started'] > $this->startTimeout) {                $this->kill($wid, 'did not start within ' . $this->startTimeout . ' s');                if ($this->restarts === 0 && $this->done === 0) {                    $this->close('the workers do not start (' . implode(' ', $this->command) . ')');                    return;                }                continue;            }            foreach (array_keys($w['jobs']) as $jid) {                $job = $this->jobs[$jid] ?? null;                if ($job !== null && $job['sent'] !== null && $now - $job['sent'] > $job['timeout']) {                    $this->kill($wid, "a job ({$job['type']}) took more than {$job['timeout']} s");                    continue 2;                }            }        }        unset($w);        $this->dispatch();    }    /** @param array<string, mixed> $w */    private function answer(int $wid, array &$w, string $line): void    {        $data = json_decode($line, true);        if (!is_array($data)) {            return;           // a stray line (a notice printed on stdout): not an answer        }        if (!empty($data['ready'])) {            $w['ready'] = true;            return;        }        $jid = (int)($data['id'] ?? 0);        $job = $this->jobs[$jid] ?? null;        unset($w['jobs'][$jid]);        if ($job === null) {            return;        }        unset($this->jobs[$jid]);        if (!empty($data['ok'])) {            $this->done++;            $job['deferred']->resolve($data['value'] ?? null);        } else {            $this->failed++;            $job['deferred']->reject(new WorkerError((string)($data['error'] ?? 'failed'), (string)($data['class'] ?? ''), (string)($data['at'] ?? '')));        }    }    /** Gives the queued jobs to the workers that are ready, a few each. */    private function dispatch(): void    {        if ($this->queue === []) {            return;        }        foreach ($this->workers as $wid => &$w) {            if (!$w['alive'] || !$w['ready']) {                continue;            }            $lines = '';            while ($this->queue !== [] && count($w['jobs']) < self::PER_WORKER) {                $jid = array_shift($this->queue);                if (!isset($this->jobs[$jid])) {                    continue;                }                $this->jobs[$jid]['worker'] = $wid;                $this->jobs[$jid]['sent'] = microtime(true);                $this->jobs[$jid]['tries']++;                $w['jobs'][$jid] = true;                $lines .= json_encode(['id' => $jid, 'type' => $this->jobs[$jid]['type']] + $this->jobs[$jid]['payload'], JSON_UNESCAPED_SLASHES) . "\n";            }            if ($lines !== '' && !$this->processes->write($w['proc'], $lines)) {                $this->kill($wid, 'its input is closed');            }        }        unset($w);        $this->spawn();    }    /** Starts workers up to the size while there is work. */    private function spawn(int $atLeast = 1): void    {        if ($this->closed) {            return;        }        $alive = count(array_filter($this->workers, fn ($w) => $w['alive']));        $wanted = min($this->size, max($atLeast, (int)ceil(count($this->jobs) / self::PER_WORKER)));        for (; $alive < $wanted; $alive++) {            $wid = $this->nextWorker++;            $started = $this->processes->start($this->command, (string)getcwd(), $this->env + ['WINZIK_WORKER' => '1'],                function (string $chunk, string $stream) use ($wid): void {                    if ($stream === 'stdout' && isset($this->workers[$wid])) {                        $this->workers[$wid]['buffer'] .= $chunk;                    }                }, null, true);            $this->processes->discardOutput($started['id']);            $this->workers[$wid] = ['proc' => $started['id'], 'buffer' => '', 'ready' => false, 'started' => microtime(true), 'jobs' => [], 'busySince' => null, 'alive' => true];            $started['done']->then(fn () => $this->ended($wid, 'it ended'), fn (\Throwable $e) => $this->ended($wid, $e->getMessage()));        }    }    private function kill(int $wid, string $why): void    {        if (!($this->workers[$wid]['alive'] ?? false)) {            return;        }        $this->processes->stop($this->workers[$wid]['proc'], true);        $this->ended($wid, $why);    }    /** A worker is gone: its jobs go to another one (once), it is replaced while there is work. */    private function ended(int $wid, string $why): void    {        $w = $this->workers[$wid] ?? null;        if ($w === null || !$w['alive']) {            return;        }        $this->workers[$wid]['alive'] = false;        // the lines it wrote before it ended are answers too        while (($nl = strpos($this->workers[$wid]['buffer'], "\n")) !== false) {            $line = substr($this->workers[$wid]['buffer'], 0, $nl);            $this->workers[$wid]['buffer'] = (string)substr($this->workers[$wid]['buffer'], $nl + 1);            $ww = &$this->workers[$wid];            $this->answer($wid, $ww, $line);            unset($ww);        }        $orphans = array_keys($this->workers[$wid]['jobs']);        unset($this->workers[$wid]);        if ($this->closed) {            return;        }        if ($w['ready'] || $orphans !== []) {            $this->deaths[] = microtime(true);        }        foreach ($orphans as $jid) {            $job = $this->jobs[$jid] ?? null;            if ($job === null) {                continue;            }            if ($job['tries'] < 2) {                $this->retried++;                $this->jobs[$jid]['worker'] = null;                $this->jobs[$jid]['sent'] = null;                array_unshift($this->queue, $jid);            } else {                unset($this->jobs[$jid]);                $this->failed++;                $job['deferred']->reject(new WorkerError("the worker died twice on this job ($why)", 'WorkerDied'));            }        }        $this->deaths = array_values(array_filter($this->deaths, fn (float $t) => $t > microtime(true) - 60));        if (count($this->deaths) >= self::MAX_DEATHS_PER_MINUTE) {            $this->close("its workers died too often ($why)");            return;        }        if (!$w['ready'] && $w['jobs'] === [] && $this->done === 0) {            // it never started: no use starting it again and again            $this->close("a worker did not start: $why");            return;        }        if ($this->jobs !== []) {            $this->restarts++;            $this->spawn();        }    }    /** Stops every worker; the jobs not answered are rejected (their callers do the work themselves). */    public function close(string $why = 'closed'): void    {        if ($this->closed) {            return;        }        $this->closed = true;        $this->closedWhy = $why;        foreach ($this->workers as $w) {            if ($w['alive']) {                $this->processes->write($w['proc'], json_encode(['id' => 0, 'type' => 'exit']) . "\n");                $this->processes->closeInput($w['proc']);                $this->processes->stopLater($w['proc'], 2.0);            }        }        $this->workers = array_map(fn ($w) => ['alive' => false] + $w, $this->workers);        $jobs = $this->jobs;        $this->jobs = [];        $this->queue = [];        foreach ($jobs as $job) {            $job['deferred']->reject(new WorkerError("the workers are off: $why", 'WorkerPoolClosed'));        }    }    /** Workers with nothing to do are let go (they start again with the next job). */    public function idle(): void    {        if ($this->jobs !== [] || $this->closed) {            return;        }        foreach ($this->workers as $wid => $w) {            if ($w['alive']) {                $this->processes->write($w['proc'], json_encode(['id' => 0, 'type' => 'exit']) . "\n");                $this->processes->closeInput($w['proc']);                $this->processes->stopLater($w['proc'], 2.0);                $this->workers[$wid]['alive'] = false;            }        }        $this->workers = [];    }    /** Whether background processes still need polling (workers ending, jobs). */    public function busy(): bool    {        return $this->jobs !== [] || $this->processes->count() > 0;    }    /** What the Logs / the performance command show. @return array<string, mixed> */    public function status(): array    {        return ['size' => $this->size, 'alive' => count(array_filter($this->workers, fn ($w) => $w['alive'])), 'pending' => count($this->jobs),            'done' => $this->done, 'failed' => $this->failed, 'retried' => $this->retried, 'restarts' => $this->restarts,            'closed' => $this->closed, 'why' => $this->closedWhy];    }    /** The worker processes' ids (tests: one is killed in the middle of a job). @return list<int> */    public function pids(): array    {        $out = [];        foreach ($this->workers as $w) {            if ($w['alive'] && ($pid = $this->processes->pid($w['proc'])) !== null) {                $out[] = $pid;            }        }        return $out;    }}