se.lth.cs.realtime.event
Class Buffer

java.lang.Object
  se.lth.cs.realtime.event.RTEventBuffer
      se.lth.cs.realtime.event.Buffer

All Implemented Interfaces:

RTEventBufferInput, RTEventBufferOutput, Synchronized

public class Buffer

extends RTEventBuffer

The standard full-featured RTEventBuffer implementation, including methods for conditional blocking on full/empty conditions. By using separate Condition objects for each extra buffer condition, improved efficiency (fewer context switches) is accomplished in the case that many threads are waiting on different things. This requires the application to be started via class Main or being compiled with a suitable compiler, otherwise about the same efficiency as if the implicit condition was used will be obtained.

To meet the efficiency demands of some applications, most methods are final. The class as such is, however, not final since subclassing is expected for adding more features, hence the protected visibility of fields. Additionally, the methods post and fetch are virtual (i.e., not final). They by default call the corresponding do-method and are typed accordingly, but they are free for redefinition which can even result in synchronized being omitted if mutual exclusion is ensured elsewhere (in enclosing monitor, etc.). See also the implemented interfaces, which are facilitating access to only one end of the buffer.

For simple applications the more easy to understand implementation BufferPlain could be used. Also that class extends the RTEventBuffer.

See Also:

BufferPlain, License

Nested Class Summary

Nested classes inherited from class se.lth.cs.realtime.Synchronized

Synchronized.Lock

Field Summary

Fields inherited from class se.lth.cs.realtime.event.RTEventBuffer

DEFAULT_SIZE

Constructor Summary

Buffer()
Initializes the buffer with a size of DEFAULT_SIZE.

Buffer(int maxSize)
Initializes the queue (buffer) with a given maximal size.

Buffer(int maxSize, Synchronized.Lock lock)
Initializes the queue (buffer) with a given maximal size, and with a lock object to be used for synchronization.

Method Summary

void	awaitEmpty() Waits for buffer to become empty.
void	awaitFull() Waits for buffer to become full.
void	awaitNotEmpty() Waits for buffer to become non-empty.
void	awaitNotFull() Waits for buffer to become non-full.
int	currentSize() The current size of the buffer.
RTEvent	doFetch() Returns the next RTEvent in the queue, blocks if none available.
void	doPost(RTEvent e) Adds an RTEvent to the queue, blocks caller if the queue is full.
RTEvent[]	fetchAll() Get all buffered events leaving the buffer empty.
void	flush() Removes all buffered events.
int	getMaxSize() Gets the maximum size of the buffer.
boolean	isEmpty() Checks if buffer is empty.
boolean	isFull() Checks if buffer is full.
void	setMaxSize(int newSize) Changes size of buffer.
RTEvent	tryFetch() Returns the next available RTEvent in the queue, or null if the queue is empty.
RTEvent	tryFetch(long timeout) Get the next RTEvent in the queue, or block (up to the specified timeout time) if no event is available.
RTEvent	tryPost(RTEvent e) Adds an EventObject to the queue, without blocking if the queue is full.
RTEvent	tryPost(RTEvent e, long timeout) Adds an RTEvent to the queue, blocks caller if the queue is full up to the specified timeout time.

Methods inherited from class se.lth.cs.realtime.event.RTEventBuffer

fetch, post

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Buffer

public Buffer()

Initializes the buffer with a size of DEFAULT_SIZE.

Buffer

public Buffer(int maxSize)

Initializes the queue (buffer) with a given maximal size. A size smaller than one results in a buffer with size one.

Parameters:

maxSize - maximum queue size

Buffer

public Buffer(int maxSize,
              Synchronized.Lock lock)

Initializes the queue (buffer) with a given maximal size, and with a lock object to be used for synchronization.

Parameters:

maxSize - maximum queue size

lock - external monitor/object to synchronized with

Method Detail

doFetch

public final RTEvent doFetch()

Returns the next RTEvent in the queue, blocks if none available.

Specified by:

doFetch in interface RTEventBufferOutput

Specified by:

doFetch in class RTEventBuffer

