mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-06-03 04:38:13 +02:00
e567ca6b03
Modified files: docs/xml/lazutils/fileutil.xml docs/xml/lazutils/graphtype.xml docs/xml/lazutils/lazcollections.xml docs/xml/lazutils/lazlistclasses.xml docs/xml/lazutils/lazloggerbase.xml docs/xml/lazutils/lazstringutils.xml docs/xml/lazutils/masks.xml
977 lines
44 KiB
XML
977 lines
44 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<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>
|
|
This 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<String>;
|
|
TLazThreadedQueueInt = specialize TLazThreadedQueue<Integer>;
|
|
TLazThreadedQueueRect = specialize TLazThreadedQueue<TRectangle>;
|
|
</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>
|
|
<notes><note>TODO: Discuss the RTL events and their usage.</note></notes>
|
|
<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/>
|
|
</element>
|
|
<element name="TLazThreadedQueue.TryPushItemUnprotected.AItem">
|
|
<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/>
|
|
</element>
|
|
<element name="TLazThreadedQueue.TryPopItemUnprotected.AItem">
|
|
<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>
|