javax.realtime

Class WaitFreeReadQueue<T>

java.lang.Object

javax.realtime.WaitFreeReadQueue<T>

Type Parameters:

T - the type of the object in this queue

public class WaitFreeReadQueue<T>
extends java.lang.Object

A queue that can be non-blocking for consumers. The WaitFreeReadQueue class is intended for single-reader multiple-writer communication, although it may also be used (with care) for multiple readers. A reader is generally an instance of Schedulable which may not use the heap, and the writers are generally regular Java threads or heap-using instances of Schedulable. Communication is through a bounded buffer of Objects that is managed first-in-first-out. The principal methods for this class are write and read.

• The write method appends a new element onto the queue. It is synchronized, and blocks when the queue is full. It may be called by more than one writer, in which case, the different callers will write to different elements of the queue.
• The read method removes the oldest element from the queue. It is not synchronized and does not block; it will return null when the queue is empty. Multiple reader threads or schedulables are permitted, but when two or more intend to read from the same WaitFreeWriteQueue they will need to arrange explicit synchronization.

For convenience, and to avoid requiring a reader to poll until the queue is non-empty, this class also supports instances that can be accessed by a reader that blocks on queue empty. To obtain this behavior, the reader needs to invoke the waitForData() method on a queue that has been constructed with a notify parameter set to true.

WaitFreeReadQueue is one of the classes enabling instances of Schedulable that may not use the heap and conventional Java threads to synchronize on an object without the risk of that Schedulable instance incurring Garbage Collector latency due to priority inversion avoidance management.

Incompatibility with V1.0: Three exceptions previously thrown by the constructor have been deleted. These are

• java.lang.IllegalAccessException,
• java.lang.ClassNotFoundException, and
• java.lang.InstantiationException.

These exceptions were in error. Their deletion may cause compile-time errors in code using the previous constructor. The repair is to remove the exceptions from the catch clause around the constructor invocation.

Constructor Summary

Constructors

Constructor and Description
WaitFreeReadQueue(int maximum, boolean notify) Constructs a queue containing up to maximum elements in immortal memory.
WaitFreeReadQueue(int maximum, MemoryArea memory, boolean notify) Constructs a queue containing up to maximum elements in memory.
WaitFreeReadQueue(java.lang.Runnable writer, java.lang.Runnable reader, int maximum, MemoryArea memory) Constructs a queue containing up to maximum elements in memory.
WaitFreeReadQueue(java.lang.Runnable writer, java.lang.Runnable reader, int maximum, MemoryArea memory, boolean notify) Constructs a queue containing up to maximum elements in memory.

Method Summary

Modifier and Type	Method and Description
void	clear() Sets this to empty.
boolean	isEmpty() Queries the queue to determine if this is empty.
boolean	isFull() Queries the system to determine if this is full.
T	read() Reads the least recently inserted element from the queue and returns it as the result, unless the queue is empty.
int	size() Queries the queue to determine the number of elements in this.
void	waitForData() When this is empty block until a writer inserts an element.
void	write(T value) A synchronized and blocking write.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WaitFreeReadQueue

public WaitFreeReadQueue(java.lang.Runnable writer,
                         java.lang.Runnable reader,
                         int maximum,
                         MemoryArea memory,
                         boolean notify)
                  throws StaticIllegalArgumentException,
                         MemoryScopeException,
                         InaccessibleAreaException

Constructs a queue containing up to maximum elements in memory. The queue has an unsynchronized and nonblocking read() method and a synchronized and blocking write() method.

The writer and reader parameters, when non-null, are checked to insure that they are compatible with the MemoryArea specified by memory (when non-null.) When memory is null and both Runnables are non-null, the constructor will select the nearest common scoped parent memory area, or when there is no such scope it will use immortal memory. When all three parameters are null, the queue will be allocated in immortal memory.

reader and writer are not necessarily the only instances of Schedule that will access the queue; moreover, there is no check that they actually access the queue at all.

Note that the wait free queue's internal queue is allocated in memory, but the memory area of the wait free queue instance itself is determined by the current allocation context.

Parameters:

writer - An instance of Runnable or null.

reader - An instance of Runnable or null.

maximum - The maximum number of elements in the queue.

memory - The MemoryArea in which internal elements are allocated.

notify - A flag that establishes whether a reader is notified when the queue becomes non-empty.

Throws:

