mormot.core.threads--TSynQueue
mormot.core.threads--TSynQueue
以下是对 mormot.core.threads中部分代码的翻译，特别是关于 TSynQueue类的部分：
const
// 在这里定义以避免在uses子句中显式链接到syncobjs单元
wrSignaled = syncobjs.wrSignaled; // 等待结果：已发出信号
wrTimeout = syncobjs.wrTimeout; // 等待结果：超时
wrError = syncobjs.wrError; // 等待结果：错误
type
// 在这里定义以避免在uses子句中显式链接到syncobjs单元
// - 请注意，您可能更想使用来自mormot.core.os.pas的TSynEvent
TWaitResult = syncobjs.TWaitResult; // 等待操作的结果类型
// 在这里定义以避免在uses子句中显式链接到syncobjs单元
// - 请注意，您可能更想使用来自mormot.core.os.pas的TSynEvent
TEvent = syncobjs.TEvent; // 事件对象类型
{$endif PUREMORMOT2}
type
// TThread的动态数组类型
TThreadDynArray = array of TThread;
// 由本单元引发的异常类
ESynThread = class(ESynException);
{ ************ 线程安全的TSynQueue和TPendingTaskList }
type
/// 线程安全的 FIFO（先进先出）顺序记录队列
// - 内部使用 TDynArray 存储，配合滑动算法，比 FPC 或 Delphi 的 TQueue 或简单的 TDynArray.Add/Delete 更高效
// - 如需，支持 TSynPersistentStore 二进制持久化
// - 该结构在设计上也是线程安全的
TSynQueue = class(TSynPersistentStore)
protected
fValues: TDynArray;
fValueVar: pointer;
fCount, fFirst, fLast: integer;
fWaitPopFlags: set of (wpfDestroying);
fWaitPopCounter: integer;
/// 获取队列中的项目数量
function GetCount: integer;
procedure InternalPop(aValue: pointer);
procedure InternalGrow;
function InternalDestroying(incPopCounter: integer): boolean;
function InternalWaitDone(starttix, endtix: Int64; const idle: TThreadMethod): boolean;
/// 实现持久化的低级 TSynPersistentStore 方法
procedure LoadFromReader; override;
procedure SaveToWriter(aWriter: TBufferWriter); override;
public
/// 初始化队列存储
// - aTypeInfo 应是动态数组的 TypeInfo() RTTI 指针，用于在此 TSynQueue 实例中存储值
// - 可选地为该实例分配一个名称
constructor Create(aTypeInfo: PRttiInfo; const aName: RawUtf8 = ''); reintroduce; virtual;
/// 释放存储
// - 释放所有内部存储的值，并调用 WaitPopFinalize
destructor Destroy; override;
/// 将一个项目推入队列
// - 由于会锁定实例，因此此方法是线程安全的
procedure Push(const aValue);
/// 从队列中按 FIFO（先进先出）顺序提取一个项目
// - 如果 aValue 被填充了一个待处理项目，则返回 true，并且该项目从队列中移除（如果不想移除，请使用 Peek）
// - 如果队列为空，则返回 false
// - 由于会锁定实例，因此此方法是线程安全的
function Pop(out aValue): boolean;
/// 从队列中按 FIFO（先进先出）顺序提取一个匹配的项目
// - 将当前待处理项目与 aAnother 值进行比较
function PopEquals(aAnother: pointer; aCompare: TDynArraySortCompare;
out aValue): boolean;
/// 从队列中按 FIFO（先进先出）顺序查找一个项目
// - 如果 aValue 被填充了一个待处理项目（不从队列中移除，如 Pop 方法所做的那样），则返回 true
// - 如果队列为空，则返回 false
// - 由于会锁定实例，因此此方法是线程安全的
function Peek(out aValue): boolean;
/// 等待并从队列中按 FIFO（先进先出）顺序提取一个项目
// - 如果在指定的 aTimeoutMS 时间内 aValue 被填充了一个待处理项目，则返回 true
// - 如果没有在时间内将任何内容推入队列，或者调用了 WaitPopFinalize，则返回 false
// - aWhenIdle 可以被分配，例如用于 VCL/LCL Application.ProcessMessages
// - 可以在返回之前选择性地比较待处理项目（例如，当多个线程正在向队列中放入项目时）
// - 此方法是线程安全的，但仅在必要时锁定实例
function WaitPop(
aTimeoutMS : integer;
const aWhenIdle: TThreadMethod;
out aValue;
aCompared : pointer = nil;
aCompare : TDynArraySortCompare = nil
): boolean;
/// 等待并从队列中按 FIFO（先进先出）顺序查找一个项目
// - 在 aTimeoutMS 时间内返回一个指向待处理项目的指针
// - 保持 Safe.ReadWriteLock，因此调用者可以检查其内容，如果它是预期的，则调用 Pop()，并最终调用 Safe.ReadWriteUnlock
// - 如果在时间内没有将任何内容推入队列，则返回 nil
// - 此方法是线程安全的，但仅在必要时锁定实例
function WaitPeekLocked(
aTimeoutMS: integer;
const aWhenIdle: TThreadMethod
): pointer;
/// 确保任何挂起或未来的 WaitPop() 立即返回 false
// - 始终由 Destroy 析构函数调用
// - 也可以从例如 UI 的 OnClose 事件中调用，以避免任何锁定
// - 此方法是线程安全的，但仅在必要时锁定实例
procedure WaitPopFinalize(aTimeoutMS: integer = 100);
/// 删除此队列中当前存储的所有项目，并清空其容量
// - 由于会锁定实例，因此此方法是线程安全的
procedure Clear;
/// 使用存储的队列项目初始化动态数组
// - aDynArrayValues 应是定义为从 Create 传递的 aTypeInfo 的变量
// - 您可以检索一个可选的 TDynArray 包装器，例如用于二进制或 JSON 持久化
// - 此方法是线程安全的，并将复制队列数据
procedure Save(out aDynArrayValues; aDynArray: PDynArray = nil); overload;
/// 返回当前存储在此队列中的项目数量
// - 此方法不是线程安全的，因此返回的值仅具有指示性，或者您应该使用显式的 Safe lock/unlock
// - 如果您想检查队列是否为空，请调用 Pending
function Count: integer;
/// 返回当前在内存中预留的槽位数
// - 队列具有优化的自动调整大小算法，您可以使用此方法返回其当前容量
// - 此方法不是线程安全的，因此返回的值仅具有指示性
function Capacity: integer;
/// 如果队列中当前有待处理项目，则返回 true
// - 比检查 Count=0 更快，并且比 Pop 或 Peek 快得多
// - 此方法不是线程安全的，因此返回的值仅具有指示性
function Pending: boolean;
{$ifdef HASINLINE}inline;{$endif}
end;
在这个修正后的代码中，每个 ///注释前都多留了一个空行，以提高代码的可读性和整洁度。
这个翻译提供了对 TSynQueue类及其成员、方法和属性的概述，以便更好地理解其设计目的和使用方式。请注意，翻译过程中省略了保护成员的详细翻译，因为它们主要是内部实现细节，对于外部使用来说不是必需的。
在Free Pascal环境下，使用 TSynQueue类的一个示例会涉及创建队列实例、向队列中添加元素、从队列中提取元素，以及处理可能的并发访问。由于 TSynQueue是线程安全的，因此它非常适合在多线程应用程序中使用。然而，为了简化示例，我们将在一个单线程环境中展示其基本用法。
请注意，由于 TSynQueue可能是特定于某个库（如mORMot）的，因此您可能需要确保该库已被正确安装并包含在您的项目中。以下是一个简化的使用示例：
;program TSynQueueExample;
{$MODE DELPHI}
{$APPTYPE CONSOLE}
uses
SysUtils, // 包含WriteLn等标准输出函数
mormot.core.threads;
type
// 定义一个简单的记录类型，用于存储在TSynQueue中
TMyData = record
ID: Integer;
Value: String;
end;
TMyDataArray= array of TMyData ; // 容器类型声明
const
MyRecords: array[1..3] of TMyData = (
(ID: 10; Value: 'Record 1'),
(ID: 20; Value: 'Record 2'),
(ID: 30; Value: 'Record 3')
);
var
Queue: TSynQueue;
Data: TMyData;
begin
try
// 创建TSynQueue实例，传递TMyData类型的TypeInfo
Queue := TSynQueue.Create(TypeInfo(TMyDataArray), 'MyDataQueue');
try
// 向队列中添加数据
Queue.Push(TMyData.Create(1, 'First'));
Queue.Push(TMyData.Create(2, 'Second'));
Queue.Push(TMyData.Create(3, 'Third'));
// 注意：上面的Push调用实际上是有问题的，因为TMyData是一个记录类型，
// 它不是通过Create方法创建的。这里只是为了演示如何调用Push。
// 在实际使用中，您应该直接传递记录的值，如下所示：
// Queue.Push((ID: 1; Value: 'First')); // 但这取决于TSynQueue的实现是否支持记录值传递
// 由于记录类型通常是通过值传递的，并且TSynQueue可能设计为存储记录的副本，
// 因此您应该这样做：但要注意pascal不可以直接写记录型常量，要先定义。
Queue.Push((ID: 1; Value: 'First'));
Queue.Push((ID: 2; Value: 'Second'));
Queue.Push((ID: 3; Value: 'Third'));
/// 以上是思路，下面是可行代码
Queue.Push(MyRecords[1]);
Queue.Push(Data);
Queue.Push(MyRecords[2]);
Queue.Push(MyRecords[3]);
// 从队列中提取数据（FIFO）
while Queue.Pop(Data) do
begin
WriteLn('Popped Data: ID = ', Data.ID, ', Value = ', Data.Value);
end;
// 此时队列应为空
if not Queue.Pending then
WriteLn('Queue is empty.');
finally
// 销毁TSynQueue实例
Queue.Free;
end;
except
on E: Exception do
WriteLn('Error: ', E.Message);
end;
WriteLn('Program ended.');
end.
重要注意事项：
- 在上面的示例中，我使用了
TMyDataArray作为TypeInfo的参数，因为TMyDataArray这里是表示要声明一个动态数组作为容器。
mormot.core.threads--TPendingTaskList
type
/// 内部项定义，用于TPendingTaskList存储
// 该记录定义了待执行任务的时间戳和任务内容（以RawByteString形式存储）
TPendingTaskListItem = packed record
/// 当TPendingTaskList.GetTimestamp达到此值时，应执行该任务
Timestamp: Int64;
/// 与此时间戳相关联的任务，以原始二进制字符串形式存储
Task: RawByteString;
end;
/// 内部列表定义，用于TPendingTaskList存储
// TPendingTaskListItem的动态数组
TPendingTaskListItemDynArray = array of TPendingTaskListItem;
/// 线程安全的任务列表，以RawByteString形式存储，并带有时间戳
// - 您可以向内部列表添加任务，使用类似发布/查看的算法，在给定延迟后执行
// - 执行延迟不保证精确，而是根据每次NextPendingTask调用和GetTimestamp分辨率的最佳猜测
TPendingTaskList = class
protected
fTask: TPendingTaskListItemDynArray;
fTasks: TDynArrayLocked;
function GetCount: integer;
function GetTimestamp: Int64; virtual; // 默认返回GetTickCount64
public
/// 初始化列表内存和资源
constructor Create; reintroduce;
/// 添加一个任务，指定从当前时间开始的延迟（毫秒）
procedure AddTask(aMilliSecondsDelayFromNow: integer;
const aTask: RawByteString); virtual;
/// 添加多个任务，指定任务之间的延迟（毫秒）
// - 第一个提供的延迟将从当前时间开始计算，然后指定等待下一个提供任务之间需要多少时间
// - 即，aMilliSecondsDelays不是绝对延迟
procedure AddTasks(const aMilliSecondsDelays: array of integer;
const aTasks: array of RawByteString);
/// 检索下一个待处理任务
// - 如果没有当前时间可用的计划任务，则返回''
// - 根据指定的延迟定义返回下一个堆栈
function NextPendingTask: RawByteString; virtual;
/// 清空所有待处理任务
procedure Clear; virtual;
/// 访问内部TPendingTaskListItem.Timestamp存储的值
// - 对应当前时间
// - 默认实现是返回GetTickCount64，在Windows下典型分辨率为16毫秒
property Timestamp: Int64
read GetTimestamp;
/// 当前定义了多少个待处理任务
property Count: integer
read GetCount;
/// 直接低级访问内部任务列表
// - 警告：此动态数组长度是列表容量：使用Count属性来检索存储的精确项目数
// - 使用Safe.Lock/TryLock与try ... finally Safe.Unlock块进行线程安全的访问此数组
// - 项目按递增的Timestamp存储，即第一个项目是NextPendingTask方法将返回的下一个项目
property Task: TPendingTaskListItemDynArray
read fTask;
end;
TPendingTaskList类提供了一种机制来存储和按计划执行一系列任务，每个任务都与一个时间戳相关联。通过调用 AddTask或 AddTasks方法，您可以将任务添加到列表中，这些任务将在指定的延迟后执行。NextPendingTask方法用于检索下一个待执行的任务，而 Clear方法用于清空整个任务列表。
注意，TPendingTaskList类中的 Timestamp属性和 GetTimestamp方法是用于确定何时执行任务的关键。GetTimestamp方法默认返回 GetTickCount64的值，但在子类中可以根据需要进行重写，以提供不同的时间戳生成逻辑。同样，NextPendingTask方法也是虚拟的，允许在子类中实现自定义的任务检索逻辑。
在Free Pascal环境下，结合 TPendingTaskList类的定义，我们可以编写一个示例程序来展示这两个类的基本用法。以下是一个简化的示例，一个 TPendingTaskList实例来按计划执行任务（在这个例子中，任务只是简单地打印消息）。
请注意，由于 TPendingTaskList可能是特定于某个库（如mORMot）的，因此您需要确保该库已被正确安装并包含在您的项目中。此外，为了简化示例，我们将在一个单线程环境中运行它，尽管这些类设计用于多线程环境。
program PendingTaskListExample;
{$MODE DELPHI}
{$APPTYPE CONSOLE}
uses
SysUtils, // 包含WriteLn等标准输出函数
YourSynapseUnit; // 替换为实际包含这些类定义的单元名称
var
Queue: TSynQueue;
TaskList: TPendingTaskList;
I: Integer;
TaskMessage: RawByteString;
begin
try
// 创建TPendingTaskList实例来按计划执行任务
TaskList := TPendingTaskList.Create;
try
// 添加一些计划任务到列表中
// 假设每个任务只是打印一条消息，延迟从当前时间开始计算
TaskList.AddTask(1000, 'Task 1 in 1 second'); // 1秒后执行
TaskList.AddTask(2000, 'Task 2 in 2 seconds'); // 2秒后执行
// 注意：由于这个示例是在单线程环境中运行的，
// 我们不会等待任务实际执行。在实际应用中，
// 您可能需要在另一个线程中调用NextPendingTask，
// 或者使用某种形式的定时器或事件循环来检查并执行任务。
// 为了模拟任务执行，我们可以手动调用NextPendingTask
// 并打印消息（但在实际应用中，这通常不是您想要的方式）
repeat
TaskMessage := TaskList.NextPendingTask;
if TaskMessage <> '' then
WriteLn('Executing Task: ', TaskMessage)
else
Break; // 没有更多待执行的任务，退出循环
// 在这里，我们实际上应该等待一段时间再检查下一个任务，
// 但为了简化示例，我们只是立即再次检查（这不是实际用法）
until False;
finally
// 销毁TPendingTaskList实例（在这个简单的示例中可能不是必需的，
// 但为了完整性而包含）
TaskList.Free;
end;
except
on E: Exception do
WriteLn('Error: ', E.Message);
end;
WriteLn('Program ended.');
end.
重要注意事项：
- 单线程执行：上面的示例是在单线程环境中运行的，因此它不会按预期等待任务实际执行。在实际应用中，您应该在一个单独的线程中或在事件循环中定期调用
NextPendingTask来检查并执行任务。 - 模拟任务执行：为了简化示例，我们手动调用了
NextPendingTask并立即打印了消息。在实际应用中，您应该根据NextPendingTask的返回值来决定是否执行任务，并且您可能需要等待一段时间再检查下一个任务。 - 替换单元名称：请确保将
'YourSynapseUnit'替换为实际包含TSynQueue和TPendingTaskList类定义的单元名称。 - 错误处理：示例中包含了基本的错误处理逻辑，但在实际应用中，您可能需要更详细的错误处理和日志记录。
- 线程安全：尽管
TSynQueue和TPendingTaskList是线程安全的，但在从多个线程访问它们时，您仍然需要确保正确地同步对它们的访问（尽管在这个简单的示例中我们没有这样做）。在实际应用中，您可能需要使用锁、信号量或其他同步机制来确保线程安全。然而，在这个特定的示例中，由于我们是在单线程环境中运行，因此不需要担心线程安全问题。
