Package org.jcsp.lang

This provides classes and interfaces corresponding to the fundamental primitives of CSP.

See:
Description

Interface Summary

Any2AnyChannel	This defines the interface for an any-to-any Object channel, safe for use by many writers and many readers.
Any2AnyChannelInt	This defines an interface for an any-to-any integer channel, safe for use by many writers and many readers.
Any2AnyConnection	Defines an interface for a connection shared by multiple clients and multiple servers.
Any2OneChannel	This defines an interface for an any-to-one Object channel, safe for use by many writers and one reader.
Any2OneChannelInt	This defines an interface for an any-to-one integer channel, safe for use by many writers and one reader.
Any2OneConnection	Defines an interface for a connection that can be shared by multiple concurrent clients but used by a single server.
BufferedChannelArrayFactory	Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.
BufferedChannelFactory	Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.
BufferedChannelIntArrayFactory	Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.
BufferedChannelIntFactory	Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.
ChannelAccept	This defines the interface for accepting CALL channels.
ChannelArrayFactory	Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.
ChannelFactory	Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.
ChannelInput	This defines the interface for reading from an Object channel.
ChannelInputInt	This defines the interface for reading from object channels.
ChannelIntArrayFactory	Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.
ChannelIntFactory	Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.
ChannelOutput	This defines the interface for writing to object channels.
ChannelOutputInt	This defines the interface for writing to integer channels.
ConnectionArrayFactory	Defines an interface for a factory that can create arrays of connections.
ConnectionClient	This is an interface to be implemented by classes that wish to act as a client to connect to a ConnectionServer.
ConnectionFactory	Defines an interface for a factory than can create connections.
ConnectionServer	This interface should be implemented by classes that wish to act as connection servers and to accept requests from ConnectionClient objects.
CSProcess	This is the JCSP interface for a process - an active component that encapsulates the data structures on which it operates.
One2AnyChannel	This defines the interface for a one-to-any Object channel, safe for use by one writer and many readers.
One2AnyChannelInt	This defines the interface for a one-to-any integer channel, safe for use by one writer and many readers.
One2AnyConnection	An interface for a connection which can be used by only one client but which can be used by multiple concurrent servers.
One2OneChannel	This defines the interface for a one-to-one Object channel.
One2OneChannelInt	This defines the interface for a one-to-one integer channel.
One2OneChannelSymmetric	This defines the interface for a symmetric one-to-one Object channel.
One2OneChannelSymmetricInt	This defines the interface for a symmetric one-to-one integer channel.
One2OneConnection	Defines an interface for a connection that can be used by a single server and single client.
Poisonable	All channel-ends implement this inteface.
RejectableChannel	Deprecated. This channel is superceded by the poison mechanisms, please see PoisonException.
RejectableChannelInput	Deprecated. This channel is superceded by the poison mechanisms, please see PoisonException.
RejectableChannelOutput	Deprecated. This channel is superceded by the poison mechanisms, please see PoisonException.
SharedChannelInput	This is the same as ChannelInput except that it is guaranteed safe to pass on to more than one internal process for parallel reading.
SharedChannelInputInt	This is the same as ChannelInputInt except that it is guaranteed safe to pass on to more than one internal process for parallel reading.
SharedChannelOutput	This is the same as ChannelOutput except that it is guaranteed safe to pass on to more than one internal process for parallel writing.
SharedChannelOutputInt	This is the same as ChannelOutputInt except that it is guaranteed safe to pass on to more than one internal process for parallel writing.
SharedConnectionClient	Defines an interface for a client end of a connection that can be shared by multiple clients.
SharedConnectionServer	Defines an interface for a server end of a connection that can be shared by multiple concurrent processes.

Class Summary

