Copilot commented on code in PR #3229:
URL: https://github.com/apache/brpc/pull/3229#discussion_r2869230222
##########
docs/en/backup_request.md:
##########
@@ -39,6 +39,81 @@ my_func_latency << tm.u_elapsed(); // u represents for
microsecond, and s_elaps
// All work is done here. My_func_qps, my_func_latency, my_func_latency_cdf
and many other counters would be shown in /vars.
```
+## Rate-limited backup requests
+
+To limit the ratio of backup requests sent, use the built-in factory function
or implement the `BackupRequestPolicy` interface yourself.
+
+Priority order: `backup_request_policy` > `backup_request_ms`.
+
+### Using the built-in rate-limiting policy
+
+Call `CreateRateLimitedBackupPolicy` and set the result on
`ChannelOptions.backup_request_policy`:
+
+```c++
+#include "brpc/backup_request_policy.h"
+#include <memory>
+
+brpc::RateLimitedBackupPolicyOptions opts;
+opts.backup_request_ms = 10; // send backup if RPC does not complete
within 10ms
+opts.max_backup_ratio = 0.3; // cap backup requests at 30% of total
+opts.window_size_seconds = 10; // sliding window width in seconds
+opts.update_interval_seconds = 5; // how often the cached ratio is refreshed
+
+// The caller owns the returned pointer.
+// Use unique_ptr to manage the lifetime; ensure the policy outlives the
channel.
+std::unique_ptr<brpc::BackupRequestPolicy> policy(
+ brpc::CreateRateLimitedBackupPolicy(opts));
+
+brpc::ChannelOptions options;
+options.backup_request_policy = policy.get(); // NOT owned by channel
+channel.Init(..., &options);
+// policy is released automatically when unique_ptr goes out of scope,
+// as long as it outlives the channel.
Review Comment:
This sentence is self-contradictory: a unique_ptr *does* release the policy
when it goes out of scope, which would violate the requirement that the policy
outlives the channel. Consider rewording to explicitly state that the
unique_ptr must remain alive until after the channel is destroyed (e.g., keep
it in the same scope/object that owns the channel).
```suggestion
// The caller owns the returned pointer and must keep it alive.
// Use unique_ptr to manage the lifetime, and ensure the policy (and
unique_ptr)
// outlive the channel (for example, store them as members of the same
object).
std::unique_ptr<brpc::BackupRequestPolicy> policy(
brpc::CreateRateLimitedBackupPolicy(opts));
brpc::ChannelOptions options;
options.backup_request_policy = policy.get(); // NOT owned by channel
channel.Init(..., &options);
// Do NOT let 'policy' go out of scope while 'channel' is still in use,
// otherwise the channel will hold a dangling pointer.
```
##########
docs/cn/backup_request.md:
##########
@@ -39,6 +39,80 @@ my_func_latency << tm.u_elapsed(); // u代表微秒，还有s_elapsed(),
m_elap
// 好了，在/vars中会显示my_func_qps, my_func_latency, my_func_latency_cdf等很多计数器。
```
+## Backup Request 限流
+
+如需限制 backup request 的发送比例，可使用内置工厂函数创建限流策略，也可自行实现 `BackupRequestPolicy` 接口。
+
+优先级顺序：`backup_request_policy` > `backup_request_ms`。
+
+### 使用内置限流策略
+
+调用 `CreateRateLimitedBackupPolicy` 创建限流策略，并将其设置到
`ChannelOptions.backup_request_policy`：
+
+```c++
+#include "brpc/backup_request_policy.h"
+#include <memory>
+
+brpc::RateLimitedBackupPolicyOptions opts;
+opts.backup_request_ms = 10; // 超过10ms未返回时发送backup请求
+opts.max_backup_ratio = 0.3; // backup请求比例上限30%
+opts.window_size_seconds = 10; // 滑动窗口宽度（秒）
+opts.update_interval_seconds = 5; // 缓存比例的刷新间隔（秒）
+
+// CreateRateLimitedBackupPolicy返回的指针由调用方负责释放。
+// 推荐使用unique_ptr管理生命周期，确保policy在Channel销毁后才释放。
+std::unique_ptr<brpc::BackupRequestPolicy> policy(
+ brpc::CreateRateLimitedBackupPolicy(opts));
+
+brpc::ChannelOptions options;
+options.backup_request_policy = policy.get(); // Channel不拥有该对象
+channel.Init(..., &options);
+// policy在unique_ptr析构时自动释放，确保其生命周期长于channel即可。
+```
+
+参数说明（`RateLimitedBackupPolicyOptions`）：
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `backup_request_ms` | -1 | 超时阈值（毫秒）。-1 表示继承
`ChannelOptions.backup_request_ms`（仅在通过 `ChannelOptions.backup_request_policy`
设置策略时有效；通过 Controller 注入时没有 channel 级的回退值，应显式指定 >= 0 的值）。必须 >= -1。 |
+| `max_backup_ratio` | 0.1 | backup比例上限，取值范围 (0, 1] |
+| `window_size_seconds` | 10 | 滑动窗口宽度（秒），取值范围 [1, 3600] |
+| `update_interval_seconds` | 5 | 缓存刷新间隔（秒），必须 >= 1 |
+
Review Comment:
The markdown table rows here start with `||`, which creates an extra empty
column in GitHub-flavored markdown. Consider using a standard table format with
a single leading/trailing `|` per row so the table renders as intended.
##########
docs/en/backup_request.md:
##########
@@ -39,6 +39,81 @@ my_func_latency << tm.u_elapsed(); // u represents for
microsecond, and s_elaps
// All work is done here. My_func_qps, my_func_latency, my_func_latency_cdf
and many other counters would be shown in /vars.
```
+## Rate-limited backup requests
+
+To limit the ratio of backup requests sent, use the built-in factory function
or implement the `BackupRequestPolicy` interface yourself.
+
+Priority order: `backup_request_policy` > `backup_request_ms`.
+
+### Using the built-in rate-limiting policy
+
+Call `CreateRateLimitedBackupPolicy` and set the result on
`ChannelOptions.backup_request_policy`:
+
+```c++
+#include "brpc/backup_request_policy.h"
+#include <memory>
+
+brpc::RateLimitedBackupPolicyOptions opts;
+opts.backup_request_ms = 10; // send backup if RPC does not complete
within 10ms
+opts.max_backup_ratio = 0.3; // cap backup requests at 30% of total
+opts.window_size_seconds = 10; // sliding window width in seconds
+opts.update_interval_seconds = 5; // how often the cached ratio is refreshed
+
+// The caller owns the returned pointer.
+// Use unique_ptr to manage the lifetime; ensure the policy outlives the
channel.
+std::unique_ptr<brpc::BackupRequestPolicy> policy(
+ brpc::CreateRateLimitedBackupPolicy(opts));
+
+brpc::ChannelOptions options;
+options.backup_request_policy = policy.get(); // NOT owned by channel
+channel.Init(..., &options);
+// policy is released automatically when unique_ptr goes out of scope,
+// as long as it outlives the channel.
+```
+
+`RateLimitedBackupPolicyOptions` fields:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `backup_request_ms` | -1 | Timeout threshold in ms. -1 means inherit from
`ChannelOptions.backup_request_ms` (only works when the policy is set via
`ChannelOptions.backup_request_policy`; at controller level there is no
channel-level fallback, so set an explicit >= 0 value instead). Must be >= -1. |
+| `max_backup_ratio` | 0.1 | Max backup ratio; range (0, 1] |
+| `window_size_seconds` | 10 | Sliding window width in seconds; range [1,
3600] |
+| `update_interval_seconds` | 5 | Cached-ratio refresh interval in seconds;
must be >= 1 |
+
Review Comment:
The markdown table here starts each row with `||`, which renders as an extra
empty column in standard GitHub-flavored markdown. Consider formatting the
table with a single leading/trailing `|` per row (e.g., `| Field | Default |
Description |`) so it renders correctly.
##########
docs/cn/backup_request.md:
##########
@@ -39,6 +39,80 @@ my_func_latency << tm.u_elapsed(); // u代表微秒，还有s_elapsed(),
m_elap
// 好了，在/vars中会显示my_func_qps, my_func_latency, my_func_latency_cdf等很多计数器。
```
+## Backup Request 限流
+
+如需限制 backup request 的发送比例，可使用内置工厂函数创建限流策略，也可自行实现 `BackupRequestPolicy` 接口。
+
+优先级顺序：`backup_request_policy` > `backup_request_ms`。
+
+### 使用内置限流策略
+
+调用 `CreateRateLimitedBackupPolicy` 创建限流策略，并将其设置到
`ChannelOptions.backup_request_policy`：
+
+```c++
+#include "brpc/backup_request_policy.h"
+#include <memory>
+
+brpc::RateLimitedBackupPolicyOptions opts;
+opts.backup_request_ms = 10; // 超过10ms未返回时发送backup请求
+opts.max_backup_ratio = 0.3; // backup请求比例上限30%
+opts.window_size_seconds = 10; // 滑动窗口宽度（秒）
+opts.update_interval_seconds = 5; // 缓存比例的刷新间隔（秒）
+
+// CreateRateLimitedBackupPolicy返回的指针由调用方负责释放。
+// 推荐使用unique_ptr管理生命周期，确保policy在Channel销毁后才释放。
+std::unique_ptr<brpc::BackupRequestPolicy> policy(
+ brpc::CreateRateLimitedBackupPolicy(opts));
+
+brpc::ChannelOptions options;
+options.backup_request_policy = policy.get(); // Channel不拥有该对象
+channel.Init(..., &options);
+// policy在unique_ptr析构时自动释放，确保其生命周期长于channel即可。
Review Comment:
The note about using unique_ptr is misleading: if the unique_ptr goes out of
scope it will free the policy, which must *not* happen while the channel is
still using it. Consider rephrasing to state clearly that the unique_ptr (or
other owner) must live longer than the channel instance.
```suggestion
// 推荐使用unique_ptr或其他所有者管理生命周期，且该所有者的生命周期必须不短于使用它的Channel。
std::unique_ptr<brpc::BackupRequestPolicy> policy(
brpc::CreateRateLimitedBackupPolicy(opts));
brpc::ChannelOptions options;
options.backup_request_policy = policy.get(); // Channel不拥有该对象，仅保存原始指针
channel.Init(..., &options);
// policy会在unique_ptr析构时自动释放，请确保持有该unique_ptr的对象（或作用域）比channel活得更久，
// 例如将policy作为与channel同生命周期的成员变量，而不要在channel仍在使用时销毁它。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
