plugins/org.eclipse.app4mc.amalthea.model.help/docu/user_channel.textile

h3. Communication via channels


h4. Channel

Sender and receiver communicating via a channel by issuing send and receive operations; read policy and transmission policy define communication details.

!../pictures/user_channel.png!

A channel is specified by three attributes:
* *elementType*: the type that is sent to or read from the channel.
* *defaultElements*:  number of elements initially in the channel (at start-up).
* *maxElements* (integer) denoting a buffer limit, that is, the channel depth. In other words, no more than maxElements elements of the given element type may be stored in the channel.

h4. Channel Access

In the basic thinking model, all elements are stored as a sequential collection in the channel.

!../pictures/user_channel_access.png!


h5. Sending

A runnable may send elements to a channel by issuing send operations.
The send operation has a single parameter:
* *elements* (integer): Number of elements that are written.


h5. Receiving

A runnable may receive elements from a channel by issuing receive operations.
The receive operation is specified with a *receive policy* that defines the main behaviour of the operation:

* *LIFO* (last-in, first-out) is chosen if processing the last written elements is the primary focus and thereby missing elements is tolerable.
* *FIFO* (first-in, first-out) is chosen if every written element needs to be handled, that is, loss of elements is not tolerable.
* *Read* will received elements without modifying the channel
* *Take* will remove the received elements from the channel

The receive policy defines the direction a receive operation takes effect with LIFO accesses are from top of the sequential collection, while with FIFO accesses are from bottom of the sequential collection-and they define if the receive operation is destructive (take) or non-destructive) read.

Each operation further has two parameters and two attributes specifying the exact behavior. The two parameters are:
* *elements* (integer): Maximum number n of elements that are received.
* *elementIndex* (integer): Position (index i) in channel at which the operation is effective. Zero is the default and denotes the oldest (FIFO) or newest element (LIFO) in the channel.

In the following several examples are shown, of how to read or take elements out of a channel with the introduced parameters.

!../pictures/user_channel_operations.png!

Two attributes further detail the receive operation:
* *lowerBound* (integer): Specify the minimum number of elements returned by the operation. The value must be in the range [0,n], with n is the value of the parameter elements. Default value is n.
* *dataMustBeNew* (Boolean): Specify if the operation must only return elements that are not previously read by this Runnable. Default value is false.


h4. Transmission Policy

To further specify how elements are accessed by a runnable in terms of computing time, an optional transmission policy may specify details for each receive and send operation. The intention of the transmission policy is to reflect computing demand (time) depending on data.

The transmission policy consists of the following attributes:
* *chunkSize*: Size of a part of an element, maximum is the element size.
* *chunkProcessingTicks* (integer): Number of ticks that will be executed to process one chunk (algorithmic overhead).
* *transmitRatio* (float): Specify the ratio of each element that is actually transmitted by the runnable in percent. Value must be between [0, 1], default value is 1.0.

Example for using transmission policy to detail the receiving phase of a runnable execution. Two elements are received, leading to transmission time as given in the formula. After the receiving phase, the runnable starts with the computing phase.

!../pictures/user_channel_transmission_example.png!