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.

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.

Author:

gary

Constructor Summary

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

void	clear() Sets this to empty.
boolean	force(java.lang.Object object) Unconditionally insert object 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() A synchronized and possibly blocking operation on the queue.
int	size() Queries the queue to determine the number of elements in this.
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.

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)

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 Runnable/s 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.

Not currently implemented

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.

- HREF="MemoryScopeException.html"> 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.

- HREF="InaccessibleAreaException.html"> 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.

Not currently implemented

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.

WaitFreeWriteQueue

public WaitFreeWriteQueue(int maximum)

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

Not currently implemented

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.

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

isFull

public boolean isFull()

A synchronized and possibly blocking operation on the queue.

Not currently implemented

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.

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.

Not currently implemented

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

Not currently implemented

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:

- HREF="MemoryScopeException.html"> 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:

- HREF="MemoryScopeException.html"> 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.