update stubs for ext-parallel

PhpStormStubsMap.php

@@ -3577,6 +3577,7 @@ const FUNCTIONS = array (
   'output_reset_rewrite_vars' => 'standard/standard_9.php',
   'pack' => 'standard/standard_7.php',
   'parallel\\bootstrap' => 'parallel/parallel.php',
+  'parallel\\count' => 'parallel/parallel.php',
   'parallel\\run' => 'parallel/parallel.php',
   'parse_ini_file' => 'standard/standard_4.php',
   'parse_ini_string' => 'standard/standard_4.php',

parallel/parallel.php

@@ -3,33 +3,43 @@
 namespace parallel;
 
 use Closure;
-use parallel\Runtime\Error\Bootstrap;
 
 /**
- * Shall use the provided file to bootstrap all runtimes created for automatic scheduling via parallel\run().
+ * Shall use the provided file to bootstrap all runtimes created for automatic scheduling via @see run().
  *
  * @param string $file
  *
- * @return void
- *
- * @throws Bootstrap if previously called for this process.
- * @throws Bootstrap if called after parallel\run().
+ * @throws Runtime\Error\Bootstrap if previously called for this process.
+ * @throws Runtime\Error\Bootstrap if called after @see run().
  */
-function bootstrap(string $file) {}
+function bootstrap(string $file) : void{}
 
 /**
- * @see Runtime::run for run details and schematics
+ * @see Runtime::run() for more details
  *
- * @param Closure $task A Closure with specific characteristics.
- * @param array|null $argv An array of arguments with specific characteristics to be passed to task at execution time.
+ * @param Closure $task
+ * @param array   $argv
  *
- * @return Future
- * Warning: The return \parallel\Future must not be ignored when the task contains a return or throw statement.
+ * ### Automatic Scheduling
+ * ---------------------------------------------------------------------------------------------------------------------
+ * If a \parallel\Runtime internally created and cached by a previous call to parallel\run() is idle, it will be used
+ *     to execute the task. If no \parallel\Runtime is idle parallel will create and cache a \parallel\Runtime.
  *
- * @throws Runtime\Error\Closed if Runtime was closed.
+ * Note: \parallel\Runtime objects created by the programmer are not used for automatic scheduling.
+ *
+ * @return Future|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.
  */
-function run(Closure $task, array $argv = null) : Future {}
+function run(Closure $task, array $argv = null) : ?Future{}
+
+#ifdef ZEND_DEBUG
+/**
+ * @return int
+ */
+function count() : int{}
+#endif

parallel/parallel/Channel.php

@@ -2,61 +2,107 @@
 
 namespace parallel;
 
-use parallel\Channel\Error\Closed;
-use parallel\Channel\Error\Existence;
-use parallel\Channel\Error\IllegalValue;
+/**
+ * ### Unbuffered Channels
+ * ---------------------------------------------------------------------------------------------------------------------
+ * An unbuffered channel will block on calls to @see Channel::send() until there is a receiver, and block on calls
+ * to @see Channel::recv() until there is a sender. This means an unbuffered channel is not only a way to share
+ * data among tasks but also a simple method of synchronization.
+ *
+ *  An unbuffered channel is the fastest way to share data among tasks, requiring the least copying.
+ *
+ * ### Buffered Channels
+ * ---------------------------------------------------------------------------------------------------------------------
+ *  A buffered channel will not block on calls to @see Channel::send() until capacity is reached, calls to
+ * @see Channel::recv() will block until there is data in the buffer.
+ *
+ * ### Closures over Channels
+ * ---------------------------------------------------------------------------------------------------------------------
+ * A powerful feature of parallel channels is that they allow the exchange of closures between tasks (and runtimes).
+ *
+ * When a closure is sent over a channel the closure is buffered, it doesn't change the buffering of the channel
+ *     transmitting the closure, but it does effect the static scope inside the closure: The same closure sent to
+ *     different runtimes, or the same runtime, will not share their static scope.
+ *
+ * This means that whenever a closure is executed that was transmitted by a channel, static state will be as it was
+ *     when the closure was buffered.
+ *
+ * ### Anonymous Channels
+ * ---------------------------------------------------------------------------------------------------------------------
+ * The anonymous channel constructor allows the programmer to avoid assigning names to every channel: parallel will
+ *     generate a unique name for anonymous channels.
+ */
+final class Channel{
 
-final class Channel
-{
-    public const Infinite = -1;
+	/**
+	 * Constant for Infinitely Buffered
+	 */
+	public const Infinite = -1;
 
-    /**
-     * Without capacity argument: Shall make an unbuffered channel with the given name.
-     * With capacity argument: Shall make a buffered channel with the given name and capacity
-     *
-     * @param string   $name     The name of the channel.
-     * @param int|null $capacity May be Channel::Infinite or a positive integer
-     *
-     * @return Channel
-     *
-     * @throws Existence if channel already exists.
-     */
-    public static function make(string $name, int $capacity = null): Channel {}
+	/* Anonymous Constructor */
 
-    /**
-     * Shall open the channel with the given name.
-     *
-     * @param string $name The name of the channel.
-     *
-     * @return Channel
-     *
-     * @throws Existence  if channel does not exist.
-     */
-    public static function open(string $name): Channel {}
+	/**
+	 * Shall make an anonymous unbuffered channel
+	 * Shall make an anonymous buffered channel with the given capacity
+	 *
+	 * @param int $capacity May be Channel::Infinite or a positive integer
+	 */
+	public function __construct(int $capacity = null){}
 
-    /**
-     * Shall recv a value from this channel.
-     *
-     * @return mixed
-     *
-     * @throws Closed if channel is closed.
-     */
-    public function recv() {}
+	/* Access */
 
-    /**
-     * Shall send the given value on this channel
-     *
-     * @param mixed $value
-     *
-     * @throws Closed if channel is closed.
-     * @throws IllegalValue if value is illegal. (Same arguments characteristics apply as for Runtime::run.)
-     */
-    public function send($value): void {}
+	/**
+	 * Shall make an unbuffered channel with the given name
+	 * Shall make a buffered channel with the given name and capacity
+	 *
+	 * @param string $name     The name of the channel.
+	 * @param int    $capacity May be Channel::Infinite or a positive integer
+	 *
+	 * @return Channel
+	 *
+	 * @throws Channel\Error\Existence if channel already exists.
+	 */
+	public static function make(string $name, int $capacity = null) : Channel{}
 
-    /**
-     * Shall close this channel.
-     *
-     * @throws Closed if channel is closed.
-     */
-    public function close(): void {}
-}
+	/**
+	 * Shall open the channel with the given name
+	 *
+	 * @param string $name
+	 * @return Channel
+	 *
+	 * @throws Channel\Error\Existence if channel does not exist.
+	 */
+	public static function open(string $name) : Channel{}
+
+	/* Sharing */
+
+	/**
+	 * Shall send the given value on this channel
+	 * @param mixed $value
+	 *
+	 * @throws Channel\Error\Closed if channel is closed.
+	 * @throws Channel\Error\IllegalValue if value is illegal.
+	 */
+	public function send($value) : void{}
+
+	/**
+	 * Shall recv a value from this channel
+	 * @return mixed
+	 *
+	 * @throws Channel\Error\Closed if channel is closed.
+	 */
+	public function recv(){}
+	/* Closing */
+
+	/**
+	 * Shall close this channel
+	 * @throws Channel\Error\Closed if channel is closed.
+	 */
+	public function close() : void{}
+
+	/**
+	 * Returns name of channel
+	 * @return string
+	 */
+	public function __toString() : string{}
+}

parallel/parallel/Channel/Error.php

@@ -2,8 +2,5 @@
 
 namespace parallel\Channel;
 
-use parallel\Error as ParallelError;
-
-class Error extends ParallelError
-{
-}
+class Error extends \parallel\Error{
+}

parallel/parallel/Channel/Error/Closed.php

@@ -4,6 +4,5 @@ namespace parallel\Channel\Error;
 
 use parallel\Channel\Error;
 
-class Closed extends Error
-{
-}
+class Closed extends Error{
+}

parallel/parallel/Channel/Error/Existence.php

@@ -4,6 +4,5 @@ namespace parallel\Channel\Error;
 
 use parallel\Channel\Error;
 
-class Existence extends Error
-{
-}
+class Existence extends Error{
+}

parallel/parallel/Channel/Error/IllegalValue.php

@@ -4,6 +4,5 @@ namespace parallel\Channel\Error;
 
 use parallel\Channel\Error;
 
-class IllegalValue extends Error
-{
-}
+class IllegalValue extends Error{
+}

parallel/parallel/Error.php

@@ -2,8 +2,5 @@
 
 namespace parallel;
 
-use Error as CoreError;
-
-class Error extends CoreError
-{
-}
+class Error extends \Error{
+}

parallel/parallel/Events.php

@@ -2,102 +2,111 @@
 
 namespace parallel;
 
-use parallel\Events\Error;
-use parallel\Events\Error\Existence;
-use parallel\Events\Error\Timeout;
-use parallel\Events\Event;
-use parallel\Events\Input;
+use Countable;
+use parallel\Events\{Event, Input};
+use Traversable;
 
-final class Events
-{
-    /**
-     * Shall set input for this event loop.
-     *
-     * @param Input $input
-     *
-     * @return void
-     */
-    public function setInput(Input $input): void {}
+/**
+ * ### The Event Loop
+ * ---------------------------------------------------------------------------------------------------------------------
+ * The Event loop monitors the state of sets of futures and or channels (targets) in order to perform read
+ * (Future::value(), Channel::recv()) and write (Channel::send()) operations as the targets become available and the
+ * operations may be performed without blocking the event loop.
+ */
+final class Events implements Countable, Traversable{
 
-    /**
-     * Shall watch for events on the given channel.
-     *
-     * @param Channel $channel
-     *
-     * @return void
-     *
-     * @throws Existence if channel was already added.
-     */
-    public function addChannel(Channel $channel): void {}
+	/* Input */
 
-    /**
-     * Shall watch for events on the given future.
-     *
-     * @param string $name
-     * @param Future $future
-     *
-     * @return void
-     *
-     * @throws Existence if target with the given name was already added.
-     */
-    public function addFuture(string $name, Future $future): void {}
+	/**
+	 * Shall set input for this event loop
+	 * @param Events\Input $input
+	 */
+	public function setInput(Input $input) : void{}
 
-    /**
-     * Shall remove the given target.
-     *
-     * @param string $target
-     *
-     * @return void
-     *
-     * @throws Existence if target with the given name was not found.
-     */
-    public function remove(string $target): void {}
+	/* Targets */
 
-    /**
-     * Shall set blocking mode.
-     *
-     * By default when events are polled for, blocking will occur (at the PHP level) until the first event can be
-     * returned: Setting blocking mode to false will cause poll to return control if the first target polled is not
-     * ready.
-     *
-     * This differs from setting a timeout of 0 with parallel\Events::setTimeout(), since a timeout of 0, while
-     * allowed, will cause an exception to be raised, which may be extremely slow or wasteful if what is really
-     * desired is non-blocking behaviour.
-     *
-     * A non-blocking loop effects the return value of parallel\Events::poll(), such that it may be null before all
-     * events have been processed.
-     *
-     * @param bool $blocking
-     *
-     * @return void
-     *
-     * @throws Error if loop has timeout set.
-     */
-    public function setBlocking(bool $blocking): void {}
+	/**
+	 * Shall watch for events on the given channel
+	 * @param Channel $channel
+	 *
+	 * @throws Events\Error\Existence if channel was already added.
+	 */
+	public function addChannel(Channel $channel) : void{}
 
-    /**
-     * Shall set the timeout in microseconds.
-     *
-     * By default when events are polled for, blocking will occur (at the PHP level) until the first event can be
-     * returned: Setting the timeout causes an exception to be thrown when the timeout is reached
-     *
-     * This differs from setting blocking mode to false with parallel\Events::setBlocking(), which will not cause an
-     * exception to be thrown.
-     *
-     * @param int $timeout
-     *
-     * @return void
-     *
-     * @throws Error if loop is non-blocking.
-     */
-    public function setTimeout(int $timeout): void {}
+	/**
+	 * Shall watch for events on the given future
+	 *
+	 * @param string $name
+	 * @param Future $future
+	 *
+	 * @throws Events\Error\Existence if target with the given name was already added.
+	 */
+	public function addFuture(string $name, Future $future) : void{}
 
-    /**
-     * Shall poll for the next event.
-     *
-     * @return Event|null Should there be no targets remaining, null shall be returned. Should this be a non-blocking loop, and blocking would occur, null shall be returned. Otherwise Event is returned.
-     *
-     * @throws Timeout if timeout is used and reached.
-     */
-    public function poll(): Event {}
-}
+	/**
+	 * Shall remove the given target
+	 * @param string $target
+	 *
+	 * @throws Events\Error\Existence if target with the given name was not found.
+	 */
+	public function remove(string $target) : void{}
+
+	/* Behaviour */
+
+	/**
+	 * Shall set blocking mode
+	 *
+	 * By default when events are polled for, blocking will occur (at the PHP level) until the first event can be
+	 * returned: Setting blocking mode to false will cause poll to return control if the first target polled is not
+	 * ready.
+	 *
+	 * This differs from setting a timeout of 0 with @see Events::setTimeout(), since a timeout of 0, while
+	 * allowed, will cause an exception to be raised, which may be extremely slow or wasteful if what is really desired
+	 * is non-blocking behaviour.
+	 *
+	 * A non-blocking loop effects the return value of @see Events::poll(), such that it may be null before all events
+	 * have been processed.
+	 *
+	 * @param bool $blocking
+	 *
+	 * @throws Events\Error if loop has timeout set.
+	 */
+	public function setBlocking(bool $blocking) : void{}
+
+	/* Behaviour */
+
+	/**
+	 * Shall set the timeout in microseconds
+	 *
+	 * By default when events are polled for, blocking will occur (at the PHP level) until the first event can be
+	 * returned: Setting the timeout causes an exception to be thrown when the timeout is reached.
+	 *
+	 * This differs from setting blocking mode to false with @see Events::setBlocking(), which will not cause an
+	 * exception to be thrown.
+	 *
+	 * @throws Events\Error if loop is non-blocking.
+	 *
+	 * @param int $timeout
+	 */
+	public function setTimeout(int $timeout) : void{}
+
+	/* Polling */
+
+	/**
+	 * Shall poll for the next event
+	 *
+	 * Should there be no targets remaining, null shall be returned
+	 * Should this be a non-blocking loop, and blocking would occur, null shall be returned
+	 * Otherwise, the Event returned describes the event.
+	 *
+	 * @return Event|null
+	 *
+	 * @throws Events\Error\Timeout if timeout is used and reached.
+	 */
+	public function poll() : ?Event{}
+
+	/**
+	 * @return int
+	 */
+	public function count() : int{}
+}

parallel/parallel/Events/Error.php

@@ -2,8 +2,5 @@
 
 namespace parallel\Events;
 
-use parallel\Error as ParallelError;
-
-class Error extends ParallelError
-{
-}
+class Error extends \parallel\Error{
+}

parallel/parallel/Events/Error/Existence.php

@@ -4,6 +4,5 @@ namespace parallel\Events\Error;
 
 use parallel\Events\Error;
 
-class Existence extends Error
-{
-}
+class Existence extends Error{
+}

parallel/parallel/Events/Error/Timeout.php

@@ -4,6 +4,5 @@ namespace parallel\Events\Error;
 
 use parallel\Events\Error;
 
-class Timeout extends Error
-{
-}
+class Timeout extends Error{
+}

parallel/parallel/Events/Event.php

@@ -3,36 +3,31 @@
 namespace parallel\Events;
 
 /**
- * When an Event is returned, Event::$object shall be removed from the loop that returned it, should the event be a
- * write event the Input for Event::$source shall also be removed.
+ * When an Event is returned, @see Event::$object shall be removed from the loop that returned it, should the event be a
+ * write event the Input for @see Event::$source shall also be removed.
  */
-final class Event
-{
-    /**
-     * Shall be one of Event\Type constants.
-     *
-     * @var int
-     */
-    public $type;
+final class Event{
+	/**
+	 * Shall be one of Event\Type constants
+	 * @var int
+	 */
+	public $type;
 
-    /**
-     * Shall be the source of the event (target name).
-     *
-     * @var string
-     */
-    public $source;
+	/**
+	 * Shall be the source of the event (target name)
+	 * @var string
+	 */
+	public $source;
 
-    /**
-     * Shall be either Future or Channel.
-     *
-     * @var object
-     */
-    public $object;
+	/**
+	 * Shall be either Future or Channel
+	 * @var object
+	 */
+	public $object;
 
-    /***
-     * Shall be set for Read/Error events.
-     *
-     * @var mixed
-     */
-    public $value;
-}
+	/**
+	 * Shall be set for Read/Error events
+	 * @var mixed
+	 */
+	public $value;
+}

parallel/parallel/Events/Event/Error.php

@@ -0,0 +1,6 @@
+<?php
+
+namespace parallel\Events\Event;
+
+class Error extends \parallel\Error{
+}

parallel/parallel/Events/Event/Type.php

@@ -2,51 +2,22 @@
 
 namespace parallel\Events\Event;
 
-/**
- * The values of all constants are an implementation detail and cannot be relied upon.
- * @link https://github.com/krakjoe/parallel/issues/37#issuecomment-493502459
- */
-final class Type
-{
-    /**
-     * Event::$object was read into Event::$value
-     *
-     * @var int
-     */
-    public const Read = null;
+final class Type{
+	/** Event::$object was read into Event::$value */
+	public const Read = 1;
 
-    /**
-     * Input for Event::$source written to Event::$object
-     *
-     * @var int
-     */
-    public const Write = null;
+	/** Input for Event::$source written to Event::$object */
+	public const Write = 2;
 
-    /**
-     * Event::$object (Channel) was closed
-     *
-     * @var int
-     */
-    public const Close = null;
+	/** Event::$object (Channel) was closed */
+	public const Close = 3;
 
-    /**
-     * Event::$object (Future) was cancelled
-     *
-     * @var int
-     */
-    public const Cancel = null;
+	/** Event::$object (Future) was cancelled */
+	public const Cancel = 5;
 
-    /**
-     * Runtime executing Event::$object (Future) was killed
-     *
-     * @var int
-     */
-    public const Kill = null;
+	/** Runtime executing Event::$object (Future) was killed */
+	public const Kill = 6;
 
-    /**
-     * Event::$object (Future) raised error
-     *
-     * @var int
-     */
-    public const Error = null;
-}
+	/** Event::$object (Future) raised error */
+	public const Error = 4;
+}

parallel/parallel/Events/Input.php

@@ -2,37 +2,38 @@
 
 namespace parallel\Events;
 
-use parallel\Events\Input\Error\Existence;
-use parallel\Events\Input\Error\IllegalValue;
+/**
+ * ### Events Input
+ * ---------------------------------------------------------------------------------------------------------------------
+ * An Input object is a container for data that the @see \parallel\Events object will write to @see \parallel\Channel
+ * objects as they become available. Multiple event loops may share an Input container - parallel does not verify the
+ * contents of the container when it is set as the input for a \parallel\Events object.
+ *
+ * Note: When a parallel\Events object performs a write, the target is removed from the input object as if
+ * @see Input::remove() were called.
+ */
+final class Input{
 
-final class Input
-{
-    /**
-     * Shall set input for the given target
-     *
-     * @param string $target
-     * @param mixed  $value
-     *
-     * @return void
-     *
-     * @throws Existence if input for target already exists.
-     * @throws IllegalValue if value is illegal (object, null).
-     */
-    public function add(string $target, $value): void {}
+	/**
+	 * Shall set input for the given target
+	 *
+	 * @param string $target
+	 * @param mixed  $value
+	 *
+	 * @throws Input\Error\Existence if input for target already exists.
+	 * @throws Input\Error\IllegalValue if value is illegal (object, null).
+	 */
+	public function add(string $target, $value) : void{}
 
-    /**
-     * Shall remove input for the given target.
-     *
-     * @param string $target
-     *
-     * @throws Existence if input for target does not exist.
-     */
-    public function remove(string $target): void {}
+	/**
+	 * Shall remove input for the given target
+	 * @param string $target
+	 * @throws Input\Error\Existence if input for target does not exist.
+	 */
+	public function remove(string $target) : void{}
 
-    /**
-     * Shall remove input for all targets.
-     *
-     * @return void
-     */
-    public function clear(): void {}
-}
+	/**
+	 * Shall remove input for all targets
+	 */
+	public function clear() : void{}
+}

parallel/parallel/Events/Input/Error.php

@@ -2,8 +2,5 @@
 
 namespace parallel\Events\Input;
 
-use parallel\Error as ParallelError;
-
-class Error extends ParallelError
-{
-}
+class Error extends \parallel\Error{
+}

parallel/parallel/Events/Input/Error/Existence.php

@@ -4,6 +4,5 @@ namespace parallel\Events\Input\Error;
 
 use parallel\Events\Input\Error;
 
-class Existence extends Error
-{
-}
+class Existence extends Error{
+}

parallel/parallel/Events/Input/Error/IllegalValue.php

@@ -4,6 +4,5 @@ namespace parallel\Events\Input\Error;
 
 use parallel\Events\Input\Error;
 
-class IllegalValue extends Error
-{
-}
+class IllegalValue extends Error{
+}

parallel/parallel/Future.php

@@ -2,45 +2,58 @@
 
 namespace parallel;
 
-use parallel\Future\Error;
 use Throwable;
 
-final class Future
-{
-    /**
-     * Shall return (and if necessary wait for) return from task.
-     *
-     * @throws Error if waiting failed (internal error).
-     * @throws Error\Killed if the Runtime executing task was killed.
-     * @throws Error\Cancelled if task was already cancelled.
-     * @throws Error\Foreign if task raised an unrecognized uncaught exception.
-     * @throws Throwable Shall rethrow \Throwable uncaught in task
-     *
-     * @return mixed
-     */
-    public function value() {}
+/**
+ * A Future represents the return value or uncaught exception from a task, and exposes an API for cancellation.
+ *
+ * The behaviour of a future also allows it to be used as a simple synchronization point even where the task does not
+ * return a value explicitly.
+ *
+ * @examples https://www.php.net/manual/ru/class.parallel-future.php
+ */
+final class Future{
 
-    /**
-     * Shall indicate if the task was cancelled.
-     *
-     * @return bool
-     */
-    public function cancelled(): bool {}
+	/* Resolution */
 
-    /**
-     * Shall indicate if the task is completed.
-     *
-     * @return bool
-     */
-    public function done(): bool {}
+	/**
+	 * Shall return (and if necessary wait for) return from task
+	 *
+	 * @return mixed
+	 *
+	 * @throws Future\Error if waiting failed (internal error).
+	 * @throws Future\Error\Killed if \parallel\Runtime executing task was killed.
+	 * @throws Future\Error\Cancelled if task was cancelled.
+	 * @throws Future\Error\Foreign if task raised an unrecognized uncaught exception.
+	 * @throws Throwable Shall rethrow \Throwable uncaught in task
+	 */
+	public function value(){}
 
-    /**
-     * Shall try to cancel the task
-     *
-     * @throws Error\Killed if the Runtime executing task was killed.
-     * @throws Error\Cancelled if task was already cancelled.
-     *
-     * @return bool
-     */
-    public function cancel(): bool {}
-}
+	/* State */
+
+	/**
+	 * Shall indicate if the task is completed
+	 * @return bool
+	 */
+	public function done() : bool{}
+
+	/**
+	 * Shall indicate if the task was cancelled
+	 * @return bool
+	 */
+	public function cancelled() : bool{}
+
+	/* Cancellation */
+
+	/**
+	 * Shall try to cancel the task
+	 * Note: If task is running, it will be interrupted.
+	 * Warning: Internal function calls in progress cannot be interrupted.
+	 *
+	 * @return bool
+	 *
+	 * @throws Future\Error\Killed if \parallel\Runtime executing task was killed.
+	 * @throws Future\Error\Cancelled if task was already cancelled.
+	 */
+	public function cancel() : bool{}
+}

parallel/parallel/Future/Error.php

@@ -2,8 +2,5 @@
 
 namespace parallel\Future;
 
-use parallel\Error as ParallelError;
-
-class Error extends ParallelError
-{
-}
+class Error extends \parallel\Error{
+}

parallel/parallel/Future/Error/Cancelled.php

@@ -2,8 +2,7 @@
 
 namespace parallel\Future\Error;
 
-use parallel\Future\Error;
+use parallel\Error;
 
-class Cancelled extends Error
-{
-}
+class Cancelled extends Error{
+}

parallel/parallel/Future/Error/Foreign.php

@@ -2,8 +2,7 @@
 
 namespace parallel\Future\Error;
 
-use parallel\Future\Error;
+use parallel\Error;
 
-class Foreign extends Error
-{
-}
+class Foreign extends Error{
+}

parallel/parallel/Future/Error/Killed.php

@@ -2,8 +2,7 @@
 
 namespace parallel\Future\Error;
 
-use parallel\Future\Error;
+use parallel\Error;
 
-class Killed extends Error
-{
-}
+class Killed extends Error{
+}

parallel/parallel/Runtime.php

@@ -3,81 +3,115 @@
 namespace parallel;
 
 use Closure;
-use parallel\Runtime\Bootstrap;
-use parallel\Runtime\Error;
 
-final class Runtime
-{
-    /**
-     * When passed a bootstrap file: Shall construct a bootstrapped runtime.
-     * Without a passed bootstrap file: Shall construct a new runtime without bootstrapping.
-     *
-     * @param string|null $bootstrap The location of a bootstrap file, generally an autoloader.
-     *
-     * @throws Error if thread could not be created.
-     * @throws Bootstrap if bootstrapping failed.
-     */
-    public function __construct($bootstrap = null) {}
+/**
+ * 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{
 
-    /**
-     * Shall schedule task for execution in parallel, passing argv at execution time when available.
-     *
-     * @param Closure    $task A Closure with specific characteristics.
-     * @param array|null $argv
-     *
-     * Task Characteristics:
-     * Closures scheduled for parallel execution must not:
-     *
-     * accept or return by reference
-     * accept or return objects (that are not closures)
-     * execute a limited set of instructions
-     * Instructions prohibited in Closures intended for parallel execution are:
-     *
-     * yield
-     * use by-reference
-     * declare class
-     * declare named function
-     *
-     * Note:Nested closures may yield or use by-reference, but must not contain class or named function declarations.
-     * Note:No instructions are prohibited in the files which the task may include.
-     *
-     * Arguments Characteristics
-     * Arguments must not:
-     *
-     * contain references
-     * contain objects (that are not closures)
-     * contain resources
-     *
-     * Note: In the case of file stream resources, the resource will be cast to the file descriptor and passed as int
-     * where possible, this is unsupported on Windows.
-     *
-     * @return Future|null Returns a Future when the passed $task containers a return or throw statement, otherwise null.
-     * Warning: The return \parallel\Future must not be ignored when the task contains a return or throw statement.
-     *
-     * @throws Error\Closed if Runtime was closed.
-     * @throws Error\IllegalFunction if task is a closure created from an internal function.
-     * @throws Error\IllegalInstruction if task contains illegal instructions.
-     * @throws Error\IllegalParameter if task accepts or argv contains illegal variables.
-     * @throws Error\IllegalReturn if task returns illegally.
-     */
-    public function run(Closure $task , array $argv = null) : Future {}
+	/* Create */
 
-    /**
-     * Shall request that the runtime shutsdown.
-     *
-     * Note: Tasks scheduled for execution will be executed before the shutdown occurs.
-     *
-     * @throws Error\Closed if Runtime was closed.
-     */
-    public function close(): void {}
+	/**
+	 * Shall construct a new runtime without bootstrapping.
+	 * Shall construct a bootstrapped runtime.
+	 *
+	 * @param string $bootstrap The location of a bootstrap file, generally an autoloader.
+	 *
+	 * @throws Runtime\Error if thread could not be created
+	 * @throws Runtime\Error\Bootstrap if bootstrapping failed
+	 */
+	public function __construct(string $bootstrap = null){}
 
-    /**
-     * Shall attempt to force the runtime to shutdown.
-     *
-     * Note: Tasks scheduled for execution will not be executed, the currently running task shall be interrupted.
-     * Warning: Internal function calls in progress cannot be interrupted.
-     *
-     * @throws Error\Closed if Runtime was closed.
-     */
-    public function kill(): void {}
-}
+	/* Execute */
+
+	/**
+	 * Shall schedule task for execution in parallel, passing argv at execution time.
+	 *
+	 * @param Closure $task    A Closure with specific characteristics.
+	 * @param array   $argv    An array of arguments with specific characteristics to be passed to task at execution
+	 *                         time.
+	 *
+	 * ### Task Characteristics
+	 * -----------------------------------------------------------------------------------------------------------------
+	 * Closures scheduled for parallel execution must not:
+	 *  - accept or return by reference
+	 *  - accept or return internal objects (see notes)
+	 *  - execute a limited set of instructions
+	 *
+	 * Instructions prohibited in Closures intended for parallel execution are:
+	 *  - yield
+	 *  - use by-reference
+	 *  - declare class
+	 *  - declare named function
+	 *
+	 * Note: Nested closures may yield or use by-reference, but must not contain class or named function declarations.
+	 * Note: No instructions are prohibited in the files which the task may include.
+	 *
+	 * ### Arguments Characteristics
+	 * -----------------------------------------------------------------------------------------------------------------
+	 * Arguments must not:
+	 *  - contain references
+	 *  - contain resources
+	 *  - contain internal objects (see notes)
+	 *
+	 * Note: In the case of file stream resources, the resource will be cast to the file descriptor and passed as int
+	 *     where possible, this is unsupported on Windows
+	 *
+	 * ### Internal Objects Notes
+	 * -----------------------------------------------------------------------------------------------------------------
+	 * Internal objects generally use a custom structure which cannot be copied by value safely, PHP currently lacks
+	 *     the mechanics to do this (without serialization) and so only objects that do not use a custom structure may
+	 *     be shared.
+	 *
+	 * Some internal objects do not use a custom structure, for example @see \parallel\Events\Event and so may be
+	 *     shared. Closures are a special kind of internal object and support being copied by value, and so may be
+	 *     shared. Channels are central to writing parallel code and support concurrent access and execution by
+	 *     necessity, and so may be shared.
+	 *
+	 * Warning: A user class that extends an internal class may use a custom structure as defined by the internal
+	 *     class, in which case they cannot be copied by value safely, and so may not be shared.
+	 *
+	 * @return Future|null The return Future must not be ignored when the task contains a return or throw
+	 *     statement.
+	 *
+	 * @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 */
+
+	/**
+	 * Shall request that the runtime shutsdown.
+	 * Note: Tasks scheduled for execution will be executed before the shutdown occurs.
+	 *
+	 * @throws Runtime\Error\Closed if Runtime was already closed.
+	 */
+	public function close() : void{}
+
+	/**
+	 * Shall attempt to force the runtime to shutdown.
+	 *
+	 * Note: Tasks scheduled for execution will not be executed, the currently running task shall be interrupted.
+	 * Warning: Internal function calls in progress cannot be interrupted.
+	 *
+	 * @throws Runtime\Error\Closed if Runtime was closed.
+	 */
+	public function kill() : void{}
+}

