<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2024, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
====================================================================
lazCollections
====================================================================
-->
<module name="lazCollections">
<short>Contains classes used to implement thread-safe collections.</short>
<descr>
<p>
<file>lazCollections.pas</file> contains classes used to implement 
thread-safe collections.
</p>
<p>
<file>lazCollections.pas</file> is part of the <file>LazUtils</file> package.
</p>
</descr>

<!-- unresolved external references -->
<element name="SysUtils"/>
<element name="Math"/>
<element name="SyncObjs"/>
<element name="LazSysUtils"/>

<element name="PPRTLEvent">
<short>Pointer to a PRTLEvent type.</short>
<descr>
<p>
For Windows, the pointer is to a THandle type. For other platforms, the 
pointer is to a record type. Used to implement TWaitableSection.
</p>
</descr>
<seealso>
<link id="TWaitableSection"/>
<link id="#rtl.system.PRTLEvent">PRTLEvent</link>
</seealso>
</element>

<element name="TWaitableSection">
<short>Protects a section of code in multi-threaded applications.</short>
<descr>
<p>
<var>TWaitableSection</var> is an <b>advanced record</b> type used to 
serialize access to a section of code in a multi-threaded application. It 
uses a pointer to a RTL event, accessible to all interested threads, to 
protect its resources. When the event is set by an acquiring thread, other 
threads must wait until the event is reset.
</p>
<p>
TWaitableSection is used in the implementation of the Dwarf debugger for the 
Lazarus IDE.
</p>
</descr>
<seealso>
<link id="PPRTLEvent"/>
<link id="#rtl.system.PRTLEvent">PRTLEvent</link>
</seealso>
</element>

<element name="TWaitableSection.FEventPtr"/>
<element name="TWaitableSection.WaitForLeave"/>
<element name="TWaitableSection.WaitForLeave.AnEventCache"/>
<element name="TWaitableSection.SECTION_ENTERED_INDICATOR"/>

<element name="TWaitableSection.GetCachedOrNewEvent">
<short>Gets or creates the RTL event for the synchronization object.</short>
<descr/>
<seealso>
<link id="#rtl.system.RTLEventCreate">RTLEventCreate</link>
<link id="#rtl.system.InterlockedExchange">InterlockedExchange</link>
</seealso>
</element>
<element name="TWaitableSection.GetCachedOrNewEvent.Result">
<short>Pointer to the RTL event acquired or created in the method.</short>
</element>
<element name="TWaitableSection.GetCachedOrNewEvent.AnEventCache">
<short>Cached event acquired or updated in the method.</short>
</element>

<element name="TWaitableSection.FreeOrCacheEvent">
<short>Caches or Frees the RTL event for the synchronization object.</short>
<descr/>
<seealso>
<link id="#rtl.system.RTLEventDestroy">RTLEventDestroy</link>
<link id="#rtl.system.InterlockedExchange">InterlockedExchange</link>
</seealso>
</element>
<element name="TWaitableSection.FreeOrCacheEvent.AnEventCache">
<short>Cache where the RTL event is stored.</short>
</element>
<element name="TWaitableSection.FreeOrCacheEvent.AnEvent">
<short>RTL event cached or destroyed in the method.</short>
</element>

<element name="TWaitableSection.EnterOrWait">
<short>Enters the protected section, or waits until it is available.</short>
<descr/>
<seealso>
<link id="TWaitableSection.GetCachedOrNewEvent"/>
<link id="#rtl.system.InterlockedCompareExchange">InterlockedCompareExchange</link>
<link id="#rtl.system.RTLEventSetEvent">RTLEventSetEvent</link>
<link id="#rtl.system.RTLEventWaitFor">RTLEventWaitFor</link>
</seealso>
</element>
<element name="TWaitableSection.EnterOrWait.Result">
<short>True if the protected section has not been entered.</short>
</element>
<element name="TWaitableSection.EnterOrWait.AnEventCache">
<short>Cached RTL event set and monitored in the method.</short>
</element>

<element name="TWaitableSection.Leave">
<short>Leaves the protected section.</short>
<descr/>
<seealso>
<link id="#rtl.system.InterlockedExchange">InterlockedExchange</link>
<link id="#rtl.system.RTLEventSetEvent">RTLEventSetEvent</link>
</seealso>
</element>

<!-- class Visibility: default -->
<element name="TLazMonitor">
<short>
Implements a synchronization construct which provides thread-safe access to 
resources.
</short>
<descr>
<p>
<var>TLazMonitor</var> is a <var>TCriticalSection</var> descendant which 
implements a synchronization construct that provides thread-safe access to 
resources. TLazMonitor extends the ancestor class to use a fixed number of 
spinlock (or busy waiting) attempts in its Acquire method. Acquire also 
yields CPU cycles to allow other threads to execute when fixed yield and/or 
sleep threshold(s) have been reached.
</p>
<p>
<var>TLazMonitor</var> is used in the implementation of the 
<var>TLazThreadedQueue</var> class, and in the <var>fppkg</var> package.
</p>
</descr>
<seealso>
<link id="TLazMonitor.Acquire"/>
<link id="TLazMonitor.SpinCount"/>
<link id="TLazMonitor.DefaultSpinCount"/>
<link id="TLazThreadedQueue"/>
<link id="#fcl.syncobjs.TCriticalSection">TCriticalSection</link>
</seealso>
</element>

