javax.realtime

Class WaitFreeWriteQueue<T>

java.lang.Object

javax.realtime.WaitFreeWriteQueue<T>

public class WaitFreeWriteQueue<T>
extends Object

Jamaica Real-Time Specification for Java class WaitFreeWriteQueue.

This class permits a thread to write to one or more other threads without being blocked by the other threads. This is required in RTSJ implementations that do not have real-time garbage collection to permit communication between NoHeapRealtimeThreads and normal Threads or RealtimeThreads to avoid the potential priority inversion problem of the NoHeapRealtimeThread being blocked waiting for another thread that itself if blocked by garbage collection activity.

In the JamaicaVM implementation, a thread that does not perform memory allocation is never blocked by the garbage collector unless it was preempted by a higher priority thread that performs memory allocation. In conjunction with the priority inversion avoidance mechanisms provided for monitors in the RTSJ (priority inheritance and priority ceiling emulation), this priority-inversion situation cannot occur in JamaicaVM, and normal protection using monitors is sufficient for the communication between NoHeapRealtimeThreads and normal Java threads. This class is consequently provided only for compatibility with other RTSJ implementations that do not provide realtime garbage collection.

Constructor Summary

Constructors

Constructor and Description
WaitFreeWriteQueue(int maximum) Constructor to construct a non-blocking write queue in immortal memory.
WaitFreeWriteQueue(int maximum, MemoryArea memory) Constructor to construct a non-blocking write queue in given memory area.
WaitFreeWriteQueue(Runnable writer, Runnable reader, int maximum, MemoryArea memory) Constructor to construct a non-blocking write queue in given memory area.

Method Summary

Modifier and Type	Method and Description
void	clear() clear clears this queue.
boolean	force(T object) force writes object into the queue even if the queue is full.
boolean	isEmpty() isEmpty checks if the queue is currently empty.
boolean	isFull() isFull checks if the queue is currently full.
T	read() read reads one element from the queue.
int	size() size returns the current size of the queue, i.e., the number of elements that have been written but not yet read.
boolean	write(T object) write writes an element to the queue.

Methods inherited from class java.lang.Object

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

Constructor Detail

WaitFreeWriteQueue

public WaitFreeWriteQueue(int maximum)
                   throws StaticIllegalArgumentException

Constructor to construct a non-blocking write queue in immortal memory.

Throws:

StaticIllegalArgumentException - if maximum <= 0.

Parameters:

maximum - capacity of this queue

Since:

RTSJ V1.0.1

WaitFreeWriteQueue

public WaitFreeWriteQueue(int maximum,
                          MemoryArea memory)
                   throws StaticIllegalArgumentException

Constructor to construct a non-blocking write queue in given memory area.

Throws:

StaticIllegalArgumentException - if maximum <= 0 or memory is null.

Parameters:

maximum - capacity of this queue

memory - The memory area in which internal elements are allocated.

Since:

RTSJ V1.0.1

WaitFreeWriteQueue

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

Constructor to construct a non-blocking write queue in given memory area.

Throws:

StaticIllegalArgumentException - if maximum <= 0 or writer or reader are not referring to a Thread or a Schedulable object.

MemoryScopeException - if writer or reader is non-null and in a memory area that is not assignment compatible with memory.

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

Parameters:

writer - A thread or schedulable object that may write to this queue or null

reader - A thread or schedulable object that may read from this queue or null.

maximum - capacity of this queue

memory - The memory area in which internal elements are allocated, or null.

Method Detail

clear

public void clear()

clear clears this queue. This may not be called concurrently with reads or write since it does not synchronize.

isEmpty

public boolean isEmpty()

isEmpty checks if the queue is currently empty. Note that the result may no longer be valid if a concurrent call to read() or write() is performed.

Returns:

true iff the queue is empty.

isFull

public boolean isFull()

isFull checks if the queue is currently full. Note that the result may no longer be valid if a concurrent call to read() or write() is performed.

Returns:

true iff the queue is full.

read

public T read()
       throws InterruptedException

read reads one element from the queue. If the queue is empty, this call blocks until an element is written to the queue that can be read.

Throws:

InterruptedException - if the wait is interrupted.

Returns:

the read element.

Since:

RTSJ V1.0.1 added throws InterruptedException.

size

public int size()

size returns the current size of the queue, i.e., the number of elements that have been written but not yet read. Note that the result may no longer be valid if a concurrent call to read() or write() is performed.

Returns:

The current size of the queue.

force

public boolean force(T object)
              throws MemoryScopeException

force writes object into the queue even if the queue is full. If the queue is not full, this is equivalent to write(). If the queue is full, this will try to replace the last entry.

Throws:

StaticIllegalArgumentException - when object is null

MemoryScopeException

Parameters:

object - The object to be put in the queue.

Returns:

true if the last element was overwritten, false if this performed a normal write that did not overwrite any other element.

write

public boolean write(T object)

write writes an element to the queue. If the queue is full, the element will not be written to the queue. If the queue is empty and any other thread is blocked doing a read() on this queue, the highest priority waiting thread will be unblocked to read this element.

Throws:

StaticIllegalArgumentException - when object is null

Parameters:

object - The object to be put in the queue.