Alternative	This enables a process to wait passively for and choose between a number of Guard events.
AltingBarrier	This is the front-end for a barrier that can be used as a Guard in an Alternative.
AltingChannelAccept	This extends Guard and ChannelAccept to enable a process to choose between many CALL channel (and other) events.
AltingChannelInput	This extends Guard and ChannelInput to enable a process to choose between many object input (and other) events.
AltingChannelInputInt	This extends Guard and ChannelInputInt to enable a process to choose between many integer input (and other) events.
AltingChannelInputWrapper	Deprecated. There is no longer any need to use this class, after the 1.1 class reorganisation.
AltingChannelOutput	This extends Guard and ChannelOutput to enable a process to choose between many integer output (and other) events.
AltingChannelOutputInt	This extends Guard and ChannelOutputInt to enable a process to choose between many integer output (and other) events.
AltingConnectionClient	This class is sub-classed by JCSP.NET classes to provide ConnectionClient objects which can have their receive() method alted over.
AltingConnectionClientImpl	This class does not need to be used by standard JCSP users.
AltingConnectionServer	An interface to connection.
AltingConnectionServerImpl	This class does not need to be used by standard JCSP users.
Any2AnyCallChannel	This is the super-class for any-to-any interface-specific CALL channels, safe for use by many clients and many servers.
Any2OneCallChannel	This is the super-class for any-to-one interface-specific CALL channels, safe for use by many clients and one server.
Barrier	This enables barrier synchronisation between a set of processes.
BlackHoleChannel	This implements ChannelOutput with black hole semantics.
BlackHoleChannelInt	This implements ChannelOutputInt with black hole semantics.
Bucket	This enables bucket synchronisation between a set of processes.
Channel	This class provides static factory methods for constructing all the different types of channel.
ChannelInputWrapper	Deprecated. There is no longer any need to use this class, after the 1.1 class reorganisation.
ChannelInt	Deprecated. To create integer channels, use the methods in the Channel class.
ChannelOutputWrapper	Deprecated. There is no longer any need to use this class, after the 1.1 class reorganisation.
Connection	This class provides static factory methods for constructing different types of connection.
Crew	This provides a Concurrent Read Exclusive Write (CREW) lock for synchronising fair and secure access to a shared resource.
CSTimer	This is a Guard for setting timeouts in an Alternative.
Guard	This is the super-class for all Alternative events selectable by a process.
InlineAlternative	This class is experimental (i.e.
One2AnyCallChannel	This is the super-class for one-to-any interface-specific CALL channels, safe for use by one client and many servers.
One2OneCallChannel	This is the super-class for one-to-one interface-specific CALL channels.
Parallel	This process constructor taks an array of CSProcesses and returns a CSProcess that is the parallel composition of its process arguments.
PriParallel	This is an extension of the Parallel class that prioritises the processes given to its control.
ProcessManager	This enables a CSProcess to be spawned concurrently with the process doing the spawning.
RejectableAltingChannelInput	Deprecated. This channel is superceded by the poison mechanisms, please see PoisonException
RejectableBufferedOne2AnyChannel	Deprecated. This channel is superceded by the poison mechanisms, please see PoisonException
RejectableBufferedOne2OneChannel	Deprecated. This channel is superceded by the poison mechanisms, please see PoisonException
RejectableOne2AnyChannel	Deprecated. This channel is superceded by the poison mechanisms, please see PoisonException.
RejectableOne2OneChannel	Deprecated. This channel is superceded by the poison mechanisms, please see PoisonException.
Sequence	This constructor taks an array of CSProcesses and returns a CSProcess that is the sequential composition of its process arguments.
SharedAltingConnectionClient	Implements a client end of a Connection which can have multiple client processes.
SharedConnectionServerImpl	This class does not need to be used by standard JCSP users.
Skip	This is a process that immediately terminates and a Guard that is always ready.
SpuriousLog	This holds the log of spurious wakeups and early timeouts.
StandardChannelFactory	This class acts as a Factory for creating channels.
StandardChannelIntFactory	This class acts as a Factory for creating channels.
StandardConnectionFactory	Implements a factory for creating connections.
Stop	This is a process that starts, engages in no events, performs no computation but refuses to terminate.
TaggedProtocol	TaggedProtocol is the base class for messages carrying an occam2-like tagged (CASE) protocol over JCSP channels.

Exception Summary

ChannelDataRejectedException	Thrown by a read or a write method of a channel when a reject has been called and the synchronization and data transfer will not complete.
PoisonException	This exception is thrown when a process tries to use a channel that has been poisoned.

Error Summary

AlternativeError	This is thrown for an illegal operation on an Alternative.
AltingBarrierError	This is thrown for an illegal operation on an AltingBarrier.
BarrierError	This is thrown for an illegal operation on an Barrier.
JCSP_InternalError	This is thrown by an inconsistency detected in the internal structures of JCSP.
ProcessInterruptedException	This is thrown if a process is interrupted whilst blocked during synchronisation - processes should never be interrupted.

Package org.jcsp.lang Description

This provides classes and interfaces corresponding to the fundamental primitives of CSP.

Processes, Networks and Synchronisation

In JCSP, a process is an instance of a class implementing the CSProcess interface - its behaviour being determined by the implementation of its run() method. Processes may be composed in Sequence or Parallel (or PriParallel), the result of this composition being another process. Processes may also be spawned to run concurrently with the spawning process - see ProcessManager. A collection of parallel processes is called a network.

Processes encapsulate both data and algorithms. Parallel processes interact either by synchronised communication along Channels (the cleanest and simplest way) or by synchronised access to shared objects. The latter synchronisation may be achieved through channel signals or by a range of other JCSP primitives (such as Barrier, AltingBarrier, Bucket or Crew).

Channels

Channels come in two varieties: those that carry Object references and those that carry ints. For completeness, JCSP should provide channels specific to all the Java primitive types. These could trivially be added but, so far, do not seem to be needed in practice. Specialised channels, using Java generics, are easy to add and will be done soon – please mail us if you have urgent need.

Channels (from the Point of View of a Process)

Processes should drive their channels through channel ends: ChannelInput / ChannelOutput (for Object channels) and ChannelInputInt / ChannelOutputInt (for int channels). To allow choice of receiving input (see next paragraph), processes must drive their channels through AltingChannelInput / AltingChannelInputInt (rather than ChannelInput / ChannelInputInt).

Processes may passively wait for a number of events using Alternative. These events include channel inputs (AltingChannelInput / AltingChannelInputInt), channel accepts (AltingChannelAccept), alting barriers (AltingBarrier), timeouts (CSTimer) and skips (Skip). If more than one event is ready, an arbitrary, prioritised or fair choice can be made between them. The super-interface for all these ALTable events is Guard.

Channels (from the Point of View of a Network)

Actual channels must be constructed by the Parallel network builder with appropriate channel ends passed to the processes needing them (usually via their constructors). Four varieties are available for Object channels: One2OneChannel, Any2OneChannel, One2AnyChannel and Any2AnyChannel. Similarly, four varieties are available for int channels: One2OneChannelInt, Any2OneChannelInt, One2AnyChannelInt and Any2AnyChannelInt. Please note that the last two in each set are not broadcasting channels - broadcasting has to be achieved by active processes (e.g. Delta). Channels are constructed by the static manufacturing methods of the Channel class. Input and output channel ends are obtained from channels by their in() and out methods, respectively.

Note that the default semantics for all the above channels are zero-buffering and full synchronisation. This means that a writer to a channel will wait for a matching reader and vice-versa - whoever gets to the channel first will wait for its partner. Various forms of buffering can be introduced by splicing active buffer processes into these channels. However, because this is a common need, JCSP provides a range of plug-ins that can be used to create channels with the common varieties of buffering: blocking FIFO, overwriting (oldest) FIFO, overwriting (latest) FIFO and infinite FIFO. That set of plug-ins is for Object channels and comes from the org.jcsp.util package. A similar set for int channels is provided in org.jcsp.util.ints.

It is the network builder's responsibility to decide whether to use 1-1, any-1, 1-any or any-any channels and whether to incorporate buffers in them. The process designer is not concerned with these decisions - only with whether the channel is for input or output and what type of information it carries.

Call Channels

Call Channels provide a method interface for client-server communication between active processes, yet their semantics remain those of a synchronising zero-buffered channel. Without them, we would normally have to set up a pair of channels (giving bi-directional communication) and use a sequence of channel write(s) and read (at the client end) matched by a sequence of channel read(s) and write (at the server end).

The client process sees a server-specific method interface and invokes it in the normal way - however, the invocation will block until the server chooses to accept the call. The server sees the ChannelAccept interface - invoking an accept will block until the client makes a call.

The network builder constructs a server-specific actual call channel by sub-classing from one of One2OneCallChannel, Any2OneCallChannel, One2AnyCallChannel and Any2AnyCallChannel. Precise rules for making this extension are given in their documentation.

Symmetric Channels

Thanks to alting barriers (AltingBarrier), symmetric channels are now available: One2OneChannelSymmetric and One2OneChannelSymmetricInt. These work the same as ordinary channels but, in addition, their output ends can be used as guards in a choice (Alternative). It is quite safe for both the sending and receiving process to be alting on these symmetric channels.