Package org.jcsp.util.ints

# Class OverWriteOldestBufferInt

java.lang.Object
org.jcsp.util.ints.OverWriteOldestBufferInt

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

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

## Description

`OverWriteOldestBufferInt` is an implementation of `ChannelDataStoreInt` 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.one2oneInt(org.jcsp.util.ints.ChannelDataStoreInt)` etc.).

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

Author:
  P.D. Austin
See Also:
  - `ZeroBufferInt`
  - `BufferInt`
  - `OverWritingBufferInt`
  - `OverFlowingBufferInt`
  - `InfiniteBufferInt`
  - `ChannelInt`
  - Serialized Form

## Field Summary

### Fields inherited from interface org.jcsp.util.ints.ChannelDataStoreInt

`EMPTY, FULL, NONEMPTYFULL`

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`Object`
`clone()`
Returns a new (and `EMPTY`) `OverWriteOldestBufferInt` with the same creation parameters as this one.
`void`
`endGet()`
See `startGet()` for a description of the semantics of this method.
`int`
`get()`
Returns the oldest `int` from the `OverWriteOldestBufferInt` and removes it.
`int`
`getState()`
Returns the current state of the `OverWriteOldestBufferInt`.
`void`
`put(int value)`
Puts a new `int` into the `OverWriteOldestBufferInt`.
`void`
`removeAll()`
`int`
`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

### OverWriteOldestBufferInt

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

Parameters:
  `size` - the number of ints the OverWriteOldestBufferInt can store.
Throws:
  `BufferIntSizeError` - 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 int get()
Returns the oldest `int` from the `OverWriteOldestBufferInt` and removes it.

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

Specified by:
  `get` in interface `ChannelDataStoreInt`
Returns:
  the oldest `int` from the `OverWriteOldestBufferInt`

### startGet

public int 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 `ChannelDataStoreInt`
Returns:
  The oldest value in the buffer at this time
See Also:
  - `ChannelDataStoreInt.endGet()`

### endGet

public void endGet()
See `startGet()` for a description of the semantics of this method.

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

### put

public void put(int value)
Puts a new `int` into the `OverWriteOldestBufferInt`.

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

Specified by:
  `put` in interface `ChannelDataStoreInt`
Parameters:
  `value` - the int to put into the OverWriteOldestBufferInt

### getState

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

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

### clone

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

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

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

### removeAll

public void removeAll()

Specified by:
  `removeAll` in interface `ChannelDataStoreInt`