mormot.core.threads--TSynQueue

mormot.core.threads--TSynQueue

以下是对 mormot.core.threads中部分代码的翻译，特别是关于 TSynQueue类的部分：

1. const
2.   // 在这里定义以避免在uses子句中显式链接到syncobjs单元
3.   wrSignaled = syncobjs.wrSignaled; // 等待结果：已发出信号
4.   wrTimeout  = syncobjs.wrTimeout;  // 等待结果：超时
5.   wrError    = syncobjs.wrError;    // 等待结果：错误
7. type
8.   // 在这里定义以避免在uses子句中显式链接到syncobjs单元
9.   // - 请注意，您可能更想使用来自mormot.core.os.pas的TSynEvent
10.   TWaitResult = syncobjs.TWaitResult; // 等待操作的结果类型
12.   // 在这里定义以避免在uses子句中显式链接到syncobjs单元
13.   // - 请注意，您可能更想使用来自mormot.core.os.pas的TSynEvent
14.   TEvent = syncobjs.TEvent; // 事件对象类型
16. {$endif PUREMORMOT2}
18. type
19.   // TThread的动态数组类型
20.   TThreadDynArray = array of TThread;
22.   // 由本单元引发的异常类
23.   ESynThread = class(ESynException);
25. { ************ 线程安全的TSynQueue和TPendingTaskList }
27. type
28.   // 线程安全的FIFO（先进先出）记录队列
29.   // - 内部使用TDynArray存储，采用滑动算法，比FPC或Delphi的TQueue或简单的TDynArray.Add/Delete更高效
30.   // - 如果需要，支持TSynPersistentStore二进制持久化
31.   // - 此结构也是线程安全的
32.   TSynQueue = class(TSynPersistentStore)
33.   protected
34.     // ...（省略了保护成员的详细翻译，它们主要是内部实现细节）
35.   public
36.     /// 初始化队列存储
37.     // - aTypeInfo应该是存储在此TSynQueue实例中的值的动态数组TypeInfo() RTTI指针
38.     // - 可以选择性地为此实例分配一个名称
39.     constructor Create(aTypeInfo: PRttiInfo; const aName: RawUtf8 = ''); reintroduce; virtual;
40.     /// 释放存储
41.     // - 将释放所有内部存储的值，并调用WaitPopFinalize
42.     destructor Destroy; override;
43.     /// 将一个项目推入队列
44.     // - 此方法是线程安全的，因为它会锁定实例
45.     procedure Push(const aValue);
46.     /// 从队列中提取一个项目，作为FIFO（先进先出）
47.     // - 如果aValue已被填充为挂起的项目，则返回true，并且该项目从队列中移除（如果不想移除，请使用Peek）
48.     // - 如果队列为空，则返回false
49.     // - 此方法是线程安全的，因为它会锁定实例
50.     function Pop(out aValue): boolean;
51.     /// 从队列中提取一个匹配的项目，作为FIFO（先进先出）
52.     // - 将当前挂起的项目与aAnother值进行比较
53.     function PopEquals(aAnother: pointer; aCompare: TDynArraySortCompare;
54.       out aValue): boolean;
55.     /// 从队列中查找一个项目，作为FIFO（先进先出）
56.     // - 如果aValue已被填充为挂起的项目，则返回true，并且该项目不会从队列中移除（与Pop方法不同）
57.     // - 如果队列为空，则返回false
58.     // - 此方法是线程安全的，因为它会锁定实例
59.     function Peek(out aValue): boolean;
60.     /// 等待并从队列中提取一个项目，作为FIFO（先进先出）
61.     // - 如果在指定的aTimeoutMS时间内aValue已被填充为挂起的项目，则返回true
62.     // - 如果没有在时间内将项目推入队列，或者已调用WaitPopFinalize，则返回false
63.     // - aWhenIdle可用于空闲时处理消息，例如VCL/LCL的Application.ProcessMessages
64.     // - 您可以选择在返回之前比较挂起的项目（当多个线程将项目放入队列时可能很有用）
65.     // - 此方法是线程安全的，但仅在需要时锁定实例
66.     function WaitPop(aTimeoutMS: integer; const aWhenIdle: TThreadMethod;
67.       out aValue; aCompared: pointer = nil;
68.       aCompare: TDynArraySortCompare = nil): boolean;
69.     /// 在队列中等待查找一个项目，作为FIFO（先进先出）
70.     // - 在aTimeoutMS时间内返回一个指向挂起项目的指针
71.     // - 保持Safe.ReadWriteLock，因此调用者可以检查其内容，然后如果它是预期的，则调用Pop()，并最终调用Safe.ReadWriteUnlock
72.     // - 如果没有在时间内将项目推入队列，则返回nil
73.     // - 此方法是线程安全的，但仅在需要时锁定实例
74.     function WaitPeekLocked(aTimeoutMS: integer;
75.       const aWhenIdle: TThreadMethod): pointer;
76.     /// 确保任何挂起或未来的WaitPop()立即返回false
77.     // - 总是由Destroy析构函数调用
78.     // - 也可以从例如UI的OnClose事件中调用，以避免任何锁定
79.     // - 此方法是线程安全的，但仅在需要时锁定实例
80.     procedure WaitPopFinalize(aTimeoutMS: integer = 100);
81.     /// 删除此队列中当前存储的所有项目，并清空其容量
82.     // - 此方法是线程安全的，因为它会锁定实例
83.     procedure Clear;
84.     /// 用存储的队列项目初始化一个动态数组
85.     // - aDynArrayValues应该是Create方法中aTypeInfo定义的变量
86.     // - 您可以检索一个可选的TDynArray包装器，例如用于二进制或JSON持久化
87.     // - 此方法是线程安全的，并将复制队列数据
88.     procedure Save(out aDynArrayValues; aDynArray: PDynArray = nil); overload;
89.     /// 返回当前存储在此队列中的项目数
90.     // - 此方法不是线程安全的，因此返回的值应是指示性的，或者您应使用显式的Safe锁/解锁
91.     // - 如果您想检查队列是否为空，请调用Pending
92.     function Count: integer;
93.     /// 返回当前在内存中保留的槽位数
94.     // - 队列具有优化的自动调整大小算法，您可以使用此方法返回其当前容量
95.     // - 此方法不是线程安全的，因此返回的值是指示性的
96.     function Capacity: integer;
97.     /// 如果队列中有一些项目当前挂起，则返回true
98.     // - 比检查Count=0更快，并且比Pop或Peek快得多
99.     // - 此方法不是线程安全的，因此返回的值是指示性的
100.     function Pending: boolean;
101.       {$ifdef HASINLINE}inline;{$endif}
102.   end;

