Package org.jcsp.util

# Class OverWriteOldestBuffer

java.lang.Object
org.jcsp.util.OverWriteOldestBuffer

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `ChannelDataStore`

public class OverWriteOldestBuffer extends Object implements ChannelDataStore, Serializable
This is used to create a buffered object channel that always accepts input, overwriting its oldest data if full.

## Description

`OverWriteOldestBuffer` is an implementation of `ChannelDataStore` that yields a FIFO buffered semantics for a channel. When empty, the channel blocks readers. When full, a writer will overwrite the oldest item left unread in the channel. See the `static` construction methods of `Channel` (`Channel.one2one(org.jcsp.util.ChannelDataStore)` etc.).

The `getState` method returns `EMPTY` or `NONEMPTYFULL`, but never `FULL`.

Author:
  P.D. Austin
See Also:
  - `ZeroBuffer`
  - `Buffer`
  - `OverWritingBuffer`
  - `OverFlowingBuffer`
  - `InfiniteBuffer`
  - `Channel`
  - Serialized Form

## Field Summary

### Fields inherited from interface org.jcsp.util.ChannelDataStore

`EMPTY, FULL, NONEMPTYFULL`

## Constructor Summary

Constructors
Constructor
Description
`OverWriteOldestBuffer(int size)`
Construct a new `OverWriteOldestBuffer` with the specified size.

## Method Summary

Modifier and Type
Method
Description
`Object`
`clone()`
Returns a new (and `EMPTY`) `OverWriteOldestBuffer` with the same creation parameters as this one.
`void`
`endGet()`
This ends an extended rendezvous by the reader.
`Object`
`get()`
Returns the oldest `Object` from the `OverWriteOldestBuffer` and removes it.
`int`
`getState()`
Returns the current state of the `OverWriteOldestBuffer`.
`void`
`put(Object value)`
Puts a new `Object` into the `OverWriteOldestBuffer`.
`void`
`removeAll()`
Deletes all items in the buffer, leaving it empty.
`Object`
`startGet()`
Begins an extended rendezvous by the reader.

### Methods inherited from class java.lang.Object

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

## Constructor Details

### OverWriteOldestBuffer

public OverWriteOldestBuffer(int size)
Construct a new `OverWriteOldestBuffer` with the specified size.

Parameters:
  `size` - the number of Objects the OverWriteOldestBuffer can store.
Throws:
  `BufferSizeError` - if `size` is zero or negative. Note: no action should be taken to `try`/`catch` this exception - application code generating it is in error and needs correcting.

## Method Details

### get

public Object get()
Returns the oldest `Object` from the `OverWriteOldestBuffer` and removes it.

Pre-condition: `getState` must not currently return `EMPTY`.

Specified by:
  `get` in interface `ChannelDataStore`
Returns:
  the oldest `Object` from the `OverWriteOldestBuffer`

### startGet

public Object startGet()
Begins an extended rendezvous by the reader. The semantics of an extended rendezvous on an overwrite-oldest buffer are slightly complicated, but hopefully intuitive.

When a reader begins an extended rendezvous, the oldest value is returned from the buffer (as it would be for a call to `get()`). While an extended rendezvous is ongoing, the writer may (repeatedly) write to the buffer, without ever blocking.

When the reader finishes an extended rendezvous, the following options are possible:

- The writer has not written to the channel during the rendezvous. In this case, the value that was read at the start of the rendezvous is removed from the buffer.
- The writer has written to the channel during the rendezvous, but has not over-written the value that was read at the start of the rendezvous. In this case, the value that was read at the start of the rendezvous is removed from the buffer.
- The writer has written to the channel during the rendezvous, and has over-written (perhaps repeatedly) the value that was read at the start of the rendezvous. In this case, the value that was read at the start of the rendezvous is no longer in the buffer, and hence nothing is removed.

Specified by:
  `startGet` in interface `ChannelDataStore`
Returns:
  The oldest value in the buffer at this time
See Also:
  - `ChannelDataStore.endGet()`

### endGet

public void endGet()
This ends an extended rendezvous by the reader.

Specified by:
  `endGet` in interface `ChannelDataStore`
See Also:
  - `startGet()`

### put

public void put(Object value)
Puts a new `Object` into the `OverWriteOldestBuffer`.

If `OverWriteOldestBuffer` is full, the oldest item left unread in the buffer will be overwritten.

Specified by:
  `put` in interface `ChannelDataStore`
Parameters:
  `value` - the Object to put into the OverWriteOldestBuffer

### getState

public int getState()
Returns the current state of the `OverWriteOldestBuffer`.

Specified by:
  `getState` in interface `ChannelDataStore`
Returns:
  the current state of the `OverWriteOldestBuffer` (`EMPTY` or `NONEMPTYFULL`)

### clone

public Object clone()
Returns a new (and `EMPTY`) `OverWriteOldestBuffer` with the same creation parameters as this one.

Note: Only the size and structure of the `OverWriteOldestBuffer` is cloned, not any stored data.

Specified by:
  `clone` in interface `ChannelDataStore`
Overrides:
  `clone` in class `Object`
Returns:
  the cloned instance of this `OverWriteOldestBuffer`.

### removeAll

public void removeAll()
Description copied from interface: `ChannelDataStore`
Deletes all items in the buffer, leaving it empty.

Specified by:
  `removeAll` in interface `ChannelDataStore`