T
- is the type of the object in this queuepublic class WaitFreeWriteQueue<T>
extends java.lang.Object
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 Schedulable
which may not use the heap, and the
readers are generally conventional Java threads or instances
of Schedulable
which use the heap. 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
schedulables are permitted, but when 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 enabling
schedulables which may not use the heap and regular Java threads to
synchronize on an object without the risk of the schedulable
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 and Description |
---|
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. |
Modifier and Type | Method and Description |
---|---|
void |
clear()
Sets
this to empty. |
boolean |
force(T value)
Unconditionally inserts
value 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. |
T |
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(T value)
Inserts
value into this when
this is non-full and otherwise has no effect on
this ; the boolean result reflects whether
value has been inserted. |
public WaitFreeWriteQueue(java.lang.Runnable writer, java.lang.Runnable reader, int maximum, MemoryArea memory) throws StaticIllegalArgumentException, MemoryScopeException, InaccessibleAreaException
memory
with an unsynchronized and
nonblocking write()
method and a
synchronized and blocking read()
method.
The writer
and reader
parameters, when non-null,
are checked to insure that they are compatible with the
MemoryArea
specified by memory
(when
non-null.) When memory
is null
and both
Runnables are non-null, the constructor will select the nearest
common scoped parent memory area, or when there is no such scope it
will use immortal memory. When all three parameters are
null
, the queue will be allocated in immortal memory.
reader
and writer
are not necessarily the only threads or
schedulables that will access the queues; moreover,
there is no check that they actually access the queue at all.
Note, 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 Schedulable
or null
.reader
- An instance of Schedulable
or null
.maximum
- The maximum number of elements in the queue.memory
- The MemoryArea
in which this
and
internal elements are allocated.StaticIllegalArgumentException
- when an argument holds an
invalid value. The writer
argument must be
null
, a reference to a Thread
,
or a reference to a schedulable (a
RealtimeThread
, or an
AsyncEventHandler
.) The reader
argument must be null
, a reference to
a Thread
, or a reference to a schedulable.
The maximum
argument must be greater than zero.MemoryScopeException
- when
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.InaccessibleAreaException
- when memory
is a scoped memory that is not on the caller's
scope stack.public WaitFreeWriteQueue(int maximum, MemoryArea memory) throws StaticIllegalArgumentException, InaccessibleAreaException
maximum
elements in memory
. The queue has an unsynchronized and
nonblocking write()
method and a
synchronized and blocking read()
method.
Equivalent to
WaitFreeWriteQueue(null,null,maximum, memory)
StaticIllegalArgumentException
InaccessibleAreaException
public WaitFreeWriteQueue(int maximum) throws StaticIllegalArgumentException
maximum
elements in immortal memory. The queue has an unsynchronized and
nonblocking write()
method and a
synchronized and blocking read()
method.
Equivalent to
WaitFreeWriteQueue(null,null,mximum, null)
StaticIllegalArgumentException
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.
true
, when this
is empty;
false
, when 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.
true
, when this
is full;
false
, when this
is not full.public T read() throws java.lang.InterruptedException
T
least recently written to the queue.
When this
is empty, the calling schedulable blocks until
an element is inserted; when it is resumed, read
removes and returns the element.java.lang.InterruptedException
- when 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(T value) throws MemoryScopeException, StaticIllegalArgumentException
value
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 value
was inserted was vacant
(false
) or occupied (true
).value
- An instance of T
to insert.true
when value
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
- when a memory access error
or illegal assignment error would occur
while storing value
in the queue.StaticIllegalArgumentException
- when value
is null
.public boolean write(T value) throws MemoryScopeException, StaticIllegalArgumentException
value
into this
when
this
is non-full and otherwise has no effect on
this
; the boolean
result reflects whether
value
has been inserted. When the queue was empty and
one or more threads or schedulables were waiting to read,
then one will be awakened after the write. The choice of which to
awaken depends on the involved scheduler(s).value
- An instance of T
to insert.true
when the queue was non-full;
false
otherwise.MemoryScopeException
- when a memory access error
or illegal assignment error would occur
while storing value
in the queue.StaticIllegalArgumentException
- when value
is
null
.