E.2 Atomic Queues

Atomic queues are DECthreads Library objects that you can use to communicate information among threads or among routines in a single thread.

Note

Atomic queues are documented in Appendix F, the DECthreads Library reference section. The queue routines begin with the cma_lib_ prefix; they are not included with the pthread interface.

Operations on queues are atomic because any operation on the queue is guaranteed to complete before any other operation on that same queue can begin. Queue operations are not interruptable.

An atomic queue contains preallocated queue items. Each element (an integer identifier or a pointer to a block of data) inserted into the queue consumes a queue item. The number of elements allowed on the queue is called the queue size. The queuesize attribute can be specified by calling the cma_lib_attr_set_queuesize routine. The default is 128 queue items.

You can insert an element at the end of a queue by calling cma_lib_ queue_ enqueue or at the front of a queue by calling cma_lib_queue_requeue. You can remove an element from a queue by calling cma_lib_queue_ dequeue. In each of these routines, if the element cannot be inserted or removed because the queue is full or empty, the calling thread is blocked until the action can be performed.

If you want to insert or remove an element but return with a status value if the queue is full or empty rather than cause the thread to wait, you can call the cma_lib_queue_try_enqueue, cma_lib_ queue_try_requeue, or cma_lib_queue_try_dequeue routines. These routines return a Boolean value indicating whether or not the routine succeeded.

The cma_lib_queue_try_enqueue_int routine works exactly like cma_ lib_queue_try_enqueue except that it can be called from an interrupt handler. Only routines with an _int suffix can be called from interrupt routines.