正文今天想寫的內容有點多，就不寫在紙上了。首先，最高興的，還是我們的《艾爾登法環》有了進展。我和兄長終於通過了 “火山官邸：地底拷問所”。我真是不知道，我和他在這個地方被那兩個擄人少女人拷問了多少次了。不僅如此，拉塔恩也打過了，去了亞壇高原，反正進展很大。周六的時候加班。從早上 10 點多，持 ...

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
  // 假設YourSynapseUnit包含了TSynBackgroundTimer的定義
  YourSynapseUnit;

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方法，所以您可能需要實現自己的同步機制來達到這個目的。