javax.realtime
Class WaitFreeWriteQueue

java.lang.Object
  javax.realtime.WaitFreeWriteQueue

public class WaitFreeWriteQueue
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 real-time garbage collection.

Constructor Summary

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

void	clear() clear clears this queue.
boolean	force(Object 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.
Object	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(Object 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 IllegalArgumentException

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

Parameters:

maximum - capacity of this queue

Throws:

IllegalArgumentException - if maximum <= 0.

Since:

RTSJ V1.0.1

WaitFreeWriteQueue

public WaitFreeWriteQueue(int maximum,
                          MemoryArea memory)
                   throws IllegalArgumentException

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

Parameters:

maximum - capacity of this queue

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

Throws:

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

Since:

RTSJ V1.0.1

WaitFreeWriteQueue

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

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

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.

Throws:

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

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

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

Returns:

the read element.

Throws:

InterruptedException - if the wait is interrupted.

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(Object 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.

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.

Throws:

MemoryScopeException

write

public boolean write(Object 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.

Parameters:

object - The object to be put in the queue.