parallel/parallel/Runtime/Bootstrap.php

@@ -1,7 +0,0 @@
-<?php
-
-namespace parallel\Runtime;
-
-class Bootstrap extends Error
-{
-}

parallel/parallel/Runtime/Error.php

@@ -2,8 +2,5 @@
 
 namespace parallel\Runtime;
 
-use parallel\Error as ParallelError;
-
-class Error extends ParallelError
-{
-}
+class Error extends \parallel\Error{
+}

parallel/parallel/Runtime/Error/Bootstrap.php

@@ -4,6 +4,5 @@ namespace parallel\Runtime\Error;
 
 use parallel\Runtime\Error;
 
-class Bootstrap extends Error
-{
-}
+class Bootstrap extends Error{
+}

parallel/parallel/Runtime/Error/Closed.php

@@ -4,6 +4,5 @@ namespace parallel\Runtime\Error;
 
 use parallel\Runtime\Error;
 
-class Closed extends Error
-{
-}
+class Closed extends Error{
+}

parallel/parallel/Runtime/Error/IllegalFunction.php

@@ -4,6 +4,5 @@ namespace parallel\Runtime\Error;
 
 use parallel\Runtime\Error;
 
-class IllegalFunction extends Error
-{
-}
+class IllegalFunction extends Error{
+}