<!-- variable Visibility: private -->
<element name="TLazMonitor.FSpinCount" link="#lazutils.lazcollections.TLazMonitor.SpinCount"/>

<!-- variable Visibility: private -->
<element name="TLazMonitor.FDefaultSpinCount" link="#lazutils.lazcollections.TLazMonitor.DefaultSpinCount"/>

<!-- class function Visibility: private -->
<element name="TLazMonitor.GetDefaultSpinCount">
<short>Gets the value for the DefaultSpinCount class property.</short>
<seealso>
<link id="TLazMonitor.DefaultSpinCount"/>
</seealso>
</element>
<!-- function result Visibility: private -->
<element name="TLazMonitor.GetDefaultSpinCount.Result">
<short>Value for the class property.</short>
</element>

<!-- class procedure Visibility: private -->
<element name="TLazMonitor.SetDefaultSpinCount">
<short>Sets the value for the DefaultSpinCount property.</short>
<seealso>
<link id="TLazMonitor.DefaultSpinCount"/>
</seealso>
</element>
<!-- argument Visibility: default -->
<element name="TLazMonitor.SetDefaultSpinCount.AValue">
<short>New value for the property.</short>
</element>

<!-- function Visibility: private -->
<element name="TLazMonitor.GetSpinCount">
<short>Gets the value for the SpinCount property.</short>
<seealso>
<link id="TLazMonitor.SpinCount"/>
</seealso>
</element>
<!-- function result Visibility: private -->
<element name="TLazMonitor.GetSpinCount.Result">
<short>Value for the property.</short>
</element>

<!-- procedure Visibility: private -->
<element name="TLazMonitor.SetSpinCount">
<short>Sets the value for the SpinCount property.</short>
<seealso>
<link id="TLazMonitor.SpinCount"/>
</seealso>
</element>
<!-- argument Visibility: default -->
<element name="TLazMonitor.SetSpinCount.AValue">
<short>New value for the property.</short>
</element>

<!-- constructor Visibility: public -->
<element name="TLazMonitor.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance, and sets the 
value in the <var>SpinCount</var> property to the <var>DefaultSpinCount</var> 
used in   instances of the class. Create calls the inherited constructor 
prior to exiting from the method.
</p>
</descr>
<seealso>
<link id="TLazMonitor.SpinCount"/>
<link id="TLazMonitor.DefaultSpinCount"/>
<link id="#fcl.syncobjs.TCriticalSection.Create">TCriticalSection.Create</link>
</seealso>
</element>

<!-- procedure Visibility: public -->
<element name="TLazMonitor.Acquire">
<short>Limits thread access to the calling thread.</short>
<descr>
<p>
<var>Acquire</var> is an overridden procedure used to limit threaded access 
to resources to the current calling thread. Acquire extends the inherited 
method to use a spinlock (or busy waiting loop) to get mutually exclusive 
access to resources shared between threads.
</p>
<p>
The SpinLock processing loop waits for successful completion of the 
Enter/Acquire method, but yields CPU cycles by calling <var>sleep()</var> to 
allow other threads to execute periodically. The internal yield/sleep 
thresholds are artificially low (10ms - 20ms) to avoid process 
scheduler/context switching conflicts for executing threads.
</p>
<p>
The inherited <var>Acquire</var> method is called when the method has 
successfully blocked access to other threads by entering the critical section.
</p>
<p>
Use the <var>SpinCount</var> property to determine the maximum number of 
iterations for the spinlock processing cycle. Use <var>DefaultSpinCount</var> 
to determine the default value used for the SpinCount property in new 
instances of the class.
</p>
</descr>
<seealso>
<link id="TLazMonitor.SpinCount"/>
<link id="TLazMonitor.DefaultSpinCount"/>
<link id="#fcl.syncobjs.TCriticalSection.Enter">TCriticalSection.Enter</link>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TLazMonitor.SpinCount">
<short>Number of busy waiting iterations used in the monitor.</short>
<descr>
<p>
<var>SpinCount</var> is an <var>Integer</var> property which indicates the 
number of busy waiting iterations used in the monitor. The default value for 
the property is set in the <var>Create</var> constructor to the value in the 
<var>DefaultSpinCount</var> class property.
</p>
<p>
Set the value in <var>SpinCount</var> to increase or decrease the number of 
spinlock iterations performed in the <var>Acquire</var> method. The value 
should be kept as small as possible to avoid the overhead of process 
scheduler/context switching conflicts for executing threads.
</p>
</descr>
<seealso>
<link id="TLazMonitor.Create"/>
<link id="TLazMonitor.DefaultSpinCount"/>
<link id="TLazMonitor.Acquire"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TLazMonitor.DefaultSpinCount">
<short>
Default number of busy waiting iterations used in instances of the class.
</short>
<descr>
<p>
<var>DefaultSpinCount</var> is an <var>Integer</var> class property which 
identifies the default number of busy waiting iterations used in instances of 
the class. <var>DefaultSpinCount</var> provides the default value for the 
<var>SpinCount</var> property in new instances of the class.
</p>
</descr>
<seealso>
<link id="TLazMonitor.SpinCount"/>
<link id="TLazMonitor.Acquire"/>
</seealso>
</element>

