Queue Class

A Queue object provides a very easy way to pass objects between threads within Carapace scripts. Access to a Queue is protected by a lock, so that only one thread at a time can put values onto the queue or can remove them from the queue.

A very common use of a Queue is to have a single thread which receives new communication connections and which puts them onto the queue. Multiple other threads then wait on the queue and remove them from the queue as appropriate.

Queue Creation

The create function can be used to create a Queue object eg.

    (create Queue)

• have objects put onto it
• have other threads wait for objects to appear on it
• have other threads get objects from it

Queue Properties

A Queue object supports the following properties:

Queue Methods

A Queue object supports the following methods:

put

Put an item onto the queue. Note that any type of object can be put onto a Queue.

Arguments:

Return type: the empty List () is returned.

wait

Wait for an item to arrive on the queue -- this does not affect the items on the queue. The supplied no. of milliseconds is supplied.

Note that waiting for an item to be queued does not guarantee that it will still be there when you come to get it, since another thread may have de-queued it in the mean time.

Arguments:

Return type: if an item is queued in time, the Symbol true is returned, otherwise the empty List () is returned.

get

Get an item queue -- this may not succeed, since some other thread may already have consumed the entire contents of the queue.

If no value is successfully de-queued, the empty List () is returned. If, on the other hand, a value is de-queued, this value is first wrapped in a List and it is this single-length list which is returned.

This allows the caller to distinguish between 'nothing received' -- which returns the empty list () -- and something successfully received. The function headOf can be used to extract the item from its enclosing list.

This method can be called with no arguments -- meaning 'get an item from the queue if one exists but don't wait' or with a timeout (milliseconds) for waiting.

Arguments:

Return type: a List containing the received item -- may be empty!