Package org.jcsp.lang

# Class One2AnyCallChannel

java.lang.Object
org.jcsp.lang.One2AnyCallChannel

All Implemented Interfaces:
  `Serializable`, `ChannelAccept`

public abstract class One2AnyCallChannel extends Object implements ChannelAccept, Serializable
This is the super-class for one-to-any `interface`-specific CALL channels, safe for use by one client and many servers.

Shortcut to the Constructor and Method Summaries.

## Description

Please see `One2OneCallChannel` for general information about CALL channels. Documented here is information specific to this 1-any version.

### Converting a Method Interface into a Variant CALL Channel

Constructing a 1-any CALL channel for a specific `interface` follows exactly the same pattern as in the 1-1 case. Of course, it must extend `One2AnyCallChannel` rather than `One2OneCallChannel`.

For example, using the same `Foo` interface as before, we derive:

     import org.jcsp.lang.*;

     public class One2AnyFooChannel extends One2AnyCallChannel implements Foo {

       ...  same body as One2OneFooChannel

     }

### Calling a CALL Channel

All the client needs to see is the method `interface` implemented by the CALL channel. So far as the client is concerned, therefore, there is no difference between any of the varieties of CALL channel - it just makes the call.

### Accepting a CALL Channel

The mechanics of accepting a CALL channel are the same for all varieties. However, the server should declare which kind (or kinds) it allows to be attached:

     import org.jcsp.lang.*;

     class B implements CSProcess, Foo {

       private final ChannelAccept in;

       public B (final One2OneFooChannel in) {         // original constructor
         this.in = in;
       }

       public B (final One2AnyFooChannel in) {        // additional constructor
         this.in = in;
       }

       ...  rest as before

     }

When wrapping the above to hide its raw method interface, don't forget to include the extra constructor(s):

     import org.jcsp.lang.*;

     public class B2 implements CSProcess {            // no Foo interface

       private final B b;

       public B2 (final One2OneFooChannel in) {        // original constructor
         b = new B (in);
       }

       public B2 (final One2AnyFooChannel in) {       // additional constructor
         b = new B (in);
       }

       public void run () {
         b.run ();
       }

     }

### ALTing on a CALL Channel

As for ordinary channels, ALTing over 1-Any or Any-Any versions is not supported. Hence, a server can only choose to ``accept`` or not to `accept` a `One2AnyFooChannel` - it cannot back off because of some other event.

### Building a CALL Channel Network

Network building with CALL channels is the same as building with ordinary channels. First construct the channels and, then, construct the processes - plugging in the channels as required and running them in `Parallel`.

For example, the network consisting of one client and several servers:

where `A` is unchanged from its definition in `One2OneCallChannel`, is implemented by:

         One2AnyFooChannel c = new One2AnyFooChannel ();

         final B2[] bServers = new B2[n_bClients];
         for (int i = 0; i invalid input: '<' bServers.length; i++) {
           bServers[i] = new B2 (c);
         }

         new Parallel (
           new CSProcess[] {
             new A (c),
             new Parallel (bServers)
           }
         ).run ();

[Reminder: XXX-any channels are not broadcasters of information. In the above, when `A` makes a CALL on `c`, it must not care which of the `B2` servers picks it up. The servers compete with each other to service the client.]

## Example

Please see `Any2AnyCallChannel` for an example that includes many clients and many servers competing for each other's attention.

Author:
  P.H. Welch
See Also:
  - `One2OneCallChannel`
  - `Any2OneCallChannel`
  - `Any2AnyCallChannel`
  - `Alternative`
  - Serialized Form

## Field Summary

Fields
Modifier and Type
Field
Description
`protected int`
`selected`
This may be set during the standard calling sequence to record which method was invoked by a client.
`protected CSProcess`
`server`
This holds a reference to a server process so that a client may make the call.

## Constructor Summary

Constructors
Constructor
Description
`One2AnyCallChannel()`

## Method Summary

Modifier and Type
Method
Description
`int`
`accept(CSProcess server)`
This is invoked by a server when it commits to accepting a CALL from a client.
`protected void`
`fork()`
This is invoked by a client during the standard calling sequence.
`protected void`
`join()`
This is invoked by a client during the standard calling sequence.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### server

protected CSProcess server
This holds a reference to a server process so that a client may make the call. The reference is only valid between the ``join`` and ``fork`` elements of the standard calling sequence. As shown in that sequence, it will need casting up to the relevant interface supported by the specific CALL channel derived from this class.

### selected

protected int selected
This may be set during the standard calling sequence to record which method was invoked by a client. It is only safe to do this between the ``join`` and ``fork`` elements of that sequence. Either all the CALL channel methods should do this or none - in the latter case, its default value remains as zero. Its value is returned to a server as the result the server's invocation of ``accept``.

## Constructor Details

### One2AnyCallChannel

public One2AnyCallChannel()

## Method Details

### accept

public int accept(CSProcess server)
This is invoked by a server when it commits to accepting a CALL from a client. The parameter supplied must be a reference to this server - see the example from `One2OneCallChannel`. It will not complete until a CALL has been made. If the derived CALL channel has set the `selected` field in the way defined by the standard calling sequence, the value returned by this method will indicate which method was called.

Specified by:
  `accept` in interface `ChannelAccept`
Parameters:
  `server` - the server process receiving the CALL.

### join

protected void join()
This is invoked by a client during the standard calling sequence. It will not complete until a server invokes an ``accept`` on this channel. In turn, that `accept` will not complete until the client invokes a ``fork``, after having made its CALL on the server.

### fork

protected void fork()
This is invoked by a client during the standard calling sequence. A server must have invoked an ``accept`` for the client to have got this far in the sequence - see the ``join``. This call unblocks that `accept`, releasing the server and client to resume separate lives.