Package org.jcsp.util

# Class OverWritingBuffer

java.lang.Object
org.jcsp.util.OverWritingBuffer

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

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

## Description

It 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 latest item written to 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`
  - `OverWriteOldestBuffer`
  - `OverFlowingBuffer`
  - `InfiniteBuffer`
  - `Channel`
  - Serialized Form

## Field Summary

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

`EMPTY, FULL, NONEMPTYFULL`

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`Object`
`clone()`
Returns a new (and `EMPTY`) `OverWritingBuffer` 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 `OverWritingBuffer` and removes it.
`int`
`getState()`
Returns the current state of the `OverWritingBuffer`.
`void`
`put(Object value)`
Puts a new `Object` into the `OverWritingBuffer`.
`void`
`removeAll()`
Deletes all items in the buffer, leaving it empty.
`Object`
`startGet()`
This 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

### OverWritingBuffer

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

Parameters:
  `size` - the number of Objects the OverWritingBuffer 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 `OverWritingBuffer` and removes it.

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

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

### put

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

If `OverWritingBuffer` is full, the last item previously put into the buffer will be overwritten.

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

### startGet

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

If the buffer is of size 2 or larger, the semantics are as follows. Beginning an extended rendezvous will return the oldest value in the buffer, but not remove it. If the writer writes to the buffer during the rendezvous, it will grow the buffer and end up overwriting the newest value as normal. At the end of the extended rendezvous, the oldest value is removed.

If the buffer is of size 1, the semantics are identical to those of an `OverWriteOldestBuffer`. For a complete description, refer to the documentation for the `OverWriteOldestBuffer.startGet()` method.

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()`

### getState

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

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

### clone

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

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

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

### removeAll

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

Specified by:
  `removeAll` in interface `ChannelDataStore`