mormot.core.threads--TSynBackgroundTimer

mormot.core.threads--TSynBackgroundTimer

1. type
2.   // TSynBackgroundThreadProcess 类声明（稍后定义）
3.   TSynBackgroundThreadProcess = class;
5.   /// 由 TSynBackgroundThreadProcess 定期执行的事件回调
6.   TOnSynBackgroundThreadProcess = procedure(Sender: TSynBackgroundThreadProcess) of object;
8.   /// 能够以给定周期运行方法的 TThread 类
9.   TSynBackgroundThreadProcess = class(TSynBackgroundThreadAbstract)
10.   protected
11.     fOnProcess: TOnSynBackgroundThreadProcess; // 定期执行的方法回调
12.     fOnException: TNotifyEvent; // 当 OnProcess 引发异常时执行的事件回调
13.     fOnProcessMS: cardinal; // 定期执行任务的时间间隔（毫秒）
14.     fStats: TSynMonitor; // 处理统计信息
15.     procedure ExecuteLoop; override; // 重写执行循环
16.   public
17.     /// 初始化线程以进行周期性任务处理
18.     // - 当 ProcessEvent.SetEvent 被调用或自上次处理以来过去了 aOnProcessMS 毫秒时，将调用 aOnProcess
19.     // - 如果 aOnProcessMS 为 0，则等待直到 ProcessEvent.SetEvent 被调用
20.     // - 您可以定义一些回调来嵌套线程执行，例如，分配给 TRestServer.BeginCurrentThread/EndCurrentThread
21.     constructor Create(const aThreadName: RawUtf8;
22.       const aOnProcess: TOnSynBackgroundThreadProcess;
23.       aOnProcessMS: cardinal; const aOnBeforeExecute: TOnNotifyThread = nil;
24.       const aOnAfterExecute: TOnNotifyThread = nil;
25.       aStats: TSynMonitorClass = nil;
26.       CreateSuspended: boolean = false); reintroduce; virtual;
27.     /// 终结线程并等待其结束
28.     destructor Destroy; override;
29.     /// 访问周期性任务的实现事件
30.     property OnProcess: TOnSynBackgroundThreadProcess
31.       read fOnProcess;
32.     /// 当 OnProcess 引发异常时执行的事件回调
33.     // - 提供的 Sender 参数是引发的异常实例
34.     property OnException: TNotifyEvent
35.       read fOnException write fOnException;
36.   published
37.     /// 访问周期性任务处理的延迟时间（毫秒）
38.     property OnProcessMS: cardinal
39.       read fOnProcessMS write fOnProcessMS;
40.     /// 处理统计信息
41.     // - 如果在类构造函数中 aStats 为 nil，则可能为 nil
42.     property Stats: TSynMonitor
43.       read fStats;
44.   end;
46.   // TSynBackgroundTimer 类声明（稍后定义）
47.   TSynBackgroundTimer = class;
49.   /// 由 TSynBackgroundThreadProcess 定期执行的事件回调（特定于 TSynBackgroundTimer）
50.   // - 如果此任务 FIFO 中没有挂起的消息，则 Msg 为 ''
51.   // - 对于此任务 FIFO 中的每个挂起消息，都会设置 Msg
52.   // - 在 mORMot 1 中，有一个 TWaitEvent 参数，现在已被移除
53.   TOnSynBackgroundTimerProcess = procedure(Sender: TSynBackgroundTimer;
54.     const Msg: RawUtf8) of object;
56.   /// TSynBackgroundTimer 内部注册列表使用的记录类型
57.   TSynBackgroundTimerTask = record
58.     OnProcess: TOnSynBackgroundTimerProcess; // 处理任务的回调过程
59.     Secs: cardinal; // 任务执行的间隔时间（秒）
60.     NextTix: Int64; // 下一次执行任务的时间戳
61.     Msg: TRawUtf8DynArray; // 与此任务关联的待处理消息队列
62.     MsgSafe: TLightLock; // 保护 Msg[] 列表的轻量级锁
63.   end;
65.   /// 存储 TSynBackgroundTimer 内部注册列表的动态数组类型
66.   TSynBackgroundTimerTaskDynArray = array of TSynBackgroundTimerTask;
68.   /// 能够在后台线程中以定期的速度运行一个或多个任务的线程类
69.   // - 例如，通过继承自 TRestBackgroundTimer 的 TRest.TimerEnable/TimerDisable 方法使用
70.   // - 每个进程可以有自己的文本消息 FIFO 队列
71.   // - 如果您期望更新某些 GUI，则应该使用 TTimer 组件（例如，周期为 200ms），
72.   // 因为 TSynBackgroundTimer 将使用它自己的独立线程
73.   TSynBackgroundTimer = class(TSynBackgroundThreadProcess)
74.   protected
75.     fTask: TSynBackgroundTimerTaskDynArray; // 内部任务列表
76.     fTasks: TDynArrayLocked; // 任务列表的封装和同步访问
77.     fProcessing: boolean; // 标记当前是否有任务正在处理
78.     fProcessingCounter: integer; // 处理中的任务计数器（可能是内部使用）
79.     procedure EverySecond(Sender: TSynBackgroundThreadProcess); // 每秒执行一次的回调，用于处理任务
80.     function Find(const aProcess: TMethod): PtrInt; // 查找已注册的任务（内部使用）
81.     function Add(const aOnProcess: TOnSynBackgroundTimerProcess;
82.       const aMsg: RawUtf8; aExecuteNow: boolean): boolean; // 添加任务到内部列表
83.   public
84.     /// 初始化线程以进行周期性任务处理
85.     // - 您可以定义一些回调来嵌套线程执行，例如，
86.     // 分配给 TRestServer.BeginCurrentThread/EndCurrentThread，如 TRestBackgroundTimer.Create 所做
87.     constructor Create(const aThreadName: RawUtf8;
88.       const aOnBeforeExecute: TOnNotifyThread = nil;
89.       aOnAfterExecute: TOnNotifyThread = nil;
90.       aStats: TSynMonitorClass = nil;
91.       aLogClass: TSynLogClass = nil); reintroduce; virtual;
92.     /// 销毁线程
93.     destructor Destroy; override;
94.     /// 为在固定秒数周期上运行的任务定义一个处理方法
95.     // - 对于 mORMot 服务上的后台进程，请考虑使用 TRest 的
96.     // TimerEnable/TimerDisable 方法及其关联的 BackgroundTimer 线程
97.     procedure Enable(const aOnProcess: TOnSynBackgroundTimerProcess;
98.       aOnProcessSecs: cardinal);
99.     /// 取消定义在固定秒数周期上运行的任务
100.     // - aOnProcess 应通过之前的 Enable() 方法调用进行注册
101.     // - 成功时返回 true，如果提供的任务未注册则返回 false
102.     // - 对于 mORMot 服务上的后台进程，请考虑使用 TRestServer 的
103.     // TimerEnable/TimerDisable 方法及其 TSynBackgroundTimer 线程
104.     function Disable(const aOnProcess: TOnSynBackgroundTimerProcess): boolean;
105.     /// 在任务的下一次执行期间添加要处理的消息
106.     // - 提供的消息将被添加到与 aOnProcess 关联的内部 FIFO 列表中，
107.     // 然后作为 aMsg 参数传递给每次调用
108.     // - 如果 aExecuteNow 为 true，则不会等待下一个 aOnProcessSecs 的发生
109.     // - aOnProcess 应通过之前的 Enable() 方法调用进行注册
110.     // - 成功时返回 true，如果提供的任务未注册则返回 false
111.     function EnQueue(const aOnProcess: TOnSynBackgroundTimerProcess;
112.       const aMsg: RawUtf8; aExecuteNow: boolean = false): boolean; overload;
113.     /// 在任务的下一次执行期间添加要处理的消息（格式化版本）
114.     // - ...（与上一个 EnQueue 重载类似，但允许格式化消息）
115.     function EnQueue(const aOnProcess: TOnSynBackgroundTimerProcess;
116.       const aMsgFmt: RawUtf8; const Args: array of const;
117.       aExecuteNow: boolean = false): boolean; overload;
118.     /// 从处理列表中删除消息
119.     // - 提供的消息将在与 aOnProcess 关联的内部 FIFO 列表中进行搜索，
120.     // 如果找到则从列表中删除
121.     // - aOnProcess 应通过之前的 Enable() 方法调用进行注册
122.     // - 成功时返回 true，如果提供的消息未注册则返回 false
123.     function DeQueue(const aOnProcess: TOnSynBackgroundTimerProcess;
124.       const aMsg: RawUtf8): boolean;
125.     /// 不等待下一个 aOnProcessSecs 发生，立即执行任务
126.     // - aOnProcess 应通过之前的 Enable() 方法调用进行注册
127.     // - 成功时返回 true，如果提供的任务未注册则返回 false
128.     function ExecuteNow(const aOnProcess: TOnSynBackgroundTimerProcess): boolean;
129.     /// 不等待下一个 aOnProcessSecs 发生，仅执行一次任务
130.     // - aOnProcess 不需要通过之前的 Enable() 方法调用进行注册
131.     function ExecuteOnce(const aOnProcess: TOnSynBackgroundTimerProcess): boolean;
132.     /// 等待直到没有后台任务正在处理
133.     procedure WaitUntilNotProcessing(timeoutsecs: integer = 10);
134.     /// 对内部任务列表的低级访问
135.     property Task: TSynBackgroundTimerTaskDynArray read fTask;
136.     /// 对内部任务列表封装和安全的低级访问
137.     property Tasks: TDynArrayLocked read fTasks;
138.     /// 返回当前是否有任务正在处理
139.     property Processing: boolean read fProcessing;
140.   end;

