feat: support concurrent runtime contexts

analysis-baseline.toml

@@ -198,12 +198,6 @@ code = "reference-to-undefined-variable"
 message = "Reference created from a previously undefined variable `$matches`."
 count = 1
 
-[[issues]]
-file = "src/ErrorHandler.php"
-code = "write-only-property"
-message = "Property `$reservedMemory` is written to but never read."
-count = 1
-
 [[issues]]
 file = "src/Event.php"
 code = "impossible-condition"

src/ErrorHandler.php

@@ -112,8 +112,6 @@ final class ErrorHandler
 
     /**
      * @var string|null A portion of pre-allocated memory data that will be reclaimed in case a fatal error occurs to handle it
-     *
-     * @phpstan-ignore-next-line This property is used to reserve memory for the fatal error handler and is thus never read
      */
     private static $reservedMemory;
 
@@ -315,7 +313,10 @@ public static function resetFatalErrorHandlerState(): void
         self::$disableFatalErrorHandler = false;
         self::$didIncreaseMemoryLimit = false;
 
-        if (self::$handlerInstance !== null && self::$handlerInstance->isFatalErrorHandlerRegistered) {
+        if (self::$handlerInstance !== null
+            && self::$handlerInstance->isFatalErrorHandlerRegistered
+            && self::$reservedMemory === null
+        ) {
             self::$reservedMemory = str_repeat('x', self::$reservedMemorySize);
         }
     }

src/SentrySdk.php

@@ -10,6 +10,7 @@
 use Sentry\State\HubInterface;
 use Sentry\State\RuntimeContext;
 use Sentry\State\RuntimeContextManager;
+use Sentry\State\RuntimeContextStorageInterface;
 
 /**
  * This class is the main entry point for all the most common SDK features.
@@ -28,6 +29,11 @@ final class SentrySdk
      */
     private static $runtimeContextManager;
 
+    /**
+     * @var RuntimeContextStorageInterface|null
+     */
+    private static $runtimeContextStorage;
+
     /**
      * Constructor.
      */
@@ -41,12 +47,34 @@ private function __construct()
      */
     public static function init(): HubInterface
     {
+        if (self::$runtimeContextManager !== null) {
+            self::$runtimeContextManager->discardActiveContext();
+        }
+
         self::$currentHub = new Hub();
-        self::$runtimeContextManager = new RuntimeContextManager(self::$currentHub);
+        self::$runtimeContextManager = null;
 
         return self::getCurrentHub();
     }
 
+    /**
+     * Registers storage for isolating runtime contexts across overlapping logical executions.
+     *
+     * The registration persists across SDK initialization. Changing it discards the active
+     * context for the current logical execution without flushing it. Concurrent runtimes
+     * should register storage before logical executions begin and must not replace it while
+     * other logical executions are active.
+     */
+    public static function setRuntimeContextStorage(?RuntimeContextStorageInterface $runtimeContextStorage): void
+    {
+        if (self::$runtimeContextManager !== null) {
+            self::$runtimeContextManager->discardActiveContext();
+        }
+
+        self::$runtimeContextStorage = $runtimeContextStorage;
+        self::$runtimeContextManager = null;
+    }
+
     /**
      * Gets the current hub. If it's not initialized then creates a new instance
      * and sets it as current hub.
@@ -89,7 +117,7 @@ public static function endContext(?int $timeout = null): void
     /**
      * Executes the given callback within an isolated context.
      *
-     * If a context is already active for the current execution key, this method
+     * If a context is already active for the current logical execution, this method
      * reuses it and only executes the callback.
      *
      * @param callable $callback The callback to execute
@@ -105,11 +133,7 @@ public static function endContext(?int $timeout = null): void
     public static function withContext(callable $callback, ?int $timeout = null)
     {
         $runtimeContextManager = self::getRuntimeContextManager();
-        $startedNewContext = !$runtimeContextManager->hasActiveContext();
-
-        if ($startedNewContext) {
-            $runtimeContextManager->startContext();
-        }
+        $startedNewContext = $runtimeContextManager->startContext();
 
         try {
             return $callback();
@@ -159,7 +183,7 @@ private static function getRuntimeContextManager(): RuntimeContextManager
         }
 
         if (self::$runtimeContextManager === null) {
-            self::$runtimeContextManager = new RuntimeContextManager(self::$currentHub);
+            self::$runtimeContextManager = new RuntimeContextManager(self::$currentHub, self::$runtimeContextStorage);
         }
 
         return self::$runtimeContextManager;

src/State/RuntimeContext.php

@@ -13,7 +13,8 @@
  * A unit of work can be an HTTP request, a queue job, a worker task, or any
  * explicit lifecycle wrapped with startContext()/endContext().
  *
- * @internal
+ * Storage implementations should treat instances as opaque values owned by the
+ * SDK and must not create or mutate them directly.
  */
 final class RuntimeContext
 {
@@ -37,6 +38,9 @@ final class RuntimeContext
      */
     private $metricsAggregator;
 
+    /**
+     * @internal
+     */
     public function __construct(string $id, HubInterface $hub)
     {
         $this->id = $id;
@@ -45,26 +49,41 @@ public function __construct(string $id, HubInterface $hub)
         $this->metricsAggregator = new MetricsAggregator();
     }
 
+    /**
+     * @internal
+     */
     public function getId(): string
     {
         return $this->id;
     }
 
+    /**
+     * @internal
+     */
     public function getHub(): HubInterface
     {
         return $this->hub;
     }
 
+    /**
+     * @internal
+     */
     public function setHub(HubInterface $hub): void
     {
         $this->hub = $hub;
     }
 
+    /**
+     * @internal
+     */
     public function getLogsAggregator(): LogsAggregator
     {
         return $this->logsAggregator;
     }
 
+    /**
+     * @internal
+     */
     public function getMetricsAggregator(): MetricsAggregator
     {
         return $this->metricsAggregator;