javax.realtime
Class WaitFreeReadQueue

java.lang.Object
  javax.realtime.WaitFreeReadQueue

public class WaitFreeReadQueue
extends Object

Jamaica Real-Time Specification for Java class WaitFreeReadQueue.

This class permits a thread to read from 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

WaitFreeReadQueue(int maximum, boolean notify)
Constructor to construct a queue in immortal memory.

WaitFreeReadQueue(int maximum, MemoryArea memory, boolean notify)
Constructor to construct a queue in given memory area.

WaitFreeReadQueue(Runnable writer, Runnable reader, int maximum, MemoryArea memory)
Constructor to construct a non-blocking read queue in given memory area.

WaitFreeReadQueue(Runnable writer, Runnable reader, int maximum, MemoryArea memory, boolean notify)
Constructor to construct a non-blocking read queue in given memory area.

Method Summary

void	clear() clear clears this queue.
boolean	isEmpty() isEmpty checks if the queue is currently empty.
boolean	isFull() isFull checks if the queue is currently full.
Object	read() read reads the oldest 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.
void	waitForData() waitForData blocks until this queue is non-empty.
void	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

WaitFreeReadQueue

public WaitFreeReadQueue(int maximum,
                         boolean notify)
                  throws IllegalArgumentException

Constructor to construct a queue in immortal memory.

Parameters:

maximum - capacity of this queue

notify - true to allow for blocking reads, i.e., notification when an element is added to an empty queue.

Throws:

IllegalArgumentException - if maximum <= 0.

Since:

RTSJ V1.0.1

WaitFreeReadQueue

public WaitFreeReadQueue(int maximum,
                         MemoryArea memory,
                         boolean notify)
                  throws IllegalArgumentException

Constructor to construct a queue in given memory area.

Parameters:

maximum - capacity of this queue

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

notify - true to allow for blocking reads, i.e., notification when an element is added to an empty queue.

Throws:

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

Since:

RTSJ V1.0.1

WaitFreeReadQueue

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

Constructor to construct a non-blocking read 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.

WaitFreeReadQueue

public WaitFreeReadQueue(Runnable writer,
                         Runnable reader,
                         int maximum,
                         MemoryArea memory,
                         boolean notify)
                  throws IllegalArgumentException,
                         MemoryScopeException

Constructor to construct a non-blocking read 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.

notify - true to allow for blocking reads, i.e., notification when an element is added to an empty queue.

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 read 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()

read reads the oldest element from the queue.

Returns:

the read element, or null if the queue is empty.

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.

waitForData

public void waitForData()
                 throws InterruptedException,
                        UnsupportedOperationException

waitForData blocks until this queue is non-empty. Returns immediately if the queue already is non-empty.

Throws:

InterruptedException - if the wait is interrupted.

UnsupportedOperationException - if this queue was constructed with notify== false;

Since:

RTSJ V1.0.1 added throws InterruptedException.

write

public void write(Object object)
           throws InterruptedException

write writes an element to the queue. This routine synchronizes and blocks if the queue is full to wait until an element has been removed such that the write can proceed.

Parameters:

object - The object to be put in the queue.

Throws:

InterruptedException - if the wait is interrupted.

Since:

RTSJ V1.0.1 added throws InterruptedException.