|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.realtime.WaitFreeWriteQueue
public class WaitFreeWriteQueue
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
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.
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.
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()
Queries the system to determine if this is full. |
java.lang.Object |
read()
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 |
---|
public WaitFreeWriteQueue(java.lang.Runnable writer, java.lang.Runnable reader, int maximum, MemoryArea memory)
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 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 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.
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.
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.
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.
InnaccessibleAreaException
- Thrown if memory is a scoped
memory that is not on the caller's scope stack.
Checks on reader
and writer
are not
clearly defined in the specification. Mackinac ensures that the
writer cannot produce objects that are not storable in the
internal queue if it remains in the memory area declared while
constructing the writer. For the reader, we are only concerned
by the read check. Hence, a problem is reported only if the
area is the Heap and if the reader is an NHRT or a noheap
AsyncEventHandler.
public WaitFreeWriteQueue(int maximum, MemoryArea memory)
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.
maximum
- The maximum number of elements in the queue.memory
- The MemoryArea
in which this object and internal elements are
allocated.
java.lang.IllegalArgumentException
- Thrown if
the maximum
argument is less than or equal to zero,
or memory
is null.public WaitFreeWriteQueue(int maximum)
maximum
elements in immortal memory. The queue has an unsynchronized and
nonblocking write()
method and a
synchronized and blocking read()
method.
maximum
- The maximum number of elements in the queue.
java.lang.IllegalArgumentException
- Thrown if
the maximum
argument is less than or equal to zero.Method Detail |
---|
public void clear()
this
to empty.
public boolean isEmpty()
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.
this
is empty.
False, if this
is not empty.public boolean isFull()
this
is full.
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.
this
is full.
False, if this
is not full.public java.lang.Object read() throws java.lang.InterruptedException
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.
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.InterruptedException
public int size()
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.
this
occupied by
elements that have been written but not yet read.public boolean force(java.lang.Object object)
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
).
object
- A non-null java.lang.Object
to insert.
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)
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.public boolean write(java.lang.Object object)
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).
object
- A non-null java.lang.Object
to insert.
true
if the queue was non-full;
false
otherwise.
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.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |