feat: Add support for limiting the number of CPU cores calcualted for parallelisation

infection.json5

@@ -23,6 +23,13 @@
                 "Fidry\\CpuCoreCounter\\CpuCoreCounter::getDefaultFinders"
             ]
         },
+        "CastInt": {
+            "ignore": [
+                // This is a bug or case handled by strict types. Not sure why
+                // infection can't detect it.V
+                "Fidry\\CpuCoreCounter\\Finder\\EnvVariableFinder::isPositiveInteger"
+            ]
+        },
         "CastString": {
             "ignore": [
                 // I can't find a case in practice where this would happen
@@ -41,6 +48,12 @@
                 "Fidry\\CpuCoreCounter\\Executor\\ProcOpenExecutor::execute"
             ]
         },
+        "GreaterThan": {
+            "ignore": [
+                // This is an actual false positive.
+                "Fidry\\CpuCoreCounter\\CpuCoreCounter::getAvailableForParallelisation"
+            ]
+        },
         "IncrementInteger": {
             "ignore": [
                 "Fidry\\CpuCoreCounter\\CpuCoreCounter::getAvailableForParallelisation"

phpstan.src.neon

@@ -8,3 +8,9 @@ parameters:
 		- src
 
 	tmpDir: .build/phpstan/src/
+
+	ignoreErrors:
+
+		# This is a sanity check
+		- path: src/Finder/EnvVariableFinder.php
+		  message: '#find\(\) should return int\<1\, max\>\|null but returns int\|null\.#'

src/CpuCoreCounter.php

@@ -14,6 +14,7 @@
 namespace Fidry\CpuCoreCounter;
 
 use Fidry\CpuCoreCounter\Finder\CpuCoreFinder;
+use Fidry\CpuCoreCounter\Finder\EnvVariableFinder;
 use Fidry\CpuCoreCounter\Finder\FinderRegistry;
 
 final class CpuCoreCounter
@@ -37,15 +38,27 @@ public function __construct(?array $finders = null)
     }
 
     /**
-     * @param positive-int $reservedCpus
+     * @param positive-int      $reservedCpus
+     * @param positive-int|null $limit        If no limit is given, all available CPUs will be returned.
      *
      * @return positive-int
      */
-    public function getAvailableForParallelisation(int $reservedCpus = 1): int
-    {
+    public function getAvailableForParallelisation(
+        int $reservedCpus = 1,
+        ?int $limit = null
+    ): int {
+        $limit = null === $limit
+            ? self::getKubernetesLimit()
+            : $limit;
+
         $count = $this->getCountWithFallback(1);
+
         $availableCpus = $count - $reservedCpus;
 
+        if (null !== $limit && $availableCpus > $limit) {
+            $availableCpus = $limit;
+        }
+
         return max(1, $availableCpus);
     }
 
@@ -113,4 +126,11 @@ public function getFinderAndCores(): array
 
         throw NumberOfCpuCoreNotFound::create();
     }
+
+    public static function getKubernetesLimit(): ?int
+    {
+        $finder = new EnvVariableFinder('KUBERNETES_CPU_LIMIT');
+
+        return $finder->find();
+    }
 }

src/Finder/EnvVariableFinder.php

@@ -0,0 +1,69 @@
+<?php
+
+/*
+ * This file is part of the Fidry CPUCounter Config package.
+ *
+ * (c) Théo FIDRY <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Fidry\CpuCoreCounter\Finder;
+
+use function getenv;
+use function preg_match;
+use function sprintf;
+use function var_export;
+
+final class EnvVariableFinder implements CpuCoreFinder
+{
+    /** @var string */
+    private $environmentVariableName;
+
+    public function __construct(string $environmentVariableName)
+    {
+        $this->environmentVariableName = $environmentVariableName;
+    }
+
+    public function diagnose(): string
+    {
+        $value = getenv($this->environmentVariableName);
+
+        return sprintf(
+            'parse(getenv(%s)=%s)=%s',
+            $this->environmentVariableName,
+            var_export($value, true),
+            self::isPositiveInteger($value) ? $value : 'null'
+        );
+    }
+
+    public function find(): ?int
+    {
+        $value = getenv($this->environmentVariableName);
+
+        return self::isPositiveInteger($value)
+            ? (int) $value
+            : null;
+    }
+
+    public function toString(): string
+    {
+        return sprintf(
+            'getenv(%s)',
+            $this->environmentVariableName
+        );
+    }
+
+    /**
+     * @param string|false $value
+     */
+    private static function isPositiveInteger($value): bool
+    {
+        return false !== $value
+            && 1 === preg_match('/^\d+$/', $value)
+            && (int) $value > 0;
+    }
+}

tests/CpuCoreCounterTest.php

@@ -13,6 +13,7 @@
 
 namespace Fidry\CpuCoreCounter\Test;
 
+use Closure;
 use Exception;
 use Fidry\CpuCoreCounter\CpuCoreCounter;
 use Fidry\CpuCoreCounter\Finder\CpuCoreFinder;
@@ -22,6 +23,7 @@
 use PHPUnit\Framework\TestCase;
 use function get_class;
 use function is_array;
