javax.realtime
Class WaitFreeWriteQueue

java.lang.Object
  javax.realtime.WaitFreeWriteQueue

public class WaitFreeWriteQueue
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 of NoHeapRealtimeThread, and the readers are generally regular Java threads or heap-using real-time threads or schedulable objects. 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 schedulable objects are permitted, but if 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 allowing NoHeapRealtimeThreads and regular Java threads to synchronize on an object without the risk of a NoHeapRealtimeThread incurring Garbage Collector latency due to priority inversion avoidance management.

• 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.

WaitFreeWriteQueue

public 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.

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

reader and writer are not necessarily the only threads or schedulable objects that will access the queues; 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 Thread, a schedulable object, or null.

reader - An instance of Thread, a schedulable object, or null.

maximum - The maximum number of elements in the queue.

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

Throws:

java.lang.IllegalArgumentException - Thrown if an argument holds an invalid value. The writer argument must be null, a reference to a Thread, or a reference to a schedulable object (a RealtimeThread, or an AsyncEventHandler.) The reader argument must be null, a reference to a Thread, or a reference to a schedulable object. The maximum argument must be greater than zero.

MemoryScopeException - Thrown if 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 - Thrown if memory is a scoped memory that is not on the caller's scope stack.

WaitFreeWriteQueue

public WaitFreeWriteQueue(int maximum,
                          MemoryArea memory)

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.

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:

maximum - The maximum number of elements in the queue.

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

Throws:

java.lang.IllegalArgumentException - Thrown if the maximum argument is less than or equal to zero, or memory is null.

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

Since:

1.0.1

WaitFreeWriteQueue

public WaitFreeWriteQueue(int maximum)

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.

Parameters:

maximum - The maximum number of elements in the queue.

Throws:

java.lang.IllegalArgumentException - Thrown if the maximum argument is less than or equal to zero.

Since:

1.0.1

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, if this is empty. False, if 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, if this is full. False, if this is not full.

read

public java.lang.Object read()
                      throws java.lang.InterruptedException

A synchronized and possibly blocking operation on the queue.

Returns:

The Object least recently written to the queue. If this is empty, the calling thread or schedulable objects blocks until an element is inserted; when it is resumed, read removes and returns the element.

Throws:

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

Since:

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(java.lang.Object object)

Unconditionally insert object 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 object was inserted was vacant (false) or occupied (true).

Parameters:

object - A non-null java.lang.Object to insert.

Returns:

true if object 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 - Thrown if a memory access error or illegal assignment error would occur while storing object in the queue.

java.lang.IllegalArgumentException - Thrown if object is null.

write

public boolean write(java.lang.Object object)

Inserts object into this if this is non-full and otherwise has no effect on this; the boolean result reflects whether object has been inserted. If the queue was empty and one or more threads or schedulable objects 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:

object - A non-null java.lang.Object to insert.

Returns:

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

Throws:

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

java.lang.IllegalArgumentException - Thrown if object is null.