复制代码

这个翻译提供了对 TSynQueue类及其成员、方法和属性的概述，以便更好地理解其设计目的和使用方式。请注意，翻译过程中省略了保护成员的详细翻译，因为它们主要是内部实现细节，对于外部使用来说不是必须的。
在Free Pascal环境下，使用 TSynQueue类的一个示例会涉及创建队列实例、向队列中添加元素、从队列中提取元素，以及处理可能的并发访问。由于 TSynQueue是线程安全的，因此它非常恰当在多线程应用程序中使用。然而，为了简化示例，我们将在一个单线程环境中展示其基本用法。
请注意，由于 TSynQueue可能是特定于某个库（如mORMot）的，因此您可能需要确保该库已被正确安装并包含在您的项目中。以下是一个简化的使用示例：

1. program TSynQueueExample;
3. {$MODE DELPHI}
4. {$APPTYPE CONSOLE}
6. uses
7.   SysUtils, // 包含WriteLn等标准输出函数
8.   mormot.core.threads;
10. type
11.   // 定义一个简单的记录类型，用于存储在TSynQueue中
12.   TMyData = record
13.     ID: Integer;
14.     Value: String;
15.   end;
17. var
18.   Queue: TSynQueue;
19.   Data: TMyData;
21. begin
22.   try
23.     // 创建TSynQueue实例，传递TMyData类型的TypeInfo
24.     Queue := TSynQueue.Create(TypeInfo(TMyDataArray), 'MyDataQueue');
25.     try
26.       // 向队列中添加数据
27.       Queue.Push(TMyData.Create(1, 'First'));
28.       Queue.Push(TMyData.Create(2, 'Second'));
29.       Queue.Push(TMyData.Create(3, 'Third'));
31.       // 注意：上面的Push调用实际上是有问题的，因为TMyData是一个记录类型，
32.       // 它不是通过Create方法创建的。这里只是为了演示如何调用Push。
33.       // 在实际使用中，您应该直接传递记录的值，如下所示：
34.       // Queue.Push((ID: 1; Value: 'First')); // 但这取决于TSynQueue的实现是否支持记录值传递
36.       // 由于记录类型通常是通过值传递的，并且TSynQueue可能设计为存储记录的副本，
37.       // 因此您应该这样做：
38.       Queue.Push((ID: 1, Value: 'First'));
39.       Queue.Push((ID: 2, Value: 'Second'));
40.       Queue.Push((ID: 3, Value: 'Third'));
42.       // 从队列中提取数据（FIFO）
43.       while Queue.Pop(Data) do
44.       begin
45.         WriteLn('Popped Data: ID = ', Data.ID, ', Value = ', Data.Value);
46.       end;
48.       // 此时队列应为空
49.       if not Queue.Pending then
50.         WriteLn('Queue is empty.');
52.     finally
53.       // 销毁TSynQueue实例
54.       Queue.Free;
55.     end;
56.   except
57.     on E: Exception do
58.       WriteLn('Error: ', E.Message);
59.   end;
60.   WriteLn('Program ended.');
61. end.

