Add a custom queue documents

docs/i18n/zh/docusaurus-plugin-content-docs/current/user_docs/dev_manual/queue-custom.md

@@ -0,0 +1,83 @@
+---
+sidebar_position: 4
+---
+
+# 阻塞队列自定义
+
+Hippo4j 通过 SPI 的方式对拒绝策略进行扩展，可以让用户在 Hippo4j 中完成自定义阻塞队列实现。
+
+## 1. 定义自定义队列类
+
+实现接口 `cn.hippo4j.common.executor.support.CustomBlockingQueue<T>`：
+
+```java
+package com.example.queue;
+
+import cn.hippo4j.common.executor.support.CustomBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.ArrayBlockingQueue;
+
+public class MyArrayBlockingQueue implements CustomBlockingQueue<Runnable> {
+
+    @Override
+    public Integer getType() {
+        return 1001; 
+    }
+
+    @Override
+    public String getName() {
+        return "MyArrayBlockingQueue"; 
+    }
+
+    @Override
+    public BlockingQueue<Runnable> generateBlockingQueue() {
+        return new ArrayBlockingQueue<>(256);
+    }
+}
+```
+
+## 2. 声明 SPI 文件
+
+在 `src/main/resources/META-INF/services/` 目录下新增文件：
+
+```
+cn.hippo4j.common.executor.support.CustomBlockingQueue
+```
+
+文件内容仅一行：
+
+```
+com.example.queue.MyArrayBlockingQueue
+```
+
+## 3. 服务端生效方式
+
+当服务端下发的 `queueType` 与 `capacity` 命中自定义类型时，框架会通过 SPI 自动创建队列：
+
+```java
+// 创建与验证
+BlockingQueue<T> q = BlockingQueueManager.createQueue(queueType, capacity);
+boolean valid = BlockingQueueManager.validateQueueConfig(queueType, capacity);
+
+// 在线替换
+boolean swapped = BlockingQueueManager.replaceQueue(executor, q);
+
+// 动态调整容量（仅 ResizableCapacityLinkedBlockingQueue 支持）
+boolean ok = BlockingQueueManager.changeQueueCapacity(executor.getQueue(), newCapacity);
+```
+
+服务端动态刷新处：
+
+```java
+// ServerThreadPoolDynamicRefresh#handleQueueChanges
+boolean queueTypeChanged = parameter.getQueueType() != null && 
+    !Objects.equals(BlockingQueueManager.getQueueType(executor.getQueue()), parameter.getQueueType());
+
+if (queueTypeChanged) {
+    boolean swapped = BlockingQueueManager.replaceQueue(
+        executor, BlockingQueueManager.createQueue(parameter.getQueueType(), parameter.getCapacity()));
+    ...
+}
+```
+
+

docs/i18n/zh/docusaurus-plugin-content-docs/current/user_docs/dev_manual/queue-info.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 3
+---
+
+# 内置阻塞队列
+
+Hippo4j 内置多种常用阻塞队列类型，支持开箱即用，亦可通过 SPI 扩展自定义队列类型。
+
+## 内置类型清单
+
+以下类型可直接在服务端或配置中选择（枚举：`BlockingQueueTypeEnum`）：
+
+- ArrayBlockingQueue（数组有界队列）
+- LinkedBlockingQueue（链表队列）
+- LinkedBlockingDeque（双端队列）
+- SynchronousQueue（同步移交队列）
+- LinkedTransferQueue（可转移队列）
+- PriorityBlockingQueue（优先级队列）
+- ResizableCapacityLinkedBlockingQueue（可在线动态调容量的链表队列）
+
+其中 `ResizableCapacityLinkedBlockingQueue` 支持在线变更 `capacity`，无需重建线程池，适合动态调优场景。
+
+## 代码对应
+
+枚举定义：
+
+```java
+// cn.hippo4j.common.executor.support.BlockingQueueTypeEnum
+RESIZABLE_LINKED_BLOCKING_QUEUE(9, "ResizableCapacityLinkedBlockingQueue") {
+    @Override
+    <T> BlockingQueue<T> of(Integer capacity) {
+        return new ResizableCapacityLinkedBlockingQueue<>(capacity);
+    }
+    @Override
+    <T> BlockingQueue<T> of() {
+        return new ResizableCapacityLinkedBlockingQueue<>();
+    }
+}
+```
+
+创建与验证：
+
+```java
+// cn.hippo4j.common.executor.support.BlockingQueueManager
+BlockingQueue<T> q = BlockingQueueManager.createQueue(queueType, capacity);
+boolean valid = BlockingQueueManager.validateQueueConfig(queueType, capacity);
+boolean ok = BlockingQueueManager.changeQueueCapacity(executor.getQueue(), newCapacity);
+```
+
+## 使用建议
+
+- 需要在线调容量：优先选择 `ResizableCapacityLinkedBlockingQueue`
+- 需要严格有界：选择 `ArrayBlockingQueue`
+- 需要无界吞吐：选择 `LinkedBlockingQueue`
+- 需要优先级：选择 `PriorityBlockingQueue`
+- 需要同步移交：选择 `SynchronousQueue`
+
+如需自定义队列类型，请参考《阻塞队列自定义》。
+
+

