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

dg / dresscode / 42622521246

09 Nov 2026 12:44PM UTC coverage: 97.794% (+0.8%) from 96.997%
42622521246

push

github

dg
released version 1.3.4

23626 of 24159 relevant lines covered (97.79%)

0.98 hits per line

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

84.98
/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
        /** seconds the end of a worker is waited for once its connection has closed */
24
        private const EndTimeout = 1;
25

26
        /**
27
         * The listening socket: from ext/sockets when available, because the stream layer on Windows waits 500 ms
28
         * for a socket to become writable before closing it, which a listening one never does.
29
         * @var \Socket|resource|null
30
         */
31
        private mixed $server = null;
32

33
        /** @var array<int, resource>  connected workers by socket id */
34
        private array $sockets = [];
35

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

39
        /** workers that have connected so far */
40
        private int $accepted = 0;
41

42
        /** workers started once the first has connected */
43
        private int $pending = 0;
44

45
        /** the address the workers connect to */
46
        private string $address = '';
47

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

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

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

57
        /** when the last worker was started */
58
        private float $spawnedAt = 0;
59

60
        /** @var list<string> */
61
        private array $queue = [];
62

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

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

69

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

85

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

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

98
                return max(1, $count);
1 ✔
99
        }
100

101

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

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

119

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

127
                $path = dirname(PHP_BINARY) . '/php' . (PHP_OS_FAMILY === 'Windows' ? '.exe' : '');
×
128
                return is_file($path) ? $path : null;
×
129
        }
130

131

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

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

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

163
                return $options;
1 ✔
164
        }
165

166

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

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

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

204
                } finally {
1 ✔
205
                        foreach ($this->sockets as $socket) {
1 ✔
206
                                fclose($socket);
1 ✔
207
                        }
208

209
                        $this->closeServer();
1 ✔
210
                        $this->stop();
1 ✔
211
                }
212
        }
1 ✔
213

214

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

224

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

234

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

249
                        $this->server = $server;
1 ✔
250
                        return "$ip:$port";
1 ✔
251
                }
252

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

259
                $this->server = $server;
×
260
                return (string) stream_socket_get_name($server, remote: false);
×
261
        }
262

263

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

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

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

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

305
                return $streams;
1 ✔
306
        }
307

308

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

319
                        $blocking = false;
1 ✔
320
                        $connection = socket_accept($server);
1 ✔
321
                        if ($connection === false) {
1 ✔
322
                                return;
×
323
                        }
324

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

331
                        $this->acceptConnection($stream);
1 ✔
332
                }
333
        }
×
334

335

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

345

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

360
                $id = (int) $socket;
1 ✔
361
                $this->sockets[$id] = $socket;
1 ✔
362
                $this->assign($id);
1 ✔
363
        }
1 ✔
364

365

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

374
                $this->server = null;
1 ✔
375
        }
1 ✔
376

377

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

390
                $chunk = fread($socket, 1 << 20);
1 ✔
391
                if ($chunk === false || ($chunk === '' && feof($socket))) {
1 ✔
392
                        if (isset($this->inProgress[$id])) {
1 ✔
393
                                $end = $this->findWorkerFailure();
1 ✔
394
                                throw new \RuntimeException('A worker ended ' . ($end === null ? '' : "$end ") . "while processing `{$this->inProgress[$id][0]}`." . $this->collectErrors());
1 ✔
395
                        }
396

397
                        $this->disconnect($id);
×
398
                        return [];
×
399
                }
400

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

411
                        unset($this->inProgress[$id]);
1 ✔
412
                        foreach (is_array($data['dependencies'] ?? null) ? $data['dependencies'] : [] as $file) {
1 ✔
413
                                $this->dependencies[(string) $file] = true;
1 ✔
414
                        }
415

416
                        foreach (is_array($data['runWarnings'] ?? null) ? $data['runWarnings'] : [] as $warning) {
1 ✔
417
                                $this->warnings[(string) $warning] = true;
1 ✔
418
                        }
419

420
                        $results[$path] = WorkerCodec::decode($data, $code);
1 ✔
421
                        $this->assign($id);
1 ✔
422
                }
423

424
                if (isset($this->sockets[$id]) && strlen($buffer)) {
1 ✔
425
                        $this->buffers[$id] = $buffer;
1 ✔
426
                } else {
427
                        unset($this->buffers[$id]);
1 ✔
428
                }
429

430
                return $results;
1 ✔
431
        }
432

433

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

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

448

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

457
                return $paths;
×
458
        }
459

460

461
        private function disconnect(int $id): void
462
        {
463
                fclose($this->sockets[$id]);
1 ✔
464
                unset($this->sockets[$id], $this->inProgress[$id], $this->buffers[$id]);
1 ✔
465
        }
1 ✔
466

467

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

482
                fclose($pipes[0]);
1 ✔
483
                $this->spawnedAt = microtime(as_float: true);
1 ✔
484
                return [$process, $output];
1 ✔
485
        }
486

487

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

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

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

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

523

524
        /**
525
         * How a worker that failed ended, given a moment to end, because its connection closes before its process is gone;
526
         * null where none has failed.
527
         */
528
        private function findWorkerFailure(): ?string
529
        {
530
                $deadline = microtime(as_float: true) + self::EndTimeout;
1 ✔
531
                do {
532
                        foreach ($this->workers as [$process]) {
1 ✔
533
                                $status = proc_get_status($process);
1 ✔
534
                                if (!$status['running'] && $status['exitcode'] !== 0) {
1 ✔
535
                                        return self::formatEnd($status);
1 ✔
536
                                }
537
                        }
538

539
                        usleep(10_000);
1 ✔
540
                } while (microtime(as_float: true) < $deadline);
1 ✔
541

542
                return null;
×
543
        }
544

545

546
        /**
547
         * How a process ended, for a message: its exit code, one of Windows in the form it is known by (`0xC0000005` for a
548
         * crash of PHP itself), or the signal that ended it.
549
         * @param  array{signaled: bool, termsig: int, exitcode: int}  $status
550
         */
551
        private static function formatEnd(array $status): string
552
        {
553
                $code = $status['exitcode'];
1 ✔
554
                return match (true) {
555
                        $status['signaled'] => "on signal {$status['termsig']}",
1 ✔
556
                        PHP_OS_FAMILY === 'Windows' && ($code < 0 || $code > 0xFFFF) => sprintf('with code 0x%08X', $code & 0xFFFFFFFF),
1 ✔
557
                        default => "with code $code",
1 ✔
558
                };
559
        }
560

561

562
        private function collectErrors(): string
563
        {
564
                $errors = '';
1 ✔
565
                foreach ($this->workers as [, $output]) {
1 ✔
566
                        $errors .= trim((string) @file_get_contents($output)); // @ file may have been deleted meanwhile
1 ✔
567
                }
568

569
                return $errors === '' ? '' : "\n$errors";
1 ✔
570
        }
571

572

573
        private function stop(): void
574
        {
575
                foreach ($this->workers as [$process, $output]) {
1 ✔
576
                        if (proc_get_status($process)['running']) {
1 ✔
577
                                proc_terminate($process);
1 ✔
578
                        }
579

580
                        proc_close($process);
1 ✔
581
                        @unlink($output); // @ file may have been deleted meanwhile
1 ✔
582
                }
583

584
                $this->workers = $this->sockets = $this->inProgress = $this->buffers = [];
1 ✔
585
                $this->accepted = $this->pending = 0;
1 ✔
586
                $this->read = null;
1 ✔
587
        }
1 ✔
588
}
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