From e557ff24960e95be2b95f8bf1ed54500a1cba101 Mon Sep 17 00:00:00 2001 From: "Dylan K. Taylor" Date: Tue, 2 Apr 2024 14:55:01 +0100 Subject: [PATCH] Update pmmpthread stubs --- PhpStormStubsMap.php | 1 + pmmpthread/Thread.stub.php | 214 +++++++++++++++------------- pmmpthread/ThreadSafe.stub.php | 2 +- pmmpthread/ThreadSafeArray.stub.php | 27 ++-- pmmpthread/Worker.stub.php | 4 +- 5 files changed, 133 insertions(+), 115 deletions(-) diff --git a/PhpStormStubsMap.php b/PhpStormStubsMap.php index 0725cf8e6..9ad0cd98b 100644 --- a/PhpStormStubsMap.php +++ b/PhpStormStubsMap.php @@ -1327,6 +1327,7 @@ final class PhpStormStubsMap 'pmmp\\encoding\\ByteBuffer' => 'encoding/encoding.php', 'pmmp\\encoding\\DataDecodeException' => 'encoding/encoding.php', 'pmmp\\thread\\ConnectionException' => 'pmmpthread/ConnectionException.stub.php', + 'pmmp\\thread\\NonThreadSafeValueError' => 'pmmpthread/NonThreadSafeValueError.stub.php', 'pmmp\\thread\\Pool' => 'pmmpthread/Pool.stub.php', 'pmmp\\thread\\Runnable' => 'pmmpthread/Runnable.stub.php', 'pmmp\\thread\\Thread' => 'pmmpthread/Thread.stub.php', diff --git a/pmmpthread/Thread.stub.php b/pmmpthread/Thread.stub.php index b288b8cba..19b8624e7 100644 --- a/pmmpthread/Thread.stub.php +++ b/pmmpthread/Thread.stub.php @@ -14,99 +14,99 @@ */ abstract class Thread extends Runnable { - /** - * @var int - * @cvalue PMMPTHREAD_INHERIT_NONE - * - * The newly created thread will inherit nothing from its parent, as if starting a new request. - */ - public const INHERIT_NONE = UNKNOWN; - - /** - * @var int - * @cvalue PMMPTHREAD_INHERIT_INI - * - * The newly created thread will inherit INI overrides set by ini_set() in the parent thread(s). - * If not set, the settings defined in php.ini will be used. - */ - public const INHERIT_INI = UNKNOWN; - - /** - * @var int - * @cvalue PMMPTHREAD_INHERIT_CONSTANTS - * - * The newly created thread will copy all global constants with simple or thread-safe values from its parent. - * Note: Constants containing non-thread-safe objects or resources cannot be copied. - * - * Do not rely on this for production. Prefer relying on autoloading instead (e.g. Composer - * bootstrap files), which is more reliable (and takes less memory, when OPcache is used). - */ - public const INHERIT_CONSTANTS = UNKNOWN; - - /** - * @var int - * @cvalue PMMPTHREAD_INHERIT_FUNCTIONS - * - * The newly created thread will copy all global functions from its parent. - * - * Do not rely on this for production. Prefer relying on autoloading instead (e.g. Composer - * bootstrap files), which is more reliable (and takes less memory, when OPcache is used). - */ - public const INHERIT_FUNCTIONS = UNKNOWN; - - /** - * @var int - * @cvalue PMMPTHREAD_INHERIT_CLASSES - * - * The newly created thread will copy all classes from its parent. - * - * !!!!! WARNING !!!!! This has a significant performance cost in large applications with many - * classes. Avoid relying on this. Prefer relying on autoloading instead (e.g. Composer - * bootstrap files), which is more reliable (and takes less memory, when OPcache is used). - * - * Note: Disabling this flag only prevents class copying during thread start. Classes may still - * be copied at other times, such as when a new thread is started, since no autoloader would be - * present inside the new thread to load the thread's own class. - */ - public const INHERIT_CLASSES = UNKNOWN; - - /** - * @var int - * @cvalue PMMPTHREAD_INHERIT_INCLUDES - * - * The newly created thread will copy the list of included and required files from its parent. - */ - public const INHERIT_INCLUDES = UNKNOWN; - - /** - * @var int - * @cvalue PMMPTHREAD_INHERIT_COMMENTS - * - * The newly created thread will copy doc comments of any classes, functions or constants that - * it inherits from its parent. - */ - public const INHERIT_COMMENTS = UNKNOWN; - - /** - * @var int - * @cvalue PMMPTHREAD_INHERIT_ALL - * - * Everything (classes, functions, constants, includes, doc comments, ini settings) will be - * copied from the parent thread. - * - * !!!!! WARNING !!!!! This has a significant performance cost in large applications with many - * classes. Avoid relying on this. Prefer relying on autoloading instead (e.g. Composer - * bootstrap files), which is more reliable (and takes less memory, when OPcache is used). - */ - public const INHERIT_ALL = UNKNOWN; - - /** - * @var int - * @cvalue PMMPTHREAD_ALLOW_HEADERS - * - * Allows the new thread to emit HTTP headers. - */ - public const ALLOW_HEADERS = UNKNOWN; + /** + * @var int + * @cvalue PMMPTHREAD_INHERIT_NONE + * + * The newly created thread will inherit nothing from its parent, as if starting a new request. + */ + public const INHERIT_NONE = UNKNOWN; + + /** + * @var int + * @cvalue PMMPTHREAD_INHERIT_INI + * + * The newly created thread will inherit INI overrides set by ini_set() in the parent thread(s). + * If not set, the settings defined in php.ini will be used. + */ + public const INHERIT_INI = UNKNOWN; + + /** + * @var int + * @cvalue PMMPTHREAD_INHERIT_CONSTANTS + * + * The newly created thread will copy all global constants with simple or thread-safe values from its parent. + * Note: Constants containing non-thread-safe objects or resources cannot be copied. + * + * Do not rely on this for production. Prefer relying on autoloading instead (e.g. Composer + * bootstrap files), which is more reliable (and takes less memory, when OPcache is used). + */ + public const INHERIT_CONSTANTS = UNKNOWN; + + /** + * @var int + * @cvalue PMMPTHREAD_INHERIT_FUNCTIONS + * + * The newly created thread will copy all global functions from its parent. + * + * Do not rely on this for production. Prefer relying on autoloading instead (e.g. Composer + * bootstrap files), which is more reliable (and takes less memory, when OPcache is used). + */ + public const INHERIT_FUNCTIONS = UNKNOWN; + + /** + * @var int + * @cvalue PMMPTHREAD_INHERIT_CLASSES + * + * The newly created thread will copy all classes from its parent. + * + * !!!!! WARNING !!!!! This has a significant performance cost in large applications with many + * classes. Avoid relying on this. Prefer relying on autoloading instead (e.g. Composer + * bootstrap files), which is more reliable (and takes less memory, when OPcache is used). + * + * Note: Disabling this flag only prevents class copying during thread start. Classes may still + * be copied at other times, such as when a new thread is started, since no autoloader would be + * present inside the new thread to load the thread's own class. + */ + public const INHERIT_CLASSES = UNKNOWN; + + /** + * @var int + * @cvalue PMMPTHREAD_INHERIT_INCLUDES + * + * The newly created thread will copy the list of included and required files from its parent. + */ + public const INHERIT_INCLUDES = UNKNOWN; + + /** + * @var int + * @cvalue PMMPTHREAD_INHERIT_COMMENTS + * + * The newly created thread will copy doc comments of any classes, functions or constants that + * it inherits from its parent. + */ + public const INHERIT_COMMENTS = UNKNOWN; + + /** + * @var int + * @cvalue PMMPTHREAD_INHERIT_ALL + * + * Everything (classes, functions, constants, includes, doc comments, ini settings) will be + * copied from the parent thread. + * + * !!!!! WARNING !!!!! This has a significant performance cost in large applications with many + * classes. Avoid relying on this. Prefer relying on autoloading instead (e.g. Composer + * bootstrap files), which is more reliable (and takes less memory, when OPcache is used). + */ + public const INHERIT_ALL = UNKNOWN; + + /** + * @var int + * @cvalue PMMPTHREAD_ALLOW_HEADERS + * + * Allows the new thread to emit HTTP headers. + */ + public const ALLOW_HEADERS = UNKNOWN; /** * Will return the identity of the Thread that created the referenced Thread @@ -129,13 +129,27 @@ public static function getCurrentThread() : ?Thread{} */ public static function getCurrentThreadId() : int{} - /** - * Returns a ThreadSafeArray of globals accessible to all threads - * Any modification made will be seen by all threads - * - * @return ThreadSafeArray - */ - public static function getSharedGlobals() : ThreadSafeArray{} + /** + * Returns a ThreadSafeArray of globals accessible to all threads + * Any modification made will be seen by all threads + * + * @return ThreadSafeArray + */ + public static function getSharedGlobals() : ThreadSafeArray{} + + /** + * Returns the total number of Threads and Workers which have been + * started but not yet successfully joined/shutdown. + * + * The following are **not** included: + * - Threads which have been created but not started + * - Threads which have already been joined/shutdown + * - Threads which are not managed by pmmpthread (e.g. created by other extensions) + * - The main process thread + * + * @return int + */ + public static function getRunningCount() : int{} /** * Will return the identity of the referenced Thread diff --git a/pmmpthread/ThreadSafe.stub.php b/pmmpthread/ThreadSafe.stub.php index d858af98a..afc53cc59 100644 --- a/pmmpthread/ThreadSafe.stub.php +++ b/pmmpthread/ThreadSafe.stub.php @@ -54,5 +54,5 @@ public function synchronized(\Closure $function, mixed ...$args) : mixed{} */ public function wait(int $timeout = 0) : bool{} - public function getIterator() : \Iterator{} + public function getIterator() : \Iterator{} } diff --git a/pmmpthread/ThreadSafeArray.stub.php b/pmmpthread/ThreadSafeArray.stub.php index 8a9a456bf..6ced272d2 100644 --- a/pmmpthread/ThreadSafeArray.stub.php +++ b/pmmpthread/ThreadSafeArray.stub.php @@ -16,12 +16,13 @@ final class ThreadSafeArray extends ThreadSafe implements \Countable, \ArrayAccess { /** - * Fetches a chunk of the objects properties table of the given size + * Removes and returns $size items from the array. Equivalent to calling shift() $size times. + * Similar to array_slice() with offset 0, but also removes the items returned. * * @param int $size The number of items to fetch * @param bool $preserve Preserve the keys of members * - * @return array An array of items from the objects member table + * @return array An array of items removed from the array */ public function chunk(int $size, bool $preserve = false) : array{} @@ -35,38 +36,40 @@ public function count() : int{} * @param array $array * * @return ThreadSafeArray A ThreadSafeArray object created from the provided array + * @throws NonThreadSafeValueError if the array contains any non-thread-safe values */ - public static function fromArray(array $array) : ThreadSafeArray {} + public static function fromArray(array $array) : ThreadSafeArray{} /** - * Merges data into the current ThreadSafeArray + * Merges data into the current ThreadSafeArray, similar to array_merge() * - * @param mixed $from The data to merge + * @param array|object $from The data to merge * @param bool $overwrite Overwrite existing keys flag * * @return bool A boolean indication of success + * @throws NonThreadSafeValueError if $from contains any non-thread-safe values */ - public function merge(mixed $from, bool $overwrite = true) : bool{} + public function merge(array|object $from, bool $overwrite = true) : bool{} /** - * Pops an item from the array + * Pops an item from the end of the array, similar to array_pop() * * @return mixed The last item in the array */ public function pop() : mixed{} /** - * Shifts an item from the array + * Shifts an item from the start of the array, similar to array_shift() * * @return mixed The first item in the array */ public function shift() : mixed{} - public function offsetGet(mixed $offset) : mixed{} + public function offsetGet(mixed $offset) : mixed{} - public function offsetSet(mixed $offset, mixed $value) : void{} + public function offsetSet(mixed $offset, mixed $value) : void{} - public function offsetExists(mixed $offset) : bool{} + public function offsetExists(mixed $offset) : bool{} - public function offsetUnset(mixed $offset) : void{} + public function offsetUnset(mixed $offset) : void{} } diff --git a/pmmpthread/Worker.stub.php b/pmmpthread/Worker.stub.php index 5e6ff1754..f510351a2 100644 --- a/pmmpthread/Worker.stub.php +++ b/pmmpthread/Worker.stub.php @@ -48,7 +48,7 @@ public function getStacked() : int{} * Tell if the referenced Worker has been shutdown * * @return bool A boolean indication of state - * @alias pmmp\thread\Thread::isJoined + * @alias pmmp\thread\Thread::isJoined */ public function isShutdown() : bool{} @@ -56,7 +56,7 @@ public function isShutdown() : bool{} * Shuts down the Worker after executing all the threaded tasks previously stacked * * @return bool A boolean indication of success - * @alias pmmp\thread\Thread::join + * @alias pmmp\thread\Thread::join */ public function shutdown() : bool{}