<?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; }}