1
//////////////////////////////////////////////////////////////////////
3
// JCSP ("CSP for Java") Libraries //
4
// Copyright (C) 1996-2008 Peter Welch and Paul Austin. //
5
// 2001-2004 Quickstone Technologies Limited. //
7
// This library is free software; you can redistribute it and/or //
8
// modify it under the terms of the GNU Lesser General Public //
9
// License as published by the Free Software Foundation; either //
10
// version 2.1 of the License, or (at your option) any later //
13
// This library is distributed in the hope that it will be //
14
// useful, but WITHOUT ANY WARRANTY; without even the implied //
15
// warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
16
// PURPOSE. See the GNU Lesser General Public License for more //
19
// You should have received a copy of the GNU Lesser General //
20
// Public License along with this library; if not, write to the //
21
// Free Software Foundation, Inc., 59 Temple Place, Suite 330, //
22
// Boston, MA 02111-1307, USA. //
24
// Author contact: P.H.Welch@kent.ac.uk //
27
//////////////////////////////////////////////////////////////////////
29
package org.jcsp.lang;
32
* This defines the interface for a <i>one-to-any</i> integer channel,
33
* safe for use by one writer and many readers.
35
* The only methods provided are to obtain the <i>ends</i> of the channel,
36
* through which all reading and writing operations are done.
37
* Only an appropriate <i>channel-end</i> should be plugged into a process
38
* – not the <i>whole</i> channel.
39
* A process may use its external channels in one direction only
40
* – either for <i>writing</i> or <i>reading</i>.
42
* <P>Actual channels conforming to this interface are made using the relevant
43
* <tt>static</tt> construction methods from {@link Channel}.
44
* Channels may be {@link Channel#one2anyInt() <i>synchronising</i>},
45
* {@link Channel#one2anyInt(org.jcsp.util.ints.ChannelDataStoreInt) <i>buffered</i>},
46
* {@link Channel#one2anyInt(int) <i>poisonable</i>}
47
* or {@link Channel#one2anyInt(org.jcsp.util.ints.ChannelDataStoreInt,int) <i>both</i>}
48
* <i>(i.e. buffered and poisonable)</i>.
50
* <H2>Description</H2>
51
* <TT>One2AnyChannelInt</TT> is an interface for a channel which is safe
52
* for use by many reading processes but only one writer. Reading processes
53
* compete with each other to use the channel. Only one reader and the writer will
54
* actually be using the channel at any one time. This is managed by the
55
* channel – user processes just read from or write to it.
57
* <I>Please note that this is a safely shared channel and not
58
* a broadcaster. Currently, broadcasting has to be managed by
59
* writing an active process (see {@link org.jcsp.plugNplay.DynamicDelta}
60
* for an example).</I>
63
* All reading processes and the writing process commit to the channel
64
* (i.e. may not back off). This means that the reading processes
65
* <I>may not</I> {@link Alternative <TT>ALT</TT>} on this channel.
68
* The default semantics of the channel is that of CSP – i.e. it is
69
* zero-buffered and fully synchronised. A reading process must wait
70
* for the matching writer and vice-versa.
73
* The <tt>static</tt> methods of {@link Channel} construct channels with
74
* either the default semantics or with buffering to user-specified capacity
75
* and a range of blocking/overwriting policies.
76
* Various buffering plugins are given in the <TT>org.jcsp.util</TT> package, but
77
* <I>careful users</I> may write their own.
80
* The {@link Channel} methods also provide for the construction of
81
* {@link Poisonable} channels and for arrays of channels.
83
* <H3><A NAME="Caution">Implementation Note and Caution</H3>
84
* <I>Fair</I> servicing of readers to this channel depends on the <I>fair</I>
85
* servicing of requests to enter a <TT>synchronized</TT> block (or method) by
86
* the underlying Java Virtual Machine (JVM). Java does not specify how threads
87
* waiting to synchronize should be handled. Currently, Sun's standard JDKs queue
88
* these requests - which is <I>fair</I>. However, there is at least one JVM
89
* that puts such competing requests on a stack - which is legal but <I>unfair</I>
90
* and can lead to infinite starvation. This is a problem for <I>any</I> Java system
91
* relying on good behaviour from <TT>synchronized</TT>, not just for these
92
* <I>1-any</I> channels.
94
* @see org.jcsp.lang.Channel
95
* @see org.jcsp.lang.One2OneChannelInt
96
* @see org.jcsp.lang.Any2OneChannelInt
97
* @see org.jcsp.lang.Any2AnyChannelInt
98
* @see org.jcsp.util.ints.ChannelDataStoreInt
100
* @author P.D. Austin and P.H. Welch
102
public interface One2AnyChannelInt
105
* Returns the input end of the channel.
107
public SharedChannelInputInt in();
110
* Returns the output end of the channel.
112
public ChannelOutputInt out();