复制代码

以下是一个使用 TSynBackgroundTimer类的示例。在这个示例中，我们将创建一个 TSynBackgroundTimer实例，启用一个周期性任务，向该任务添加消息，并等待一段时间以观察其实行。请注意，由于 TSynBackgroundTimer是设计为在背景线程中运行的，因此我们需要确保主线程不会立刻退出，以便能够看到背景任务的效果。

1. uses
2.   SysUtils, // 包含WriteLn等标准输出函数
3.   mormot.core.threads;
5. // 定义一个处理定时任务的回调过程
6. procedure MyTimerTask(Sender: TObject; const Msg: RawUtf8);
7. begin
8.   WriteLn('Timer task executed at ' + DateTimeToStr(Now) + '. Message: ' + Msg);
9.   // 在这里执行定时任务的其他逻辑...
10. end;
12. var
13.   Timer: TSynBackgroundTimer;
15. begin
16.   try
17.     // 创建TSynBackgroundTimer实例
18.     Timer := TSynBackgroundTimer.Create('MyBackgroundTimer');
19.     try
20.       // 启用一个周期性任务，每2秒执行一次
21.       Timer.Enable(@MyTimerTask, 2);
23.       // 向任务队列添加消息
24.       Timer.EnQueue(@MyTimerTask, 'Hello from the background timer!');
26.       // 假设我们想要等待一段时间来观察后台定时器的行为
27.       // 注意：在实际应用中，您可能不需要这样做，因为主线程可能会执行其他任务
28.       WriteLn('Waiting for 10 seconds...');
29.       Sleep(10000); // 等待10秒
31.       // 如果需要，可以禁用周期性任务（在这个示例中我们不会禁用它）
32.       // Timer.Disable(@MyTimerTask);
34.       // 注意：由于我们调用了Sleep，主线程被阻塞了，因此我们可以看到后台定时器的输出
35.       // 在实际应用中，您可能不需要这样做，因为主线程可能会继续执行其他任务
37.     finally
38.       // 销毁TSynBackgroundTimer实例
39.       // 注意：在实际应用中，您可能希望等待所有后台任务完成后再销毁定时器
40.       // 但在这个简单示例中，我们立即销毁它
41.       Timer.Free;
42.       // 由于我们立即销毁了定时器，并且主线程继续执行（尽管在这个示例中被Sleep阻塞了），
43.       // 因此后台线程可能在定时器被销毁后仍然尝试执行回调，这可能会导致访问违规。
44.       // 在实际应用中，您应该确保在销毁定时器之前所有后台任务都已经完成。
45.       // 一个简单的方法是调用Timer.WaitUntilNotProcessing，但这在这个示例中是不必要的，
46.       // 因为我们立即销毁了定时器并且知道没有更多的任务会被添加。
47.     end;
48.   except
49.     on E: Exception do
50.       WriteLn('Error: ' + E.Message);
51.   end;
53.   // 注意：在实际应用中，主线程可能会继续执行其他任务，
54.   // 而后台定时器将在其自己的线程中继续运行，直到被禁用或销毁。
55.   // 在这个示例中，由于我们调用了Sleep并且立即销毁了定时器，
56.   // 因此后台线程可能没有机会执行更多的回调。
57.   WriteLn('Program ended.');
58.   // 在实际应用中，您可能希望在这里添加更多的清理代码或继续执行其他任务。
59. end.

