From 413d3ffcbc5564a5f77039fd9a395380f80ce765 Mon Sep 17 00:00:00 2001 From: Frago9876543210 Date: Thu, 8 Aug 2019 20:56:28 +0300 Subject: [PATCH] update stubs for ext-parallel --- PhpStormStubsMap.php | 1 + parallel/parallel.php | 38 ++-- parallel/parallel/Channel.php | 150 +++++++++----- parallel/parallel/Channel/Error.php | 7 +- parallel/parallel/Channel/Error/Closed.php | 5 +- parallel/parallel/Channel/Error/Existence.php | 5 +- .../parallel/Channel/Error/IllegalValue.php | 5 +- parallel/parallel/Error.php | 7 +- parallel/parallel/Events.php | 193 +++++++++--------- parallel/parallel/Events/Error.php | 7 +- parallel/parallel/Events/Error/Existence.php | 5 +- parallel/parallel/Events/Error/Timeout.php | 5 +- parallel/parallel/Events/Event.php | 53 +++-- parallel/parallel/Events/Event/Error.php | 6 + parallel/parallel/Events/Event/Type.php | 57 ++---- parallel/parallel/Events/Input.php | 63 +++--- parallel/parallel/Events/Input/Error.php | 7 +- .../parallel/Events/Input/Error/Existence.php | 5 +- .../Events/Input/Error/IllegalValue.php | 5 +- parallel/parallel/Future.php | 87 ++++---- parallel/parallel/Future/Error.php | 7 +- parallel/parallel/Future/Error/Cancelled.php | 7 +- parallel/parallel/Future/Error/Foreign.php | 7 +- parallel/parallel/Future/Error/Killed.php | 7 +- parallel/parallel/Runtime.php | 182 ++++++++++------- parallel/parallel/Runtime/Bootstrap.php | 7 - parallel/parallel/Runtime/Error.php | 7 +- parallel/parallel/Runtime/Error/Bootstrap.php | 5 +- parallel/parallel/Runtime/Error/Closed.php | 5 +- .../Runtime/Error/IllegalFunction.php | 5 +- .../Runtime/Error/IllegalInstruction.php | 5 +- .../Runtime/Error/IllegalParameter.php | 5 +- .../parallel/Runtime/Error/IllegalReturn.php | 5 +- .../Runtime/Error/IllegalVariable.php | 8 + parallel/parallel/Runtime/Error/Killed.php | 8 + .../parallel/Runtime/Object/Unavailable.php | 6 + .../parallel/Runtime/Type/Unavailable.php | 6 + parallel/parallel/Sync.php | 95 ++++----- parallel/parallel/Sync/Error.php | 7 +- parallel/parallel/Sync/Error/IllegalValue.php | 5 +- 40 files changed, 586 insertions(+), 514 deletions(-) create mode 100644 parallel/parallel/Events/Event/Error.php delete mode 100644 parallel/parallel/Runtime/Bootstrap.php create mode 100644 parallel/parallel/Runtime/Error/IllegalVariable.php create mode 100644 parallel/parallel/Runtime/Error/Killed.php create mode 100644 parallel/parallel/Runtime/Object/Unavailable.php create mode 100644 parallel/parallel/Runtime/Type/Unavailable.php diff --git a/PhpStormStubsMap.php b/PhpStormStubsMap.php index a10cc4ab..be23fd9d 100644 --- a/PhpStormStubsMap.php +++ b/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', diff --git a/parallel/parallel.php b/parallel/parallel.php index b6ea8ef8..ceaf6de8 100644 --- a/parallel/parallel.php +++ b/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 \ No newline at end of file diff --git a/parallel/parallel/Channel.php b/parallel/parallel/Channel.php index d2171268..579d20ba 100644 --- a/parallel/parallel/Channel.php +++ b/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{} +} \ No newline at end of file diff --git a/parallel/parallel/Channel/Error.php b/parallel/parallel/Channel/Error.php index 1fe30b93..e3da3b17 100644 --- a/parallel/parallel/Channel/Error.php +++ b/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{ +} \ No newline at end of file diff --git a/parallel/parallel/Channel/Error/Closed.php b/parallel/parallel/Channel/Error/Closed.php index e10fb401..81b655e4 100644 --- a/parallel/parallel/Channel/Error/Closed.php +++ b/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{ +} \ No newline at end of file diff --git a/parallel/parallel/Channel/Error/Existence.php b/parallel/parallel/Channel/Error/Existence.php index 46e755c7..6d4f16ac 100644 --- a/parallel/parallel/Channel/Error/Existence.php +++ b/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{ +} \ No newline at end of file diff --git a/parallel/parallel/Channel/Error/IllegalValue.php b/parallel/parallel/Channel/Error/IllegalValue.php index d4e7fa2e..bd16e3fa 100644 --- a/parallel/parallel/Channel/Error/IllegalValue.php +++ b/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{ +} \ No newline at end of file diff --git a/parallel/parallel/Error.php b/parallel/parallel/Error.php index 717c6b50..f04dfec6 100644 --- a/parallel/parallel/Error.php +++ b/parallel/parallel/Error.php @@ -2,8 +2,5 @@ namespace parallel; -use Error as CoreError; - -class Error extends CoreError -{ -} +class Error extends \Error{ +} \ No newline at end of file diff --git a/parallel/parallel/Events.php b/parallel/parallel/Events.php index 3e0dcacd..5ccb832f 100644 --- a/parallel/parallel/Events.php +++ b/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{} +} \ No newline at end of file diff --git a/parallel/parallel/Events/Error.php b/parallel/parallel/Events/Error.php index ccf3db6f..ec0eeb75 100644 --- a/parallel/parallel/Events/Error.php +++ b/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{ +} \ No newline at end of file diff --git a/parallel/parallel/Events/Error/Existence.php b/parallel/parallel/Events/Error/Existence.php index 698b55d5..5d7ae9c6 100644 --- a/parallel/parallel/Events/Error/Existence.php +++ b/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{ +} \ No newline at end of file diff --git a/parallel/parallel/Events/Error/Timeout.php b/parallel/parallel/Events/Error/Timeout.php index 33096625..9788eab6 100644 --- a/parallel/parallel/Events/Error/Timeout.php +++ b/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{ +} \ No newline at end of file diff --git a/parallel/parallel/Events/Event.php b/parallel/parallel/Events/Event.php index bbf5cb7a..9a45473f 100644 --- a/parallel/parallel/Events/Event.php +++ b/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; +} \ No newline at end of file diff --git a/parallel/parallel/Events/Event/Error.php b/parallel/parallel/Events/Event/Error.php new file mode 100644 index 00000000..49480aac --- /dev/null +++ b/parallel/parallel/Events/Event/Error.php @@ -0,0 +1,6 @@ +