mormot.core.os--TSynLocker和TSynLocked
mormot.core.os--TSynLocker和TSynLocked
TLightLock
{ **************** TSynLocker/TSynLocked 和 低级线程特性 }
type
/// 一个轻量级的独占非重入锁，存储在 PtrUInt 值中
// - 在自旋一段时间后调用 SwitchToThread，但不使用任何读写操作系统API
// - 警告：方法是非重入的，即在一个裸调用中两次调用 Lock 会导致死锁：
// 对于需要重入方法的情况，请使用 TRWLock 或 TSynLocker/TOSLock
// - 多个轻量级锁，每个保护少量变量（如列表），可能比更全局的 TOSLock/TRWLock 更高效
// - 我们的轻量级锁预计保持时间非常短（几个CPU周期）：
// 如果锁可能阻塞太长时间，请使用 TSynLocker 或 TOSLock
// - TryLock/UnLock 可用于线程安全地获取共享资源
// - 在 CPU32 上占用 4 字节，在 CPU64 上占用 8 字节
{$ifdef USERECORDWITHMETHODS}
TLightLock = record
{$else}
TLightLock = object
{$endif USERECORDWITHMETHODS}
private
Flags: PtrUInt; // 标志位
// 由 Lock 方法在内联时调用的低级函数
procedure LockSpin;
public
/// 如果实例未被初始化为 0，则调用此方法
// - 例如，如果 TLightLock 被定义为类字段，则不需要此方法
procedure Init;
{$ifdef HASINLINE} inline; {$endif}
/// 可用于将实例作为 TOSLock 进行终结处理
// - 不执行任何操作 - 仅与 TOSLock 兼容
procedure Done;
{$ifdef HASINLINE} inline; {$endif}
/// 进入独占非重入锁
procedure Lock;
{$ifdef HASINLINE} inline; {$endif}
/// 尝试进入独占非重入锁
// - 如果返回 true，则调用者最终应调用 UnLock()
// - 也可用于线程安全地获取共享资源
function TryLock: boolean;
{$ifdef HASINLINE} inline; {$endif}
/// 检查独占非重入锁是否已被获取
function IsLocked: boolean;
{$ifdef HASINLINE} inline; {$endif}
/// 离开独占非重入锁
procedure UnLock;
{$ifdef HASINLINE} inline; {$endif}
end;
TRWLightLock
/// 一个轻量级的支持多个读操作/独占写操作的非升级锁
// - 在自旋一段时间后调用 SwitchToThread，但不使用任何读写操作系统API
// - 警告：读锁是可重入的并允许并发访问，但在读锁内部或另一个写锁内部调用 WriteLock 会导致死锁
// - 如果您需要一个可升级的锁，请考虑使用 TRWLock - 但对于大多数读操作，
// TRWLightLock.ReadLock/ReadUnLock/WriteLock 模式比升级更快
// - 我们的轻量级锁预计保持时间非常短（几个CPU周期）：
// 如果锁可能阻塞太长时间，请使用 TSynLocker 或 TOSLock
// - 多个轻量级锁，每个保护少量变量（如列表），可能比更全局的 TOSLock/TRWLock 更高效
// - 在 CPU32 上占用 4 字节，在 CPU64 上占用 8 字节
{$ifdef USERECORDWITHMETHODS}
TRWLightLock = record
{$else}
TRWLightLock = object
{$endif USERECORDWITHMETHODS}
private
Flags: PtrUInt; // 标志位，位 0 = 写锁，>0 = 读锁计数器
// 由 Lock 方法在内联时调用的低级函数
procedure ReadLockSpin;
procedure WriteLockSpin;
public
/// 如果实例未被初始化为 0，则调用此方法
// - 例如，如果 TRWLightLock 被定义为类字段，则不需要此方法
procedure Init;
{$ifdef HASINLINE} inline; {$endif}
/// 进入不可升级的多读锁
// - 读锁维护一个线程安全的计数器，因此是可重入和非阻塞的
// - 警告：在读锁之后嵌套调用 WriteLock 会导致死锁
procedure ReadLock;
{$ifdef HASINLINE} inline; {$endif}
/// 尝试进入不可升级的多读锁
// - 如果返回 true，则调用者最终应调用 ReadUnLock
// - 读锁维护一个线程安全的计数器，因此是可重入和非阻塞的
// - 警告：在读锁之后嵌套调用 WriteLock 会导致死锁
function TryReadLock: boolean;
{$ifdef HASINLINE} inline; {$endif}
/// 离开不可升级的多读锁
procedure ReadUnLock;
{$ifdef HASINLINE} inline; {$endif}
/// 进入不可重入且不可升级的独占写锁
// - 警告：在读锁或另一个写锁之后嵌套调用 WriteLock 会导致死锁
procedure WriteLock;
{$ifdef HASINLINE} inline; {$endif}
/// 尝试进入不可重入且不可升级的独占写锁
// - 如果返回 true，则调用者最终应调用 WriteUnLock
// - 警告：在读锁或另一个写锁之后嵌套调用 TryWriteLock 会导致死锁
function TryWriteLock: boolean;
{$ifdef HASINLINE} inline; {$endif}
/// 离开不可重入且不可升级的独占写锁
procedure WriteUnLock;
{$ifdef HASINLINE} inline; {$endif}
end;
TLockedList
/// 指向TLockedList中一个数据条目的指针
PLockedListOne = ^TLockedListOne;
/// TLockedList中一个数据条目的抽象父类，存储两个PLockedListOne指针
// - TLockedList应该存储以这些字段开头的非托管记录
// - sequence字段包含一个递增的、基于随机种子的30位整数（大于65535），
// 以避免实例回收时出现的ABA问题
TLockedListOne = record
next, prev: pointer; // 指向下一个和上一个条目的指针
sequence: PtrUInt; // 序列号，用于解决ABA问题
end;
/// 用于终结一个TLockedListOne实例的可选回调事件
TOnLockedListOne = procedure(one: PLockedListOne) of object;
/// 线程安全的双链表，包含TLockedListOne后代的回收机制
{$ifdef USERECORDWITHMETHODS}
TLockedList = record
{$else}
TLockedList = object
{$endif USERECORDWITHMETHODS}
private
fHead, fBin: pointer; // 分别指向链表头部和回收箱的指针
fSize: integer; // 列表中每个实例的大小（包括TLockedListOne头部）
fSequence: PtrUInt; // 全局序列号生成器
fOnFree: TOnLockedListOne; // 当实例被释放时调用的回调
public
/// 线程安全的访问锁
Safe: TLightLock;
/// 当前列表中存储的TLockedListOne实例数量（不包括回收箱中的实例）
Count: integer;
/// 初始化继承自TLockedListOne的大小的存储
procedure Init(onesize: PtrUInt; const onefree: TOnLockedListOne = nil);
/// 释放所有存储的内存
procedure Done;
/// 在线程安全的O(1)过程中分配一个新的PLockedListOne数据实例
function New: pointer;
/// 在线程安全的O(1)过程中释放一个已使用的PLockedListOne数据实例
function Free(one: pointer): boolean;
/// 释放当前存储在此列表中的所有TLockedListOne实例
// - 不会将任何实例移动到内部回收箱
procedure Clear;
/// 释放内部回收箱中所有待回收的项
// - 返回从内部收集器中释放了多少项
function EmptyBin: integer;
/// 作为PLockedListOne双链表的原始访问存储的项
property Head: pointer
read fHead;
/// 存储的每个实例的大小，包括其TLockedListOne头部
property Size: integer
read fSize;
end;
TSynLocker
type
/// TSynLocker处理线程同步的方式
// - 默认情况下，uSharedLock将使用主TRTLCriticalSection
// - 您可以设置uRWLock并调用重载的RWLock/RWUnLock()来使用更轻量级的TRWLock - 但请注意，cReadOnly后跟cReadWrite/cWrite会导致死锁 - 常规的Lock/UnLock将使用cWrite独占锁
// - uNoLock将禁用整个锁定机制
TSynLockerUse = (
uSharedLock,
uRWLock,
uNoLock);
/// 允许向任何类实例添加跨平台锁定方法
// - 典型用途是定义一个Safe: TSynLocker属性，在构造函数/析构函数方法中调用Safe.Init和Safe.Done，并在try ... finally部分使用Safe.Lock/UnLock方法
// - 相对于TCriticalSection类，修复了可能降低多线程性能的CPU缓存行冲突问题，如http://www.delphitools.info/2011/11/30/fixing-tcriticalsection所述
// - 内部填充用于安全存储最多7个受互斥锁保护的值，因此SizeOf(TSynLocker)>128
// - 对于对象级锁定，请参阅TSynPersistentLock，它拥有一个此类实例，或在构造函数中调用低级fSafe := NewSynLocker，然后在析构函数中调用fSafe^.DoneAndFreemem
// - RWUse属性可以将TRTLCriticalSection替换为更轻量级的TRWLock
// - 如果多读/独占写锁更合适（仅当锁定过程不会花费太多时间时），请参阅TRWLock和TSynPersistentRWLock
{$ifdef USERECORDWITHMETHODS}
TSynLocker = record
{$else}
TSynLocker = object
{$endif USERECORDWITHMETHODS}
private
fSection: TRTLCriticalSection; // 主同步对象
fRW: TRWLock; // 可选的读写锁
fPaddingUsedCount: byte; // 填充区已使用计数
fInitialized: boolean; // 初始化标志
fRWUse: TSynLockerUse; // 锁使用模式
fLockCount: integer; // 锁计数（用于重入）
// 以下为用于安全访问内部填充数据的辅助方法
function GetVariant(Index: integer): Variant;
procedure SetVariant(Index: integer; const Value: Variant);
function GetInt64(Index: integer): Int64;
procedure SetInt64(Index: integer; const Value: Int64);
function GetBool(Index: integer): boolean;
procedure SetBool(Index: integer; const Value: boolean);
function GetUnlockedInt64(Index: integer): Int64;
procedure SetUnlockedInt64(Index: integer; const Value: Int64);
function GetPointer(Index: integer): Pointer;
procedure SetPointer(Index: integer; const Value: Pointer);
function GetUtf8(Index: integer): RawUtf8;
procedure SetUtf8(Index: integer; const Value: RawUtf8);
function GetIsLocked: boolean;
// - 如果RWUse=uSharedLock，则调用EnterCriticalSection（不支持并行读取）
// - 警告：如果RWUse=uRWLock，则此方法将使用内部TRWLock
// - 在受保护部分中定义，以便更好地内联并修复Delphi编译器关于uses classes中缺少Windows单元的警告
procedure RWLock(context: TRWLockContext);
{$ifdef HASINLINE} inline; {$endif}
procedure RWUnLock(context: TRWLockContext);
{$ifdef HASINLINE} inline; {$endif}
public
/// 内部填充数据，也用于存储最多7个Variant值
// - 这个内存缓冲区将确保不会发生CPU缓存行混合
// - 您不应直接使用此字段，而应使用Locked[], LockedInt64[], LockedUtf8[]或LockedPointer[]方法
// - 如果您要访问这些数组值，请确保在try ... finally结构中保护它们，并使用Safe.Lock和Safe.Unlock，同时准确维护PaddingUsedCount属性
Padding: array[0..6] of TVarData;
/// 初始化互斥锁
// - 调用此方法是强制性的（例如，在拥有TSynLocker实例的类构造函数中），否则您可能会遇到意外的行为，如访问违规或内存泄漏
procedure Init;
/// 终结互斥锁
// - 调用此方法是强制性的（例如，在拥有TSynLocker实例的类析构函数中），否则您可能会遇到意外的行为，如访问违规或内存泄漏
procedure Done;
/// 终结互斥锁，并对实例的指针调用FreeMem()
// - 应该通过NewSynLocker调用来初始化
procedure DoneAndFreeMem;
/// 低级锁定获取，相当于RWLock(cReadOnly)
// - 如果RWUse=uSharedLock，则调用EnterCriticalSection（不支持并行读取）
// - 警告：如果RWUse=uRWLock，则嵌套的Lock调用会导致死锁，但嵌套的ReadLock调用不会
procedure ReadLock;
/// 低级锁定释放，相当于RWUnLock(cReadOnly)
procedure ReadUnLock;
/// 低级锁定获取，相当于RWLock(cReadWrite)
// - 如果RWUse=uSharedLock，则调用EnterCriticalSection（不支持并行读取）
// - 如果RWUse=uRWLock，则嵌套的Lock调用不会导致死锁
procedure ReadWriteLock;
/// 低级锁定释放，相当于RWUnLock(cReadWrite)
procedure ReadWriteUnLock;
/// 对实例进行独占访问锁定，相当于RWLock(cWrite)
// - 从同一线程是可重入的，即您可以嵌套Lock/UnLock调用
// - 警告：如果RWUse=uRWLock，则在嵌套ReadLock之后会导致死锁，但在ReadWriteLock之后不会
// - 使用此类结构以避免竞态条件（从Safe: TSynLocker属性）：
// ! Safe.Lock;
// ! try
// ! ...
// ! finally
// ! Safe.Unlock;
// ! end;
procedure Lock;
/// 尝试获取互斥锁
// - 如果RWUse不是默认的uSharedLock，则什么也不做并返回false
// - 使用此类结构以避免竞态条件（从Safe: TSynLocker属性）：
// ! if Safe.TryLock then
// ! try
// ! ...
// ! finally
// ! Safe.Unlock;
// ! end;
function TryLock: boolean;
/// 尝试在给定的时间内获取互斥锁
// - 如果RWUse不是默认的uSharedLock，则只是等待并返回false
// - 使用此类结构以避免竞态条件（从Safe: TSynLocker属性）：
// ! if Safe.TryLockMS(100) then
// ! try
// ! ...
// ! finally
// ! Safe.Unlock;
// ! end;
function TryLockMS(retryms: integer; terminated: PBoolean = nil): boolean;
/// 释放实例的独占访问权，相当于RWUnLock(cWrite)
// - 每个Lock/TryLock调用都应该有一个对应的UnLock调用，因此try..finally块是安全代码所必需的
procedure UnLock; overload;
/// 将进入互斥锁，直到释放IUnknown引用
// - 在Delphi中可以这样使用：
// !begin
// ! ... // 不安全代码
// ! Safe.ProtectMethod;
// ! ... // 线程安全代码
// !end; // 局部变量隐藏的IUnknown将释放方法的锁
// - 警告：在FPC中，您应该将结果分配给局部变量 - 请参阅bug http://bugs.freepascal.org/view.php?id=26602
// !var
// ! LockFPC: IUnknown;
// !begin
// ! ... // 不安全代码
// ! LockFPC := Safe.ProtectMethod;
// ! ... // 线程安全代码
// !end; // LockFPC将释放方法的锁
// 或
// !begin
// ! ... // 不安全代码
// ! with Safe.ProtectMethod do
// ! begin
// ! ... // 线程安全代码
// ! end; // 局部变量隐藏的IUnknown将释放方法的锁
// !end;
function ProtectMethod: IUnknown;
/// 存储在内部Padding[]数组中的值数
// - 如果没有存储任何值，则为0，否则为1..7之间的数字
// - 您通常不需要使用此字段，但对于在Lock/UnLock安全块内优化对Padding[]值的低级直接访问，它是必要的
property PaddingUsedCount: byte
read fPaddingUsedCount write fPaddingUsedCount;
/// 如果互斥锁当前被另一个线程锁定，则返回true
// - 如果RWUse=uRWLock，则任何锁（即使是ReadOnlyLock）也会返回true
property IsLocked: boolean
read GetIsLocked;
/// 如果已为此互斥锁调用Init方法，则返回true
// - 仅当整个对象之前已被填充为0时（即作为类的一部分或作为全局变量），这一点才相关，但如果是在堆栈上分配的，则可能不准确
property IsInitialized: boolean
read fInitialized;
/// 安全锁定访问Variant值
// - 您可以存储最多7个变量，使用0..6索引，与LockedBool、LockedInt64、LockedPointer和LockedUtf8数组属性共享
// - 如果索引超出范围，则返回null
// - 如果RWUse设置为uRWLock，则允许并发线程读取
property Locked[Index: integer]: Variant
read GetVariant write SetVariant;
/// 安全锁定访问Int64值
// - 您可以存储最多7个变量，使用0..6索引，与Locked和LockedUtf8数组属性共享
// - Int64将作为varInt64变体内部存储
// - 如果索引超出范围或不存储Int64，则返回nil
// - 如果RWUse设置为uRWLock，则允许并发线程读取
property LockedInt64[Index: integer]: Int64
read GetInt64 write SetInt64;
/// 安全锁定访问布尔值
// - 您可以存储最多7个变量，使用0..6索引，与Locked、LockedInt64、LockedPointer和LockedUtf8数组属性共享
// - 值将作为varboolean变体内部存储
// - 如果索引超出范围或不存储布尔值，则返回nil
// - 如果RWUse设置为uRWLock，则允许并发线程读取
property LockedBool[Index: integer]: boolean
read GetBool write SetBool;
/// 安全锁定访问指针/TObject值
// - 您可以存储最多7个变量，使用0..6索引，与Locked、LockedBool、LockedInt64和LockedUtf8数组属性共享
// - 指针将作为varUnknown变体内部存储
// - 如果索引超出范围或不存储指针，则返回nil
// - 如果RWUse设置为uRWLock，则允许并发线程读取
property LockedPointer[Index: integer]: Pointer
read GetPointer write SetPointer;
/// 安全锁定访问UTF-8字符串值
// - 您可以存储最多7个变量，使用0..6索引，与Locked和LockedPointer数组属性共享
// - UTF-8字符串将作为varString变体内部存储
// - 如果索引超出范围或不存储字符串，则返回''
// - 如果RWUse设置为uRWLock，则允许并发线程读取
property LockedUtf8[Index: integer]: RawUtf8
read GetUtf8 write SetUtf8;
/// 安全锁定就地递增Int64值
// - 您可以存储最多7个变量，使用0..6索引，与Locked和LockedUtf8数组属性共享
// - Int64将作为varInt64变体内部存储
// - 返回新存储的值
// - 如果内部值尚未定义，则默认使用0
function LockedInt64Increment(Index: integer; const Increment: Int64): Int64;
/// 安全锁定就地交换Variant值
// - 您可以存储最多7个变量，使用0..6索引，与Locked和LockedUtf8数组属性共享
// - 返回之前存储的值，如果索引超出范围，则返回null
function LockedExchange(Index: integer; const Value: variant): variant;
/// 安全锁定就地交换指针/TObject值
// - 您可以存储最多7个变量，使用0..6索引，与Locked和LockedUtf8数组属性共享
// - 指针将作为varUnknown变体内部存储
// - 返回之前存储的值，如果索引超出范围或不存储指针，则返回nil
function LockedPointerExchange(Index: integer; Value: pointer): pointer;
/// 不安全访问Int64值
// - 您可以存储最多7个变量，使用0..6索引，与Locked和LockedUtf8数组属性共享
// - Int64将作为varInt64变体内部存储
// - 如果索引超出范围或不存储Int64，则返回nil
// - 您应该调用LockedInt64[]属性，或使用此属性并在Lock; try ... finally UnLock块中使用
property UnlockedInt64[Index: integer]: Int64
read GetUnlockedInt64 write SetUnlockedInt64;
/// RWLock/RWUnLock的处理方式
property RWUse: TSynLockerUse
read fRWUse write fRWUse;
end;
这段代码定义了一个 TSynLocker类型，它允许跨平台地为任何类实例添加锁定方法，以确保线程安全。它提供了多种锁定机制（如共享锁、读写锁和无锁），以及安全访问内部存储的值的方法。这些特性使得 TSynLocker成为处理多线程编程中同步问题的一个强大工具。
TAutoLock
/// 指向TSynLocker互斥锁实例的指针
// - 另请参见NewSynLocker和TSynLocker.DoneAndFreemem函数
PSynLocker = ^TSynLocker;
/// TAutoLocker.ProtectMethod和TSynLocker.ProtectMethod使用的原始类
// - 在此定义以供mormot.core.data.pas中的TAutoLocker使用
TAutoLock = class(TInterfacedObject)
protected
fLock: PSynLocker; // 指向TSynLocker的指针
public
constructor Create(aLock: PSynLocker); // 构造函数，接受一个PSynLocker参数
destructor Destroy; override; // 析构函数，重写自TInterfacedObject
end;
TSynEvent
/// 我们的轻量级跨平台TEvent类似组件
// - 在Windows上，直接调用CreateEvent/ResetEvent/SetEvent API
// - 在Linux上，将使用阻塞和非信号量模式的eventfd()
// - 在其他POSIX系统上，将使用比TEvent BasicEvent更轻的PRTLEvent
// - 唯一限制是我们不知道WaitFor是被信号触发还是超时，
// 但实际上这并不是一个大问题，因为大多数代码不需要这个信息
// 或者已经在其实现逻辑中有了自己的标志
TSynEvent = class
protected
fHandle: pointer; // Windows THandle或FPC PRTLEvent
fFD: integer; // 用于eventfd()
public
/// 初始化跨平台事件实例
constructor Create;
/// 终结跨平台事件实例
destructor Destroy; override;
/// 忽略任何挂起的事件，以便WaitFor将在下次SetEvent时被设置
procedure ResetEvent;
{$ifdef OSPOSIX} inline; {$endif}
/// 触发任何挂起的事件，释放WaitFor/WaitForEver方法
procedure SetEvent;
{$ifdef OSPOSIX} inline; {$endif}
/// 等待，直到另一个线程调用SetEvent，具有最大时间
// - 如果被信号触发或超时，则不返回
// - 警告：您应该一次只从一个线程等待
procedure WaitFor(TimeoutMS: integer);
{$ifdef OSPOSIX} inline; {$endif}
/// 无限期等待，直到另一个线程调用SetEvent
procedure WaitForEver;
{$ifdef OSPOSIX} inline; {$endif}
/// 在检查终止标志和此事件的同时，分步骤调用SleepHiRes()
function SleepStep(var start: Int64; terminated: PBoolean): Int64;
/// 如果使用了eventfd() API，则可用于调整算法
function IsEventFD: boolean;
{$ifdef HASINLINE} inline; {$endif}
end;
NewSynLocker
/// 从堆初始化一个TSynLocker实例
// - 调用DoneandFreeMem来释放相关内存和操作系统互斥锁
// - 例如，在TSynPersistentLock中使用以减少类实例大小
function NewSynLocker: PSynLocker;
TSynLocked
type
{$M+} // 开启内存管理消息
/// TSynPersistentLock的一个持久性无关替代方案
// - 当不需要自定义JSON持久性时，可以用作基类
// - 可以考虑将TRWLock字段用作更轻量级的多读/独占写选项
TSynLocked = class
protected
fSafe: PSynLocker; // TSynLocker会增加继承字段的偏移量
public
/// 初始化实例及其关联的锁
// - 定义为virtual，就像TObjectWithCustomCreate/TSynPersistent一样
constructor Create; virtual;
/// 终结实例及其关联的锁
destructor Destroy; override;
/// 访问关联的实例临界区
// - 调用Safe.Lock/UnLock来保护此存储的多线程访问
property Safe: PSynLocker
read fSafe;
end;
{$M-} // 关闭内存管理消息
/// TSynLocked层次的元类定义
TSynLockedClass = class of TSynLocked;
TLecuyerThreadSafe
/// 线程安全的Pierre L'Ecuyer软件随机数生成器
// - 仅用TLightLock包装TLecuyer
// - 除非可能比threadvar稍快，否则不应使用
{$ifdef USERECORDWITHMETHODS}
TLecuyerThreadSafe = record
{$else}
TLecuyerThreadSafe = object
{$endif USERECORDWITHMETHODS}
public
Safe: TLightLock;
Generator: TLecuyer;
/// 计算下一个生成的32位值
function Next: cardinal; overload;
/// 计算一个64位浮点数
function NextDouble: double;
/// 用随机字节异或某个内存缓冲区
procedure Fill(dest: pointer; count: integer);
/// 用7位ASCII随机文本填充某个string[31]
procedure FillShort31(var dest: TShort31);
end;
TThreadIDDynArray = array of TThreadID; // 线程ID动态数组类型
var
/// 全局线程安全的Pierre L'Ecuyer软件随机数生成器
// - 除非可能比threadvar稍快，否则不应使用
SharedRandom: TLecuyerThreadSafe;
与线程、CPU核心和事件相关的类型和函数
{$ifdef OSPOSIX}
/// 可设置为TRUE，以强制SleepHiRes(0)调用POSIX sched_yield
// - 在实践中，据报道在POSIX系统上存在问题
// - 即使是Linus Torvalds本人也对它的使用表示愤怒 - 例如，请参见
// https://www.realworldtech.com/forum/?threadid=189711&curpostid=189752
// - 您可以自己尝试它
SleepHiRes0Yield: boolean = false;
{$endif OSPOSIX}
/// 类似于Windows的sleep() API调用，真正实现跨平台
// - 使用毫秒级分辨率
// - SleepHiRes(0)在Windows上调用ThreadSwitch，但在POSIX版本中将等待10微秒
// 除非强制SleepHiRes0Yield为true（坏主意）
// - 相对于RTL的Sleep()函数，如果在任何OS信号中断时返回ESysEINTR
// - 警告：通常在Windows上等待下一个系统计时器中断，默认为每16毫秒一次；
// 因此，永远不要依赖提供的毫秒值来猜测经过的时间，而应调用GetTickCount64
procedure SleepHiRes(ms: cardinal); overload;
/// 类似于Windows的sleep() API调用，但真正实现跨平台
// 并在等待期间检查Terminated标志以快速响应中止
// - 如果terminated^被设置为true（terminatedvalue），则返回true
function SleepHiRes(ms: cardinal; var terminated: boolean;
terminatedvalue: boolean = true): boolean; overload;
/// 调用SleepHiRes()，考虑活动的步长，在0/1/5/50/120-250毫秒步长中
// - 范围设计激进，以响应性为代价燃烧一些CPU
// - 当发生某些活动时，应重置start := 0，或在Windows上设置start := -1
// 以避免任何SleepHiRes(0) = SwitchToThread调用
// - 可选地在terminated^被设置或事件被信号触发时返回
// - 返回当前的GetTickCount64值
function SleepStep(var start: Int64; terminated: PBoolean = nil): Int64;
/// 计算最佳睡眠时间作为0/1/5/50然后120-250毫秒步长
// - 范围设计激进，以响应性为代价燃烧一些CPU
function SleepDelay(elapsed: PtrInt): PtrInt;
/// 计算最佳睡眠时间，类似于SleepStep，在0/1/5/50/120-250毫秒步长中
// - 范围设计激进，以响应性为代价燃烧一些CPU
// - start=0将用tix填充其值，start<0将用tix-50填充其值
// 以便SleepDelay()永远不会调用SleepHiRes(0)
function SleepStepTime(var start, tix: Int64; endtix: PInt64 = nil): PtrInt;
/// 类似于Windows的SwitchToThread API调用，真正实现跨平台
// - 在POSIX系统上调用fpnanosleep(10)，或在Windows上调用同名API
procedure SwitchToThread;
{$ifdef OSWINDOWS} stdcall; {$endif}
/// 在循环中尝试LockedExc()，在自旋后调用SwitchToThread
procedure SpinExc(var Target: PtrUInt; NewValue, Comperand: PtrUInt);
/// 包装器，用于实现线程安全的T*ObjArray动态数组存储
function ObjArrayAdd(var aObjArray; aItem: TObject;
var aSafe: TLightLock; aCount: PInteger = nil): PtrInt; overload;
/// 包装器，用于实现线程安全的指针动态数组存储
function PtrArrayDelete(var aPtrArray; aItem: pointer; var aSafe: TLightLock;
aCount: PInteger = nil): PtrInt; overload;
/// 尝试杀死/取消一个线程
// - 在Windows上，调用TerminateThread() API
// - 在Linux/FPC下，调用异步的pthread_cancel() API
function RawKillThread(Thread: TThread): boolean;
type
/// 存储逻辑CPU核心的位掩码，由SetThreadMaskAffinity使用
// - 在Windows上为32/64位指针大小，在POSIX上为1024位
TCpuSet = {$ifdef OSWINDOWS} PtrUInt {$else} array[0..127] of byte {$endif};
var
/// 每个硬件CPU插槽托管的逻辑CPU核心的底层位掩码
// - 在进程启动时填充为CpuSocketsMask[0 .. CpuSockets - 1]范围
CpuSocketsMask: array of TCpuSet;
/// 用零填充CPU核心的位掩码
procedure ResetCpuSet(out CpuSet: TCpuSet);
{$ifdef HASINLINE} inline; {$endif}
/// 在CPU核心的位掩码中设置特定的位
function SetCpuSet(var CpuSet: TCpuSet; CpuIndex: cardinal): boolean;
/// 检索系统当前可用的CPU核心位掩码
// - 当前进程可能已被调整为仅使用核心的一个子集
// 例如，通过Linux上的"taskset -c"
// - 返回可访问的CPU核心数量 - 即GetBitsCount(CpuSet)或
// 如果函数失败则为0
function CurrentCpuSet(out CpuSet: TCpuSet): integer;
/// 尝试将给定线程分配给特定的逻辑CPU核心集
// - 在Windows上，调用SetThreadAffinityMask() API
// - 在Linux/FPC下，调用pthread_setaffinity_np() API
function SetThreadMaskAffinity(Thread: TThread; const Mask: TCpuSet): boolean;
/// 尝试将给定线程分配给特定的逻辑CPU核心
// - CpuIndex应在0 .. SystemInfo.dwNumberOfProcessors - 1范围内
function SetThreadCpuAffinity(Thread: TThread; CpuIndex: cardinal): boolean;
/// 尝试将给定线程分配给特定的硬件CPU插槽
// - SocketIndex应在0 .. CpuSockets - 1范围内，并将使用
// 在进程启动时检索的CpuSocketsMask[]信息
function SetThreadSocketAffinity(Thread: TThread; SocketIndex: cardinal): boolean;
/// 线程的底层命名
// - 在Windows上，将引发一个标准的“假”异常来通知线程名称
// - 在Linux/FPC下，调用pthread_setname_np() API，该API将名称截断为16个字符
procedure RawSetThreadName(ThreadID: TThreadID; const Name: RawUtf8);
/// 为当前线程命名，以便在IDE调试器中轻松识别
// - 可以通过CurrentThreadNameShort/GetCurrentThreadName检索
// - 只是SetThreadName(GetCurrentThreadId, ...)的包装器
procedure SetCurrentThreadName(const Format: RawUtf8; const Args: array of const); overload;
/// 为当前线程命名，以便在IDE调试器中轻松识别
// - 也可以通过CurrentThreadNameShort/GetCurrentThreadName检索
// - 只是SetThreadName(GetCurrentThreadId, ...)的包装器
procedure SetCurrentThreadName(const Name: RawUtf8); overload;
var
/// 为线程命名，以便在IDE调试器中轻松识别
// - 默认实现不执行任何操作，除非包含了mormot.core.log
// - 如果在调试应用程序时此功能出现问题，可以通过设置NOSETTHREADNAME条件来强制此函数不执行任何操作
// - 大多数无意义的模式（如'TSql'）会被修剪以减少结果长度，这在POSIX截断到16个字符时很方便
// - 您稍后可以使用CurrentThreadNameShort检索名称
// - 此方法将注册TSynLog.LogThreadName()，因此调用它的线程也应该调用TSynLogFamily.OnThreadEnded/TSynLog.NotifyThreadEnded
SetThreadName: procedure(ThreadID: TThreadID; const Format: RawUtf8;
const Args: array of const);
/// 低级访问由SetThreadName()设置的线程名称
// - 由于threadvar不能包含托管字符串，因此它被定义为TShort31，
// 因此限制为31个字符，这足够了，因为POSIX截断到16个字符，并且SetThreadName会修剪无意义的模式
function CurrentThreadNameShort: PShortString;
/// 检索由SetThreadName()设置的线程名称
// - 如果可能，直接调用CurrentThreadNameShort函数会稍微快一些
// - 将返回CurrentThreadNameShort^ threadvar的31个字符值
function GetCurrentThreadName: RawUtf8;
/// 返回线程ID和线程名称作为ShortString
// - 返回例如'Thread 0001abcd [shortthreadname]'
// - 用于在记录日志或引发异常时方便使用
function GetCurrentThreadInfo: ShortString;
/// 进入一个进程范围的巨型锁，用于线程安全的共享进程
// - 应受如下保护：
// ! GlobalLock;
// ! try
// ! .... 执行尽可能短的线程安全操作
// ! finally
// ! GlobalUnLock;
// ! end;
// - 最好不要使用这种巨型锁，而应使用专用的临界区/TSynLocker或TRWLock实例 - 这些函数仅为了方便，用于非时间关键型进程（例如，外部库的单例初始化，或在任何情况下都将使用它的RegisterGlobalShutdownRelease()之前）
procedure GlobalLock;
/// 释放线程安全的共享进程的巨型锁
procedure GlobalUnLock;
/// 框架将在此处注册一些实例以便最终释放
// - 在此根单元中比在每个finalization部分中更好
// - 其使用受到GlobalLock的保护
function RegisterGlobalShutdownRelease(Instance: TObject;
SearchExisting: boolean = false): pointer;
这段代码定义了一系列与线程、CPU核心和事件相关的类型和函数。它涵盖了跨平台的线程管理、CPU亲和性设置、线程命名等功能。这些功能在多线程应用程序中非常有用，尤其是在需要精细控制线程行为和优化性能的场景中。
