javax.realtime
Class WaitFreeDequeue

java.lang.Object
  javax.realtime.WaitFreeDequeue

public class WaitFreeDequeue
extends java.lang.Object

A WaitFreeDequeue encapsulates a WaitFreeWriteQueue and a WaitFreeReadQueue. Each method on a WaitFreeDequeue corresponds to an equivalent operation on the underlying WaitFreeWriteQueue or WaitFreeReadQueue.

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.

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

WaitFreeDequeue

public WaitFreeDequeue(java.lang.Runnable writer,
                       java.lang.Runnable reader,
                       int maximum,
                       MemoryArea memory)

Deprecated. 1.0.1 Use WaitFreeReadQueue and WaitFreeWriteQueue.

Constructs a queue, in memory, with an underlying WaitFreeWriteQueue and WaitFreeReadQueue, each of size maximum.

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 queue; moreover, there is no check that they actually access the queue at all.

Note: that the wait free queues' internal queues are allocated in memory, but the memory area of the wait free dequeue instance itself is determined by the current allocation context.

Parameters:

writer - An instance of Runnable or null.

reader - An instance of Runnable or null.

maximum - Then maximum number of elements in the both the WaitFreeReadQueue and the WaitFreeWriteQueue.

memory - The MemoryArea in which internal elements are allocated.

Throws:

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.

java.lang.IllegalArgumentException - 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.

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

nonBlockingRead

public java.lang.Object nonBlockingRead()

Deprecated. 1.0.1 Use WaitFreeReadQueue and WaitFreeWriteQueue.

An unsynchronized call of the read() method of the underlying WaitFreeReadQueue.

Returns:

A java.lang.Object object read from this. If there are no elements in this then null is returned.

blockingWrite

public void blockingWrite(java.lang.Object object)
                   throws java.lang.InterruptedException

Deprecated. 1.0.1 Use WaitFreeReadQueue and WaitFreeWriteQueue.

A synchronized call of the write() method of the underlying WaitFreeReadQueue. This call blocks on queue full and waits until there is space in this.

Parameters:

object - The java.lang.Object to place in this.

Throws:

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

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 Return type changed from boolean to void because this method always returned true, and added InterruptedException.

nonBlockingWrite

public boolean nonBlockingWrite(java.lang.Object object)

Deprecated. 1.0.1 Use WaitFreeReadQueue and WaitFreeWriteQueue.

An unsynchronized call of the write() method of the underlying WaitFreeWriteQueue. This call does not block on queue full.

Parameters:

object - The Object to attempt to place in this.

Returns:

true if object was inserted (i.e., the queue was not full), false otherwise.

Throws:

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

blockingRead

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

Deprecated. 1.0.1 Use WaitFreeReadQueue and WaitFreeWriteQueue.

A synchronized call of the read() method of the underlying WaitFreeWriteQueue. This call blocks on queue empty and will wait until there is an element in the queue to return.

Returns:

The java.lang.Object read.

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 Added throws InterruptedException.

force

public boolean force(java.lang.Object object)

Deprecated. 1.0.1 Use WaitFreeReadQueue and WaitFreeWriteQueue.

If this's underlying WaitFreeWriteQueue is full, then overwrite with object the most recently inserted element. Otherwise this call is equivalent to nonBlockingWrite().

Parameters:

object - The object to be written.

Returns:

true if an element was overwritten; false if there as an empty element into which the write occurred.

Throws:

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