parallel/parallel/Runtime/Error/IllegalInstruction.php

@@ -4,6 +4,5 @@ namespace parallel\Runtime\Error;
 
 use parallel\Runtime\Error;
 
-class IllegalInstruction extends Error
-{
-}
+class IllegalInstruction extends Error{
+}

parallel/parallel/Runtime/Error/IllegalParameter.php

@@ -4,6 +4,5 @@ namespace parallel\Runtime\Error;
 
 use parallel\Runtime\Error;
 
-class IllegalParameter extends Error
-{
-}
+class IllegalParameter extends Error{
+}

parallel/parallel/Runtime/Error/IllegalReturn.php

@@ -4,6 +4,5 @@ namespace parallel\Runtime\Error;
 
 use parallel\Runtime\Error;
 
-class IllegalReturn extends Error
-{
-}
+class IllegalReturn extends Error{
+}

parallel/parallel/Runtime/Error/IllegalVariable.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace parallel\Runtime\Error;
+
+use parallel\Runtime\Error;
+
+class IllegalVariable extends Error{
+}

parallel/parallel/Runtime/Error/Killed.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace parallel\Runtime\Error;
+
+use parallel\Runtime\Error;
+
+class Killed extends Error{
+}

parallel/parallel/Runtime/Object/Unavailable.php

@@ -0,0 +1,6 @@
+<?php
+
+namespace parallel\Runtime\Object;
+
+class Unavailable{
+}

parallel/parallel/Runtime/Type/Unavailable.php

@@ -0,0 +1,6 @@
+<?php
+
+namespace parallel\Runtime\Type;
+
+class Unavailable{
+}

parallel/parallel/Sync.php

@@ -2,59 +2,62 @@
 
 namespace parallel;
 
-use parallel\Sync\Error\IllegalValue;
-
 /**
- * The parallel\Sync class provides access to low level syncrhonization primites, mutex, condition variables, and
- * allows the implementation of semaphores.
+ * The Sync class provides access to low level synchronization primitives, mutex, condition variables, and allows the
+ * implementation of semaphores.
  *
  * Synchronization for most applications is much better implemented using channels, however, in some cases authors of
  * low level code may find it useful to be able to access these lower level mechanisms.
  */
-final class Sync
-{
-    /**
-     * Shall construct a new synchronization object containing the given scalar value. When not given a scalar value it
-     * shall construct a new synchronization object with no value.
-     *
-     * @param string|int|float|bool|null $value
-     *
-     * @throws IllegalValue if value is non-scalar.
-     */
-    public function __construct($value = null) {}
+final class Sync{
 
-    /**
-     * Shall atomically return the syncrhonization objects value.
-     *
-     * @return string|int|float|bool
-     */
-    public function get() {}
+	/* Constructor */
 
-    /**
-     * Shall atomically set the value of the synchronization object.
-     *
-     * @param string|int|float|bool $value
-     *
-     * @throws IllegalValue if value is non-scalar.
-     */
-    public function set($value) {}
+	/**
+	 * Shall construct a new synchronization object with no value
+	 * Shall construct a new synchronization object containing the given scalar value
+	 *
+	 * @param string|int|float|bool $value
+	 *
+	 * @throws Sync\Error\IllegalValue if value is non-scalar.
+	 */
+	public function __construct($value = null){}
 
-    /**
-     * Shall wait for notification on this synchronization object.
-     */
-    public function wait() {}
+	/* Access */
 
-    /**
-     * Shall notify one (by default) or all threads waiting on the synchronization object.
-     *
-     * @param bool $all
-     */
-    public function notify(bool $all = null) {}
+	/**
+	 * Shall atomically return the synchronization objects value
+	 * @return string|int|float|bool
+	 */
+	public function get(){}
 
-    /**
-     * Shall exclusively enter into the critical code.
-     *
-     * @param callable $critical
-     */
-    public function __invoke(callable $critical) {}
-}
+	/**
+	 * Shall atomically set the value of the synchronization object
+	 * @param string|int|float|bool $value
+	 *
+	 * @throws Sync\Error\IllegalValue if value is non-scalar.
+	 */
+	public function set($value){}
+
+	/* Synchronization */
+
+	/**
+	 * Shall wait for notification on this synchronization object
+	 * @return bool
+	 */
+	public function wait() : bool{}
+
+	/**
+	 * Shall notify one (by default) or all threads waiting on the synchronization object
+	 * @param bool $all
+	 *
+	 * @return bool
+	 */
+	public function notify(bool $all = null) : bool{}
+
+	/**
+	 * Shall exclusively enter into the critical code
+	 * @param callable $block
+	 */
+	public function __invoke(callable $block){}
+}

parallel/parallel/Sync/Error.php

@@ -2,8 +2,5 @@
 
 namespace parallel\Sync;
 
-use parallel\Error as ParallelError;
-
-class Error extends ParallelError
-{
-}
+class Error extends \parallel\Error{
+}

parallel/parallel/Sync/Error/IllegalValue.php

@@ -4,6 +4,5 @@ namespace parallel\Sync\Error;
 
 use parallel\Sync\Error;
 
-class IllegalValue extends Error
-{
-}
+class IllegalValue extends Error{
+}