Package org.jcsp.util

Interface ChannelDataStore<T>

All Superinterfaces:
Cloneable
All Known Implementing Classes:
AcknowledgementsBuffer, Buffer, InfiniteBuffer, OverFlowingBuffer, OverWriteOldestBuffer, OverWritingBuffer, ZeroBuffer

public interface ChannelDataStore<T> 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).

See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Indicates that the ChannelDataStore is empty -- it can accept only a put.
    static final int
    Indicates that the ChannelDataStore is full -- it can accept only a get.
    static final int
    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
    Returns a new (and EMPTY) ChannelDataStore with the same creation parameters as this one.
    void
    Ends an extended read on the buffer.
    get()
    Returns an Object from the ChannelDataStore.
    int
    Returns the current state of the ChannelDataStore.
    void
    put(T value)
    Puts a new Object into the ChannelDataStore.
    void
    Deletes all items in the buffer, leaving it empty.
    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:
    • 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:
    • FULL

      static final int FULL
      Indicates that the ChannelDataStore is full -- it can accept only a get.
      See Also:
  • 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(T 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

      T get()
      Returns an Object from the ChannelDataStore.

      Pre-condition: getState must not currently return EMPTY.

      Returns:
      an Object from the ChannelDataStore
    • startGet

      T 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

      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:
    • 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.