1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
|
<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="LazUtils">
<!--
====================================================================
DynQueue
====================================================================
-->
<module name="DynQueue">
<short>implements a dynamic FIFO queue.</short>
<descr>
<file>dynqueue.pp</file> contains types and classes needed to implement a dynamic FIFO queue for arbitrary data.
</descr>
<!-- unresolved type reference Visibility: default -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="LazLoggerBase"/>
<!-- record type Visibility: default -->
<element name="TDynamicQueueItem">
<short>Represents the size and content for a data item in TDynamicDataQueue.</short>
<descr>
<p>
<var>TDynamicQueueItem</var> is a record type used to represent the size and content for an arbitrary data item added to <var>TDynamicDataQueue</var>.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue"/>
</seealso>
</element>
<!-- variable Visibility: default -->
<element name="TDynamicQueueItem.Size">
<short>Size for the item structure and its Data.</short>
<descr></descr>
<seealso></seealso>
</element>
<!-- variable Visibility: default -->
<element name="TDynamicQueueItem.Data">
<short>Content for the queue item.</short>
<descr></descr>
<seealso></seealso>
</element>
<!-- pointer type Visibility: default -->
<element name="PDynamicQueueItem">
<short>Pointer to a TDynamicQueueItem type.</short>
<descr></descr>
<seealso></seealso>
</element>
<!-- pointer type Visibility: default -->
<element name="ListOfPDynamicQueueItem">
<short>Pointer to the PDynamicQueueItem type.</short>
<descr></descr>
<seealso></seealso>
</element>
<!-- object Visibility: default -->
<element name="TDynamicDataQueue">
<short>Implements a FIFO queue for arbitrary data.</short>
<descr>
<p>
<var>TDynamicDataQueue</var> is a class used to queue arbitrary data for First-In-First-Out usage.
</p>
<p>
<var>TDynamicDataQueue</var> provides overloaded <var>Push</var> and <var>Pop</var> methods used to enqueue or dequeue data using an untyped buffer or a <var>TStream</var> instance. Use the <var>Top</var> method to peek at data in the queue without removing it.
</p>
<p>
Internally, <var>TDynamicDataQueue</var> maintains a ring queue for pointers to chunks of data using the <var>TDynamicQueueItem</var> type. It is optimized to reduce the amount of data movement required when adding or removing items.
</p>
<p>
<var>TDynamicDataQueue</var> is used to implement storage for the <var>TCustomLazComponentQueue</var> component in the <file>lresources.pp</file> unit in the Lazarus Component Library (LCL).
</p>
</descr>
<seealso>
<link id="TDynamicQueueItem"/>
<link id="#lcl.lresources.TCustomLazComponentQueue">TCustomLazComponentQueue</link>
</seealso>
</element>
<!-- variable Visibility: private -->
<element name="TDynamicDataQueue.FItems"/>
<element name="TDynamicDataQueue.FItemCapacity"/>
<element name="TDynamicDataQueue.FTopIndex"/>
<element name="TDynamicDataQueue.FLastIndex"/>
<element name="TDynamicDataQueue.FMaximumBlockSize"/>
<element name="TDynamicDataQueue.FMinimumBlockSize"/>
<element name="TDynamicDataQueue.FSize"/>
<element name="TDynamicDataQueue.FTopItemSpace"/>
<element name="TDynamicDataQueue.FLastItemSpace"/>
<!-- method Visibility: private -->
<element name="TDynamicDataQueue.SetMaximumBlockSize">
<short>Sets the value for the MaximumBlockSize property.</short>
<descr/>
<seealso>
<link id="TDynamicDataQueue.MaximumBlockSize"/>
</seealso>
</element>
<element name="TDynamicDataQueue.SetMaximumBlockSize.AValue">
<short>New value for the property.</short>
</element>
<element name="TDynamicDataQueue.SetMinimumBlockSize">
<short>Sets the value for the MinimumBlockSize property.</short>
<descr/>
<seealso>
<link id="TDynamicDataQueue.MinimumBlockSize"/>
</seealso>
</element>
<element name="TDynamicDataQueue.SetMinimumBlockSize.AValue">
<short>New value for the property.</short>
</element>
<element name="TDynamicDataQueue.GrowItems">
<short>
Re-allocates the storage for the ring queue, optionally increasing its size.
</short>
<descr>
<p>
<var>GrowItems</var> is a procedure used to re-allocate the storage for the ring queue. GrowItems ensures that the capacity for the internal queue storage is a minimum of eight (<b>8</b>) <var>TDynamicQueueItem</var> entries. If that threshold has already been crossed, the capacity is doubled with each call to the method.
</p>
<p>
GrowItems copies existing items in the queue into the newly allocated storage, and frees the memory allocated to the old queue storage. The internal index positions to the top and bottom of the queue are reset to their new values.
</p>
<p>
GrowItems is called from the <var>AddItem</var> method when additional storage is needed for the ring queue.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.AddItem"/>
<link id="TDynamicQueueItem"/>
<link id="PDynamicQueueItem"/>
<link id="ListOfPDynamicQueueItem"/>
</seealso>
</element>
<element name="TDynamicDataQueue.AddItem">
<short>Ensures space is available, and allocates storage for a new queue item.</short>
<descr>
<p>
<var>AddItem</var> is a procedure used to allocate storage for a new item in the ring queue. AddItem ensures that space is available in the queue for a new queue entry, and calls <var>GrowItems</var> when needed.
</p>
<p>
AddItem checks the internal storage for the queue to ensure that it is assigned, and does not already contain a data item at the next position in the queue. An <var>Exception</var> is raised when either condition is not met.
</p>
<p>
AddItem allocates memory at the queue position by calling <var>GetMem</var> using the size of the <var>TDynamicQueueItem</var> type and the additional space specified in <var>ItemSize</var>.
</p>
<p>
AddItem is used in the implementation of the <var>PushInternal</var> method.
</p>
</descr>
<errors>
<p>
Raises an <var>Exception</var> if the item storage is not assigned, or when it already contains an item at the new position. The exception message is: <b>'TDynamicDataQueue.AddItem NewIndex=[n]'</b>.
</p>
</errors>
<seealso>
<link id="TDynamicQueue.GrowItems"/>
<link id="TDynamicQueue.Push"/>
<link id="TDynamicQueueItem"/>
</seealso>
</element>
<element name="TDynamicDataQueue.AddItem.ItemSize">
<short>Space required for the arbitrary data stored in the new queue item.</short>
</element>
<element name="TDynamicDataQueue.CalculateItemSize">
<short>Calculates the size for a memory block allocated for a new queue item.</short>
<descr>
<p>
<var>CalculateItemSize</var> is an <var>Integer</var> function used to calculate the memory block size needed for a new item added to the queue.
<p>
</p>
<var>ItemSize</var> contains the size requested for the data structure and its arbitrary content, and is used by default as the return value for the method. CalculateItemSize ensures that the return value is in the range defined by the <var>MinimumBlockSize</var> and <var>MaximumBlockSize</var> properties.
</p>
<p>
CalculateItemSize is used in the implementation of the private <var>PushInternal</var> method.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.MinimumBlockSize"/>
<link id="TDynamicDataQueue.MaximumBlockSize"/>
<link id="TDynamicDataQueue.Push"/>
</seealso>
</element>
<element name="TDynamicDataQueue.CalculateItemSize.Result">
<short>
Size of the memory block size needed to store a new item with the specified data size.
</short>
</element>
<element name="TDynamicDataQueue.CalculateItemSize.ItemSize">
<short>Size requested for the queue item structure and its data.</short>
</element>
<element name="TDynamicDataQueue.PushInternal">
<short>
Performs actions needed to store arbitrary byte values for an item in the FIFO queue.
</short>
<descr>
<p>
<var>PushInternal</var> is an <var>Integer</var> function used to perform actions needed to store arbitrary data for queue items in the FIFO queue. The new queue item is added to the bottom (end, tail, etc.) of the queue.
</p>
<p>
Arguments to the method provide the location where the data for the new item is stored, and the number of bytes required for the arbitrary byte data. <var>Source</var> is the untyped buffer with the item data. <var>AStream</var> is the <var>TStream</var> instance where the item data can be found. Both storage mechanisms are not used at the same time; preference is given to Source (when assigned).
</p>
<p>
PushInternal calls <var>System.Move</var> to transfer byte data from Source to the internal storage for the queue, or calls the Read method in AStream to read the item data. The <var>Size</var> property is incremented by the number of bytes actually read in the method. <var>AddItem</var> is called to adjust the internal storage allocation for the calculated item size.
</p>
<remark>
PushInternal assumes that the TStream instance is already positioned at the location needed to access the item data for the queue entry. It does not reposition the stream prior to or following a call to the TStream.Read method. Be aware that reading from a stream can raise an exception.
</remark>
<p>
The return value contains the number of bytes transferred to the internal queue storage in the method.
</p>
<p>
PushInternal is used in the implementation of the overloaded <var>Push</var> methods.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.Push"/>
<link id="TDynamicDataQueue.Size"/>
<link id="TDynamicDataQueue.AddItem"/>
</seealso>
</element>
<element name="TDynamicDataQueue.PushInternal.Result">
<short>Number of bytes stored in the queue storage for the new item.</short>
</element>
<element name="TDynamicDataQueue.PushInternal.Source">
<short>Untyped buffer with the arbitrary byte data added to the queue.</short>
</element>
<element name="TDynamicDataQueue.PushInternal.AStream">
<short>TStream instance where the arbitrary byte data for the item can be found.</short>
</element>
<element name="TDynamicDataQueue.PushInternal.Count">
<short>Number of bytes expected in the data for the queue item.</short>
</element>
<element name="TDynamicDataQueue.PopTopInternal">
<short>
Performs actions needed to read, and to optionally remove, an item in the FIFO queue.
</short>
<descr></descr>
<seealso>
<link id="TDynamicDataQueue.Pop"/>
<link id="TDynamicDataQueue.Top"/>
<link id="TDynamicDataQueue.Push"/>
<link id="TDynamicDataQueue.Clear"/>
</seealso>
</element>
<element name="TDynamicDataQueue.PopTopInternal.Result">
<short>Number of bytes read/removed from the internal queue storage.</short>
</element>
<element name="TDynamicDataQueue.PopTopInternal.Dest">
<short>Untyped buffer where data for the queue item is stored.</short>
</element>
<element name="TDynamicDataQueue.PopTopInternal.AStream">
<short>Stream instance where data for the queue item is stored.</short>
</element>
<element name="TDynamicDataQueue.PopTopInternal.Count">
<short>Number of bytes expected in the queue item.</short>
</element>
<element name="TDynamicDataQueue.PopTopInternal.KeepData">
<short>Indicates if item data should remain in the internal queue storage; used to implement Top.</short>
</element>
<!-- constructor Visibility: public -->
<element name="TDynamicDataQueue.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance. Create sets the default values for the following properties:
</p>
<dl>
<dt>MinimumBlockSize</dt>
<dd>Set to 512 (bytes)</dd>
<dt>MaximumBlockSize</dt>
<dd>Set to 4096 (bytes)</dd>
</dl>
</descr>
<seealso>
<link id="TDynamicDataQueue.MinimumBlockSize"/>
<link id="TDynamicDataQueue.MaximumBlockSize"/>
<link id="TDynamicDataQueue.Destroy"/>
</seealso>
</element>
<!-- destructor Visibility: public -->
<element name="TDynamicDataQueue.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. Destroy calls the <var>Clear</var> method to remove items stored in the queue, and to free memory allocated for their storage. Destroy calls the inherited destructor prior to exiting from the method.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.Clear"/>
</seealso>
</element>
<!-- procedure Visibility: public -->
<element name="TDynamicDataQueue.Clear">
<short>Frees data items and storage allocated for the queue.</short>
<descr>
<p>
<var>Clear</var> is a procedure used to free all items stored in the queue, and the memory allocated for their storage. Clear iterates over the items in the queue, and calls <var>FreeMem</var> to de-allocate memory reserved to store each item structure and its data. The internal storage for the queue is set to <b>Nil</b> when all items have been de-allocated.
</p>
<p>
Clear resets the values for internal members used for the queue <var>Size</var>, and those used for item positions in the queue.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.Size"/>
</seealso>
</element>
<!-- procedure Visibility: public -->
<element name="TDynamicDataQueue.ConsistencyCheck">
<short>Checks for errors in queue settings, item storage space, or item content.</short>
<descr>
<p>
<var>ConsistencyCheck</var> is a procedure used to raise an exception when an error is detected in queue settings, its item storage space, or the content for item data. ConsistencyCheck raises an exception when the following conditions are detected:
</p>
<ul>
<li>Size contains a negative non-zero value.</li>
<li>MinimumBlockSize is larger than MaximumBlockSize.</li>
<li>MinimumBlockSize is less than sixteen (16) bytes.</li>
<li>Internal storage has not been assigned, but Size contains a non-zero value.</li>
<li>The item capacity is zero (0) or a negative value.</li>
<li>Internal index positions for Top and new items contain a negative value.</li>
<li>Internal index positions for Top and new items are larger than the capacity for the queue.</li>
</ul>
<remark>
<p>
<var>ConsistencyCheck</var> is <b>NOT</b> used in the current implementation.
</p>
</remark>
</descr>
<errors>
<p>
Raises an <var>Exception</var> when an error condition is found in the queue settings, its storage space, or the items in the queue. The exception message is: 'TDynamicDataQueue.ConsistencyCheck'.
</p>
</errors>
<seealso></seealso>
</element>
<!-- procedure Visibility: public -->
<element name="TDynamicDataQueue.WriteDebugReport">
<short>
Generates debugging information for the queue state and optional item data in the queue.
</short>
<descr></descr>
<seealso></seealso>
</element>
<element name="TDynamicDataQueue.WriteDebugReport.WriteData">
<short>Includes the contents of the item data when set to True.</short>
</element>
<!-- function Visibility: public -->
<element name="TDynamicDataQueue.Push">
<short>Adds the specified content to the FIFO queue.</short>
<descr>
<p>
<var>Push</var> is an overloaded <var>Integer</var> function used to add the specified item data to the bottom of the FIFO queue. Overloaded variants are provided to supply item data as a sequence of arbitrary byte values, either from an untyped buffer or from a <var>TStream</var> instance.
</p>
<remark>
Push assumes that <var>AStream</var> is already positioned at the start of the data for the new item. It does not reposition the stream instance.
</remark>
<p>
Push calls the <var>PushInternal</var> method to perform the actions needed to enqueue the specified item data.
</p>
<p>
The return value contains the number of bytes added for the new item data to the internal storage for the ring queue.
</p>
<p>
Use <var>Pop</var> to dequeue an item from the top of the queue. Use <var>Top</var> to get the item data for the next item without removing it from the queue. Use <var>Size</var> to get the number of bytes allocated for items in the internal storage in the FIFO queue.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.Pop"/>
<link id="TDynamicDataQueue.Top"/>
<link id="TDynamicDataQueue.Size"/>
</seealso>
</element>
<element name="TDynamicDataQueue.Push.Result">
<short>Number of bytes added to the internal queue storage in the method.</short>
</element>
<element name="TDynamicDataQueue.Push.Buffer">
<short>Untyped buffer with the arbitrary item data added in the method.</short>
</element>
<element name="TDynamicDataQueue.Push.Count">
<short>Number of bytes needed for the item data added in the method.</short>
</element>
<element name="TDynamicDataQueue.Push.AStream">
<short>TStream instance where the byte values for the item data is stored.</short>
</element>
<!-- function Visibility: public -->
<element name="TDynamicDataQueue.Pop">
<short>Removes an item from the top of the FIFO queue.</short>
<descr>
<p>
<var>Pop</var> is an overloaded <var>Integer</var> function used to remove an item from the top of the FIFO queue. Overloaded variants are provided to get item data and store them as a sequence of arbitrary byte values, either in an untyped buffer or in a <var>TStream</var> instance.
</p>
<remark>
Pop assumes that <var>AStream</var> is already positioned where the item data will be written. It does not reposition the stream instance. Be aware that writing to a stream can raise an exception.
</remark>
<p>
Pop calls the <var>PopTopInternal</var> method to perform the actions needed to get the data for the queue item, and to removed the entry from the top of FIFO queue.
</p>
<p>
The return value contains the number of bytes needed for the item data, and removed from the internal storage for the queue.
</p>
<p>
Use <var>Push</var> to enqueue a new item to the bottom of the FIFO queue. Use <var>Top</var> to get the item data at the top of the queue without removing it from the queue.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.Push"/>
<link id="TDynamicDataQueue.Top"/>
<link id="TDynamicDataQueue.Size"/>
</seealso>
</element>
<element name="TDynamicDataQueue.Pop.Result">
<short>Number of bytes needed for item data removed from the queue.</short>
</element>
<element name="TDynamicDataQueue.Pop.Buffer">
<short>Untyped buffer where the queue item is stored after removal.</short>
</element>
<element name="TDynamicDataQueue.Pop.Count">
<short>Number of bytes for the item data.</short>
</element>
<element name="TDynamicDataQueue.Pop.AStream">
<short>TStream instance where the item data removed from the queue is stored.</short>
</element>
<!-- function Visibility: public -->
<element name="TDynamicDataQueue.Top">
<short>
Gets the data for the first queue entry, but does not remove it from the queue.
</short>
<descr>
<p>
<var>Top</var> is an overloaded Integer function used to get the item data stored at the top of the FIFO queue without removing it from the queue internal storage. Overloaded variants are provided to get and store item data as a sequence of arbitrary byte values, either in an untyped buffer or in a <var>TStream</var> instance.
</p>
<p>
Please note: Top assumes that <var>AStream</var> is already positioned where the item data will be written. It does not reposition the stream instance. Be aware that writing to a stream can raise an exception.
</p>
<p>
Top calls the <var>PopTopInternal</var> method to perform the actions needed to get the data for the queue item from the top of FIFO queue.
</p>
<p>
The return value contains the number of bytes needed for the item data in the internal storage for the queue.
</p>
<p>
Use <var>Push</var> to enqueue a new item to the bottom of the FIFO queue. Use <var>Pop</var> to get and remove the item data at the top of the queue.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.Push"/>
<link id="TDynamicDataQueue.Pop"/>
<link id="TDynamicDataQueue.Size"/>
</seealso>
</element>
<element name="TDynamicDataQueue.Top.Result">
<short>Number of bytes needed for item data in the queue.</short>
</element>
<element name="TDynamicDataQueue.Top.Buffer">
<short>Untyped buffer where the queue item is stored.</short>
</element>
<element name="TDynamicDataQueue.Top.Count">
<short>Number of bytes for the item data.</short>
</element>
<element name="TDynamicDataQueue.Top.AStream">
<short>TStream instance where the item data is stored.</short>
</element>
<!-- property Visibility: public -->
<element name="TDynamicDataQueue.Size">
<short>Total memory required for item data stored in the queue.</short>
<descr>
<p>
<var>Size</var> is a read-only <var>Int64</var> property that contains the total memory required for item data stored in the queue. The value in Size in incremented in <var>PushInternal</var> when an item is successfully added to the ring queue storage. Conversely, the value in Size is decremented when the <var>PopTopInternal</var> method successfully removes an item from the storage for the ring queue.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.Push"/>
<link id="TDynamicDataQueue.Pop"/>
</seealso>
</element>
<!-- property Visibility: public -->
<element name="TDynamicDataQueue.MinimumBlockSize">
<short>
Indicates the smallest memory block size allocated for an item added to the queue.
</short>
<descr>
<p>
<var>MinimumBlockSize</var> is an <var>Integer</var> property which indicates the smallest memory block size allocated for an item added to the queue. MinimumBlockSize and <var>MaximumBlockSize</var> are used in the <var>CalculateItemSize</var> method to derive the actual block size allocated for a queue item and its arbitrary data.
</p>
<p>
The default value for MinimumBlockSize is <b>512</b>, as set in the <var>Create</var> constructor. MinimumBlockSize cannot be set to a value smaller than sixteen (<b>16</b>) bytes, or a value larger than MaximumBlockSize.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.MaximumBlockSize"/>
<link id="TDynamicDataQueue.Create"/>
</seealso>
</element>
<!-- property Visibility: public -->
<element name="TDynamicDataQueue.MaximumBlockSize">
<short>
Indicates the largest memory block size allocated for an item added to the queue.
</short>
<descr>
<p>
<var>MaximumBlockSize</var> is an <var>Integer</var> property which indicates the largest memory block size allocated for an item added to the queue. <var>MinimumBlockSize</var> and <var>MaximumBlockSize</var> are used in the <var>CalculateItemSize</var> method to derive the actual block size allocated for a queue item and its arbitrary data.
</p>
<p>
The default value for MaximumBlockSize is <b>4096</b>, as set in the <var>Create</var> constructor. MaximumBlockSize cannot be set to a value smaller than MinimumBlockSize.
</p>
</descr>
<seealso>
<link id="TDynamicDataQueue.MinimumBlockSize"/>
<link id="TDynamicDataQueue.Create"/>
</seealso>
</element>
</module>
<!-- DynQueue -->
</package>
</fpdoc-descriptions>
|