Returns:

a non-null event.

tryFetch

public final RTEvent tryFetch()

Returns the next available RTEvent in the queue, or null if the queue is empty. In other words, this method always returns immediately, even if the queue is empty (non-blocking).

Specified by:

tryFetch in interface RTEventBufferOutput

Specified by:

tryFetch in class RTEventBuffer

Returns:

an RTEvent if any available, null otherwise

tryFetch

public final RTEvent tryFetch(long timeout)

Get the next RTEvent in the queue, or block (up to the specified timeout time) if no event is available. Synchronized internally after that time of arrival has been stored for later checking of the timeout, which is an enhancement compared to the plain buffer BufferPlain.

Specified by:

tryFetch in interface RTEventBufferOutput

Specified by:

tryFetch in class RTEventBuffer

Parameters:

timeout - the maximum blocking time time in milli-seconds.

Returns:

an RTEvent if any available within the timeout time, null otherwise.

doPost

public final void doPost(RTEvent e)

Adds an RTEvent to the queue, blocks caller if the queue is full.

Specified by:

doPost in interface RTEventBufferInput

Specified by:

doPost in class RTEventBuffer

Parameters:

e - the event to enqueue

tryPost

public final RTEvent tryPost(RTEvent e)

Adds an EventObject to the queue, without blocking if the queue is full.

Specified by:

tryPost in interface RTEventBufferInput

Specified by:

tryPost in class RTEventBuffer

Parameters:

e - the event to enqueue

Returns:

null when event posted to non-full buffer, the event otherwise

tryPost

public final RTEvent tryPost(RTEvent e,
                             long timeout)

Adds an RTEvent to the queue, blocks caller if the queue is full up to the specified timeout time. Synchronized internally after that the time of arrival has been stored for later checking of the timeout, which is an enhancement compared to the plain buffer BufferPlain.

Specified by:

tryPost in interface RTEventBufferInput

Specified by:

tryPost in class RTEventBuffer

Parameters:

e - the event to enqueue

timeout - the maximum blocking time time in milli-seconds.

Returns:

null when event posted within the timeout time to non-full buffer, the event otherwise.

isEmpty

public boolean isEmpty()

Checks if buffer is empty.

Specified by:

isEmpty in class RTEventBuffer

Returns:

true if the queue is empty, false if it is non-empty

awaitEmpty

public void awaitEmpty()

Waits for buffer to become empty.

awaitNotEmpty

public void awaitNotEmpty()

Waits for buffer to become non-empty.

isFull

public boolean isFull()

Checks if buffer is full.

Specified by:

isFull in class RTEventBuffer

Returns:

true if the queue is full, false if it is non-full

awaitFull

public void awaitFull()

Waits for buffer to become full. If the buffer has been resized to a size less than the current number of events, the caller is blocked until the buffer is exactly full.

awaitNotFull

public void awaitNotFull()

Waits for buffer to become non-full. If the buffer has been resized to a size less than the current number of events, the caller is blocked until the current size of the buffer is smaller than the new maximum size.

currentSize

public int currentSize()

The current size of the buffer.

Specified by:

currentSize in class RTEventBuffer

Returns:

the number of objects currently enqueued

See Also:

RTEventBuffer#maxSize

flush

public void flush()

Removes all buffered events.

Specified by:

flush in class RTEventBuffer

fetchAll

public RTEvent[] fetchAll()

Get all buffered events leaving the buffer empty. The event that was the next to be fetched is returned as the first element (index 0), followed by the other events in FIFO order with the most recently posted event as the last element.

Specified by:

fetchAll in class RTEventBuffer

Returns:

array containing buffered events. An empty array (not null) is returned if the buffer was empty.

getMaxSize

public int getMaxSize()

Gets the maximum size of the buffer.

Specified by:

getMaxSize in class RTEventBuffer

Returns:

the maximum number of objects that can be enqueued

setMaxSize

public void setMaxSize(int newSize)

Changes size of buffer.

Parameters:

newSize - the new maximum number of objects that can be enqueued