<element name="TLazFifoQueue">
<short>
Implements a First-In-First-Out queue for entries using a generic item type.
</short>
<descr>
<p>
<var>TLazFifoQueue</var> implements a FIFO queue using a generic type for the 
items in the queue. A FIFO queue processes the oldest (first) entry, or head 
of the queue, before any subsequent items added to the buffer.
</p>
<p>
TLazFifoQueue uses an internal array to store the queue items with the type 
used in the specialization. The queue size (or depth) can be specified when 
the class instance is created, and adjusted using the <var>Grow</var> method.
</p>
<p>
Use the <var>PushItem</var> and <var>PopItem</var> methods to add or remove 
entries in the queue.
</p>
<p>
Elements in the internal array are reused when the entry is popped off of the 
head of the queue. The head is moved to the next element in the internal 
array.
</p>
</descr>
<seealso/>
</element>

<element name="TLazFifoQueue.FList"/>
<element name="TLazFifoQueue.FQueueSize"/>

<element name="TLazFifoQueue.FTotalItemsPopped">
<short>
Member with the total number of items removed from the FIFO queue.
</short>
</element>

<element name="TLazFifoQueue.FTotalItemsPushed">
<short>Member with the total number of items stored on the FIFO queue.</short>
</element>

<element name="TLazFifoQueue.GetIsEmpty">
<short>Gets the value for the IsEmpty property.</short>
<descr/>
<seealso>
<link id="TLazFifoQueue.IsEmpty"/>
</seealso>
</element>
<element name="TLazFifoQueue.GetIsEmpty.Result">
<short>
True if the number of items pushed onto and popped off of the queue are the 
same.
</short>
</element>

<element name="TLazFifoQueue.GetIsFull">
<short>Gets the value for the IsFull property.</short>
<descr/>
<seealso>
<link id="TLazFifoQueue.IsFull"/>
</seealso>
</element>
<element name="TLazFifoQueue.GetIsFull.Result">
<short>
True when the number of items remaining in the queue is the same as the 
QueueSize.
</short>
</element>

<element name="TLazFifoQueue.Create">
<short>Constructor for the class instance.</short>
<descr>
<var>Create</var> is the constructor for the class instance, and calls 
<var>Grow</var> using the value in <var>AQueueDepth</var> as an argument. 
This sets the initial size for the internal queue storage to the specified 
number of entries.
</descr>
<seealso>
<link id="TLazFifoQueue.Grow"/>
</seealso>
</element>
<element name="TLazFifoQueue.Create.AQueueDepth">
<short>
Number of items allocated in the internal storage for the queue.
</short>
</element>

<element name="TLazFifoQueue.Grow">
<short>
Resizes the internal storage for the queue by the specified Delta value.
</short>
<descr>
<p>
<var>Grow</var> is a method used to resize the internal storage for the queue 
by the specified Delta value.
</p>
<p>
When <var>ADelta</var> is a position Integer value, the size for the internal 
array is enlarged by the value specified number of entries. When ADelta is a 
negative Integer value, the internal storage is shrunk by the specified 
number of entries.
</p>
<p>
Grow reallocates the internal array used to store the item types for the 
specialization. Existing items in the queue are moved to the new array, and 
the internal storage is updated.
</p>
<p>
The value in the <var>QueueSize</var> property is set to the new length for 
the internal array.
</p>
</descr>
<seealso>
<link id="TLazFifoQueue.QueueSize"/>
</seealso>
</element>
<element name="TLazFifoQueue.Grow.ADelta">
<short>Number of entries to add to (or remove from) the queue size.</short>
</element>

