• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

dg / dresscode / 41360056545

01 Nov 2026 10:35PM UTC coverage: 97.753% (+1.0%) from 96.734%
41360056545

push

github

dg
released version 1.3.2

23236 of 23770 relevant lines covered (97.75%)

0.98 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

83.18
/src/Engine/WorkerPool.php
1
<?php declare(strict_types=1);
2

3
/**
4
 * This file is part of the DressCode, a coding style and upgrade tool for PHP (https://dresscode.run)
5
 * Copyright (c) 2026 David Grudl (https://davidgrudl.com)
6
 */
7

8
namespace DressCode\Engine;
9

10
use DressCode\FileResult;
11
use function array_key_exists, count, function_exists, in_array, is_array, strlen;
12
use const PHP_OS_FAMILY, PHP_SAPI;
13

14

15
/**
16
 * Processes files in worker processes: a TCP server on the loopback hands the paths out one at a time,
17
 * a worker sends each result back as a line of JSON. The parent keeps the cache and the baseline, a worker
18
 * only processes and, when fixing, writes.
19
 * @internal
20
 */
21
final class WorkerPool
22
{
23
        /**
24
         * The listening socket: from ext/sockets when available, because the stream layer on Windows waits 500 ms
25
         * for a socket to become writable before closing it, which a listening one never does.
26
         * @var \Socket|resource|null
27
         */
28
        private mixed $server = null;
29

30
        /** @var array<int, resource>  connected workers by socket id */
31
        private array $sockets = [];
32

33
        /** @var array<int, string>  what a worker sent after its last complete line, by socket id */
34
        private array $buffers = [];
35

36
        /** workers that have connected so far */
37
        private int $accepted = 0;
38

39
        /** workers started once the first has connected */
40
        private int $pending = 0;
41

42
        /** the address the workers connect to */
43
        private string $address = '';
44

45
        /** @var array<int, array{string, float, string}>  path in progress with the time it started and its content, by socket id */
46
        private array $inProgress = [];
47

48
        /** @var ?\Closure(string): string  path => content, read when the path is handed out */
49
        private ?\Closure $read = null;
50

51
        /** @var list<array{resource, string}>  process, file with its output */
52
        private array $workers = [];
53

54
        /** when the last worker was started */
55
        private float $spawnedAt = 0;
56

57
        /** @var list<string> */
58
        private array $queue = [];
59

60
        /** @var array<string, true>  the files the results depend on, as the workers sent them */
61
        private array $dependencies = [];
62

63
        /** @var array<string, true>  what the analyses of the workers tell the user about the run */
64
        private array $warnings = [];
65

66

67
        public function __construct(
68
                /** @var list<string> the worker command line; --worker with the address is appended */
69
                private readonly array $command,
1 ✔
70
                private readonly int $jobs,
1 ✔
71
                /** working directory of the workers */
72
                private readonly ?string $cwd = null,
1 ✔
73
                /** seconds a worker may spend on one file before the run fails, since a rule has most likely looped */
74
                private readonly int $taskTimeout = 300,
1 ✔
75
                /** seconds a worker may take to connect, the first one filling the cache the others share among them */
76
                private readonly int $connectTimeout = 300,
1 ✔
77
                /** the first worker fills a cache the others share before it connects, and they start after that */
78
                private readonly bool $warmFirst = false,
1 ✔
79
        ) {
80
        }
1 ✔
81

82

83
        /** Processors the machine has, 1 when unknown. */
84
        public static function detectCpuCount(): int
85
        {
86
                $count = (int) getenv('NUMBER_OF_PROCESSORS');
1 ✔
87
                if ($count < 1 && is_readable('/proc/cpuinfo')) {
1 ✔
88
                        $count = preg_match_all('~^processor\s*:~m', (string) file_get_contents('/proc/cpuinfo'));
1 ✔
89
                }
90

91
                if ($count < 1 && in_array(PHP_OS_FAMILY, ['Darwin', 'BSD'], true) && function_exists('shell_exec')) {
1 ✔
92
                        $count = (int) @shell_exec('sysctl -n hw.ncpu 2>/dev/null'); // @ a failed command gives no count
×
93
                }
94

95
                return max(1, $count);
1 ✔
96
        }
97

98

99
        /**
100
         * The PHP a worker is started with: the same binary with the same ini file, the binary alone loading the default
101
         * one, and the settings the process has beyond it; null where no CLI binary is found to start one.
102
         * @return ?list<string>
103
         */
104
        public static function buildPhpCommand(): ?array
105
        {
106
                $binary = self::findCliBinary();
1 ✔
107
                if ($binary === null) {
1 ✔
108
                        return null;
×
109
                }
110

111
                $ini = php_ini_loaded_file();
1 ✔
112
                $php = [$binary, ...($ini === false ? (php_ini_scanned_files() === false ? ['-n'] : []) : ['-c', $ini])];
1 ✔
113
                return [...$php, ...self::findIniOverrides($php)];
1 ✔
114
        }
115

116

117
        /** The binary of the process, or under another SAPI than CLI, such as CGI, the CLI binary beside it. */
118
        private static function findCliBinary(): ?string
119
        {
120
                if (PHP_SAPI === 'cli') {
1 ✔
121
                        return PHP_BINARY;
1 ✔
122
                }
123

124
                $path = dirname(PHP_BINARY) . '/php' . (PHP_OS_FAMILY === 'Windows' ? '.exe' : '');
×
125
                return is_file($path) ? $path : null;
×
126
        }
127

128

129
        /**
130
         * The settings the process has and the PHP of the command alone would not, those given by -d above all, as the
131
         * options -d that give them to a worker; PHP tells no process the options it started with, so the PHP of the
132
         * command is asked for its settings and they are compared.
133
         * @param  list<string>  $php
134
         * @return list<string>
135
         */
136
        private static function findIniOverrides(array $php): array
137
        {
138
                $null = PHP_OS_FAMILY === 'Windows' ? 'NUL' : '/dev/null';
1 ✔
139
                $process = @proc_open([...$php, '-r', 'echo serialize(ini_get_all(null, false));'], [1 => ['pipe', 'w'], 2 => ['file', $null, 'w']], $pipes); // @ no settings then
1 ✔
140
                if ($process === false) {
1 ✔
141
                        return [];
×
142
                }
143

144
                $base = @unserialize((string) stream_get_contents($pipes[1])); // @ a PHP that failed to start gives none
1 ✔
145
                fclose($pipes[1]);
1 ✔
146
                proc_close($process);
1 ✔
147
                $own = ini_get_all(details: false);
1 ✔
148
                if (!is_array($base) || $own === false) {
1 ✔
149
                        return [];
×
150
                }
151

152
                $options = [];
1 ✔
153
                foreach ($own as $name => $value) {
1 ✔
154
                        if (array_key_exists($name, $base) && $base[$name] !== $value) {
1 ✔
155
                                $options[] = '-d';
1 ✔
156
                                $options[] = "$name=$value";
1 ✔
157
                        }
158
                }
159

160
                return $options;
1 ✔
161
        }
162

163

164
        /**
165
         * The results by path, each as soon as it arrives; the content of a file is read when it is handed out, so that
166
         * only the files in progress are held.
167
         * @param  list<string>  $paths
168
         * @param  \Closure(string): string  $read  path => content
169
         * @param  ?\Closure(int, array<string, float>): void  $onProgress  files done and the paths in progress
170
         * @return \Generator<string, FileResult>
171
         * @throws \RuntimeException  when a worker fails
172
         */
173
        public function process(array $paths, \Closure $read, ?\Closure $onProgress = null): \Generator
1 ✔
174
        {
175
                $address = $this->listen();
1 ✔
176
                $this->queue = $paths;
1 ✔
177
                $this->read = $read;
1 ✔
178
                $done = 0;
1 ✔
179
                try {
180
                        $count = min($this->jobs, count($this->queue));
1 ✔
181
                        $this->address = $address;
1 ✔
182
                        $this->pending = $this->warmFirst ? $count - 1 : 0;
1 ✔
183
                        for ($i = $count - $this->pending; $i > 0; $i--) {
1 ✔
184
                                $this->workers[] = $this->spawn($address);
1 ✔
185
                        }
186

187
                        while ($done < count($paths)) {
1 ✔
188
                                foreach ($this->await() as $stream) {
1 ✔
189
                                        foreach ($this->receive((int) $stream) as $path => $result) {
1 ✔
190
                                                $done++;
1 ✔
191
                                                yield $path => $result;
1 ✔
192
                                        }
193
                                }
194

195
                                $this->checkWorkers($done < count($paths));
1 ✔
196
                                if ($onProgress !== null) {
1 ✔
197
                                        $onProgress($done, $this->getInProgress());
×
198
                                }
199
                        }
200

201
                } finally {
1 ✔
202
                        foreach ($this->sockets as $socket) {
1 ✔
203
                                fclose($socket);
1 ✔
204
                        }
205

206
                        $this->closeServer();
1 ✔
207
                        $this->stop();
1 ✔
208
                }
209
        }
1 ✔
210

211

212
        /**
213
         * The files the results of the workers depend on beyond the configuration, as they sent them.
214
         * @return list<string>
215
         */
216
        public function getDependencies(): array
217
        {
218
                return array_keys($this->dependencies);
1 ✔
219
        }
220

221

222
        /**
223
         * What the analyses of the workers tell the user about the run, each thing once.
224
         * @return list<string>
225
         */
226
        public function getWarnings(): array
227
        {
228
                return array_keys($this->warnings);
1 ✔
229
        }
230

231

232
        /** @return string  the address the workers connect to */
233
        private function listen(): string
234
        {
235
                if (function_exists('socket_create')) {
1 ✔
236
                        $server = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
1 ✔
237
                        if (
238
                                $server === false
1 ✔
239
                                || !socket_bind($server, '127.0.0.1')
1 ✔
240
                                || !socket_listen($server, $this->jobs)
1 ✔
241
                                || !socket_getsockname($server, $ip, $port)
1 ✔
242
                        ) {
243
                                throw new \RuntimeException('Cannot start the worker server: ' . socket_strerror(socket_last_error()));
×
244
                        }
245

246
                        $this->server = $server;
1 ✔
247
                        return "$ip:$port";
1 ✔
248
                }
249

250
                $context = stream_context_create(['socket' => ['tcp_nodelay' => true]]); // Nagle would delay every small message by an ACK
×
251
                $server = @stream_socket_server('tcp://127.0.0.1:0', $errno, $error, context: $context); // @ is escalated to exception
×
252
                if ($server === false) {
×
253
                        throw new \RuntimeException("Cannot start the worker server: $error");
×
254
                }
255

256
                $this->server = $server;
×
257
                return (string) stream_socket_get_name($server, remote: false);
×
258
        }
259

260

261
        /**
262
         * Waits for messages from the workers, accepting the ones that connect meanwhile; the listening socket
263
         * from ext/sockets is closed as soon as the last worker is in.
264
         * @return list<resource>  connections with a message waiting
265
         */
266
        private function await(): array
267
        {
268
                $read = array_values($this->sockets);
1 ✔
269
                $write = $except = [];
1 ✔
270
                $seconds = 1;
1 ✔
271
                $microseconds = 0;
1 ✔
272
                $server = $this->server;
1 ✔
273
                if ($server instanceof \Socket) {
1 ✔
274
                        $this->acceptPending($server, blocking: $read === []);
1 ✔
275
                        if ($this->accepted === count($this->workers)) {
1 ✔
276
                                $this->closeServer();
1 ✔
277
                        } else { // short waits while workers may still be connecting
278
                                $seconds = 0;
1 ✔
279
                                $microseconds = 10_000;
1 ✔
280
                        }
281
                } elseif ($server !== null) {
1 ✔
282
                        $read[] = $server;
×
283
                }
284

285
                if ($read === []) { // nothing connected: the workers are still starting, or they are gone
1 ✔
286
                        return [];
1 ✔
287
                }
288

289
                if (@stream_select($read, $write, $except, $seconds, $microseconds) === false) { // @ is escalated to exception
1 ✔
290
                        throw new \RuntimeException('Waiting for the workers failed.');
×
291
                }
292

293
                $streams = [];
1 ✔
294
                foreach ($read as $stream) {
1 ✔
295
                        if ($stream === $server) {
1 ✔
296
                                $this->acceptStream($stream);
×
297
                        } else {
298
                                $streams[] = $stream;
1 ✔
299
                        }
300
                }
301

302
                return $streams;
1 ✔
303
        }
304

305

306
        /** Accepts every worker waiting to connect; with nothing to do otherwise, waits for the first one. */
307
        private function acceptPending(\Socket $server, bool $blocking): void
308
        {
309
                while (true) {
1 ✔
310
                        $read = [$server];
1 ✔
311
                        $write = $except = null;
1 ✔
312
                        if (socket_select($read, $write, $except, $blocking ? 1 : 0) !== 1) {
1 ✔
313
                                return;
1 ✔
314
                        }
315

316
                        $blocking = false;
1 ✔
317
                        $connection = socket_accept($server);
1 ✔
318
                        if ($connection === false) {
1 ✔
319
                                return;
×
320
                        }
321

322
                        socket_set_option($connection, SOL_TCP, TCP_NODELAY, 1); // Nagle would delay every small message by an ACK
1 ✔
323
                        $stream = socket_export_stream($connection);
1 ✔
324
                        if ($stream === false) {
1 ✔
325
                                throw new \RuntimeException('Cannot use the connection of a worker.');
×
326
                        }
327

328
                        $this->acceptConnection($stream);
1 ✔
329
                }
330
        }
×
331

332

333
        /** @param resource $server */
334
        private function acceptStream($server): void
335
        {
336
                $socket = @stream_socket_accept($server, 0); // @ a false alarm is harmless
×
337
                if ($socket !== false) {
×
338
                        $this->acceptConnection($socket);
×
339
                }
340
        }
×
341

342

343
        /**
344
         * Registers the connection, starts the workers that waited for it, and hands it a path. It is read without
345
         * blocking: a worker may have sent only a part of its line, and waiting for the rest would stop the parent from
346
         * hearing the others and from noticing a worker that is stuck.
347
         * @param resource $socket
348
         */
349
        private function acceptConnection($socket): void
350
        {
351
                stream_set_blocking($socket, enable: false);
1 ✔
352
                $this->accepted++;
1 ✔
353
                for (; $this->pending > 0; $this->pending--) {
1 ✔
354
                        $this->workers[] = $this->spawn($this->address);
1 ✔
355
                }
356

357
                $id = (int) $socket;
1 ✔
358
                $this->sockets[$id] = $socket;
1 ✔
359
                $this->assign($id);
1 ✔
360
        }
1 ✔
361

362

363
        private function closeServer(): void
364
        {
365
                if ($this->server instanceof \Socket) {
1 ✔
366
                        socket_close($this->server);
1 ✔
367
                } elseif ($this->server !== null) {
1 ✔
368
                        fclose($this->server);
×
369
                }
370

371
                $this->server = null;
1 ✔
372
        }
1 ✔
373

374

375
        /**
376
         * The results the worker has finished sending, by path: every line answers the path in progress, and a line
377
         * about any other one is a failure, as is an ended worker with a path in progress.
378
         * @return array<string, FileResult>
379
         */
380
        private function receive(int $id): array
381
        {
382
                $socket = $this->sockets[$id] ?? null;
1 ✔
383
                if ($socket === null) {
1 ✔
384
                        return [];
×
385
                }
386

387
                $chunk = fread($socket, 1 << 20);
1 ✔
388
                if ($chunk === false || ($chunk === '' && feof($socket))) {
1 ✔
389
                        if (isset($this->inProgress[$id])) {
×
390
                                throw new \RuntimeException("A worker ended while processing `{$this->inProgress[$id][0]}`." . $this->collectErrors());
×
391
                        }
392

393
                        $this->disconnect($id);
×
394
                        return [];
×
395
                }
396

397
                $buffer = ($this->buffers[$id] ?? '') . $chunk;
1 ✔
398
                $results = [];
1 ✔
399
                while (($end = strpos($buffer, "\n")) !== false) {
1 ✔
400
                        $data = json_decode(substr($buffer, 0, $end), associative: true);
1 ✔
401
                        $buffer = substr($buffer, $end + 1);
1 ✔
402
                        [$path, , $code] = $this->inProgress[$id] ?? [null, null, ''];
1 ✔
403
                        if (!is_array($data) || $path === null || ($data['path'] ?? null) !== base64_encode($path)) {
1 ✔
404
                                throw new \RuntimeException('A worker sent an unexpected message.' . $this->collectErrors());
1 ✔
405
                        }
406

407
                        unset($this->inProgress[$id]);
1 ✔
408
                        foreach (is_array($data['dependencies'] ?? null) ? $data['dependencies'] : [] as $file) {
1 ✔
409
                                $this->dependencies[(string) $file] = true;
1 ✔
410
                        }
411

412
                        foreach (is_array($data['runWarnings'] ?? null) ? $data['runWarnings'] : [] as $warning) {
1 ✔
413
                                $this->warnings[(string) $warning] = true;
1 ✔
414
                        }
415

416
                        $results[$path] = WorkerCodec::decode($data, $code);
1 ✔
417
                        $this->assign($id);
1 ✔
418
                }
419

420
                if (isset($this->sockets[$id]) && strlen($buffer)) {
1 ✔
421
                        $this->buffers[$id] = $buffer;
1 ✔
422
                } else {
423
                        unset($this->buffers[$id]);
1 ✔
424
                }
425

426
                return $results;
1 ✔
427
        }
428

429

430
        /** Hands the next path to the worker, or closes its connection when there is none. */
431
        private function assign(int $id): void
432
        {
433
                $path = array_shift($this->queue);
1 ✔
434
                if ($path === null) {
1 ✔
435
                        $this->disconnect($id);
1 ✔
436
                        return;
1 ✔
437
                }
438

439
                $read = $this->read ?? throw new \LogicException('No run is in progress.');
1 ✔
440
                $this->inProgress[$id] = [$path, microtime(as_float: true), $read($path)];
1 ✔
441
                fwrite($this->sockets[$id], json_encode(['path' => base64_encode($path)], JSON_THROW_ON_ERROR) . "\n"); // a path need not be UTF-8
1 ✔
442
        }
1 ✔
443

444

445
        /** @return array<string, float>  path in progress => the time it started */
446
        private function getInProgress(): array
447
        {
448
                $paths = [];
×
449
                foreach ($this->inProgress as [$path, $since]) {
×
450
                        $paths[$path] = $since;
×
451
                }
452

453
                return $paths;
×
454
        }
455

456

457
        private function disconnect(int $id): void
458
        {
459
                fclose($this->sockets[$id]);
1 ✔
460
                unset($this->sockets[$id], $this->inProgress[$id], $this->buffers[$id]);
1 ✔
461
        }
1 ✔
462

463

464
        /** @return array{resource, string}  process, file with its output */
465
        private function spawn(string $address): array
466
        {
467
                $output = (string) tempnam(sys_get_temp_dir(), 'dresscode-worker-');
1 ✔
468
                $process = @proc_open( // @ is escalated to exception
1 ✔
469
                        [...$this->command, '--worker', $address],
1 ✔
470
                        [0 => ['pipe', 'r'], 1 => ['file', $output, 'a'], 2 => ['file', $output, 'a']],
1 ✔
471
                        $pipes,
472
                        $this->cwd,
1 ✔
473
                );
474
                if ($process === false) {
1 ✔
475
                        throw new \RuntimeException('Cannot start a worker process: `' . implode(' ', $this->command) . '`');
×
476
                }
477

478
                fclose($pipes[0]);
1 ✔
479
                $this->spawnedAt = microtime(as_float: true);
1 ✔
480
                return [$process, $output];
1 ✔
481
        }
482

483

484
        /**
485
         * A worker that exited with an error, one that has spent longer than the timeout on a file, a worker the run waits
486
         * for that has not connected within its timeout, or every worker gone while results are missing fails the run.
487
         */
488
        private function checkWorkers(bool $resultsMissing): void
489
        {
490
                $running = false;
1 ✔
491
                foreach ($this->workers as [$process]) {
1 ✔
492
                        $status = proc_get_status($process);
1 ✔
493
                        if ($status['running']) {
1 ✔
494
                                $running = true;
1 ✔
495
                        } elseif ($status['exitcode'] !== 0) {
1 ✔
496
                                throw new \RuntimeException("A worker exited with code {$status['exitcode']}." . $this->collectErrors());
×
497
                        }
498
                }
499

500
                foreach ($this->inProgress as [$path, $since]) {
1 ✔
501
                        if (microtime(as_float: true) - $since > $this->taskTimeout) {
1 ✔
502
                                throw new \RuntimeException("A worker has spent more than $this->taskTimeout s on `$path`; a rule has most likely looped." . $this->collectErrors());
1 ✔
503
                        }
504
                }
505

506
                if (
507
                        $this->sockets === []
1 ✔
508
                        && $this->accepted < count($this->workers)
1 ✔
509
                        && microtime(as_float: true) - $this->spawnedAt > $this->connectTimeout
1 ✔
510
                ) {
511
                        throw new \RuntimeException("A worker has not connected within $this->connectTimeout s." . $this->collectErrors());
1 ✔
512
                }
513

514
                if (!$running && $resultsMissing) {
1 ✔
515
                        throw new \RuntimeException('The workers ended before processing every file.' . $this->collectErrors());
×
516
                }
517
        }
1 ✔
518

519

520
        private function collectErrors(): string
521
        {
522
                $errors = '';
1 ✔
523
                foreach ($this->workers as [, $output]) {
1 ✔
524
                        $errors .= trim((string) @file_get_contents($output)); // @ file may have been deleted meanwhile
1 ✔
525
                }
526

527
                return $errors === '' ? '' : "\n$errors";
1 ✔
528
        }
529

530

531
        private function stop(): void
532
        {
533
                foreach ($this->workers as [$process, $output]) {
1 ✔
534
                        if (proc_get_status($process)['running']) {
1 ✔
535
                                proc_terminate($process);
1 ✔
536
                        }
537

538
                        proc_close($process);
1 ✔
539
                        @unlink($output); // @ file may have been deleted meanwhile
1 ✔
540
                }
541

542
                $this->workers = $this->sockets = $this->inProgress = $this->buffers = [];
1 ✔
543
                $this->accepted = $this->pending = 0;
1 ✔
544
                $this->read = null;
1 ✔
545
        }
1 ✔
546
}
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE TRIAL · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc