mormot.core.threads--TSynBackgroundTimer
type
// TSynBackgroundThreadProcess 類宣告（稍後定義）
TSynBackgroundThreadProcess = class;
/// 由 TSynBackgroundThreadProcess 定期執行的事件回撥
TOnSynBackgroundThreadProcess = procedure(Sender: TSynBackgroundThreadProcess) of object;
/// 能夠以給定週期執行方法的 TThread 類
TSynBackgroundThreadProcess = class(TSynBackgroundThreadAbstract)
protected
fOnProcess: TOnSynBackgroundThreadProcess; // 定期執行的方法回撥
fOnException: TNotifyEvent; // 當 OnProcess 引發異常時執行的事件回撥
fOnProcessMS: cardinal; // 定期執行任務的時間間隔（毫秒）
fStats: TSynMonitor; // 處理統計資訊
procedure ExecuteLoop; override; // 重寫執行迴圈
public
/// 初始化執行緒以進行週期性任務處理
// - 當 ProcessEvent.SetEvent 被呼叫或自上次處理以來過去了 aOnProcessMS 毫秒時，將呼叫 aOnProcess
// - 如果 aOnProcessMS 為 0，則等待直到 ProcessEvent.SetEvent 被呼叫
// - 您可以定義一些回撥來巢狀執行緒執行，例如，分配給 TRestServer.BeginCurrentThread/EndCurrentThread
constructor Create(const aThreadName: RawUtf8;
const aOnProcess: TOnSynBackgroundThreadProcess;
aOnProcessMS: cardinal; const aOnBeforeExecute: TOnNotifyThread = nil;
const aOnAfterExecute: TOnNotifyThread = nil;
aStats: TSynMonitorClass = nil;
CreateSuspended: boolean = false); reintroduce; virtual;
/// 終結執行緒並等待其結束
destructor Destroy; override;
/// 訪問週期性任務的實現事件
property OnProcess: TOnSynBackgroundThreadProcess
read fOnProcess;
/// 當 OnProcess 引發異常時執行的事件回撥
// - 提供的 Sender 引數是引發的異常例項
property OnException: TNotifyEvent
read fOnException write fOnException;
published
/// 訪問週期性任務處理的延遲時間（毫秒）
property OnProcessMS: cardinal
read fOnProcessMS write fOnProcessMS;
/// 處理統計資訊
// - 如果在類建構函式中 aStats 為 nil，則可能為 nil
property Stats: TSynMonitor
read fStats;
end;
// TSynBackgroundTimer 類宣告（稍後定義）
TSynBackgroundTimer = class;
/// 由 TSynBackgroundThreadProcess 定期執行的事件回撥（特定於 TSynBackgroundTimer）
// - 如果此任務 FIFO 中沒有掛起的訊息，則 Msg 為 ''
// - 對於此任務 FIFO 中的每個掛起訊息，都會設定 Msg
// - 在 mORMot 1 中，有一個 TWaitEvent 引數，現在已被移除
TOnSynBackgroundTimerProcess = procedure(Sender: TSynBackgroundTimer;
const Msg: RawUtf8) of object;
/// TSynBackgroundTimer 內部註冊列表使用的記錄型別
TSynBackgroundTimerTask = record
OnProcess: TOnSynBackgroundTimerProcess; // 處理任務的回撥過程
Secs: cardinal; // 任務執行的間隔時間（秒）
NextTix: Int64; // 下一次執行任務的時間戳
Msg: TRawUtf8DynArray; // 與此任務關聯的待處理訊息佇列
MsgSafe: TLightLock; // 保護 Msg[] 列表的輕量級鎖
end;
/// 儲存 TSynBackgroundTimer 內部註冊列表的動態陣列型別
TSynBackgroundTimerTaskDynArray = array of TSynBackgroundTimerTask;
/// 能夠在後臺執行緒中以定期的速度執行一個或多個任務的執行緒類
// - 例如，透過繼承自 TRestBackgroundTimer 的 TRest.TimerEnable/TimerDisable 方法使用
// - 每個程序可以有自己的文字訊息 FIFO 佇列
// - 如果您期望更新某些 GUI，則應該使用 TTimer 元件（例如，週期為 200ms），
// 因為 TSynBackgroundTimer 將使用它自己的獨立執行緒
TSynBackgroundTimer = class(TSynBackgroundThreadProcess)
protected
fTask: TSynBackgroundTimerTaskDynArray; // 內部任務列表
fTasks: TDynArrayLocked; // 任務列表的封裝和同步訪問
fProcessing: boolean; // 標記當前是否有任務正在處理
fProcessingCounter: integer; // 處理中的任務計數器（可能是內部使用）
procedure EverySecond(Sender: TSynBackgroundThreadProcess); // 每秒執行一次的回撥，用於處理任務
function Find(const aProcess: TMethod): PtrInt; // 查詢已註冊的任務（內部使用）
function Add(const aOnProcess: TOnSynBackgroundTimerProcess;
const aMsg: RawUtf8; aExecuteNow: boolean): boolean; // 新增任務到內部列表
public
/// 初始化執行緒以進行週期性任務處理
// - 您可以定義一些回撥來巢狀執行緒執行，例如，
// 分配給 TRestServer.BeginCurrentThread/EndCurrentThread，如 TRestBackgroundTimer.Create 所做
constructor Create(const aThreadName: RawUtf8;
const aOnBeforeExecute: TOnNotifyThread = nil;
aOnAfterExecute: TOnNotifyThread = nil;
aStats: TSynMonitorClass = nil;
aLogClass: TSynLogClass = nil); reintroduce; virtual;
/// 銷燬執行緒
destructor Destroy; override;
/// 為在固定秒數週期上執行的任務定義一個處理方法
// - 對於 mORMot 服務上的後臺程序，請考慮使用 TRest 的
// TimerEnable/TimerDisable 方法及其關聯的 BackgroundTimer 執行緒
procedure Enable(const aOnProcess: TOnSynBackgroundTimerProcess;
aOnProcessSecs: cardinal);
/// 取消定義在固定秒數週期上執行的任務
// - aOnProcess 應透過之前的 Enable() 方法呼叫進行註冊
// - 成功時返回 true，如果提供的任務未註冊則返回 false
// - 對於 mORMot 服務上的後臺程序，請考慮使用 TRestServer 的
// TimerEnable/TimerDisable 方法及其 TSynBackgroundTimer 執行緒
function Disable(const aOnProcess: TOnSynBackgroundTimerProcess): boolean;
/// 在任務的下一次執行期間新增要處理的訊息
// - 提供的訊息將被新增到與 aOnProcess 關聯的內部 FIFO 列表中，
// 然後作為 aMsg 引數傳遞給每次呼叫
// - 如果 aExecuteNow 為 true，則不會等待下一個 aOnProcessSecs 的發生
// - aOnProcess 應透過之前的 Enable() 方法呼叫進行註冊
// - 成功時返回 true，如果提供的任務未註冊則返回 false
function EnQueue(const aOnProcess: TOnSynBackgroundTimerProcess;
const aMsg: RawUtf8; aExecuteNow: boolean = false): boolean; overload;
/// 在任務的下一次執行期間新增要處理的訊息（格式化版本）
// - ...（與上一個 EnQueue 過載類似，但允許格式化訊息）
function EnQueue(const aOnProcess: TOnSynBackgroundTimerProcess;
const aMsgFmt: RawUtf8; const Args: array of const;
aExecuteNow: boolean = false): boolean; overload;
/// 從處理列表中刪除訊息
// - 提供的訊息將在與 aOnProcess 關聯的內部 FIFO 列表中進行搜尋，
// 如果找到則從列表中刪除
// - aOnProcess 應透過之前的 Enable() 方法呼叫進行註冊
// - 成功時返回 true，如果提供的訊息未註冊則返回 false
function DeQueue(const aOnProcess: TOnSynBackgroundTimerProcess;
const aMsg: RawUtf8): boolean;
/// 不等待下一個 aOnProcessSecs 發生，立即執行任務
// - aOnProcess 應透過之前的 Enable() 方法呼叫進行註冊
// - 成功時返回 true，如果提供的任務未註冊則返回 false
function ExecuteNow(const aOnProcess: TOnSynBackgroundTimerProcess): boolean;
/// 不等待下一個 aOnProcessSecs 發生，僅執行一次任務
// - aOnProcess 不需要透過之前的 Enable() 方法呼叫進行註冊
function ExecuteOnce(const aOnProcess: TOnSynBackgroundTimerProcess): boolean;
/// 等待直到沒有後臺任務正在處理
procedure WaitUntilNotProcessing(timeoutsecs: integer = 10);
/// 對內部任務列表的低階訪問
property Task: TSynBackgroundTimerTaskDynArray read fTask;
/// 對內部任務列表封裝和安全的低階訪問
property Tasks: TDynArrayLocked read fTasks;
/// 返回當前是否有任務正在處理
property Processing: boolean read fProcessing;
end;
以下是一個使用 TSynBackgroundTimer類的示例。在這個示例中，我們將建立一個 TSynBackgroundTimer例項，啟用一個週期性任務，向該任務新增訊息，並等待一段時間以觀察其執行。請注意，由於 TSynBackgroundTimer是設計為在後臺執行緒中執行的，因此我們需要確保主執行緒不會立即退出，以便能夠看到後臺任務的效果。
uses
SysUtils, // 包含WriteLn等標準輸出函式
mormot.core.threads;
// 定義一個處理定時任務的回撥過程
procedure MyTimerTask(Sender: TObject; const Msg: RawUtf8);
begin
WriteLn('Timer task executed at ' + DateTimeToStr(Now) + '. Message: ' + Msg);
// 在這裡執行定時任務的其他邏輯...
end;
var
Timer: TSynBackgroundTimer;
begin
try
// 建立TSynBackgroundTimer例項
Timer := TSynBackgroundTimer.Create('MyBackgroundTimer');
try
// 啟用一個週期性任務，每2秒執行一次
Timer.Enable(@MyTimerTask, 2);
// 向任務佇列新增訊息
Timer.EnQueue(@MyTimerTask, 'Hello from the background timer!');
// 假設我們想要等待一段時間來觀察後臺定時器的行為
// 注意：在實際應用中，您可能不需要這樣做，因為主執行緒可能會執行其他任務
WriteLn('Waiting for 10 seconds...');
Sleep(10000); // 等待10秒
// 如果需要，可以禁用週期性任務（在這個示例中我們不會禁用它）
// Timer.Disable(@MyTimerTask);
// 注意：由於我們呼叫了Sleep，主執行緒被阻塞了，因此我們可以看到後臺定時器的輸出
// 在實際應用中，您可能不需要這樣做，因為主執行緒可能會繼續執行其他任務
finally
// 銷燬TSynBackgroundTimer例項
// 注意：在實際應用中，您可能希望等待所有後臺任務完成後再銷燬定時器
// 但在這個簡單示例中，我們立即銷燬它
Timer.Free;
// 由於我們立即銷燬了定時器，並且主執行緒繼續執行（儘管在這個示例中被Sleep阻塞了），
// 因此後臺執行緒可能在定時器被銷燬後仍然嘗試執行回撥，這可能會導致訪問違規。
// 在實際應用中，您應該確保在銷燬定時器之前所有後臺任務都已經完成。
// 一個簡單的方法是呼叫Timer.WaitUntilNotProcessing，但這在這個示例中是不必要的，
// 因為我們立即銷燬了定時器並且知道沒有更多的任務會被新增。
end;
except
on E: Exception do
WriteLn('Error: ' + E.Message);
end;
// 注意：在實際應用中，主執行緒可能會繼續執行其他任務，
// 而後臺定時器將在其自己的執行緒中繼續執行，直到被禁用或銷燬。
// 在這個示例中，由於我們呼叫了Sleep並且立即銷燬了定時器，
// 因此後臺執行緒可能沒有機會執行更多的回撥。
WriteLn('Program ended.');
// 在實際應用中，您可能希望在這裡新增更多的清理程式碼或繼續執行其他任務。
end.
重要注意事項：
- 在上述示例中，我們呼叫了
Sleep(10000);來模擬主執行緒中的其他工作，以便我們可以看到後臺定時器的行為。在實際應用中，您可能不需要這樣做，因為主執行緒可能會執行其他有用的任務。 - 我們立即銷燬了
TSynBackgroundTimer例項，這在實際應用中可能不是最佳做法。在銷燬定時器之前，您應該確保所有後臺任務都已經完成。一個更安全的方法是呼叫Timer.WaitUntilNotProcessing（儘管在這個簡單示例中它是不必要的）。但是，請注意，如果定時器被禁用或沒有更多的任務被新增，那麼呼叫WaitUntilNotProcessing可能會立即返回。 - 由於我們呼叫了
Sleep並且立即銷燬了定時器，因此後臺執行緒可能沒有機會執行更多的回撥。在實際應用中，您應該確保在銷燬定時器之前給後臺執行緒足夠的時間來完成其工作。 - 請確保將
'YourSynapseUnit'替換為包含TSynBackgroundTimer定義的實際單元名稱。
當然，以下是根據上述類定義編寫的 TSynBackgroundThreadProcess和 TSynBackgroundTimer兩個類的例程程式碼。請注意，由於這些類可能依賴於特定的庫（如mORMot），以下示例將盡可能地保持通用性，並假設您已經有一個適當的環境來執行這些程式碼。
TSynBackgroundThreadProcess 例程程式碼
uses
SysUtils, Classes, // 引入SysUtils和Classes單元以使用WriteLn和TThread等
// 假設YourSynapseUnit包含了TSynBackgroundThreadProcess的定義
YourSynapseUnit;
procedure MyProcessMethod(Sender: TSynBackgroundThreadProcess);
begin
WriteLn('Process method called in background thread.');
// 在這裡執行您的後臺處理邏輯
end;
var
BGThread: TSynBackgroundThreadProcess;
begin
try
// 建立TSynBackgroundThreadProcess例項
BGThread := TSynBackgroundThreadProcess.Create(
'MyBackgroundThread', // 執行緒名稱
MyProcessMethod, // 週期性執行的方法
1000, // 週期時間，單位為毫秒
nil, // OnBeforeExecute回撥，這裡不使用
nil // OnAfterExecute回撥，這裡不使用
// aStats和其他引數根據需要進行設定
);
try
// 啟動執行緒（注意：在TSynBackgroundThreadProcess的建構函式中，
// 如果CreateSuspended引數為false，則執行緒將自動啟動）
// 在這個例子中，我們假設CreateSuspended預設為false
// 等待一段時間以觀察後臺執行緒的行為
// 注意：在實際應用中，您可能不需要這樣做，因為主執行緒可能會繼續執行其他任務
Sleep(5000); // 等待5秒
finally
// 銷燬執行緒物件（注意：在解構函式中，執行緒將嘗試優雅地終止）
BGThread.Free;
// 等待執行緒真正結束（可選，但在這個例子中我們依賴解構函式的行為）
end;
except
on E: Exception do
WriteLn('Error: ' + E.Message);
end;
WriteLn('Program ended.');
end.
注意：在上面的示例中，我假設 TSynBackgroundThreadProcess的建構函式有一個 CreateSuspended引數（這在標準的 TThread建構函式中是存在的），但根據您提供的類定義，這個引數實際上並沒有在 TSynBackgroundThreadProcess的建構函式中明確列出。如果 TSynBackgroundThreadProcess是自動啟動執行緒的，那麼您可能不需要顯式呼叫任何啟動方法。
TSynBackgroundTimer 例程程式碼
uses
SysUtils, // 引入SysUtils單元以使用WriteLn
mormot.core.os,
mormot.core.Thread;
procedure MyTimerProcess(Sender: TSynBackgroundTimer; const Msg: RawUtf8);
begin
WriteLn('Timer process called in background thread. Message: ' + Msg);
// 在這裡執行您的定時任務邏輯
end;
var
Timer: TSynBackgroundTimer;
begin
try
// 建立TSynBackgroundTimer例項
Timer := TSynBackgroundTimer.Create(
'MyBackgroundTimer' // 執行緒名稱
// 其他引數根據需要進行設定，這裡省略了OnBeforeExecute、OnAfterExecute、aStats和aLogClass
);
try
// 啟用一個週期性任務，每2秒執行一次
Timer.Enable(@MyTimerProcess, 2);
// 向任務佇列新增訊息，並請求立即執行（儘管在這個上下文中，立即執行可能不會立即發生）
Timer.EnQueue(@MyTimerProcess, 'Hello from background timer!', true);
// 等待一段時間以觀察後臺定時器的行為
// 注意：在實際應用中，您可能不需要這樣做，因為主執行緒可能會繼續執行其他任務
Sleep(10000); // 等待10秒
// 禁用週期性任務（在這個示例中我們不會禁用它，但展示瞭如何禁用）
// Timer.Disable(@MyTimerProcess);
finally
// 銷燬TSynBackgroundTimer例項（注意：在實際應用中，您可能希望等待所有後臺任務完成後再銷燬定時器）
// 但在這個簡單示例中，我們立即銷燬它
Timer.Free;
// 由於我們立即銷燬了定時器，並且主執行緒繼續執行（儘管在這個示例中被Sleep阻塞了），
// 因此後臺執行緒可能沒有機會執行更多的回撥。
// 在實際應用中，您應該確保在銷燬定時器之前給後臺執行緒足夠的時間來完成其工作。
end;
except
on E: Exception do
WriteLn('Error: ' + E.Message);
end;
WriteLn('Program ended.');
end.
在上面的 TSynBackgroundTimer示例中，我展示瞭如何建立定時器、啟用週期性任務、向任務佇列新增訊息，並等待一段時間以觀察定時器的行為。請注意，由於我們呼叫了 Sleep並且立即銷燬了定時器，因此後臺執行緒可能沒有機會執行更多的回撥。在實際應用中，您應該確保在銷燬定時器之前給後臺執行緒足夠的時間來完成其工作，或者呼叫 Timer.WaitUntilNotProcessing（如果該類提供了這樣的方法）來等待所有後臺任務完成。然而，根據提供的類定義，TSynBackgroundTimer並沒有直接提供 WaitUntilNotProcessing方法，所以您可能需要實現自己的同步機制來達到這個目的。