<element name="TLazFifoQueue.PushItem">
<short>
Pushes an item of the specified type onto the tail of the queue.
</short>
<descr>
<p>
<var>Pushitem</var> is a <var>Boolean</var> function used to add the value in 
<var>AItem</var> to the tail of the queue. The return value is <b>True</b> if 
the queue was not full when the method was called. No actions are performed 
in the method when a slot is not available in the internal storage for the 
queue.
</p>
<p>
PushItem stores the value in AItem at the next element in the internal array, 
and increments the value in the <var>TotalItemsPushed</var> property.
</p>
<p>
Use <var>PopItem</var> to remove the item at the head of the queue.
</p>
</descr>
<seealso>
<link id="TLazFifoQueue.IsFull"/>
<link id="TLazFifoQueue.QueueSize"/>
<link id="TLazFifoQueue.TotalItemsPushed"/>
<link id="TLazFifoQueue.TotalItemsPopped"/>
<link id="TLazFifoQueue.PopItem"/>
</seealso>
</element>
<element name="TLazFifoQueue.PushItem.Result">
<short>
True if the specified item was added to the queue, or False when the queue is 
full.
</short>
</element>
<element name="TLazFifoQueue.PushItem.AItem">
<short>Item added to the tail of the queue.</short>
</element>

<element name="TLazFifoQueue.PopItem">
<short>
Pops an item of the specified type off of the head of the queue.
</short>
<descr>
<p>
<var>PopItem</var> is a <var>Boolean</var> function used to get the value in 
AItem from the head of the queue. The return value is <b>True</b> if the 
queue was not empty when the method was called. No actions are performed in 
the method when items have not been stored in the internal storage for the 
queue.
</p>
<p>
PopItem retrieves the value in AItem from the storage slot at 
TotalItemsPopped mod QueueSize, and increments the value in the 
<var>TotalItemsPopped</var> property.
</p>
<p>
Use <var>PushItem</var> to add an item to the tail of the queue.
</p>
</descr>
<seealso>
<link id="TLazFifoQueue.IsEmpty"/>
<link id="TLazFifoQueue.QueueSize"/>
<link id="TLazFifoQueue.PushItem"/>
</seealso>
</element>
<element name="TLazFifoQueue.PopItem.Result">
<short>
True if the item was retrieved from the queue storage, False if the queue is 
empty.
</short>
</element>
<element name="TLazFifoQueue.PopItem.AItem">
<short>Item retrieved from the head of the queue.</short>
</element>

<element name="TLazFifoQueue.QueueSize">
<short>Size (or depth) for the queue.</short>
<descr>
<p>
Indicates the number of storage slots available in the internal storage for 
the queue.
</p>
<p>
Use TotalItemsPushed and TotalItemsPopped to determine the utilization level 
for the queue. Use IsFull or IsEmpty to determine if all or none of the 
storage slots have been filled in the queue. Use Grow to increase (or 
decrease) the queue depth.
</p>
</descr>
<seealso>
<link id="TLazFifoQueue.TotalItemsPopped"/>
<link id="TLazFifoQueue.TotalItemsPushed"/>
<link id="TLazFifoQueue.IsFull"/>
<link id="TLazFifoQueue.IsEmpty"/>
<link id="TLazFifoQueue.Grow"/>
</seealso>
</element>

<element name="TLazFifoQueue.TotalItemsPopped">
<short>Total number of entries that have been popped off of the queue.</short>
<descr>
<p>
Used with <var>QueueSize</var> to determine the next position (head) for the 
queue. (TotalItemsPopped mod QueueSize). Used with 
<var>TotalItemsPushed</var> to determine if the queue is empty or full. The 
value for the property is incremented in the <var>PopItem</var> method after 
the item at the head of the queue has been retrieved from the internal 
storage.
</p>
</descr>
<seealso>
<link id="TLazFifoQueue.TotalItemsPushed"/>
<link id="TLazFifoQueue.QueueSize"/>
<link id="TLazFifoQueue.PopItem"/>
</seealso>
</element>

<element name="TLazFifoQueue.TotalItemsPushed">
<short>Total number of entries that have been pushed onto the queue.</short>
<descr>
<p>
Used with <var>QueueSize</var> to determine the last position (tail) for the 
queue. (TotalItemsPushed mod QueueSize). Used with 
<var>TotalItemsPopped</var> to determine if the queue is empty or full. The 
value for the property is incremented in the <var>PushItem</var> method after 
the item has been stored in the internal storage at the tail for the queue.
</p>
</descr>
<seealso>
<link id="TLazFifoQueue.TotalItemsPopped"/>
<link id="TLazFifoQueue.QueueSize"/>
<link id="TLazFifoQueue.PushItem"/>
</seealso>
</element>

<element name="TLazFifoQueue.IsEmpty">
<short>
Indicates if none of the internal storage slots have been used in the queue 
storage.
</short>
<descr>
<p>
<var>IsEmpty</var> is a read-only <var>Boolean</var> property which indicates 
if none of the storage slots are used in the internal storage for the queue. 
The value is <b>True</b> when <var>TotalItemsPushed</var> and 
<var>TotalItemsPopped</var> have the same value.
</p>
<p>
Use <var>IsFull</var> to determine if all available storage slots are in use 
in the internal storage for the queue.
</p>
</descr>
<seealso>
<link id="TLazFifoQueue.TotalItemsPopped"/>
<link id="TLazFifoQueue.TotalItemsPushed"/>
<link id="TLazFifoQueue.IsFull"/>
</seealso>
</element>

