OmniThreadLibrary internals - OtlContainers

The time has come to bring the OtlContainers subthread to the end. In previous parts (1, 2, 3, 4) I obsessively described underlying lock-free structures but hadn't said a word about the higher-level classes that are actually used for message transfer inside the OmniThreadLibrary. Let's take a quick look at all OtlContainers classes. TOmniBaseContainer is an abstract parent of the whole container hierarchy. It's basic function is to provide memory allocation and lock-free algorithms for all descendants. Most of the code I already described in previous installments and the rest is trivial. TOmniBaseContainer = class abstract(TInterfacedObject) strict protected obcBuffer : pointer; obcElementSize : integer; obcNumElements : integer; obcPublicChain : TOmniHeadAndSpin; obcRecycleChain: TOmniHeadAndSpin; class function InvertOrder(chainHead: POmniLinkedData): POmniLinkedData; static; class function PopLink(var chain: TOmniHeadAndSpin): POmniLinkedData; static; class procedure PushLink(const link: POmniLinkedData; var chain: TOmniHeadAndSpin); static; class function UnlinkAll(var chain: TOmniHeadAndSpin): POmniLinkedData; static; public destructor Destroy; override; procedure Empty; virtual; procedure Initialize(numElements, elementSize: integer); virtual; function IsEmpty: boolean; virtual; function IsFull: boolean; virtual; property ElementSize: integer read obcElementSize; property NumElements: integer read obcNumElements; end; { TOmniBaseContainer } Then there is the base stack implementation, which only adds Push and Pop to the base container. We've seen those two already. TOmniBaseStack = class(TOmniBaseContainer) public function Pop(var value): boolean; virtual; function Push(const value): boolean; virtual; end; { TOmniBaseStack } The queue is only slightly more complex. It provides Enqueue and Dequeue, which we already know, and overrides Empty and IsEmpty to take the dequeued messages chain into account. TOmniBaseQueue = class(TOmniBaseContainer) strict protected obqDequeuedMessages: TOmniHeadAndSpin; public constructor Create; function Dequeue(var value): boolean; virtual; procedure Empty; override; function Enqueue(const value): boolean; virtual; function IsEmpty: boolean; override; end; { TOmniBaseQueue } Now we come to the interesting part. Basic stack and queue operations are also described with interfaces IOmniStack and IOmniQueue - just in case you'd like to use them in your programs. OTL uses class representation of the queue directly. IOmniStack = interface ['{F4C57327-18A0-44D6-B95D-2D51A0EF32B4}'] procedure Empty; procedure Initialize(numElements, elementSize: integer); function Pop(var value): boolean; function Push(const value): boolean; function IsEmpty: boolean; function IsFull: boolean; end; { IOmniStack } IOmniQueue = interface ['{AE6454A2-CDB4-43EE-9F1B-5A7307593EE9}'] procedure Empty; procedure Initialize(numElements, elementSize: integer); function Enqueue(const value): boolean; function Dequeue(var value): boolean; function IsEmpty: boolean; function IsFull: boolean; end; { IOmniQueue } Actual implementation of the higher-level structures is exposed with classes TOmniStack and TOmniQueue. Besides implementing IOmniStack and IOmniQueue (respectively), they both implement IOmniNotifySupport and IOmniMonitorSupport. TOmniStack = class(TOmniBaseStack, IOmniStack, IOmniNotifySupport, IOmniMonitorSupport) TOmniQueue = class(TOmniBaseQueue, IOmniQueue, IOmniNotifySupport, IOmniMonitorSupport) IOmniMonitorSupport is describing a container with monitoring support (notifies attached monitor whenever new message is sent). IOmniNotifySupport is describing a container that notifies interested parties (by setting an event) that new message has been sent. Both are used in the OTL - notification support is needed to implement IOmniCommunicationEndpoint.NewMessageEvent in the OtlComm and monitoring support is needed to support IOmniTaskControl.MonitorWith in the OtlTaskControl unit. IOmniMonitorSupport = interface ['{6D5F1191-9E4A-4DD5-99D8-694C95B0DE90}'] function GetMonitor: IOmniMonitorParams; // procedure Notify; procedure RemoveMonitor; procedure SetMonitor(monitor: IOmniMonitorParams); property Monitor: IOmniMonitorParams read GetMonitor; end; { IOmniMonitorSupport } IOmniNotifySupport = interface ['{E5FFC739-669A-4931-B0DC-C5005A94A08B}'] function GetNewDataEvent: THandle; // procedure Signal; property NewDataEvent: THandle read GetNewDataEvent; end; { IOmniNotifySupport } The following excerpt from the TOmniQueue code demonstrates the implementation of those interfaces. TOmniStack is implemented in a similar manner. The constructor takes the options parameter when you can enable monitoring and/or notification support. type TOmniContainerOption = (coEnableMonitor, coEnableNotify); TOmniContainerOptions = set of TOmniContainerOption; constructor TOmniQueue.Create(numElements, elementSize: integer; options: TOmniContainerOptions); begin inherited Create; Initialize(numElements, elementSize); orbOptions := options; if coEnableMonitor in Options then orbMonitorSupport := TOmniMonitorSupport.Create; if coEnableNotify in Options then orbNotifySupport := TOmniNotifySupport.Create; end; { TOmniQueue.Create } function TOmniQueue.Dequeue(var value): boolean; begin Result := inherited Dequeue(value); if Result then if coEnableNotify in Options then orbNotifySupport.Signal; end; { TOmniQueue.Dequeue } function TOmniQueue.Enqueue(const value): boolean; begin Result := inherited Enqueue(value); if Result then begin if coEnableNotify in Options then orbNotifySupport.Signal; if coEnableMonitor in Options then orbMonitorSupport.Notify; end; end; { TOmniQueue.Enqueue } Enqueue calls original enqueueing code and then signals notification (if enabled) and notifies the monitor (if enabled). Dequeue is similar, except that it only triggers notification so that the reader rechecks the input queue. Stop. Enough words have been said about the OtlContainer. Next time, I'll discuss something completely different.