复制代码

重要注意事项：

• 在上述示例中，我们调用了 Sleep(10000);来模拟主线程中的其他工作，以便我们可以看到背景定时器的行为。在现实应用中，您可能不需要这样做，由于主线程可能会实行其他有用的任务。
  
• 我们立刻烧毁了 TSynBackgroundTimer实例，这在现实应用中可能不是最佳做法。在烧毁定时器之前，您应该确保全部背景任务都已经完成。一个更安全的方法是调用 Timer.WaitUntilNotProcessing（尽管在这个简单示例中它是不必要的）。但是，请注意，如果定时器被禁用或没有更多的任务被添加，那么调用 WaitUntilNotProcessing可能会立刻返回。
  
• 由于我们调用了 Sleep而且立刻烧毁了定时器，因今背景线程可能没有机会实行更多的回调。在现实应用中，您应该确保在烧毁定时器之前给背景线程足够的时间来完成其工作。
  
• 请确保将 'YourSynapseUnit'替换为包含 TSynBackgroundTimer界说的现实单元名称。
  

当然，以下是根据上述类界说编写的TSynBackgroundThreadProcess和TSynBackgroundTimer两个类的例程代码。请注意，由于这些类可能依靠于特定的库（如mORMot），以下示例将尽可能地保持通用性，并假设您已经有一个得当的环境来运行这些代码。
TSynBackgroundThreadProcess 例程代码

1. uses
2.   SysUtils, Classes, // 引入SysUtils和Classes单元以使用WriteLn和TThread等
3.   // 假设YourSynapseUnit包含了TSynBackgroundThreadProcess的定义
4.   YourSynapseUnit;
6. procedure MyProcessMethod(Sender: TSynBackgroundThreadProcess);
7. begin
8.   WriteLn('Process method called in background thread.');
9.   // 在这里执行您的后台处理逻辑
10. end;
12. var
13.   BGThread: TSynBackgroundThreadProcess;
15. begin
16.   try
17.     // 创建TSynBackgroundThreadProcess实例
18.     BGThread := TSynBackgroundThreadProcess.Create(
19.       'MyBackgroundThread', // 线程名称
20.       MyProcessMethod, // 周期性执行的方法
21.       1000, // 周期时间，单位为毫秒
22.       nil, // OnBeforeExecute回调，这里不使用
23.       nil  // OnAfterExecute回调，这里不使用
24.       // aStats和其他参数根据需要进行设置
25.     );
26.     try
27.       // 启动线程（注意：在TSynBackgroundThreadProcess的构造函数中，
28.       // 如果CreateSuspended参数为false，则线程将自动启动）
29.       // 在这个例子中，我们假设CreateSuspended默认为false
31.       // 等待一段时间以观察后台线程的行为
32.       // 注意：在实际应用中，您可能不需要这样做，因为主线程可能会继续执行其他任务
33.       Sleep(5000); // 等待5秒
35.     finally
36.       // 销毁线程对象（注意：在析构函数中，线程将尝试优雅地终止）
37.       BGThread.Free;
38.       // 等待线程真正结束（可选，但在这个例子中我们依赖析构函数的行为）
39.     end;
40.   except
41.     on E: Exception do
42.       WriteLn('Error: ' + E.Message);
43.   end;
44.   WriteLn('Program ended.');
45. end.

复制代码

注意：在上面的示例中，我假设TSynBackgroundThreadProcess的构造函数有一个CreateSuspended参数（这在尺度的TThread构造函数中是存在的），但根据您提供的类界说，这个参数现实上并没有在TSynBackgroundThreadProcess的构造函数中明确列出。如果TSynBackgroundThreadProcess是自动启动线程的，那么您可能不需要显式调用任何启动方法。
TSynBackgroundTimer 例程代码

1. uses
2.   SysUtils, // 引入SysUtils单元以使用WriteLn
3.   // 假设YourSynapseUnit包含了TSynBackgroundTimer的定义
4.   YourSynapseUnit;
6. procedure MyTimerProcess(Sender: TSynBackgroundTimer; const Msg: RawUtf8);
7. begin
8.   WriteLn('Timer process called in background thread. Message: ' + Msg);
9.   // 在这里执行您的定时任务逻辑
10. end;
12. var
13.   Timer: TSynBackgroundTimer;
15. begin
16.   try
17.     // 创建TSynBackgroundTimer实例
18.     Timer := TSynBackgroundTimer.Create(
19.       'MyBackgroundTimer' // 线程名称
20.       // 其他参数根据需要进行设置，这里省略了OnBeforeExecute、OnAfterExecute、aStats和aLogClass
21.     );
22.     try
23.       // 启用一个周期性任务，每2秒执行一次
24.       Timer.Enable(@MyTimerProcess, 2);
26.       // 向任务队列添加消息，并请求立即执行（尽管在这个上下文中，立即执行可能不会立即发生）
27.       Timer.EnQueue(@MyTimerProcess, 'Hello from background timer!', true);
29.       // 等待一段时间以观察后台定时器的行为
30.       // 注意：在实际应用中，您可能不需要这样做，因为主线程可能会继续执行其他任务
31.       Sleep(10000); // 等待10秒
33.       // 禁用周期性任务（在这个示例中我们不会禁用它，但展示了如何禁用）
34.       // Timer.Disable(@MyTimerProcess);
36.     finally
37.       // 销毁TSynBackgroundTimer实例（注意：在实际应用中，您可能希望等待所有后台任务完成后再销毁定时器）
38.       // 但在这个简单示例中，我们立即销毁它
39.       Timer.Free;
40.       // 由于我们立即销毁了定时器，并且主线程继续执行（尽管在这个示例中被Sleep阻塞了），
41.       // 因此后台线程可能没有机会执行更多的回调。
42.       // 在实际应用中，您应该确保在销毁定时器之前给后台线程足够的时间来完成其工作。
43.     end;
44.   except
45.     on E: Exception do
46.       WriteLn('Error: ' + E.Message);
47.   end;
48.   WriteLn('Program ended.');
49. end.

复制代码

在上面的TSynBackgroundTimer示例中，我展示了如何创建定时器、启用周期性任务、向任务队列添加消息，并等待一段时间以观察定时器的行为。请注意，由于我们调用了Sleep而且立刻烧毁了定时器，因今背景线程可能没有机会实行更多的回调。在现实应用中，您应该确保在烧毁定时器之前给背景线程足够的时间来完成其工作，或者调用Timer.WaitUntilNotProcessing（如果该类提供了这样的方法）来等待全部背景任务完成。然而，根据提供的类界说，TSynBackgroundTimer并没有直接提供WaitUntilNotProcessing方法，所以您可能需要实现本身的同步机制来达到这个目的。

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。