--- name: reference-timer description: >- MAX 内部定时器工具类完整 API 参考和使用指南。当用户编写定时任务、周期轮询、延时执行、 使用 CompensatingTimer/DispatcherTimerController/SystemTimerController/ThreadingTimerController 时自动加载。 disable-model-invocation: false --- # MAX 定时器工具类参考 项目提供了 4 个定时器工具类,分布在 `MAX.Common` 和 `MAX.Common.WPF` 中,封装了不同底层定时器并统一了反重入和异常处理。 --- ## 选择决策树 ``` 需要定时触发某操作? ├── 需要在 UI 线程执行(操作 WPF 控件/绑定属性) │ └── DispatcherTimerController ✅ │ ├── 需要自校准(消除累积漂移,如精确的周期采样) │ └── CompensatingTimer ✅ │ ├── 需要首次触发延迟(due time)+ 固定周期 │ └── ThreadingTimerController ✅ │ ├── 简单的线程池周期执行,不需要特殊功能 │ ├── SystemTimerController(有 Start/Stop,需手动控制) │ └── ThreadingTimerController(构造即启动,dispose 即停) ``` --- ## 1. CompensatingTimer — 自校准定时器 **命名空间:** `MAX.Common.Utilities`(位于 `MAX.Common` 库) **底层:** `System.Timers.Timer`(`AutoReset = false`,手动调度) **执行线程:** 线程池 ### 核心特性 - **自校准**:每次 tick 基于"预期执行时间"累加 interval,而非"实际经过时间"。这消除了累积漂移——即使单次回调执行时间有波动,长期也精确保持 interval 间隔。 - **跳过错过的时间槽**:如果回调执行太久,错过了下一次触发时间,它会快进到未来的下一个时间槽,丢弃已错过的 tick,防止连续触发导致 CPU 满载。 - **无异步支持**:回调是 `Action`(同步),不支持 `Func`。 - **异常通过 `OnTickException` 事件外抛**(不会被吞)。 ### 构造函数 ```csharp public CompensatingTimer(TimeSpan interval, Action tickCallback) ``` | 参数 | 说明 | |---|---| | `interval` | 触发间隔,必须 > 0ms | | `tickCallback` | 每次触发时执行的委托 | ### API ```csharp public class CompensatingTimer : IDisposable { public event Action? OnTickException; public CompensatingTimer(TimeSpan interval, Action tickCallback); public void Start(); // 启动(已启动则忽略) public void Stop(); // 停止 public void Dispose(); // 停止并释放底层 Timer } ``` ### 使用示例 ```csharp using MAX.Common.Utilities; // 每 100ms 采集一次数据,精确间隔,无累积漂移 CompensatingTimer timer = new(TimeSpan.FromMilliseconds(100), () => { double value = sensor.Read(); buffer.Add(value); }); timer.OnTickException += ex => Debug.WriteLine(ex); timer.Start(); // 停止时 timer.Dispose(); ``` ### 适用场景 - 数据采集(需要精确采样间隔) - 心跳检测 - 需要长时间稳定周期、不随回调执行时间偏移的定时任务 --- ## 2. DispatcherTimerController — UI 线程定时器 **命名空间:** `MAX.Common.WPF.Utilities.Timers`(位于 `MAX.Common.WPF` 库) **底层:** WPF `DispatcherTimer` **执行线程:** **UI 线程**(可直接操作 WPF 控件和绑定属性) ### 核心特性 - **UI 线程执行**,可直接更新绑定的 MVVM 属性。 - 支持 **`Action`(同步)** 和 **`Func`(异步)** 两种回调。 - **防重入**:如果上一次回调仍在执行,新的 tick 会被跳过(`isTickRunning` 门控)。 - 可通过 `DispatcherPriority` 控制调度优先级。 - 异常通过 `ExceptionOccurred` 事件外抛。 ### 构造函数 ```csharp // 同步回调 public DispatcherTimerController(DispatcherPriority dispatcherPriority, TimeSpan interval, Action action, Dispatcher dispatcher = null); // 异步回调 public DispatcherTimerController(DispatcherPriority dispatcherPriority, TimeSpan interval, Func actionAsync, Dispatcher dispatcher = null); ``` | 参数 | 说明 | |---|---| | `dispatcherPriority` | 调度优先级,常用 `DispatcherPriority.Background` 或 `DispatcherPriority.Normal` | | `interval` | 触发间隔 | | `action` / `actionAsync` | 回调委托(同步或异步) | | `dispatcher` | 可选,指定 Dispatcher;默认当前 UI 线程 | ### API ```csharp public class DispatcherTimerController : TimerControllerBase { public event TypedEventHandler ExceptionOccurred; public virtual void Start(); // 启动 public virtual void Stop(); // 停止 public override void Dispose(); // 停止、取消订阅、释放 } ``` ### 使用示例 ```csharp using MAX.Common.WPF.Utilities.Timers; using System.Windows.Threading; internal class DashboardViewModel : ViewModelBaseEx { private DispatcherTimerController? _refreshTimer; protected override void LoadedOnce() { // 每 5 秒异步刷新仪表盘数据 _refreshTimer = new DispatcherTimerController( DispatcherPriority.Background, TimeSpan.FromSeconds(5), RefreshDashboardAsync ); _refreshTimer.ExceptionOccurred += (s, ex) => Debug.WriteLine(ex); _refreshTimer.Start(); } private async Task RefreshDashboardAsync() { LatestData = await dataService.FetchLatestAsync(); } protected override void Unloaded() { _refreshTimer?.Dispose(); } } ``` ### 适用场景 - UI 定时刷新(仪表盘、状态栏、时钟) - 轮询后更新绑定属性 - 任何需要在 UI 线程执行的周期操作 --- ## 3. SystemTimerController — System.Timers 定时器 **命名空间:** `MAX.Common.WPF.Utilities.Timers`(位于 `MAX.Common.WPF` 库) **底层:** `System.Timers.Timer`(`AutoReset = true`,自动重复触发) **执行线程:** 线程池 ### 核心特性 - `AutoReset = true`,自动按 interval 重复触发。 - 支持 **`Action`(同步)** 和 **`Func`(异步)** 两种回调。 - **防重入**:如果上一次回调仍在执行,新的 tick 会被跳过。 - 有 `Start()` / `Stop()` 控制生命周期。 - 异常通过 `ExceptionOccurred` 事件外抛。 ### 构造函数 ```csharp // 同步回调 public SystemTimerController(TimeSpan interval, Action action); // 异步回调 public SystemTimerController(TimeSpan interval, Func actionAsync); ``` ### API ```csharp public class SystemTimerController : TimerControllerBase { public event TypedEventHandler ExceptionOccurred; public void Start(); // 启动 public void Stop(); // 停止 public override void Dispose(); // 停止并释放底层 Timer } ``` ### 使用示例 ```csharp using MAX.Common.WPF.Utilities.Timers; // 每 30 秒在后台清理过期缓存 SystemTimerController cleaner = new(TimeSpan.FromSeconds(30), () => { cache.CleanExpired(); }); cleaner.ExceptionOccurred += (s, ex) => Debug.WriteLine(ex); cleaner.Start(); // 停止时 cleaner.Dispose(); ``` ### 适用场景 - 后台定时清理/维护任务 - 不需要 UI 线程的周期性工作 - 需要 `Start`/`Stop` 显式控制(与 `ThreadingTimerController` 的区别) --- ## 4. ThreadingTimerController — System.Threading 定时器 **命名空间:** `MAX.Common.WPF.Utilities.Timers`(位于 `MAX.Common.WPF` 库) **底层:** `System.Threading.Timer` **执行线程:** 线程池 ### 核心特性 - 支持首次触发延迟(`due` 参数)和周期(`period` 参数)。 - 支持 **`Action`(同步)** 和 **`Func`(异步)** 两种回调。 - **防重入**:如果上一次回调仍在执行,新的 tick 会被跳过。 - **无 `Start`/`Stop`**:构造函数创建后立即开始触发,`Dispose()` 时停止。 - 异常通过 `ExceptionOccurred` 事件外抛。 ### 构造函数 ```csharp // 同步回调 — 无延迟 public ThreadingTimerController(TimeSpan period, Action action); // 同步回调 — 有延迟 public ThreadingTimerController(TimeSpan period, TimeSpan due, Action action); // 异步回调 — 无延迟 public ThreadingTimerController(TimeSpan period, Func actionAsync); // 异步回调 — 有延迟 public ThreadingTimerController(TimeSpan period, TimeSpan due, Func actionAsync); ``` | 参数 | 说明 | |---|---| | `period` | 触发周期 | | `due` | 首次触发前的延迟(不传则 `TimeSpan.Zero`,立即执行首次) | | `action` / `actionAsync` | 回调委托 | ### API ```csharp public class ThreadingTimerController : TimerControllerBase { public event TypedEventHandler ExceptionOccurred; // 无 Start / Stop public override void Dispose(); // 释放底层 Timer } ``` ### 使用示例 ```csharp using MAX.Common.WPF.Utilities.Timers; // 延迟 10 秒后,每 1 分钟检查一次许可证状态 ThreadingTimerController licenseChecker = new( period: TimeSpan.FromMinutes(1), due: TimeSpan.FromSeconds(10), actionAsync: CheckLicenseAsync ); licenseChecker.ExceptionOccurred += (s, ex) => Debug.WriteLine(ex); // 停止时(无需 Stop,直接 Dispose) licenseChecker.Dispose(); ``` ### 适用场景 - 需要"延迟启动"的周期性任务 - 不需要显式 `Start`/`Stop`,生命周期跟随对象 - 轻量级的 fire-and-forget 定时 --- ## 5. 共同模式 ### 防重入机制 `DispatcherTimerController`、`SystemTimerController`、`ThreadingTimerController` 都内置了 `isTickRunning` 门控: - 每次 tick 进入时检查,如果上一次回调还未结束,**跳过本次 tick**。 - 这防止了"回调执行慢于间隔"时积压多个并发执行。 ### 异常处理 三个 `TimerControllerBase` 子类统一通过 `ExceptionOccurred` 事件外抛异常,同时会调用 `Debug.WriteLine(exception)` + `Debugger.Break()`。 `CompensatingTimer` 通过 `OnTickException` 事件外抛异常(仅 `Debug.WriteLine`,无 `Debugger.Break`)。 ### Dispose 模式 所有四个类都实现 `IDisposable`。`Dispose()` 会自动停止定时器并释放底层资源。三个 `TimerControllerBase` 子类会额外调用 `GC.SuppressFinalize(this)`。 --- ## 6. 对照速查 | 类 | 底层 Timer | 执行线程 | 异步支持 | Start/Stop | 首次延迟 | 自校准 | |---|---|---|---|---|---|---| | `CompensatingTimer` | `System.Timers` | 线程池 | ❌ 仅 Action | ✅ | ❌ | ✅ | | `DispatcherTimerController` | WPF `DispatcherTimer` | **UI 线程** | ✅ | ✅ | ❌ | ❌ | | `SystemTimerController` | `System.Timers` | 线程池 | ✅ | ✅ | ❌ | ❌ | | `ThreadingTimerController` | `System.Threading` | 线程池 | ✅ | ❌ 构造即启 | ✅ `due` | ❌ |