jcsp.lang
Class Any2OneChannel

java.lang.Object
  |
  +--jcsp.lang.Guard
        |
        +--jcsp.lang.AltingChannelInput
              |
              +--jcsp.lang.AltingChannel
                    |
                    +--jcsp.lang.Any2OneChannel

All Implemented Interfaces:

Channel, ChannelInput, ChannelOutput, Serializable

public class Any2OneChannel

extends AltingChannel

implements Serializable

This implements a any-to-one object channel, safe for use by many writers and one reader.

Description

Any2OneChannel is an implementation of a channel which is safe for use by many writing processes but only one reader. Writing processes compete with each other to use the channel. Only the reader and one writer will actually be using the channel at any one time. This is taken care of by Any2OneChannel -- user processes just read from or write to it.

The reading process may ALT on this channel. The writing process is committed (i.e. it may not back off).

The default semantics of the channel is that of CSP -- i.e. it is zero-buffered and fully synchronised. The reading process must wait for a matching writer and vice-versa.

However, the static create method allows the user to create a channel with a plug-in driver conforming to the jcsp.util.ChannelDataStore interface. This allows a variety of different channel semantics to be introduced -- including buffered channels of user-defined capacity (including infinite), overwriting channels (with various overwriting policies) etc.. Standard examples are given in the jcsp.util package, but careful users may write their own.

Other static create methods allows the user to create fully initialised arrays of channels, including plug-ins if required.

Implementation Note and Caution

Fair servicing of writers to this channel depends on the fair servicing of requests to enter a synchronized block (or method) by the underlying Java Virtual Machine (JVM). Java does not specify how threads waiting to synchronize should be handled. Currently, Sun's standard JDKs queue these requests - which is fair. However, there is at least one JVM that puts such competing requests on a stack - which is legal but unfair and can lead to infinite starvation. This is a problem for any Java system relying on good behaviour from synchronized, not just for JCSP's any-1 channels.

Author:

P.D.Austin and P.H.Welch

See Also:

Alternative, One2OneChannel, One2AnyChannel, Any2AnyChannel, ChannelDataStore, Serialized Form

Constructor Summary

Any2OneChannel()
Constructs a new Any2OneChannel with a ZeroBuffer ChannelDataStore.

Any2OneChannel(ChannelDataStore data)
Deprecated. Use Any2AnyChannel.create (ChannelDataStore).

Method Summary

static Any2OneChannel	create(ChannelDataStore store) Creates a Any2OneChannel using the specified ChannelDataStore.
static Any2OneChannel[]	create(int n) Creates an array of Any2OneChannels.
static Any2OneChannel[]	create(int n, ChannelDataStore store) Creates an array of Any2OneChannel using the specified ChannelDataStore.
boolean	pending() Returns whether there is data pending on this channel.
Object	read() Reads an Object from the Channel.
void	write(Object value) Writes an Object to the Channel.

Methods inherited from class java.lang.Object

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

Constructor Detail

Any2OneChannel

public Any2OneChannel()

Constructs a new Any2OneChannel with a ZeroBuffer ChannelDataStore.

Any2OneChannel

public Any2OneChannel(ChannelDataStore data)

Deprecated. Use Any2AnyChannel.create (ChannelDataStore).

Constructs a new Any2OneChannel with the specified ChannelDataStore.

Parameters:

data - The ChannelDataStore used to store the data for the Channel

Method Detail

read

public Object read()

Reads an Object from the Channel.

Returns:

The object returned from the Channel.

write

public void write(Object value)

Writes an Object to the Channel. This method also ensures only one of the writers can actually be writing at any time. All other writers are blocked until it completes the write.

Parameters:

value - The object to write to the Channel.

pending

public boolean pending()

Returns whether there is data pending on this channel.

Note: if there is, it won't go away until you read it. But if there isn't, there may be some by the time you check the result of this method.

This method is provided for convenience. Its functionality can be provided by Pri Alting the channel against a SKIP guard, although at greater run-time and syntactic cost. For example, the following code fragment:

   if (c.pending ()) {
     Object x = c.read ();
     ...  do something with x
   } else (
     ...  do something else
   }
 

is equivalent to:

   if (c_pending.priSelect () == 0) {
     Object x = c.read ();
     ...  do something with x
   } else (
     ...  do something else
 }
 

where earlier would have had to have been declared:

 final Alternative c_pending =
   new Alternative (new Guard[] {c, new Skip ()});
 

Overrides:

pending in class AltingChannelInput

Returns:

state of the channel.

create

public static Any2OneChannel[] create(int n)

Creates an array of Any2OneChannels.

Parameters:

n - the number of channels to create in the array

Returns:

the array of Any2OneChannels

create

public static Any2OneChannel create(ChannelDataStore store)

Creates a Any2OneChannel using the specified ChannelDataStore.

Returns:

the Any2OneChannel

create

public static Any2OneChannel[] create(int n,
                                      ChannelDataStore store)

Creates an array of Any2OneChannel using the specified ChannelDataStore.

Parameters:

n - the number of channels to create in the array

Returns:

the array of Any2OneChannels