ZBasic Language Reference
63
ZBasic Microcontrollers
data. For example, the producer could copy several Single data values to a queue and as long as the
consumer copies them out to Single variables all will be well.
Prior to using a queue it must be initialized by using the System Library routine OpenQueue(). An
example of this is shown below.
Dim myQueue(1 to 40)
Call OpenQueue(myQueue, SizeOf(myQueue))
This call prepares the queue for use by initializing the first 9 bytes of the specified array with queue
management data. The remainder of the array is used for the data to be held by the queue, in this case
the queue can hold up to 31 bytes of data since it was defined as being 40 bytes long. This implies that
the smallest array usable as a queue is 10 bytes. A pre-defined constant, System.MinQueueSize, can
be used in your programs to represent this minimum size.
Note the use of the SizeOf() function. Although the second parameter could just as well have been the
literal value 40, if you later changed the size of the myQueue array you’d have to also remember to
change the second parameter to match. If you made the queue larger, opening the queue with a smaller
value would have no ill effect other than wasting RAM. On the other hand, if you reduced the size of the
queue array but left the larger value as the second parameter, the data area inside the queue would
overlap adjacent variables leading to puzzling results. For this reason it is highly recommend to use
SizeOf() in this and other similar situations rather than hard-coded constants. An alternative method is to
use a defined constant as shown below.
Const myQueueSize as Integer = System.MinQueueSize + 30
Dim myQueue(1 to myQueueSize)
Call OpenQueue(myQueue, myQueueSize)
Either of these methods of improving the maintainability of your program is acceptable. Which you
choose is more of a stylistic issue than a technical one. The code generated by the compiler in the two
cases is identical.
There are several System Library routines available for adding data to and extracting data from a queue
as well as some querying functions for determining the status of the queue. Once initialized as shown
above, the code fragment below will place some data in the queue.
Dim punct(1 to 2) as Byte
punct(1) = &H2c
punct(2) = &H20
Call PutQueueStr(myQueue, "Hello") ' add a string
Call PutQueue(myQueue, punct, 2) ' add some individual bytes
Call PutQueueStr(myQueue, "world") ' add another string
Call PutQueueByte(myQueue, &H21) ' add an exclamation point
After the data is in the queue, the following code fragment will extract it and display it on the console.
Do While (StatusQueue(myQueue) ' add a string
Dim b as Byte
Call GetQueue(myQueue, b, 1) ' retrieve a byte from the queue
Debug.Print Chr(b);
Loop
Debug.Print
It is important to note that the queue insertion routines all wait until there is sufficient space available in
the queue for the data being inserted before inserting any data. This may lead to deadlock situations,
particularly if the size of the data being inserted is larger than the queue’s data area.
 |
 |
 |