+use function sprintf;
 
 /**
  * @covers \Fidry\CpuCoreCounter\CpuCoreCounter
@@ -30,6 +32,21 @@
  */
 final class CpuCoreCounterTest extends TestCase
 {
+    /**
+     * @var null|Closure(): void
+     */
+    private $cleanupEnvironmentVariables;
+
+    protected function tearDown(): void
+    {
+        $cleanupEnvironmentVariables = $this->cleanupEnvironmentVariables;
+
+        if (null !== $cleanupEnvironmentVariables) {
+            ($cleanupEnvironmentVariables)();
+            $this->cleanupEnvironmentVariables = null;
+        }
+    }
+
     public function test_it_can_get_the_number_of_cpu_cores(): void
     {
         $counter = new CpuCoreCounter();
@@ -154,19 +171,29 @@ public static function cpuCoreFinderProvider(): iterable
     /**
      * @dataProvider availableCpuCoreProvider
      *
-     * @param list<CpuCoreFinder> $finders
-     * @param positive-int        $expected
+     * @param list<CpuCoreFinder>        $finders
+     * @param array<string, string|null> $environmentVariables
+     * @param positive-int               $expected
      */
     public function test_it_can_get_the_number_of_available_cpu_cores_for_parallelisation(
         array $finders,
+        array $environmentVariables,
         ?int $reservedCpus,
+        ?int $limit,
         int $expected
     ): void {
+        $this->setUpEnvironmentVariables($environmentVariables);
+
         $counter = new CpuCoreCounter($finders);
 
+        // Sanity check: this is due to not being able to use named parameters.
+        if (null === $reservedCpus) {
+            self::assertNull($limit);
+        }
+
         $actual = null === $reservedCpus
             ? $counter->getAvailableForParallelisation()
-            : $counter->getAvailableForParallelisation($reservedCpus);
+            : $counter->getAvailableForParallelisation($reservedCpus, $limit);
 
         self::assertSame($expected, $actual);
     }
@@ -175,32 +202,112 @@ public static function availableCpuCoreProvider(): iterable
     {
         yield 'no finder' => [
             [],
+            [],
+            null,
             null,
             1,
         ];
 
         yield 'no finder, multiple CPUs reserved' => [
+            [],
             [],
             3,
+            null,
             1,
         ];
 
+        yield 'CPU count found: kubernetes limit set and lower than the count found' => (static function () {
+            $finder = new DummyCpuCoreFinder(5);
+
+            return [
+                [$finder],
+                ['KUBERNETES_CPU_LIMIT' => 2],
+                null,
+                null,
+                2,
+            ];
+        })();
+
+        yield 'CPU count found: kubernetes limit set and higher than the count found' => (static function () {
+            $finder = new DummyCpuCoreFinder(5);
+
+            return [
+                [$finder],
+                ['KUBERNETES_CPU_LIMIT' => 8],
+                null,
+                null,
+                4,
+            ];
+        })();
+
+        yield 'CPU count found: kubernetes limit set and equal to the count found' => (static function () {
+            $finder = new DummyCpuCoreFinder(5);
+
+            return [
+                [$finder],
+                ['KUBERNETES_CPU_LIMIT' => 5],
+                null,
+                null,
+                4,
+            ];
+        })();
+
+        yield 'CPU count found: kubernetes limit set and equal to the count found after reserved CPUs' => (static function () {
+            $finder = new DummyCpuCoreFinder(5);
+
+            return [
+                [$finder],
+                ['KUBERNETES_CPU_LIMIT' => 4],
+                null,
+                null,
+                4,
+            ];
+        })();
+
+        yield 'CPU count found: kubernetes limit set and limit set' => (static function () {
+            $finder = new DummyCpuCoreFinder(5);
+
+            return [
+                [$finder],
+                ['KUBERNETES_CPU_LIMIT' => 2],
+                1,
+                3,
+                3,
+            ];
+        })();
+
         yield 'CPU count found' => (static function () {
             $finder = new DummyCpuCoreFinder(5);
 
             return [
                 [$finder],
+                [],
+                null,
                 null,
                 4,
             ];
         })();
 
+        yield 'CPU count found higher than the limit passed' => (static function () {
+            $finder = new DummyCpuCoreFinder(5);
+
+            return [
+                [$finder],
+                [],
+                1,
+                3,
+                3,
+            ];
+        })();
+
         yield 'CPU count found, multiple CPUs reserved' => (static function () {
             $finder = new DummyCpuCoreFinder(5);
 
             return [
                 [$finder],
+                [],
                 2,
+                null,
                 3,
             ];
         })();
@@ -210,9 +317,39 @@ public static function availableCpuCoreProvider(): iterable
 
             return [
                 [$finder],
+                [],
                 5,
+                null,
                 1,
             ];
         })();
     }
+
+    /**
+     * @param array<string, string|null> $environmentVariables
+     */
+    private function setUpEnvironmentVariables(array $environmentVariables): void
+    {
+        $cleanupCalls = [];
+
+        foreach ($environmentVariables as $environmentName => $environmentValue) {
+            putenv(
+                sprintf(
+                    '%s=%s',
+                    $environmentName,
+                    $environmentValue
+                )
+            );
+
+            $cleanupCalls[] = static function () use ($environmentName): void {
+                putenv($environmentName);
+            };
+        }
+
+        $this->cleanupEnvironmentVariables = static function () use ($cleanupCalls): void {
+            foreach ($cleanupCalls as $cleanupCall) {
+                $cleanupCall();
+            }
+        };
+    }
 }