<element name="TLazFifoQueue.IsFull">
<short>
Indicates if all of the internal storage slots have been used in the queue 
storage.
</short>
<descr>
<p>
<var>IsFull</var> is a read-only <var>Boolean</var> property which indicates 
if all of the storage slots are used in the internal storage for the queue. 
The value is <b>True</b> when <var>TotalItemsPushed</var> - 
<var>TotalItemsPopped</var> = <var>QueueSize</var>.
</p>
<p>
Use <var>IsEmpty</var> to determine if none of the available storage slots 
are in use in the internal storage for the queue.
</p>
</descr>
<seealso>
<link id="TLazFifoQueue.TotalItemsPopped"/>
<link id="TLazFifoQueue.TotalItemsPushed"/>
<link id="TLazFifoQueue.QueueSize"/>
<link id="TLazFifoQueue.IsEmpty"/>
</seealso>
</element>

<element name="TLazThreadedQueue">
<short>
Implements a thread-safe FIFO queue for items of a generic type.
</short>
<descr>
<p>
<var>TLazThreadedQueue</var> is generic class which implements a thread-safe 
FIFO queue using a generic type for its items. The class requires 
specialization to specify the type stored in the items for the queue. For 
example:
</p>
<code>
TLazThreadedQueueString = specialize TLazThreadedQueue&lt;String&gt;;
TLazThreadedQueueInt = specialize TLazThreadedQueue&lt;Integer&gt;;
TLazThreadedQueueRect = specialize TLazThreadedQueue&lt;TRectangle&gt;;
</code>
<p>
<var>TLazThreadedQueue</var> uses an internal <var>TLazMonitor</var> member 
to synchronize access to resources in the queue between executing threads. 
Methods in the class which require thread-safe access use the monitor to 
enable/disable resource protection. Items in the queue are maintained using 
the <var>PushItem</var>, <var>PopItem</var>, and <var>PopItemTimeout</var> 
methods. Properties are provided to determine the size of the queue, and the 
number of items added or removed.
</p>
<p>
TLazThreadedQueue specializations are used in the implementation of the 
<var>fpdserver</var> component, and its integration into the Lazarus IDE.
</p>
</descr>
<seealso>
<link id="TLazMonitor"/>
</seealso>
</element>

<element name="TLazThreadedQueue.TLazTypedFifoQueue">
<short>
Type used to the specialize the internal TLazFifoQueue instance for the class.
</short>
<descr/>
<seealso/>
</element>

<!-- variable Visibility: private -->
<element name="TLazThreadedQueue.FMonitor"/>
<element name="TLazThreadedQueue.FFifoQueue"/>
<element name="TLazThreadedQueue.FPushTimeout"/>
<element name="TLazThreadedQueue.FPopTimeout"/>
<element name="TLazThreadedQueue.FHasRoomEvent"/>
<element name="TLazThreadedQueue.FHasItemEvent"/>
<element name="TLazThreadedQueue.FShutDown"/>

<element name="TLazThreadedQueue.GetQueueSize">
<short>Gets the value for the QueueSize property.</short>
<descr/>
<seealso>
<link id="TLazThreadedQueue.QueueSize"/>
</seealso>
</element>
<element name="TLazThreadedQueue.GetQueueSize.Result">
<short>Value for the property.</short>
</element>

<element name="TLazThreadedQueue.GetTotalItemsPopped">
<short>Gets the value for the TotalItemsPopped property.</short>
<descr/>
<seealso/>
</element>
<element name="TLazThreadedQueue.GetTotalItemsPopped.Result">
<short>Value for the property.</short>
</element>

<element name="TLazThreadedQueue.GetTotalItemsPushed">
<short>Gets the value for the TotalItemsPushed property.</short>
<descr/>
<seealso>
<link id="TLazThreadedQueue.TotalItemsPushed"/>
</seealso>
</element>
<element name="TLazThreadedQueue.GetTotalItemsPushed.Result">
<short>Value for the property.</short>
</element>

<element name="TLazThreadedQueue.TryPushItem">
<short>Tries to add the specified item to the queue.</short>
<descr>
<p>
<var>TryPushItem</var> is a <var>Boolean</var> function which tries to add 
the item specified in <var>AItem</var> to the internal storage for the queue. 
The return value is <b>True</b> if the item was successfully added in the 
method.
</p>
<p>
<var>TryPushItem</var> is used in the implementation of the 
<var>PushItem</var> method. Use <var>PushItem</var> to add an item to the 
thread-safe queue.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.PushItem"/>
</seealso>
</element>
<element name="TLazThreadedQueue.TryPushItem.Result">
<short>True if the item was added successfully.</short>
</element>
<element name="TLazThreadedQueue.TryPushItem.AItem">
<short>Item added to the queue in the method.</short>
</element>

