From 388e18af2a431a5860b1ea03f23a11b7817f8063 Mon Sep 17 00:00:00 2001
From: asahi <mikiyashiki@outlook.com>
Date: Wed, 3 Sep 2025 15:51:32 +0800
Subject: [PATCH] =?UTF-8?q?doc:=20=E9=98=85=E8=AF=BBTimeLimiter=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../CircuitBreaker/CircuitBreaker.md          | 68 ++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)

diff --git a/spring/Spring Cloud/CircuitBreaker/CircuitBreaker.md b/spring/Spring Cloud/CircuitBreaker/CircuitBreaker.md
index c82efe0..faaaae5 100644
--- a/spring/Spring Cloud/CircuitBreaker/CircuitBreaker.md	
+++ b/spring/Spring Cloud/CircuitBreaker/CircuitBreaker.md	
@@ -38,6 +38,10 @@
     - [Decorate and execute a functional interface](#decorate-and-execute-a-functional-interface-3)
     - [consume emitted RegistryEvents](#consume-emitted-registryevents-3)
     - [use custom IntervalFunction](#use-custom-intervalfunction)
+  - [TimeLimiter](#timelimiter)
+    - [Create a TimeLimiterRegistry](#create-a-timelimiterregistry)
+    - [Create and configure TimeLimiter](#create-and-configure-timelimiter)
+    - [decorate and execute a functional interface](#decorate-and-execute-a-functional-interface-4)
 
 
 # CircuitBreaker
@@ -861,4 +865,66 @@ RetryConfig retryConfig = RetryConfig.custom()
 >
 > 如果指定了intervalFunction，那么在通过builder创建RetryConfig时，会自动通过intervalFunction给intervalBiFunction也赋值。
 >
-> 如果指定了intervalFunction或intervalBiFunction中任一，则使用指定的函数来计算waitDuration，当二者都没有指定时，则waitDuration固定为waitDuration
\ No newline at end of file
+> 如果指定了intervalFunction或intervalBiFunction中任一，则使用指定的函数来计算waitDuration，当二者都没有指定时，则waitDuration固定为waitDuration
+
+## TimeLimiter
+### Create a TimeLimiterRegistry
+和`CircuitBreaker` module类似，TimeLimiter module支持提供in-memory TimeLimiterRegistry，可用于管理TimeLimiter实例。
+```java
+TimeLimiterRegistry timeLimiterRegistry = TimeLimiterRegistry.ofDefaults();
+```
+
+### Create and configure TimeLimiter
+可以提供一个全局的自定义TimeLimiterConfig，支持通过builder创建。
+
+TimeLimiterConfig支持配置如下两个参数：
+- the timeout duration
+- whether cancel should be called on the running future
+
+使用示例如下所示：
+```java
+TimeLimiterConfig config = TimeLimiterConfig.custom()
+   .cancelRunningFuture(true)
+   .timeoutDuration(Duration.ofMillis(500))
+   .build();
+
+// Create a TimeLimiterRegistry with a custom global configuration
+TimeLimiterRegistry timeLimiterRegistry = TimeLimiterRegistry.of(config);
+
+// Get or create a TimeLimiter from the registry - 
+// TimeLimiter will be backed by the default config
+TimeLimiter timeLimiterWithDefaultConfig = registry.timeLimiter("name1");
+
+// Get or create a TimeLimiter from the registry, 
+// use a custom configuration when creating the TimeLimiter
+TimeLimiterConfig config = TimeLimiterConfig.custom()
+   .cancelRunningFuture(false)
+   .timeoutDuration(Duration.ofMillis(1000))
+   .build();
+
+TimeLimiter timeLimiterWithCustomConfig = registry.timeLimiter("name2", config);
+```
+### decorate and execute a functional interface
+TimeLimiter可以对`CompletionStage`和`Future`进行decorate，示例如下：
+```java
+// Given I have a helloWorldService.sayHelloWorld() method which takes too long
+HelloWorldService helloWorldService = mock(HelloWorldService.class);
+
+// Create a TimeLimiter
+TimeLimiter timeLimiter = TimeLimiter.of(Duration.ofSeconds(1));
+// The Scheduler is needed to schedule a timeout on a non-blocking CompletableFuture
+ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(3);
+
+// The non-blocking variant with a CompletableFuture
+CompletableFuture<String> result = timeLimiter.executeCompletionStage(
+  scheduler, () -> CompletableFuture.supplyAsync(helloWorldService::sayHelloWorld)).toCompletableFuture();
+
+// The blocking variant which is basically future.get(timeoutDuration, MILLISECONDS)
+String result = timeLimiter.executeFutureSupplier(
+  () -> CompletableFuture.supplyAsync(() -> helloWorldService::sayHelloWorld));
+```
+
+在TimeLimiter的实现中，`timeoutDuration`设置了`等待future执行结束的最长等待时间`，如果该等待时间超时，将会抛出`TimeoutException`。
+
+当发生等待超时时，将会根据`shouldCancelRunningFuture`参数的配置来决定`是否针对尚未执行完成的future调用cancel`。
+