Control when PHP's garbage collector is triggered

ChangeLog-10.3.md

@@ -7,6 +7,7 @@ All notable changes of the PHPUnit 10.3 release series are documented in this fi
 ### Added
 
 * [#5428](https://github.com/sebastianbergmann/phpunit/issues/5428): Attribute `#[WithoutErrorHandler]` to disable PHPUnit's error handler for a test method
+* [#5368](https://github.com/sebastianbergmann/phpunit/pull/5368): Control when PHP's garbage collector is triggered
 * [#5431](https://github.com/sebastianbergmann/phpunit/pull/5431): Add more garbage collector details to event telemetry
 
 ### Changed

phpunit.xsd

@@ -172,6 +172,8 @@
         <xs:attribute name="cacheResultFile" type="xs:anyURI"/>
         <xs:attribute name="colors" type="xs:boolean" default="false"/>
         <xs:attribute name="columns" type="columnsType" default="80"/>
+        <xs:attribute name="controlGarbageCollector" type="xs:boolean" default="false"/>
+        <xs:attribute name="numberOfTestsBeforeGarbageCollection" type="xs:integer" default="100"/>
         <xs:attribute name="requireCoverageMetadata" type="xs:boolean" default="false"/>
         <xs:attribute name="processIsolation" type="xs:boolean" default="false"/>
         <xs:attribute name="failOnDeprecation" type="xs:boolean" default="false"/>

src/Event/Emitter/DispatchingEmitter.php

@@ -234,6 +234,28 @@ public function testRunnerExecutionStarted(TestSuite $testSuite): void
         );
     }
 
+    /**
+     * @throws InvalidArgumentException
+     * @throws UnknownEventTypeException
+     */
+    public function testRunnerDisabledGarbageCollection(): void
+    {
+        $this->dispatcher->dispatch(
+            new TestRunner\GarbageCollectionDisabled($this->telemetryInfo()),
+        );
+    }
+
+    /**
+     * @throws InvalidArgumentException
+     * @throws UnknownEventTypeException
+     */
+    public function testRunnerTriggeredGarbageCollection(): void
+    {
+        $this->dispatcher->dispatch(
+            new TestRunner\GarbageCollectionTriggered($this->telemetryInfo()),
+        );
+    }
+
     /**
      * @throws InvalidArgumentException
      * @throws UnknownEventTypeException
@@ -1057,6 +1079,17 @@ public function testRunnerTriggeredWarning(string $message): void
         );
     }
 
+    /**
+     * @throws InvalidArgumentException
+     * @throws UnknownEventTypeException
+     */
+    public function testRunnerEnabledGarbageCollection(): void
+    {
+        $this->dispatcher->dispatch(
+            new TestRunner\GarbageCollectionEnabled($this->telemetryInfo()),
+        );
+    }
+
     /**
      * @throws InvalidArgumentException
      * @throws UnknownEventTypeException

src/Event/Emitter/Emitter.php

@@ -51,6 +51,10 @@ public function testRunnerEventFacadeSealed(): void;
 
     public function testRunnerExecutionStarted(TestSuite $testSuite): void;
 
+    public function testRunnerDisabledGarbageCollection(): void;
+
+    public function testRunnerTriggeredGarbageCollection(): void;
+
     public function testSuiteSkipped(TestSuite $testSuite, string $message): void;
 
     public function testSuiteStarted(TestSuite $testSuite): void;
@@ -224,6 +228,8 @@ public function testRunnerTriggeredDeprecation(string $message): void;
 
     public function testRunnerTriggeredWarning(string $message): void;
 
+    public function testRunnerEnabledGarbageCollection(): void;
+
     public function testRunnerExecutionAborted(): void;
 
     public function testRunnerExecutionFinished(): void;

src/Event/Events/TestRunner/GarbageCollectionDisabled.php

@@ -0,0 +1,38 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Event\TestRunner;
+
+use PHPUnit\Event\Event;
+use PHPUnit\Event\Telemetry;
+
+/**
+ * @psalm-immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+final class GarbageCollectionDisabled implements Event
+{
+    private readonly Telemetry\Info $telemetryInfo;
+
+    public function __construct(Telemetry\Info $telemetryInfo)
+    {
+        $this->telemetryInfo = $telemetryInfo;
+    }
+
+    public function telemetryInfo(): Telemetry\Info
+    {
+        return $this->telemetryInfo;
+    }
+
+    public function asString(): string
+    {
+        return 'Test Runner Disabled Garbage Collection';
+    }
+}

src/Event/Events/TestRunner/GarbageCollectionDisabledSubscriber.php

@@ -0,0 +1,20 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Event\TestRunner;
+
+use PHPUnit\Event\Subscriber;
+
+/**
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+interface GarbageCollectionDisabledSubscriber extends Subscriber
+{
+    public function notify(GarbageCollectionDisabled $event): void;
+}

src/Event/Events/TestRunner/GarbageCollectionEnabled.php

@@ -0,0 +1,38 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Event\TestRunner;
+
+use PHPUnit\Event\Event;
+use PHPUnit\Event\Telemetry;
+
+/**
+ * @psalm-immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+final class GarbageCollectionEnabled implements Event
+{
+    private readonly Telemetry\Info $telemetryInfo;
+
+    public function __construct(Telemetry\Info $telemetryInfo)
+    {
+        $this->telemetryInfo = $telemetryInfo;
+    }
+
+    public function telemetryInfo(): Telemetry\Info
+    {
+        return $this->telemetryInfo;
+    }
+
+    public function asString(): string
+    {
+        return 'Test Runner Enabled Garbage Collection';
+    }
+}

src/Event/Events/TestRunner/GarbageCollectionEnabledSubscriber.php

@@ -0,0 +1,20 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Event\TestRunner;
+
+use PHPUnit\Event\Subscriber;
+
+/**
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+interface GarbageCollectionEnabledSubscriber extends Subscriber
+{
+    public function notify(GarbageCollectionEnabled $event): void;
+}

src/Event/Events/TestRunner/GarbageCollectionTriggered.php

@@ -0,0 +1,38 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Event\TestRunner;
+
+use PHPUnit\Event\Event;
+use PHPUnit\Event\Telemetry;
+
+/**
+ * @psalm-immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+final class GarbageCollectionTriggered implements Event
+{
+    private readonly Telemetry\Info $telemetryInfo;
+
+    public function __construct(Telemetry\Info $telemetryInfo)
+    {
+        $this->telemetryInfo = $telemetryInfo;
+    }
+
+    public function telemetryInfo(): Telemetry\Info
+    {
+        return $this->telemetryInfo;
+    }
+
+    public function asString(): string
+    {
+        return 'Test Runner Triggered Garbage Collection';
+    }
+}

src/Event/Events/TestRunner/GarbageCollectionTriggeredSubscriber.php

@@ -0,0 +1,20 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Event\TestRunner;
+
+use PHPUnit\Event\Subscriber;
+
+/**
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+interface GarbageCollectionTriggeredSubscriber extends Subscriber
+{
+    public function notify(GarbageCollectionTriggered $event): void;
+}

src/Event/Facade.php

@@ -230,6 +230,9 @@ private function registerDefaultTypes(TypeMap $typeMap): void
             TestRunner\Started::class,
             TestRunner\DeprecationTriggered::class,
             TestRunner\WarningTriggered::class,
+            TestRunner\GarbageCollectionDisabled::class,
+            TestRunner\GarbageCollectionTriggered::class,
+            TestRunner\GarbageCollectionEnabled::class,
 
             TestSuite\Filtered::class,
             TestSuite\Finished::class,

src/Runner/GarbageCollection/GarbageCollectionHandler.php

@@ -0,0 +1,87 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Runner\GarbageCollection;
+
+use function gc_collect_cycles;
+use function gc_disable;
+use function gc_enable;
+use PHPUnit\Event\EventFacadeIsSealedException;
+use PHPUnit\Event\Facade;
+use PHPUnit\Event\UnknownSubscriberTypeException;
+
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
+final class GarbageCollectionHandler
+{
+    private readonly Facade $facade;
+    private readonly int $threshold;
+    private int $tests = 0;
+
+    /**
+     * @throws EventFacadeIsSealedException
+     * @throws UnknownSubscriberTypeException
+     */
+    public function __construct(Facade $facade, int $threshold)
+    {
+        $this->facade    = $facade;
+        $this->threshold = $threshold;
+
+        $this->registerSubscribers();
+    }
+
+    public function executionStarted(): void
+    {
+        gc_disable();
+
+        $this->facade->emitter()->testRunnerDisabledGarbageCollection();
+
+        gc_collect_cycles();
+
+        $this->facade->emitter()->testRunnerTriggeredGarbageCollection();
+    }
+
+    public function executionFinished(): void
+    {
+        gc_collect_cycles();
+
+        $this->facade->emitter()->testRunnerTriggeredGarbageCollection();
+
+        gc_enable();
+
+        $this->facade->emitter()->testRunnerEnabledGarbageCollection();
+    }
+
+    public function testFinished(): void
+    {
+        $this->tests++;
+
+        if ($this->tests === $this->threshold) {
+            gc_collect_cycles();
+
+            $this->facade->emitter()->testRunnerTriggeredGarbageCollection();
+
+            $this->tests = 0;
+        }
+    }
+
+    /**
+     * @throws EventFacadeIsSealedException
+     * @throws UnknownSubscriberTypeException
+     */
+    private function registerSubscribers(): void
+    {
+        $this->facade->registerSubscribers(
+            new ExecutionStartedSubscriber($this),
+            new ExecutionFinishedSubscriber($this),
+            new TestFinishedSubscriber($this),
+        );
+    }
+}

src/Runner/GarbageCollection/Subscriber/ExecutionFinishedSubscriber.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Runner\GarbageCollection;
+
+use PHPUnit\Event\InvalidArgumentException;
+use PHPUnit\Event\TestRunner\ExecutionFinished;
+use PHPUnit\Event\TestRunner\ExecutionFinishedSubscriber as TestRunnerExecutionFinishedSubscriber;
+
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
+final class ExecutionFinishedSubscriber extends Subscriber implements TestRunnerExecutionFinishedSubscriber
+{
+    /**
+     * @throws \PHPUnit\Framework\InvalidArgumentException
+     * @throws InvalidArgumentException
+     */
+    public function notify(ExecutionFinished $event): void
+    {
+        $this->handler()->executionFinished();
+    }
+}