<element name="TLazThreadedQueue.TryPopItem">
<short>Tries to remove the next item in the thread-safe queue.</short>
<descr/>
<seealso/>
</element>
<element name="TLazThreadedQueue.TryPopItem.Result">
<short>True if an item was successfully removed from the queue.</short>
</element>
<element name="TLazThreadedQueue.TryPopItem.AItem">
<short>Item removed from the queue in the method.</short>
</element>

<element name="TLazThreadedQueue.TryPushItemUnprotected">
<short>
Tries to push an item onto the queue without resource protection.
</short>
<descr>
<p>
Sets and resets internal RTL events when the item was successfully pushed, 
and when queue space is available.
</p>
</descr>
<seealso/>
</element>
<element name="TLazThreadedQueue.TryPushItemUnprotected.Result">
<short>
<b>True</b> if an element was available in the list storage for the queue. 
<b>False</b> if the queue is full.
</short>
</element>
<element name="TLazThreadedQueue.TryPushItemUnprotected.AItem">
<short>
Specialization type for the item pushed onto the queue.
</short>
</element>

<element name="TLazThreadedQueue.TryPopItemUnprotected">
<short>
Tries to pop an item off of the queue without resource protection.
</short>
<descr>
<p>
Sets and resets internal RTL events when the item was successfully popped, 
and when queue space is available.
</p>
</descr>
<seealso/>
</element>
<element name="TLazThreadedQueue.TryPopItemUnprotected.Result">
<short>
<b>True</b> if an item was available in the queue. <b>False</b> if the 
storage list for the queue was empty.
</short>
</element>
<element name="TLazThreadedQueue.TryPopItemUnprotected.AItem">
<short>
Specialization type for the item popped off of the queue.
</short>
</element>

<element name="TLazThreadedQueue.Lock">
<short>Enters the Monitor used for resource protection.</short>
<descr/>
<seealso>
<link id="TLazThreadedQueue.Unlock"/>
</seealso>
</element>

<element name="TLazThreadedQueue.Unlock">
<short>Leaves the Monitor used for resource protection.</short>
<descr/>
<seealso>
<link id="TLazThreadedQueue.Lock"/>
</seealso>
</element>

<element name="TLazThreadedQueue.CreateFifoQueue">
<short>Creates the TLazTypedFifoQueue instance used in the class.</short>
<descr/>
<seealso>
<link id="TLazThreadedQueue.TLazTypedFifoQueue"/>
</seealso>
</element>
<element name="TLazThreadedQueue.CreateFifoQueue.Result">
<short>TLazTypedFifoQueue instance used in the class.</short>
</element>
<element name="TLazThreadedQueue.CreateFifoQueue.AQueueDepth">
<short>Initial setting for the queue depth (or size).</short>
</element>

<element name="TLazThreadedQueue.FifoQueue">
<short>
Provides access to the TLazTypedFifoQueue instance used in the class.
</short>
<descr/>
<seealso/>
</element>

<element name="TLazThreadedQueue.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance. Create allocates 
internal resources used to implement the thread-safe queue, and sets the 
default values for its properties.
</p>
<p>
The value in <var>AQueueDepth</var> is passed as an argument to the 
<var>Grow</var> method to allocate the internal storage for the queue.
</p>
<p>
<var>PushTimeout</var> and <var>PopTimeout</var> indicate the number of 
milliseconds (or ticks) to wait for successful completion of enqueue or 
dequeue requests, and are assigned as the default value for the corresponding 
internal members in the class instance.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.Grow"/>
<link id="TLazThreadedQueue.PushItem"/>
<link id="TLazThreadedQueue.PopItem"/>
<link id="TLazThreadedQueue.Destroy"/>
</seealso>
</element>
<!-- argument Visibility: default -->
<element name="TLazThreadedQueue.Create.AQueueDepth">
<short>
Indicates the maximum number of items that can be stored in the thread-safe 
queue.
</short>
</element>
<!-- argument Visibility: default -->
<element name="TLazThreadedQueue.Create.PushTimeout">
<short>
Number of ticks (milliseconds) to wait for successful completion of an 
enqueue request.
</short>
</element>

<!-- argument Visibility: default -->
<element name="TLazThreadedQueue.Create.PopTimeout">
<short>
Number of ticks (milliseconds) to wait for successful completion of a dequeue 
request.
</short>
</element>

<!-- destructor Visibility: public -->
<element name="TLazThreadedQueue.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the destructor for the class instance. Destroy calls 
the private <var>DoShutDown</var> method to free internal resources allocated 
in the class instance. Destroy calls the inherited destructor prior to 
exiting from the method.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.DoShutDown"/>
<link id="TLazThreadedQueue.Create"/>
<link id="#fcl.syncobjs.TCriticalSection.Destroy">TCriticalSection.Destroy</link>
</seealso>
</element>