StaticIllegalArgumentException - when an argument holds an invalid value. The writer argument must be null, a reference to a Thread, or a reference to a schedulable (a RealtimeThread, or an AsyncEventHandler.) The reader argument must be null, a reference to a Thread, or a reference to a schedulable. The maximum argument must be greater than zero.

InaccessibleAreaException - when memory is a scoped memory that is not on the caller's scope stack.

MemoryScopeException - when either reader or writer is non-null and the memory argument is not compatible with reader and writer with respect to the assignment and access rules for memory areas.

WaitFreeReadQueue

public WaitFreeReadQueue(java.lang.Runnable writer,
                         java.lang.Runnable reader,
                         int maximum,
                         MemoryArea memory)
                  throws StaticIllegalArgumentException,
                         MemoryScopeException,
                         InaccessibleAreaException

Constructs a queue containing up to maximum elements in memory. The queue has an unsynchronized and nonblocking read() method and a synchronized and blocking write() method.

Equivalent to WaitFreeReadQueue(writer, reader, maximum, memory, false)

Throws:

StaticIllegalArgumentException

MemoryScopeException

InaccessibleAreaException

WaitFreeReadQueue

public WaitFreeReadQueue(int maximum,
                         MemoryArea memory,
                         boolean notify)
                  throws StaticIllegalArgumentException,
                         InaccessibleAreaException

Constructs a queue containing up to maximum elements in memory. The queue has an unsynchronized and nonblocking read() method and a synchronized and blocking write() method.

Equivalent to WaitFreeReadQueue(null, null, maximum, memory, notify)

Throws:

StaticIllegalArgumentException

InaccessibleAreaException

Since:

RTSJ 1.0.1

WaitFreeReadQueue

public WaitFreeReadQueue(int maximum,
                         boolean notify)
                  throws StaticIllegalArgumentException

Constructs a queue containing up to maximum elements in immortal memory. The queue has an unsynchronized and nonblocking read() method and a synchronized and blocking write() method.

Equivalent to WaitFreeReadQueue(null, null, maximum, null, notify)

Throws:

StaticIllegalArgumentException

Since:

RTSJ 1.0.1

Method Detail

clear

public void clear()

Sets this to empty.

Note, this method needs to be used with care. Invoking clear concurrently with read or write can lead to unexpected results.

isEmpty

public boolean isEmpty()

Queries the queue to determine if this is empty.

Note: This method needs to be used with care since the state of the queue may change while the method is in progress or after it has returned.

Returns:

true when this is empty; false when this is not empty.

isFull

public boolean isFull()

Queries the system to determine if this is full.

Note: This method needs to be used with care since the state of the queue may change while the method is in progress or after it has returned.

Returns:

true when this is full; false when this is not full.

read

public T read()

Reads the least recently inserted element from the queue and returns it as the result, unless the queue is empty. When the queue is empty, null is returned.

Returns:

the instance of T read, or else null when this is empty.

size

public int size()

Queries the queue to determine the number of elements in this.

Note: This method needs to be used with care since the state of the queue may change while the method is in progress or after it has returned.

Returns:

the number of positions in this occupied by elements that have been written but not yet read.

waitForData

public void waitForData()
                 throws StaticUnsupportedOperationException,
                        java.lang.InterruptedException

When this is empty block until a writer inserts an element.

Note: When there is a single reader and no asynchronous invocation of clear, then it is safe to invoke read after waitForData and know that read will find the queue non-empty.

Implementation note, to avoid reader and writer synchronizing on the same object, the reader should not be notified directly by a writer. (This is the issue that the non-wait queue classes are intended to solve).

Throws:

StaticUnsupportedOperationException - when this has not been constructed with notify set to true.

java.lang.InterruptedException - when the thread is interrupted by interrupt() or AsynchronouslyInterruptedException.fire() during the time between calling this method and returning from it.

Since:

RTSJ 1.0.1 InterruptedException was added to the throws clause.

write

public void write(T value)
           throws MemoryScopeException,
                  java.lang.InterruptedException

A synchronized and blocking write. This call blocks on queue full and will wait until there is space in the queue.

Parameters:

value - The java.lang.Object that is placed in the queue.

Throws:

java.lang.InterruptedException - when the thread is interrupted by interrupt() or AsynchronouslyInterruptedException.fire() during the time between calling this method and returning from it.

MemoryScopeException - when a memory access error or illegal assignment error would occur while storing object in the queue.

StaticIllegalArgumentException - when value is null.

Since:

RTSJ 1.0.1 The return type is changed to void since it always returned` true, and InterruptedException was added to the throws clause.