Package org.jcsp.lang

# Interface ChannelInput

All Superinterfaces:
  `Poisonable`

All Known Subinterfaces:
  `FilteredChannelInput`, `FilteredSharedChannelInput`, `SharedChannelInput`

All Known Implementing Classes:
  `AltingChannelInput`, `AltingChannelInputWrapper`, `ChannelInputWrapper`, `FilteredAltingChannelInput`, `FilteredSharedChannelInputWrapper`

public interface ChannelInput extends Poisonable
This defines the interface for reading from an Object channel.

A reading-end, conforming to this interface, is obtained from a channel by invoking its `in()` method.

## Description

`ChannelInput` defines the interface for reading from object channels. The interface contains three methods: ``read``, ``startRead`` and ``endRead``. The ``read`` and ``startRead`` methods block until an `Object` has been written to the channel by a process at the other end. If an `Object` has already been written when this method is called, the method will return without blocking. Either way, the methods return the `Object` sent down the channel.

When a ``read`` completes, the matching ``write`` method (invoked by the writing process) also completes. When a ``startRead`` completes, the matching ``write`` method does not complete until the reader process invokes an ``endRead``. Actions performed by the reader in between a ``startRead`` and ``endRead`` make up an extended rendezvous.

`ChannelInput` variables are used to hold channels that are going to be used only for input by the declaring process. This is a security matter -- by declaring a `ChannelInput` interface, any attempt to output to the channel will generate a compile-time error. For example, the following code fragment will not compile:

     void doWrite (ChannelInput c, Object o) {
       c.write (o);   // illegal
     }

When configuring a `CSProcess` with input channels, they should be declared as `ChannelInput` (or, if we wish to be able to make choices between events, as `AltingChannelInput`) variables. The actual channel passed, of course, may belong to any channel class that implements `ChannelInput` (or `AltingChannelInput`).

The `Object` returned can be cast into the actual class the reader process expects. If the reader can handle more than one class of `Object` (similar to tagged protocols in occam), checks should be made before casting.

## Examples

### Discard data

     void doRead (ChannelInput c) {
       c.read ();                       // clear the channel
     }

### Cast data to expected type

     void doRead (ChannelInput c) {
       Boolean b = (Boolean) c.read();  // will cause a ClassCastException
                                        // if read does not return a Boolean
       ...  etc.
     }

### Cast data after checking type

     void doRead (ChannelInput c) {
       Object o = c.read ();
       if (o instanceof Boolean) {
         System.out.println ("Boolean: " + (Boolean) o);
       }
       else if (o instanceof Integer) {
         System.out.println ("Integer: " + (Integer) o);
       }
       else {
         System.out.println ("Unexpected Class: " + o);
       }
     }

Author:
  P.D. Austin and P.H. Welch and N.C.C.Brown
See Also:
  - `AltingChannelInput`
  - `SharedChannelInput`
  - `ChannelOutput`

## Method Summary

Modifier and Type
Method
Description
`void`
`endRead()`
End an extended rendezvous.
`Object`
`read()`
Read an Object from the channel.
`Object`
`startRead()`
Begin an extended rendezvous read from the channel.

### Methods inherited from interface org.jcsp.lang.Poisonable

`poison`

## Method Details

### read

Object read()
Read an Object from the channel.

Returns:
  the object read from the channel

### startRead

Object startRead()
Begin an extended rendezvous read from the channel. An extended rendezvous is not completed until the reader has completed its extended action. This method starts an extended rendezvous. When a writer to this channel writes, this method returns what was sent immediately. The extended rendezvous continues with reader actions until the reader invokes ``endRead``. Only then will the writer be released (from its ``write`` method). The writer is unaware of the extended nature of the communication.

The reader process must call ``endRead`` at some point after this function, otherwise the writer will not be freed and deadlock will probably follow.

The reader process may perform any actions between calling ``startRead`` and ``endRead``, including communications on other channels. Further communications on this channel, of course, should not be made.

An extended rendezvous may be started after the channel's Guard has been selected by an `Alternative` (i.e. ``startRead`` instead of ``read``).

Returns:
  The object read from the channel

### endRead

void endRead()
End an extended rendezvous. It must be invoked once (and only once) following a ``startRead``.