<element name="TLazThreadedQueue.Grow">
<short>
Expands (or shrinks) the allocated storage for the queue by the specified 
size.
</short>
<descr>
<p>
<var>Grow</var> is a method used to resize the internal storage for the queue 
by the specified Delta value.
</p>
<p>
When <var>ADelta</var> is a position Integer value, the size for the internal 
array is enlarged by the value specified number of entries. When ADelta is a 
negative Integer value, the internal storage is shrunk by the specified 
number of entries.
</p>
<p>
Grow reallocates the internal array used to store the item types for the 
specialization. Existing items in the queue are moved to the new array, and 
the internal storage is updated.
</p>
<p>
The value in the <var>QueueSize</var> property is set to the new length for 
the internal array.
</p>
<p>
Grows uses resource protection when calling the Grow method in the internal 
TLazFifoQueue instance in the class.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.Lock"/>
<link id="TLazThreadedQueue.Unlock"/>
<link id="TLazThreadedQueue.TLazTypedFifoQueue"/>
<link id="TLazFifoQueue.Grow"/>
<link id="TLazMonitor"/>
</seealso>
</element>
<element name="TLazThreadedQueue.Grow.ADelta">
<short>Value used to increase the size of the queue.</short>
</element>

<element name="TLazThreadedQueue.PushItem">
<short>Adds the specified item to the queue.</short>
<descr>
<p>
<var>PushItem</var> is a <var>TWaitResult</var> function used to add the item 
specified in <var>AItem</var> to the thread-safe queue.
</p>
<p>
PushItem uses the value in the internal <var>PushTimeout</var> member to 
determine if a timeout is in effect for the enqueue request. When PushTimeout 
contains <var>INFINITE</var>, a timeout is not used for the operation. 
Instead, the request waits for an RTL Event that indicates room is available 
in the internal storage for the queue.
</p>
<p>
When PushTimeout contains <b>0</b>, the request will timeout after the first 
failed attempt to add the specified item to the queue.
</p>
<p>
When <var>ShutDown</var> contains <b>True</b>, the return value is updated to 
indicate that the request should be abandoned.
</p>
<p>
The return value contains a <var>TWaitResult</var> enumeration value that 
indicates the status for the enqueue request. See <var>TWaitResult</var> for 
more information about enumeration values and their meanings.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.ShutDown"/>
<link id="#fcl.syncobjs.TWaitResult">TWaitResult</link>
<link id="#rtl.system.RTLEventWaitFor">RTLEventWaitFor</link>
</seealso>
</element>
<element name="TLazThreadedQueue.PushItem.Result">
<short>Contains the status for the enqueue request.</short>
</element>
<element name="TLazThreadedQueue.PushItem.AItem">
<short>Item added to the storage for the queue.</short>
</element>

<!-- function Visibility: public -->
<element name="TLazThreadedQueue.PopItem">
<short>Pops the next item from the queue.</short>
<descr>
<p>
<var>PopItem</var> is a <var>TWaitResult</var> function used remove the next 
item available in the thread-safe queue. PopItem calls the 
<var>PopItemTimeout</var> method using the value in the <var>PopTimeout</var> 
property as an argument.
</p>
<p>
<var>AItem</var> is an output variable that is updated with the item removed 
from the queue in the method.
</p>
<p>
The return value contains a <var>TWaitResult</var> enumeration value that 
indicates the status for the dequeue request. See <var>TWaitResult</var> for 
more information about enumeration values and their meanings.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.PopItemTimeout"/>
<link id="#fcl.syncobjs.TWaitResult">TWaitResult</link>
</seealso>
</element>
<!-- function result Visibility: public -->
<element name="TLazThreadedQueue.PopItem.Result">
<short>Contains the status for the dequeue request.</short>
</element>
<!-- argument Visibility: default -->
<element name="TLazThreadedQueue.PopItem.AItem">
<short>Item removed from the queue.</short>
</element>

<!-- function Visibility: public -->
<element name="TLazThreadedQueue.PopItemTimeout">
<short>Pops an item off the queue with a timeout value.</short>
<descr>
<p>
<var>PopItemTimeout</var> is a <var>TWaitResult</var> function used to remove 
the next available item in the queue with a timeout in effect for the dequeue 
operation.
</p>
<p>
AItem is an output parameter used to return the item removed from the 
thread-safe queue.
</p>
<p>
<var>Timeout</var> specifies the number of ticks (milliseconds) to wait for 
successful completion of the dequeue request. When Timeout contains the value 
<var>INFINITE</var>, a timeout is not used in the method. Instead, an 
internal RTL event is signalled to wait for an available item in the queue. 
When Timeout contains <b>0</b>, the request returns immediately after the 
first failed attempt to dequeue an item.
</p>
<p>
When <var>ShutDown</var> contains <b>True</b>, the method updates the return 
value to indicate that the request was abandoned.
</p>
<p>
The return value contains a <var>TWaitResult</var> enumeration value that 
indicates the status for the dequeue request. See <var>TWaitResult</var> for 
more information about enumeration values and their meanings.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.PopItem"/>
<link id="TLazThreadedQueue.ShutDown"/>
<link id="#fcl.syncobjs.TWaitResult">TWaitResult</link>
</seealso>
</element>
<!-- function result Visibility: public -->
<element name="TLazThreadedQueue.PopItemTimeout.Result">
<short>Contains the status for the dequeue request.</short>
</element>
<!-- argument Visibility: default -->
<element name="TLazThreadedQueue.PopItemTimeout.AItem">
<short>Item removed from the queue.</short>
</element>
<!-- argument Visibility: default -->
<element name="TLazThreadedQueue.PopItemTimeout.Timeout">
<short>
Maximum number of ticks to wait for the item to be removed from the queue.
</short>
</element>