复制代码

重要注意事项：

• 在上面的示例中，我使用了 TMyDataArray作为 TypeInfo的参数，但实际上 TypeInfo(TMyDataArray)可能不是有效的，因为 TMyDataArray在示例中并未界说。通常，您应该传递记录类型自己的 TypeInfo，但 TSynQueue可能盼望一个动态数组类型来存储其元素。然而，由于 TSynQueue的设计允许它存储记录的副本（而不是指针），因此您可能不需要界说一个动态数组类型。在实际使用中，您应该查阅 TSynQueue的文档以确定如何正确地传递 TypeInfo。
  
• 记录类型通常是通过值传递的，并且上面的 Push调用示例假设 TSynQueue能够处理记录值的直接传递。这取决于 TSynQueue的具体实现。如果 TSynQueue被设计为存储指向记录的指针，那么您可能需要界说一个动态数组类型或使用其他机制来传递记录。
  
• 由于 TSynQueue是线程安全的，因此在多线程环境中使用时，您不需要担心并发访问问题。但是，在上面的示例中，我们为了简化而在一个单线程环境中展示了其基本用法。
  
• 请确保将 'YourSynapseUnit'替换为实际包含 TSynQueue界说的单元名称。如果 TSynQueue是mORMot库的一部分，那么您可能需要包含mORMot的相应单元。
  

以下是对 TPendingTaskList及其相干类型的翻译，包括其保护类型、构造函数、方法和属性：

1. type
2.   /// 内部项定义，用于TPendingTaskList存储
3.   // 该记录定义了待执行任务的时间戳和任务内容（以RawByteString形式存储）
4.   TPendingTaskListItem = packed record
5.     /// 当TPendingTaskList.GetTimestamp达到此值时，应执行该任务
6.     Timestamp: Int64;
7.     /// 与此时间戳相关联的任务，以原始二进制字符串形式存储
8.     Task: RawByteString;
9.   end;
11.   /// 内部列表定义，用于TPendingTaskList存储
12.   // TPendingTaskListItem的动态数组
13.   TPendingTaskListItemDynArray = array of TPendingTaskListItem;
15.   /// 线程安全的任务列表，任务以RawByteString形式存储，并带有时间戳
16.   // - 您可以向内部列表添加任务，在给定延迟后执行，使用类似发布/查看的算法
17.   // - 执行延迟可能不准确，但会根据每次调用NextPendingTask和GetTimestamp的分辨率进行最佳猜测
18.   TPendingTaskList = class
19.   protected
20.     // 内部存储结构和同步访问
21.     fTask: TPendingTaskListItemDynArray; // 存储待执行任务的数组
22.     fTasks: TDynArrayLocked; // 对fTask数组的封装，提供线程安全的访问
23.     // 获取当前存储的任务数量（线程安全）
24.     function GetCount: integer;
25.     // 获取当前时间戳（默认为GetTickCount64）
26.     function GetTimestamp: Int64; virtual;
27.   public
28.     // 初始化列表的内存和资源
29.     constructor Create; reintroduce;
30.     // 添加一个任务，指定从当前时间开始的延迟（毫秒）
31.     procedure AddTask(aMilliSecondsDelayFromNow: integer;
32.       const aTask: RawByteString); virtual;
33.     // 添加多个任务，指定任务之间的延迟（毫秒）
34.     // - 第一个提供的延迟将从当前时间开始计算，然后指定下一个提供的任务之间的等待时间
35.     // - 也就是说，aMilliSecondsDelays不是绝对延迟
36.     procedure AddTasks(const aMilliSecondsDelays: array of integer;
37.       const aTasks: array of RawByteString);
38.     // 检索下一个待执行的任务
39.     // - 如果没有在当前时间可用的计划任务，则返回''
40.     // - 根据指定的延迟返回下一个任务
41.     function NextPendingTask: RawByteString; virtual;
42.     // 清空所有待执行的任务
43.     procedure Clear; virtual;
44.     // 访问内部存储的TPendingTaskListItem.Timestamp值
45.     // - 对应当前时间
46.     // - 默认实现返回GetTickCount64，在Windows下典型分辨率为16毫秒
47.     property Timestamp: Int64 read GetTimestamp;
48.     // 当前定义了多少个待执行任务
49.     property Count: integer read GetCount;
50.     // 对内部任务列表的直接低级访问
51.     // - 警告：此动态数组的长度是列表的容量：请使用Count属性来检索存储的项的确切数量
52.     // - 使用Safe.Lock/TryLock与try ... finally Safe.Unlock块进行线程安全的访问
53.     // - 项按时间戳递增存储，即第一项是NextPendingTask方法将返回的下一个项
54.     property Task: TPendingTaskListItemDynArray read fTask;
55.   end;

