What is the purpose or function of the TQueue.Capacity property? - delphi

Question

Delphi's generic TQueue class has a property called Capacity. If the number of items in the TQueue exceeds its capacity, additional items are still added to the queue. The documentation says the property "gets or sets the queue capacity, that is, the maximum size of the queue without resizing." It sounds like a queue is kind of like a fixed length array (memory-wise)--until it's full, at which point it becomes more like a dynamic array? Is that accurate?
When would a programmer want or need to get or set a TQueue's capacity?

Answer 1

Theory
Consider the following example, which generates a dynamic array of random integers:
program DynArrAlloc;
{$APPTYPE CONSOLE}
{$R *.res}
uses
Windows, System.SysUtils;
const
N = 100000000;
var
a: TArray<Integer>;
i: Integer;
tc1, tc2: Cardinal;
begin
tc1 := GetTickCount;
SetLength(a, 0);
for i := 1 to N do
begin
SetLength(a, Succ(Length(a)));
a[High(a)] := Random(1000);
end;
tc2 := GetTickCount;
Writeln(tc2 - tc1);
Readln;
end.
On my system, it takes 4.5 seconds to run it.
Notice that I -- in each iteration -- reallocate the array so it can hold one more item.
It would be better if I allocated a large enough array from the beginning:
program DynArrAlloc;
{$APPTYPE CONSOLE}
{$R *.res}
uses
Windows, System.SysUtils;
const
N = 100000000;
var
a: TArray<Integer>;
i: Integer;
tc1, tc2: Cardinal;
begin
tc1 := GetTickCount;
SetLength(a, N);
for i := 1 to N do
a[N - 1] := Random(1000);
tc2 := GetTickCount;
Writeln(tc2 - tc1);
Readln;
end.
This time, the program only takes 0.6 seconds.
Hence, one should always try not to reallocate unnecessarily. Each time I reallocate in the first example, I need to ask for more memory; then I need to copy the array to the new location, and finally free the old memory. Clearly, this is very inefficient.
Unfortunately, it isn't always possible to allocate a large enough array at the start. You simply might not know the final element count.
A common strategy then is to allocate in steps: when the array is full and you need one more slot, allocate several more slots but keep track of the actual number of used slots:
program DynArrAlloc;
{$APPTYPE CONSOLE}
{$R *.res}
uses
Windows, System.SysUtils;
const
N = 100000000;
var
a: TArray<Integer>;
i: Integer;
tc1, tc2: Cardinal;
ActualLength: Integer;
const
AllocStep = 1024;
begin
tc1 := GetTickCount;
SetLength(a, AllocStep);
ActualLength := 0;
for i := 1 to N do
begin
if ActualLength = Length(a) then
SetLength(a, Length(a) + AllocStep);
a[ActualLength] := Random(1000);
Inc(ActualLength);
end;
// Trim the excess:
SetLength(a, ActualLength);
tc2 := GetTickCount;
Writeln(tc2 - tc1);
Readln;
end.
Now we need 1.3 seconds.
In this example, I allocate in fixed-sized blocks. A more common strategy is probably to double the array at each reallocation (or multiply by 1.5 or something) or combine these options in a smart way.
Applying the theory
Under the hood, TList<T>, TQueue<T>, TStack<T>, TStringList etc. need to dynamically allocate space for an unlimited number of items. To make this performant, these classes do allocate more than necessary. The Capacity is the number of elements you can fit in the currently allocated memory while the Count <= Capacity is the actual number of elements in the container.
You can set the Capacity property to reduce the need for intermediate allocation when you fill a container and you do know the final number of elements from the beginning:
var
L: TList<Integer>;
begin
L := TList<Integer>.Create;
try
while not Something.EOF do
L.Add(Something.GetNextValue);
finally
L.Free;
end;
is OK and requires probably only a few reallocations, but
L := TList<Integer>.Create;
try
L.Capacity := Something.Count;
while not Something.EOF do
L.Add(Something.GetNextValue);
finally
L.Free;
end;
will be faster since there will be no intermediate reallocations.

Answer 2

Internally TQueue contains dynamic array that stores elements.
When item count reaches current capacity, array is reallocated (for example, doubles it's size) and you can add more and more elements.
If you know reliable limit for maximum item count, it is worth to set Capacity, so you will avoid memory reallocations, saving some time.