Package org.jcsp.lang
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 Channel
s
(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 theParallel
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.-
Interface Summary Interface Description Any2AnyChannel<T> 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<T> Defines an interface for a connection shared by multiple clients and multiple servers.Any2OneChannel<T> 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<T> Defines an interface for a connection that can be shared by multiple concurrent clients but used by a single server.BufferedChannelArrayFactory<T> Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.BufferedChannelFactory<T> 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<T> Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.ChannelFactory<T> Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.ChannelInput<T> 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.ChannelInternals<T> ChannelInternalsInt ChannelIntFactory Deprecated. These channel factories are deprecated in favour of the new one2one() methods in the Channel class.ChannelOutput<T> 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<T> This is an interface to be implemented by classes that wish to act as a client to connect to aConnectionServer
.ConnectionFactory Defines an interface for a factory than can create connections.ConnectionServer<T> This interface should be implemented by classes that wish to act as connection servers and to accept requests fromConnectionClient
objects.ConnectionWithSharedAltingClient<T> This interface is justConnectionWithSharedAltingServer<T> CSProcess This is the JCSP interface for a process - an active component that encapsulates the data structures on which it operates.MultiwaySynchronisation One2AnyChannel<T> 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<T> An interface for a connection which can be used by only one client but which can be used by multiple concurrent servers.One2OneChannel<T> This defines the interface for a one-to-one Object channel.One2OneChannelInt This defines the interface for a one-to-one integer channel.One2OneChannelSymmetric<T> 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<T> 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 seePoisonException
.RejectableChannelInput Deprecated. This channel is superceded by the poison mechanisms, please seePoisonException
.RejectableChannelOutput Deprecated. This channel is superceded by the poison mechanisms, please seePoisonException
.SharedChannelInput<T> This is the same asChannelInput
except that it is guaranteed safe to pass on to more than one internal process for parallel reading.SharedChannelInputInt This is the same asChannelInputInt
except that it is guaranteed safe to pass on to more than one internal process for parallel reading.SharedChannelOutput<T> This is the same asChannelOutput
except that it is guaranteed safe to pass on to more than one internal process for parallel writing.SharedChannelOutputInt This is the same asChannelOutputInt
except that it is guaranteed safe to pass on to more than one internal process for parallel writing.SharedConnectionClient<T> Defines an interface for a client end of a connection that can be shared by multiple clients.SharedConnectionServer<T> Defines an interface for a server end of a connection that can be shared by multiple concurrent processes. -
Class Summary Class Description AbstractConnectionImpl AbstractConnectionImpl.NonSingleRequestOpenMsg Alternative This enables a process to wait passively for and choose between a number ofGuard
events.AltingBarrier This is the front-end for a barrier that can be used as aGuard
in anAlternative
.AltingBarrierBase AltingBarrierCoordinate AltingChannelAccept This extendsGuard
andChannelAccept
to enable a process to choose between many CALL channel (and other) events.AltingChannelInput<T> This extendsGuard
andChannelInput
to enable a process to choose between many object input (and other) events.AltingChannelInputImpl<T> AltingChannelInputInt This extendsGuard
andChannelInputInt
to enable a process to choose between many integer input (and other) events.AltingChannelInputIntImpl AltingChannelInputIntSymmetricImpl AltingChannelInputSymmetricImpl<T> AltingChannelInputWrapper<T> Deprecated. There is no longer any need to use this class, after the 1.1 class reorganisation.AltingChannelOutput<T> This extendsGuard
andChannelOutput
to enable a process to choose between many integer output (and other) events.AltingChannelOutputInt This extendsGuard
andChannelOutputInt
to enable a process to choose between many integer output (and other) events.AltingChannelOutputIntSymmetricImpl AltingChannelOutputSymmetricImpl<T> AltingConnectionClient<T> This class is sub-classed by JCSP.NET classes to provideConnectionClient
objects which can have theirreceive()
method alted over.AltingConnectionClientImpl<T> This class does not need to be used by standard JCSP users.AltingConnectionServer<T> An interface to connection.AltingConnectionServerImpl<T> 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.Any2AnyChannelImpl<T> This implements an any-to-any object channel, safe for use by many writers and many readers.Any2AnyChannelIntImpl This implements an any-to-any integer channel, safe for use by many writers and many readers.Any2AnyConnectionImpl<T> This class is an implementation ofAny2AnyConnection
.Any2AnyImpl<T> Any2AnyIntImpl Any2OneCallChannel This is the super-class for any-to-one interface-specific CALL channels, safe for use by many clients and one server.Any2OneChannelImpl<T> This implements an any-to-one object channel, safe for use by many writers and one reader.Any2OneChannelIntImpl This implements an any-to-one integer channel, safe for use by many writers and one reader.Refer to theAny2OneChannelInt
interface for a fuller description.Any2OneConnectionImpl<T> This class is an implementation ofAny2OneConnection
.Any2OneImpl<T> Any2OneIntImpl Barrier This enables barrier synchronisation between a set of processes.BasicOne2OneChannelSymmetric<T> BasicOne2OneChannelSymmetricInt BlackHoleChannel This implementsChannelOutput
with black hole semantics.BlackHoleChannelInt This implementsChannelOutputInt
with black hole semantics.Bucket This enables bucket synchronisation between a set of processes.BufferedAny2AnyChannel<T> This implements an any-to-any object channel with user-definable buffering, safe for use by many writers and many readers.BufferedAny2AnyChannelIntImpl This implements an any-to-any integer channel with user-definable buffering, safe for use by many writers and many readers.BufferedAny2OneChannel<T> This implements an any-to-one object channel with user-definable buffering, safe for use by many writers and one reader.BufferedAny2OneChannelIntImpl This implements an any-to-one integer channel with user-definable buffering, safe for use by many writers and one reader.BufferedOne2AnyChannel<T> This implements an any-to-any object channel with user-definable buffering, safe for use by many writers and many readers.BufferedOne2AnyChannelIntImpl This implements a one-to-any integer channel with user-definable buffering, safe for use by many writers and many readers.BufferedOne2OneChannel<T> This implements a one-to-one object channel with user-definable buffering.BufferedOne2OneChannelIntImpl This implements a one-to-one integer channel with user-definable buffering.Channel This class provides static factory methods for constructing all the different types of channel.ChannelInputImpl<T> ChannelInputIntImpl 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.ChannelOutputImpl<T> ChannelOutputIntImpl 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.ConnectionClientMessage<T> ConnectionClientOpenMessage<T> ConnectionMessage<T> ConnectionServerMessage<T> Crew This provides a Concurrent Read Exclusive Write (CREW) lock for synchronising fair and secure access to a shared resource.CrewServer CSTimer This is aGuard
for setting timeouts in anAlternative
.Guard This is the super-class for allAlternative
events selectable by a process.InlineAlternative This class is experimental (i.e.Mutex A package-visible class that implements a straightforward mutex, for use by One2AnyChannel and Any2AnyChannelOne2AnyCallChannel This is the super-class for one-to-any interface-specific CALL channels, safe for use by one client and many servers.One2AnyChannelImpl<T> This implements a one-to-any object channel, safe for use by one writer and many readers.One2AnyChannelIntImpl This implements a one-to-any integer channel, safe for use by one writer and many readers.One2AnyConnectionImpl<T> This class is an implementation ofOne2AnyConnection
.One2AnyImpl<T> One2AnyIntImpl One2OneCallChannel This is the super-class for one-to-one interface-specific CALL channels.One2OneChannelImpl<T> This implements a one-to-one object channel.One2OneChannelIntImpl This implements a one-to-one integer channel.One2OneConnectionImpl<T> This class is an implementation ofOne2OneConnection
.Parallel This process constructor taks an array of CSProcesses and returns a CSProcess that is the parallel composition of its process arguments.ParThread This is the Thread class used byParallel
to run all but one of its given processes.PoisonableAny2AnyChannelImpl<T> PoisonableAny2AnyChannelIntImpl PoisonableAny2OneChannelImpl<T> PoisonableAny2OneChannelIntImpl PoisonableBufferedAny2AnyChannel<T> PoisonableBufferedAny2AnyChannelInt PoisonableBufferedAny2OneChannel<T> PoisonableBufferedAny2OneChannelInt PoisonableBufferedOne2AnyChannel<T> PoisonableBufferedOne2AnyChannelInt PoisonableBufferedOne2OneChannel<T> This implements a one-to-one object channel with user-definable buffering.PoisonableBufferedOne2OneChannelInt PoisonableOne2AnyChannelImpl<T> PoisonableOne2AnyChannelIntImpl PoisonableOne2OneChannelImpl<T> This implements a one-to-one object channel.PoisonableOne2OneChannelIntImpl PriParallel This is an extension of theParallel
class that prioritises the processes given to its control.ProcessManager This enables aCSProcess
to be spawned concurrently with the process doing the spawning.RejectableAltingChannelInput Deprecated. This channel is superceded by the poison mechanisms, please seePoisonException
RejectableAltingChannelInputImpl RejectableBufferedOne2AnyChannel Deprecated. This channel is superceded by the poison mechanisms, please seePoisonException
RejectableBufferedOne2OneChannel Deprecated. This channel is superceded by the poison mechanisms, please seePoisonException
RejectableChannelInputImpl RejectableChannelOutputImpl RejectableOne2AnyChannel Deprecated. This channel is superceded by the poison mechanisms, please seePoisonException
.RejectableOne2OneChannel Deprecated. This channel is superceded by the poison mechanisms, please seePoisonException
.Sequence This constructor taks an array of CSProcesses and returns a CSProcess that is the sequential composition of its process arguments.SharedAltingConnectionClient<T> Implements a client end of a Connection which can have multiple client processes.SharedChannelInputImpl<T> SharedChannelInputIntImpl SharedChannelOutputImpl<T> SharedChannelOutputIntImpl SharedConnectionServerImpl This class does not need to be used by standard JCSP users.Skip This is a process that immediately terminates and aGuard
that is always ready.Spurious This holds the static flag (indicating whether spurious wakeups should be logged) and early timeout allowance (forAlternative
s withCSTimer
guards).SpuriousLog This holds the log of spurious wakeups and early timeouts.StandardChannelFactory<T> 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 Exception Description ChannelDataRejectedException Thrown by aread
or awrite
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 Error Description AlternativeError This is thrown for an illegal operation on an Alternative.AltingBarrierError This is thrown for an illegal operation on anAltingBarrier
.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.