From b507edcd168d11d16a8c3c93b92d235472680757 Mon Sep 17 00:00:00 2001 From: chaz6chez Date: Mon, 21 Oct 2024 11:29:46 +0800 Subject: [PATCH] doc update --- docs/doc/utils-en.md | 107 +++++++++++++++++++++++++++++------- docs/doc/utils.md | 63 ++++++++++++++++++++- src/Utils/Pool/Debugger.php | 5 ++ 3 files changed, 155 insertions(+), 20 deletions(-) diff --git a/docs/doc/utils-en.md b/docs/doc/utils-en.md index 67218a8..bea6403 100644 --- a/docs/doc/utils-en.md +++ b/docs/doc/utils-en.md @@ -214,42 +214,73 @@ ```php use Workbunny\WebmanCoroutine\Utils\Pool\Pool; + $source = new class { public $id = 1; - } - // Pooled copies of 2 source objects are placed in the area named normal-object, with the area index starting from 1. + }; + + // Pool two copies of the source object into the "normal-object" region, starting with index 1 Pool::create('normal-object', 2, $source, true); - - // At this point, there are three source objects in the heap data, with two source objects residing in the normal-object region of the pool. - - // Wait for an idle source object in the normal-object region, and execute the callback when one is available - // Due to copying, the original source object's ID will not be modified after the callback execution + + // At this point, there are three source objects in the heap, with two in the "normal-object" region of the Pool + + // Wait to acquire an idle source object from the "normal-object" region and execute the callback + // Due to the copy, the original source object's id will not be modified after callback execution Pool::waitForIdle('normal-object', function (Pool $pool) { $sourceObject = $pool->getElement(); $sourceObject->id = 2; }); - // echo 1 + + // Output 1 echo $source->id; - - // Retrieve the object with index 1 from the region and execute the callback when idle + + // Acquire the object at index 1 in the region and wait for it to become idle before executing the callback $source1 = Pool::get('normal-object', 1); $source1->wait(function (Pool $pool) { $sourceObject = $pool->getElement(); $sourceObject->id = 3; }); - // echo 1 + + // Output 1 echo $source->id; - // echo 3 + // Output 3 echo $source1->id; - - // Retrieve the currently idle object, and return null if none is available + + // Get the current idle object, returns null if none is available $source1 = Pool::idle('normal-object'); - - // Destroy the object with index 1 in the region + try { + $source1?->setIdle(false); + // Execute some operations + } finally { + // Release + $source1?->setIdle(true); + } + + // Wait to acquire an idle object and lock it + $source1 = Pool::getIdle('normal-object'); + try { + // Execute some operations + } finally { + // Release + $source1->setIdle(true); + } + + // Wait for up to 10 seconds to acquire an idle object and lock it + $source1 = Pool::getIdle('normal-object', 10); + try { + // Execute some operations + } finally { + // Release + $source1->setIdle(true); + } + + // Destroy the object at index 1 in the region Pool::destroy('normal-object', 1); - // Force destroy the object with index 2 in the region - Pool::destroy('normal-object', 2， true); - // Destroy all objects in the normal-object region + + // Forcefully destroy the object at index 2 in the region + Pool::destroy('normal-object', 2, true); + + // Destroy all objects in the "normal-object" region Pool::destroy('normal-object'); ``` > Tips: @@ -323,4 +354,42 @@ // ... ``` +- Debugger Assistant + + > Due to the special nature of some data, they may be unsafe in a coroutine environment. + > Therefore, some debugging assistants are provided to check whether the data has potential risks and insecurities. + + - Object has a static array property + ```php + $object = new class () { + public static $arr = [1, 2, 3]; + }; + try { + Debugger::validate($object); + } catch (PoolDebuggerException $e) { + // $e->getCode() = Debugger::ERROR_TYPE_STATIC_ARRAY + // $e->getMessage() = 'Value can not be cloned [static array]. ' + } + ``` + + - Object has a static object property + ```php + $object = new class () { + public static $object = null; + + public function __construct() + { + self::$object = new stdClass(); + } + }; + try { + Debugger::validate($object); + } catch (PoolDebuggerException $e) { + // $e->getCode() = Debugger::ERROR_TYPE_STATIC_OBJECT + // $e->getMessage() = 'Value can not be cloned [static object]. ' + } + ``` + + - For more usage, please refer to the test case `tests/UtilsCase/Pool/DebuggerTest.php` + - more，TODO diff --git a/docs/doc/utils.md b/docs/doc/utils.md index 8ebc0bc..339eaab 100644 --- a/docs/doc/utils.md +++ b/docs/doc/utils.md @@ -217,7 +217,6 @@ } // 池化拷贝2个source的对象，放入名为normal-object的区域，区域索引以1开始 Pool::create('normal-object', 2, $source, true); - // 此时堆数据中存在三个source对象，其中Pool池的normal-object区域存在两个source对象 // 等待获取normal-object区域闲置的source对象，获取到时，执行回调 @@ -242,6 +241,31 @@ // 获取当前闲置对象，未获取到时返回null $source1 = Pool::idle('normal-object'); + try { + $source1?->setIdle(false); + // do something + } finally { + // 释放 + $source1?->setIdle(true); + } + + // 等待获取限制对象，并对获取到的对象加锁 + $source1 = Pool::getIdle('normal-object'); + try { + // do something + } finally { + // 释放 + $source1->setIdle(true); + } + + // 等待10秒，获取限制对象，并对获取到的对象加锁 + $source1 = Pool::getIdle('normal-object', 10); + try { + // do something + } finally { + // 释放 + $source1->setIdle(true); + } // 销毁区域索引为1的对象 Pool::destroy('normal-object', 1); @@ -320,5 +344,42 @@ // ... ``` + +- Debugger助手 + + > 由于一些数据的特殊性，导致他们可能在协程环境中是不安全的，所以提供了一些调试助手，可以查看该数据是否存在隐患和不安全 + + - 对象存在静态数组属性 + ```php + $object = new class () { + public static $arr = [1, 2, 3]; + }; + try { + Debugger::validate($object); + } catch (PoolDebuggerException $e) { + // $e->getCode() = Debugger::ERROR_TYPE_STATIC_ARRAY + // $e->getMessage() = 'Value can not be cloned [static array]. ' + } + ``` + + - 对象存在静态对象属性 + ```php + $object = new class () { + public static $object = null; + + public function __construct() + { + self::$object = new stdClass(); + } + }; + try { + Debugger::validate($object); + } catch (PoolDebuggerException $e) { + // $e->getCode() = Debugger::ERROR_TYPE_STATIC_OBJECT + // $e->getMessage() = 'Value can not be cloned [static object]. ' + } + ``` + + - 更多用法请参考测试用例 `tests/UtilsCase/Pool/DebuggerTest.php` - 更多使用，TODO diff --git a/src/Utils/Pool/Debugger.php b/src/Utils/Pool/Debugger.php index 088c2fe..8adf61c 100644 --- a/src/Utils/Pool/Debugger.php +++ b/src/Utils/Pool/Debugger.php @@ -13,10 +13,15 @@ class Debugger { + /** @var int 无错误 */ public const ERROR_TYPE_NON = 0; + /** @var int 标量不可clone错误 */ public const ERROR_TYPE_NORMAL = -1; + /** @var int 资源不可clone错误 */ public const ERROR_TYPE_RESOURCE = -2; + /** @var int 静态数组不可clone错误 */ public const ERROR_TYPE_STATIC_ARRAY = -101; + /** @var int 静态对象不可clone错误 */ public const ERROR_TYPE_STATIC_OBJECT = -102; protected static array $_errorMap = [