1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
//! 普通消费与微批的本地任务、责任数量和进展证据,不推断远端 PEL 或业务成功。
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
/// 当前领域 owner 的本地责任快照;各数量不代表 Redis 的持久消息总数。
#[derive(Debug, Clone, Default)]
pub struct RedisTaskObservation {
/// 尚未退出的普通消费任务,包括等待激活的任务。
pub consumers: usize,
/// 尚未退出的 PEL 回收任务。
pub reclaimers: usize,
/// 尚未退出的自动微批任务。
pub flushers: usize,
/// 入队但尚未被 flusher 取出的命令参数字节,不含编码、批次和等待提交者。
pub queued_parameter_bytes: usize,
/// 已接纳但尚无本地处理结束证据的工作次数;强制退出后仍保留,不能视为可安全重放。
pub unfinished: usize,
/// 已完成本地处理的工作次数;handler 失败、服务器错误或结果未知均不等于业务成功。
pub completed: u64,
/// 微批派发中没有取得完整传输结果的批次数。
pub batch_transport_failures: u64,
/// 最近一次有效读取、处理结束或批次回执距采样时刻的间隔;None 表示尚无进展证据。
pub last_progress_ago: Option<Duration>,
}
#[derive(Default)]
pub(crate) struct Activity {
/// 同锁维护本地数量、最后进展时刻及不可逆关闭标记,使发布与任务退出互斥。
state: Mutex<(RedisTaskObservation, Option<Instant>, bool)>,
}
pub(crate) enum TaskKind {
/// 从 Stream 接收新消息的普通消费责任。
Consumer,
/// 从 PEL 领取待恢复消息的回收责任。
Reclaimer,
/// 从本地队列组批发送的自动微批责任。
Flusher,
}
pub(crate) struct TaskGuard(
/// 任务退出时归还数量并撤销接流权威的本代状态。
Arc<Activity>,
/// 决定退出时归还哪一类任务数量。
TaskKind,
);
pub(crate) struct CompletionOwner<T> {
/// 与业务接流裁决共享的本代任务状态。
activity: Arc<Activity>,
/// 保留最终状态的通知端,其退出必须晚于本代准入撤销。
sender: tokio::sync::watch::Sender<T>,
}
impl<T> CompletionOwner<T> {
/// 业务作用:由唯一收尾 owner 发布领域退出证据。
///
/// 参数说明:
/// - `value`:已经裁决的本地状态或报告,不能把任务仍未退出描述为已完成。
///
/// 返回:替换保留的最新证据,不开放已关闭准入。
pub(crate) fn send_replace(&self, value: T) {
self.sender.send_replace(value);
}
}
impl<T> Drop for CompletionOwner<T> {
/// 业务作用:收尾 owner 失去责任前先撤销接流权威,包含执行器销毁和未首次轮询的路径。
///
/// 参数说明:无。
///
/// 返回:先与最终发布串行收口,再释放退出证据通道,不遗留可接流的旧快照。
fn drop(&mut self) {
self.activity.close();
}
}
impl Activity {
/// 业务作用:让独立收尾 owner 的退出与最终接流裁决使用同一保护。
///
/// 参数说明:
/// - `sender`:本代完成证据发布端,调用方应确保唯一收尾责任,不另留独立发布者。
///
/// 返回:持有证据通道的责任守卫,释放时先撤销准入再关闭通道。
pub(crate) fn completion<T>(
self: &Arc<Self>,
sender: tokio::sync::watch::Sender<T>,
) -> CompletionOwner<T> {
CompletionOwner {
activity: self.clone(),
sender,
}
}
/// 业务作用:永久撤销本代接流权威,并等待正在提交的本地发布完成。
///
/// 参数说明:无。
///
/// 返回:后续最终裁决均拒绝执行,不代表后台任务已经退出。
pub(crate) fn close(&self) {
self.state.lock().unwrap().2 = true;
}
/// 业务作用:在本地任务责任完整的保护范围内执行接流裁决,与任务退出串行化。
///
/// 参数说明:
/// - `consumers`:准备阶段固定的普通消费任务数。
/// - `reclaimers`:准备阶段固定的 PEL 回收任务数。
/// - `flushers`:准备阶段固定的自动微批任务数。
/// - `publish`:持锁执行的最终接流裁决,不得阻塞或重入本 owner 的状态操作。
///
/// 返回:本代未关闭且全部任务数匹配时返回裁决结果,否则不执行;不推断远端可用性。
pub(crate) fn with_tasks<T>(
&self,
consumers: usize,
reclaimers: usize,
flushers: usize,
publish: impl FnOnce() -> T,
) -> Option<T> {
let state = self.state.lock().unwrap();
// 关闭或固定任务缺席都使本代失去完整运行责任,不能以剩余任务仍存活为由开放业务。
if state.2
|| (state.0.consumers, state.0.reclaimers, state.0.flushers)
!= (consumers, reclaimers, flushers)
{
return None;
}
Some(publish())
}
/// 业务作用:在任务移交执行器之前登记责任,使未被首次轮询的取消也能归还数量。
///
/// 参数说明:
/// - `kind`:登记任务的固定类别,用于独立统计消费、回收或微批责任。
///
/// 返回:随任务 future 持有的退出守卫;登记增加对应数量,不重新开放已关闭的本代准入。
pub(crate) fn task(self: &Arc<Self>, kind: TaskKind) -> TaskGuard {
let mut state = self.state.lock().unwrap();
match kind {
TaskKind::Consumer => state.0.consumers += 1,
TaskKind::Reclaimer => state.0.reclaimers += 1,
TaskKind::Flusher => state.0.flushers += 1,
}
TaskGuard(self.clone(), kind)
}
/// 业务作用:登记已被本地接受的处理责任,准备阶段不虚构业务进展。
///
/// 参数说明:
/// - `count`:本次新增的未完成工作次数,必须与后续结束记账配对。
/// - `queued_bytes`:微批队列新增的命令参数字节,普通消费传零,不包含传输编码开销。
///
/// 返回:增加未完成数量和排队字节。
pub(crate) fn accept(&self, count: usize, queued_bytes: usize) {
let mut state = self.state.lock().unwrap();
state.0.unfinished += count;
state.0.queued_parameter_bytes += queued_bytes;
}
/// 业务作用:命令移入在途批次时解除其排队字节占用,未完成责任继续保留。
///
/// 参数说明:
/// - `bytes`:本次从队列取出的命令参数字节,必须已登记且不超过当前排队量。
///
/// 返回:减少排队字节,不表示写入已完成。
pub(crate) fn dequeue(&self, bytes: usize) {
self.state.lock().unwrap().0.queued_parameter_bytes -= bytes;
}
/// 业务作用:记录本轮处理结束或有效空轮询,保留结果与业务成功的区别。
///
/// 参数说明:
/// - `count`:已结束的本地工作次数,不得超过已登记未完成量;有效空轮询传零。
/// - `transport_failed`:本次微批是否缺少完整传输结果,为真时累计一次批次传输失败。
///
/// 返回:更新计数和进展时间;取消而未调用本方法的责任继续显示未完成。
pub(crate) fn finish(&self, count: usize, transport_failed: bool) {
let mut state = self.state.lock().unwrap();
state.0.unfinished -= count;
state.0.completed = state.0.completed.saturating_add(count as u64);
state.0.batch_transport_failures = state
.0
.batch_transport_failures
.saturating_add(u64::from(transport_failed));
state.1 = Some(Instant::now());
}
/// 业务作用:任务退出后释放本地队列字节,仍保留没有结果证据的命令数量。
///
/// 参数说明:无。
///
/// 返回:队列内存不再占用;不把未知工作标记为完成。
pub(crate) fn queue_dropped(&self) {
self.state.lock().unwrap().0.queued_parameter_bytes = 0;
}
/// 业务作用:读取有限维度的本地证据,不查询或改变 Redis 数据。
///
/// 参数说明:无。
///
/// 返回:同锁采样的数量与进展时间。
pub(crate) fn snapshot(&self) -> RedisTaskObservation {
let state = self.state.lock().unwrap();
let mut value = state.0.clone();
value.last_progress_ago = state.1.map(|at| at.elapsed());
value
}
}
impl Drop for TaskGuard {
/// 业务作用:任务 future 释放时归还对应存活数量,包含异常和取消路径。
///
/// 参数说明:无。
///
/// 返回:撤销本代接流权威并减少任务数,未完成工作仍需独立裁决。
fn drop(&mut self) {
let mut state = self.0.state.lock().unwrap();
// 固定任务中任意一个退出都使本代失去完整运行责任,不能继续发布 Ready。
state.2 = true;
match self.1 {
TaskKind::Consumer => state.0.consumers -= 1,
TaskKind::Reclaimer => state.0.reclaimers -= 1,
TaskKind::Flusher => state.0.flushers -= 1,
}
}
}