docs/i18n/zh/docusaurus-plugin-content-docs/version-1.5.0/user_docs/dev_manual/queue-custom.md

@@ -0,0 +1,83 @@
+---
+sidebar_position: 4
+---
+
+# 阻塞队列自定义
+
+Hippo4j 通过 SPI 的方式对拒绝策略进行扩展，可以让用户在 Hippo4j 中完成自定义阻塞队列实现。
+
+## 1. 定义自定义队列类
+
+实现接口 `cn.hippo4j.common.executor.support.CustomBlockingQueue<T>`：
+
+```java
+package com.example.queue;
+
+import cn.hippo4j.common.executor.support.CustomBlockingQueue;
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.ArrayBlockingQueue;
+
+public class MyArrayBlockingQueue implements CustomBlockingQueue<Runnable> {
+
+    @Override
+    public Integer getType() {
+        return 1001; 
+    }
+
+    @Override
+    public String getName() {
+        return "MyArrayBlockingQueue"; 
+    }
+
+    @Override
+    public BlockingQueue<Runnable> generateBlockingQueue() {
+        return new ArrayBlockingQueue<>(256);
+    }
+}
+```
+
+## 2. 声明 SPI 文件
+
+在 `src/main/resources/META-INF/services/` 目录下新增文件：
+
+```
+cn.hippo4j.common.executor.support.CustomBlockingQueue
+```
+
+文件内容仅一行：
+
+```
+com.example.queue.MyArrayBlockingQueue
+```
+
+## 3. 服务端生效方式
+
+当服务端下发的 `queueType` 与 `capacity` 命中自定义类型时，框架会通过 SPI 自动创建队列：
+
+```java
+// 创建与验证
+BlockingQueue<T> q = BlockingQueueManager.createQueue(queueType, capacity);
+boolean valid = BlockingQueueManager.validateQueueConfig(queueType, capacity);
+
+// 在线替换
+boolean swapped = BlockingQueueManager.replaceQueue(executor, q);
+
+// 动态调整容量（仅 ResizableCapacityLinkedBlockingQueue 支持）
+boolean ok = BlockingQueueManager.changeQueueCapacity(executor.getQueue(), newCapacity);
+```
+
+服务端动态刷新处：
+
+```java
+// ServerThreadPoolDynamicRefresh#handleQueueChanges
+boolean queueTypeChanged = parameter.getQueueType() != null && 
+    !Objects.equals(BlockingQueueManager.getQueueType(executor.getQueue()), parameter.getQueueType());
+
+if (queueTypeChanged) {
+    boolean swapped = BlockingQueueManager.replaceQueue(
+        executor, BlockingQueueManager.createQueue(parameter.getQueueType(), parameter.getCapacity()));
+    ...
+}
+```
+
+

docs/i18n/zh/docusaurus-plugin-content-docs/version-1.5.0/user_docs/dev_manual/queue-info.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 3
+---
+
+# 内置阻塞队列
+
+Hippo4j 内置多种常用阻塞队列类型，支持开箱即用，亦可通过 SPI 扩展自定义队列类型。
+
+## 内置类型清单
+
+以下类型可直接在服务端或配置中选择（枚举：`BlockingQueueTypeEnum`）：
+
+- ArrayBlockingQueue（数组有界队列）
+- LinkedBlockingQueue（链表队列）
+- LinkedBlockingDeque（双端队列）
+- SynchronousQueue（同步移交队列）
+- LinkedTransferQueue（可转移队列）
+- PriorityBlockingQueue（优先级队列）
+- ResizableCapacityLinkedBlockingQueue（可在线动态调容量的链表队列）
+
+其中 `ResizableCapacityLinkedBlockingQueue` 支持在线变更 `capacity`，无需重建线程池，适合动态调优场景。
+
+## 代码对应
+
+枚举定义：
+
+```java
+// cn.hippo4j.common.executor.support.BlockingQueueTypeEnum
+RESIZABLE_LINKED_BLOCKING_QUEUE(9, "ResizableCapacityLinkedBlockingQueue") {
+    @Override
+    <T> BlockingQueue<T> of(Integer capacity) {
+        return new ResizableCapacityLinkedBlockingQueue<>(capacity);
+    }
+    @Override
+    <T> BlockingQueue<T> of() {
+        return new ResizableCapacityLinkedBlockingQueue<>();
+    }
+}
+```
+
+创建与验证：
+
+```java
+// cn.hippo4j.common.executor.support.BlockingQueueManager
+BlockingQueue<T> q = BlockingQueueManager.createQueue(queueType, capacity);
+boolean valid = BlockingQueueManager.validateQueueConfig(queueType, capacity);
+boolean ok = BlockingQueueManager.changeQueueCapacity(executor.getQueue(), newCapacity);
+```
+
+## 使用建议
+
+- 需要在线调容量：优先选择 `ResizableCapacityLinkedBlockingQueue`
+- 需要严格有界：选择 `ArrayBlockingQueue`
+- 需要无界吞吐：选择 `LinkedBlockingQueue`
+- 需要优先级：选择 `PriorityBlockingQueue`
+- 需要同步移交：选择 `SynchronousQueue`
+
+如需自定义队列类型，请参考《阻塞队列自定义》。
+
+