<!-- procedure Visibility: public -->
<element name="TLazThreadedQueue.DoShutDown">
<short>
Performs actions required when the thread-safe queue is freed.
</short>
<descr>
<p>
<var>DoShutDown</var> is a procedure used to perform actions required when 
the instance of the thread-safe queue is freed. DoShutDown sets the value in 
the <var>ShutDown</var> property to <b>True</b> to signal executing threads 
that the queue is being freed. In additional, RTL events are set/reset to 
reflect the state for the internal storage in the queue.
</p>
<p>
<var>DoShutDown</var> is called prior to freeing resources for the class 
instance in the <var>Destroy</var> method.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.ShutDown"/>
<link id="TLazThreadedQueue.Destroy"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TLazThreadedQueue.QueueSize">
<short>
Number of storage slots for items in the queue.
</short>
<descr>
<p>
<var>QueueSize</var> is a read-only <var>Integer</var> property that 
indicates the number of storage slots available in the internal storage for 
the queue. The initial value for <var>QueueSize</var> is set using an 
argument passed to the constructor.
</p>
<p>
Use the <var>Grow</var> method to adjust the number of slots in the internal 
storage for the queue.
</p>
<p>
Values in the <var>TotalItemsPushed</var>, <var>TotalItemsPopped</var>, and 
<var>QueueSize</var> properties determine if storage and/or items are 
available in the queue.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.TotalItemsPopped"/>
<link id="TLazThreadedQueue.TotalItemsPushed"/>
<link id="TLazThreadedQueue.Create"/>
<link id="TLazThreadedQueue.PushItem"/>
<link id="TLazThreadedQueue.PopItem"/>
<link id="TLazThreadedQueue.PopItemTimeout"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TLazThreadedQueue.TotalItemsPopped">
<short>
Total number of items removed from the queue.
</short>
<descr>
<p>
<var>TotalItemsPopped</var> is a read-only <var>QWord</var> property that 
indicates the total number of items removed from the queue. The value in the 
internal member for the property is incremented each time the 
<var>PopItem</var> or <var>PopItemTimeout</var> method is completed 
successfully.
</p>
<p>
Values in <var>TotalItemsPopped</var> and <var>TotalItemsPushed</var> 
determine whether items are available in the queue. Use 
<var>TotalItemsPushed</var> to determine the number of items added to the 
queue.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.PopItem"/>
<link id="TLazThreadedQueue.PopItemTimeout"/>
<link id="TLazThreadedQueue.TotalItemsPushed"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TLazThreadedQueue.TotalItemsPushed">
<short>
Total number of items added to the queue.
</short>
<descr>
<p>
<var>TotalItemsPushed</var> is a read-only <var>QWord</var> property that 
indicates the total number of items added to the queue. The value in the 
internal member for the property is incremented each time the 
<var>PushItem</var> method is completed successfully.
</p>
<p>
Values in <var>TotalItemsPushed</var> and <var>TotalItemsPopped</var> 
determine whether items are available in the queue. Use 
<var>TotalItemsPopped</var> to determine the total number of items removed 
from the queue.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.PushItem"/>
<link id="TLazThreadedQueue.TotalItemsPopped"/>
</seealso>
</element>

<!-- property Visibility: public -->
<element name="TLazThreadedQueue.ShutDown">
<short>
Indicates if the DoShutdown method has been called but not finished.
</short>
<descr>
<p>
<var>ShutDown</var> is a read-only <var>Boolean</var> property which 
indicates if the DoShutDown method has been called, but not yet completed, 
for the class instance. The value in ShutDown is used in the 
<var>PushItem</var> and <var>PopItemTimeout</var> methods to determine the 
status for the respective requests. The value <var>wrAbandoned</var> is 
returned from these methods when <var>ShutDown</var> contains <b>True</b>.
</p>
<p>
The value in <var>ShutDown</var> is set to <b>True</b> in the 
<var>DoShutDown</var> method.
</p>
</descr>
<seealso>
<link id="TLazThreadedQueue.DoShutDown"/>
<link id="TLazThreadedQueue.PushItem"/>
<link id="TLazThreadedQueue.PopItemTimeout"/>
<link id="#fcl.syncobjs.TWaitResult">TWaitResult</link>
</seealso>
</element>

</module>
<!-- lazCollections -->
</package>
</fpdoc-descriptions>