复制代码

TPendingTaskList类提供了一种机制来存储和按计划执行一系列任务，每个任务都与一个时间戳相干联。通过调用 AddTask或 AddTasks方法，您可以将任务添加到列表中，这些任务将在指定的耽误后执行。NextPendingTask方法用于检索下一个待执行的任务，而 Clear方法用于清空整个任务列表。
注意，TPendingTaskList类中的 Timestamp属性和 GetTimestamp方法是用于确定何时执行任务的关键。GetTimestamp方法默认返回 GetTickCount64的值，但在子类中可以根据需要进行重写，以提供差别的时间戳生成逻辑。同样，NextPendingTask方法也是虚拟的，允许在子类中实现自界说的任务检索逻辑。
在Free Pascal环境下，结合  TPendingTaskList类的界说，我们可以编写一个示例程序来展示这两个类的基本用法。以下是一个简化的示例，一个 TPendingTaskList实例来按计划执行任务（在这个例子中，任务只是简朴地打印消息）。
请注意，由于 TPendingTaskList可能是特定于某个库（如mORMot）的，因此您需要确保该库已被正确安装并包含在您的项目中。此外，为了简化示例，我们将在一个单线程环境中运行它，尽管这些类设计用于多线程环境。

1. program PendingTaskListExample;
3. {$MODE DELPHI}
4. {$APPTYPE CONSOLE}
6. uses
7.   SysUtils, // 包含WriteLn等标准输出函数
8.   YourSynapseUnit; // 替换为实际包含这些类定义的单元名称
10. var
11.   Queue: TSynQueue;
12.   TaskList: TPendingTaskList;
13.   I: Integer;
14.   TaskMessage: RawByteString;
16. begin
17.   try
18.     // 创建TPendingTaskList实例来按计划执行任务
19.     TaskList := TPendingTaskList.Create;
20.     try
21.       // 添加一些计划任务到列表中
22.       // 假设每个任务只是打印一条消息，延迟从当前时间开始计算
23.       TaskList.AddTask(1000, 'Task 1 in 1 second'); // 1秒后执行
24.       TaskList.AddTask(2000, 'Task 2 in 2 seconds'); // 2秒后执行
26.       // 注意：由于这个示例是在单线程环境中运行的，
27.       // 我们不会等待任务实际执行。在实际应用中，
28.       // 您可能需要在另一个线程中调用NextPendingTask，
29.       // 或者使用某种形式的定时器或事件循环来检查并执行任务。
31.       // 为了模拟任务执行，我们可以手动调用NextPendingTask
32.       // 并打印消息（但在实际应用中，这通常不是您想要的方式）
33.       repeat
34.         TaskMessage := TaskList.NextPendingTask;
35.         if TaskMessage <> '' then
36.           WriteLn('Executing Task: ', TaskMessage)
37.         else
38.           Break; // 没有更多待执行的任务，退出循环
40.         // 在这里，我们实际上应该等待一段时间再检查下一个任务，
41.         // 但为了简化示例，我们只是立即再次检查（这不是实际用法）
42.       until False;
44.     finally
45.       // 销毁TPendingTaskList实例（在这个简单的示例中可能不是必需的，
46.       // 但为了完整性而包含）
47.       TaskList.Free;
48.     end;
50.   except
51.     on E: Exception do
52.       WriteLn('Error: ', E.Message);
53.   end;
54.   WriteLn('Program ended.');
55. end.

复制代码

重要注意事项：

• 单线程执行：上面的示例是在单线程环境中运行的，因此它不会按预期等候任务实际执行。在实际应用中，您应该在一个单独的线程中或在事件循环中定期调用 NextPendingTask来检查并执行任务。
  
• 模拟任务执行：为了简化示例，我们手动调用了 NextPendingTask并立即打印了消息。在实际应用中，您应该根据 NextPendingTask的返回值来决定是否执行任务，并且您可能需要等候一段时间再检查下一个任务。
  
• 替换单元名称：请确保将 'YourSynapseUnit'替换为实际包含 TSynQueue和 TPendingTaskList类界说的单元名称。
  
• 错误处理：示例中包含了基本的错误处理逻辑，但在实际应用中，您可能需要更详细的错误处理和日志记录。
  
• 线程安全：尽管 TSynQueue和 TPendingTaskList是线程安全的，但在从多个线程访问它们时，您仍旧需要确保正确地同步对它们的访问（尽管在这个简朴的示例中我们没有这样做）。在实际应用中，您可能需要使用锁、信号量或其他同步机制来确保线程安全。然而，在这个特定的示例中，由于我们是在单线程环境中运行，因此不需要担心线程安全问题。
  

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