Merge pull request #7 from reactphp-parallel/add-runtime-stub

Add Runtime stub

Author: WyriHaximus

etc/qa/phpstan.neon

@@ -7,10 +7,11 @@ parameters:
 				- ReactParallel\EventLoop\CanceledFuture
 				- ReactParallel\EventLoop\KilledRuntime
 	stubFiles:
+		- ../../stubs/Channel.stub
 		- ../../stubs/Event.stub
-		- ../../stubs/Future.stub
 		- ../../stubs/functions.stub
-		- ../../stubs/Channel.stub
+		- ../../stubs/Future.stub
+		- ../../stubs/Runtime.stub
 
 includes:
 	- ../../vendor/wyrihaximus/async-test-utilities/rules.neon

extension.neon

@@ -4,3 +4,4 @@ parameters:
 		- stubs/Event.stub
 		- stubs/functions.stub
 		- stubs/Future.stub
+		- stubs/Runtime.stub

stubs/Runtime.stub

@@ -0,0 +1,60 @@
+<?php
+
+namespace parallel;
+
+use Closure;
+
+/**
+ * Each runtime represents a single PHP thread, the thread is created (and bootstrapped) upon construction. The thread
+ * then waits for tasks to be scheduled: Scheduled tasks will be executed FIFO and then the thread will resume waiting
+ * until more tasks are scheduled, or it's closed, killed, or destroyed by the normal scoping rules of PHP objects.
+ *
+ * Warning: When a runtime is destroyed by the normal scoping rules of PHP objects, it will first execute all of the
+ * tasks that were scheduled, and block while doing so.
+ *
+ * When a new runtime is created, it does not share code with the thread (or process) that created it. This means it
+ * doesn't have the same classes and functions loaded, nor the same autoloader set. In some cases, a very lightweight
+ * runtime is desirable because the tasks that will be scheduled do not need access to the code in the parent thread.
+ * In those cases where the tasks do need to access the same code, it is enough to set an autoloader as the bootstrap.
+ *
+ * Note: preloading may be used in conjunction with parallel, in this case preloaded code is available without
+ * bootstrapping
+ */
+final class Runtime
+{
+    /* Create */
+
+    /**
+     * @throws Runtime\Error if thread could not be created
+     * @throws Runtime\Error\Bootstrap if bootstrapping failed
+     */
+    public function __construct(?string $bootstrap = null) {}
+
+    /* Execute */
+
+    /**
+     * @param (Closure():T)|(Closure():void) $task
+     * @param array<mixed>                   $argv
+     * @template T
+     * @return ($task is (Closure():T) ? Future<T> : null)
+     *
+     * @throws Runtime\Error\Closed if \parallel\Runtime was closed.
+     * @throws Runtime\Error\IllegalFunction if task is a closure created from an internal function.
+     * @throws Runtime\Error\IllegalInstruction if task contains illegal instructions.
+     * @throws Runtime\Error\IllegalParameter if task accepts or argv contains illegal variables.
+     * @throws Runtime\Error\IllegalReturn if task returns illegally.
+     */
+    public function run(Closure $task, ?array $argv = null): ?Future {}
+
+    /* Join */
+
+    /**
+     * @throws Runtime\Error\Closed if Runtime was already closed.
+     */
+    public function close(): void {}
+
+    /**
+     * @throws Runtime\Error\Closed if Runtime was closed.
+     */
+    public function kill(): void {}
+}