javax.realtime

Class WaitFreeWriteQueue<T>

java.lang.Object

javax.realtime.WaitFreeWriteQueue<T>

Type Parameters:

T - is the type of the object in this queue

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

A queue that can be non-blocking for producers. The WaitFreeWriteQueue class is intended for single-writer multiple-reader communication, although it may also be used (with care) for multiple writers. A writer is generally an instance Schedulable which may not use the heap, and the readers are generally conventional Java threads or instances of Schedulable which use the heap. 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 not synchronized, and does not block when the queue is full (it returns false instead). Multiple writer threads or schedulables are permitted, but when two or more threads intend to write to the same WaitFreeWriteQueue they will need to arrange explicit synchronization.
• The read method removes the oldest element from the queue. It is synchronized, and will block when the queue is empty. It may be called by more than one reader, in which case the different callers will read different elements from the queue.

WaitFreeWriteQueue is one of the classes enabling schedulables which may not use the heap and regular Java threads to synchronize on an object without the risk of the schedulable incurring Garbage Collector latency due to priority inversion avoidance management.

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

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

Including these exceptions on the throws clause was an 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
WaitFreeWriteQueue(int maximum) Constructs a queue containing up to maximum elements in immortal memory.
WaitFreeWriteQueue(int maximum, MemoryArea memory) Constructs a queue containing up to maximum elements in memory.
WaitFreeWriteQueue(java.lang.Runnable writer, java.lang.Runnable reader, int maximum, MemoryArea memory) Constructs a queue in memory with an unsynchronized and nonblocking write() method and a synchronized and blocking read() method.

Method Summary

Modifier and Type	Method and Description
void	clear() Sets this to empty.
boolean	force(T value) Unconditionally inserts value into this, either in a vacant position or else overwriting the most recently inserted element.
boolean	isEmpty() Queries the system to determine if this is empty.
boolean	isFull() Queries the system to determine if this is full.
T	read() A synchronized and possibly blocking operation on the queue.
int	size() Queries the queue to determine the number of elements in this.
boolean	write(T value) Inserts value into this when this is non-full and otherwise has no effect on this; the boolean result reflects whether value has been inserted.

Methods inherited from class java.lang.Object

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

Constructor Detail

WaitFreeWriteQueue

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

Constructs a queue in memory with an unsynchronized and nonblocking write() method and a synchronized and blocking read() 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 threads or schedulables that will access the queues; moreover, there is no check that they actually access the queue at all.

Note, 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 Schedulable or null.

reader - An instance of Schedulable or null.

maximum - The maximum number of elements in the queue.

memory - The MemoryArea in which this and internal elements are allocated.

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.

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.

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

WaitFreeWriteQueue

public WaitFreeWriteQueue(int maximum,
                          MemoryArea memory)
                   throws StaticIllegalArgumentException,
                          InaccessibleAreaException

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

Equivalent to WaitFreeWriteQueue(null,null,maximum, memory)

Throws:

StaticIllegalArgumentException

InaccessibleAreaException

Since:

RTSJ 1.0.1

WaitFreeWriteQueue

public WaitFreeWriteQueue(int maximum)
                   throws StaticIllegalArgumentException

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

Equivalent to WaitFreeWriteQueue(null,null,mximum, null)

Throws:

StaticIllegalArgumentException

Since:

RTSJ 1.0.1

Method Detail

clear

public void clear()

Sets this to empty.

isEmpty

public boolean isEmpty()

Queries the system 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()
       throws java.lang.InterruptedException

A synchronized and possibly blocking operation on the queue.

Returns:

the T least recently written to the queue. When this is empty, the calling schedulable blocks until an element is inserted; when it is resumed, read removes and returns the element.

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.

Since:

RTSJ 1.0.1 Throws InterruptedException

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.

force

public boolean force(T value)
              throws MemoryScopeException,
                     StaticIllegalArgumentException

Unconditionally inserts value into this, either in a vacant position or else overwriting the most recently inserted element. The boolean result reflects whether, at the time that force() returns, the position at which value was inserted was vacant (false) or occupied (true).

Parameters:

value - An instance of T to insert.

Returns:

true when value has overwritten an element that was occupied when the function returns; false otherwise (it has been inserted into a position that was vacant when the function returns)

Throws:

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

StaticIllegalArgumentException - when value is null.

write

public boolean write(T value)
              throws MemoryScopeException,
                     StaticIllegalArgumentException

Inserts value into this when this is non-full and otherwise has no effect on this; the boolean result reflects whether value has been inserted. When the queue was empty and one or more threads or schedulables were waiting to read, then one will be awakened after the write. The choice of which to awaken depends on the involved scheduler(s).

Parameters:

value - An instance of T to insert.

Returns:

true when the queue was non-full; false otherwise.

Throws:

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

StaticIllegalArgumentException - when value is null.