Package org.jcsp.util

# Interface ChannelDataStore

All Superinterfaces:
  `Cloneable`

All Known Implementing Classes:
  `Buffer`, `InfiniteBuffer`, `OverFlowingBuffer`, `OverWriteOldestBuffer`, `OverWritingBuffer`, `ZeroBuffer`

public interface ChannelDataStore extends Cloneable
This is the interface for object channel plug-ins that define their buffering characteristics.

## Description

`ChannelDataStore` defines the interface to optional logic used by channels defined in the `org.jcsp.lang` package to manage the data being communicated. Implementations are provided yielding a range of buffering properties (e.g. `fixed sized (block when full)`, `fixed size (overwrite oldest data when full)`, `fixed size (accept but discard new data when full)`, `infinitely expandable`).

Channels are constructed using the static construction methods of `Channel`. By default, channels will be constructed with standard CSP semantics – no buffering and full synchronisation between reading and writing processes (e.g. `Channel.one2one()`). To construct buffered channels, plug in the appropriate `ChannelDataStore` (e.g. `Channel.one2one(org.jcsp.util.ChannelDataStore)`).

Note: JCSP users should not normally need to define their own implementations of this interface. However, implementors may assume that `ChannelDataStore` methods are always invoked (by the various channel classes within `org.org.jcsp.lang`) in a thread-safe way – i.e. that there will be no race hazards between invocations of ``get`` and ``put``). They may also assume that the documented pre-conditions for invoking the `get` and `put` methods will be met. `ChannelDataStore` is only intended for defining the behaviour of buffers – it is not intended for any other purpose (e.g. for data-processing or filtering channels).

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

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`EMPTY`
Indicates that the `ChannelDataStore` is empty -- it can accept only a `put`.
`static final int`
`FULL`
Indicates that the `ChannelDataStore` is full -- it can accept only a `get`.
`static final int`
`NONEMPTYFULL`
Indicates that the `ChannelDataStore` is neither empty nor full -- it can accept either a `put` or a `get` call.

## Method Summary

Modifier and Type
Method
Description
`Object`
`clone()`
Returns a new (and `EMPTY`) `ChannelDataStore` with the same creation parameters as this one.
`void`
`endGet()`
Ends an extended read on the buffer.
`Object`
`get()`
Returns an `Object` from the `ChannelDataStore`.
`int`
`getState()`
Returns the current state of the `ChannelDataStore`.
`void`
`put(Object value)`
Puts a new `Object` into the `ChannelDataStore`.
`void`
`removeAll()`
Deletes all items in the buffer, leaving it empty.
`Object`
`startGet()`
Begins an extended read on the buffer, returning the data for the extended read.

## Field Details

### EMPTY

static final int EMPTY
Indicates that the `ChannelDataStore` is empty -- it can accept only a `put`.

See Also:
  - Constant Field Values

### NONEMPTYFULL

static final int NONEMPTYFULL
Indicates that the `ChannelDataStore` is neither empty nor full -- it can accept either a `put` or a `get` call.

See Also:
  - Constant Field Values

### FULL

static final int FULL
Indicates that the `ChannelDataStore` is full -- it can accept only a `get`.

See Also:
  - Constant Field Values

## Method Details

### getState

int getState()
Returns the current state of the `ChannelDataStore`.

Returns:
  the current state of the `ChannelDataStore` (`EMPTY`, `NONEMPTYFULL` or `FULL`)

### put

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

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

Parameters:
  `value` - the Object to put into the ChannelDataStore

### get

Object get()
Returns an `Object` from the `ChannelDataStore`.

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

Returns:
  an `Object` from the `ChannelDataStore`

### startGet

Object startGet()
Begins an extended read on the buffer, returning the data for the extended read.

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

The exact behaviour of this method depends on your buffer. When a process performs an extended rendezvous on a buffered channel, it will first call this method, then the `endGet()` method.

A FIFO buffer would implement this method as returning the value from the front of the buffer and the next call would remove the value. An overflowing buffer would do the same.

However, for an overwriting buffer it is more complex. Refer to the documentation for `OverWritingBuffer.startGet()` and `OverWriteOldestBuffer.startGet()` for details

Returns:
  The object to be read from the channel at the beginning of the extended rendezvous
See Also:
  - `endGet()`

### endGet

void endGet()
Ends an extended read on the buffer. The channels guarantee that this method will be called exactly once after each ``startGet`` call. During the period between ``startGet`` and ``endGet``, it is possible that ``put`` will be called, but not ``get``.

See Also:
  - `startGet()`

### clone

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

Note: Only the size and structure of the `ChannelDataStore` should be cloned, not any stored data.

Returns:
  the cloned instance of this `ChannelDataStore`.

### removeAll

void removeAll()
Deletes all items in the buffer, leaving it empty.