← Back to branch summary

~ubuntu-branches/ubuntu/precise/jcsp/precise

« back to all changes in this revision

Viewing changes to src/org/jcsp/lang/One2AnyCallChannel.java

  • Committer: Bazaar Package Importer
  • Author(s): Miguel Landaeta
  • Date: 2010-06-20 18:12:26 UTC
  • Revision ID: james.westby@ubuntu.com-20100620181226-8yg8d9rjjjiuy7oz
Tags: upstream-1.1-rc4
Import upstream version 1.1-rc4

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/org/jcsp/lang/One2AnyCallChannel.java
 
1
    //////////////////////////////////////////////////////////////////////
 
2
    //                                                                  //
 
3
    //  JCSP ("CSP for Java") Libraries                                 //
 
4
    //  Copyright (C) 1996-2008 Peter Welch and Paul Austin.            //
 
5
    //                2001-2004 Quickstone Technologies Limited.        //
 
6
    //                                                                  //
 
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       //
 
11
    //  version.                                                        //
 
12
    //                                                                  //
 
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     //
 
17
    //  details.                                                        //
 
18
    //                                                                  //
 
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.                                     //
 
23
    //                                                                  //
 
24
    //  Author contact: P.H.Welch@kent.ac.uk                             //
 
25
    //                                                                  //
 
26
    //                                                                  //
 
27
    //////////////////////////////////////////////////////////////////////
 
28
 
 
29
package org.jcsp.lang;
 
30
 
 
31
import java.io.Serializable;
 
32
 
 
33
/**
 
34
 * This is the super-class for one-to-any <TT>interface</TT>-specific CALL channels,
 
35
 * safe for use by one client and many servers.
 
36
 * <P>
 
37
 * <A HREF="#constructor_summary">Shortcut to the Constructor and Method Summaries.</A>
 
38
 *
 
39
 * <H2>Description</H2>
 
40
 * Please see {@link One2OneCallChannel} for general information about CALL channels.
 
41
 * Documented here is information specific to this <I>1-any</I> version.
 
42
 *
 
43
 * <H3><A NAME="Convert">Converting a Method Interface into a Variant CALL Channel</H3>
 
44
 * Constructing a <I>1-any</I> CALL channel for a specific <TT>interface</TT>
 
45
 * follows exactly the same pattern as in the <I>1-1</I> case.  Of course, it must
 
46
 * extend <TT>One2AnyCallChannel</TT> rather than <TT>One2OneCallChannel</TT>.
 
47
 * <P>
 
48
 * For example, using the same <A HREF="One2OneCallChannel.html#Foo"><TT>Foo</TT></A>
 
49
 * interface as before, we derive:
 
50
 * <PRE>
 
51
 * import org.jcsp.lang.*;
 
52
 * <I></I>
 
53
 * public class One2AnyFooChannel extends One2AnyCallChannel implements Foo {
 
54
 * <I></I>
 
55
 *   ...  same body as <A HREF="One2OneCallChannel.html#One2OneFooChannel"><TT>One2OneFooChannel</TT></A>
 
56
 * <I></I>
 
57
 * }
 
58
 * </PRE>
 
59
 *
 
60
 * <H3><A NAME="Call">Calling a CALL Channel</H3>
 
61
 * All the <I>client</I> needs to see is the method <TT>interface</TT>
 
62
 * implemented by the CALL channel.  So far as the <I>client</I> is concerned, therefore,
 
63
 * there is <I>no</I> difference between any of the varieties of CALL channel
 
64
 * - it just <A HREF="One2OneCallChannel.html#Call">makes the call</A>.
 
65
 *
 
66
 * <H3><A NAME="Accept">Accepting a CALL Channel</H3>
 
67
 * The mechanics of accepting a CALL channel are the same for all varieties.
 
68
 * However, the <I>server</I> should declare which kind (or kinds) it allows
 
69
 * to be attached:
 
70
 * <PRE>
 
71
 * import org.jcsp.lang.*;
 
72
 * <I></I>
 
73
 * class B implements CSProcess, Foo {
 
74
 * <I></I>
 
75
 *   private final ChannelAccept in;
 
76
 * <I></I>
 
77
 *   public B (final One2OneFooChannel in) {         // original constructor
 
78
 *     this.in = in;
 
79
 *   }
 
80
 * <I></I>
 
81
 *   public B (final One2AnyFooChannel in) {        // additional constructor
 
82
 *     this.in = in;
 
83
 *   }
 
84
 * <I></I>
 
85
 *   ...  rest <A HREF="One2OneCallChannel.html#Accept">as before</A>
 
86
 * <I></I>
 
87
 * }
 
88
 * </PRE>
 
89
 * When wrapping the above to hide its raw method interface, don't forget to include
 
90
 * the extra constructor(s):
 
91
 * <PRE>
 
92
 * import org.jcsp.lang.*;
 
93
 * <I></I>
 
94
 * public class B2 implements CSProcess {            // no Foo interface
 
95
 * <I></I>
 
96
 *   private final B b;
 
97
 * <I></I>
 
98
 *   public B2 (final One2OneFooChannel in) {        // original constructor
 
99
 *     b = new B (in);
 
100
 *   }
 
101
 * <I></I>
 
102
 *   public B2 (final One2AnyFooChannel in) {       // additional constructor
 
103
 *     b = new B (in);
 
104
 *   }
 
105
 * <I></I>
 
106
 *   public void run () {
 
107
 *     b.run ();
 
108
 *   }
 
109
 * <I></I>
 
110
 * }
 
111
 * </PRE>
 
112
 *
 
113
 * <H3><A NAME="ALTing">ALTing on a CALL Channel</H3>
 
114
 * As for <I>ordinary</I> channels, ALTing over <I>1-Any</I> or <I>Any-Any</I> versions
 
115
 * is not supported.  Hence, a server can only choose to {@link #accept <TT>accept</TT>}
 
116
 * or not to <TT>accept</TT> a <TT>One2AnyFooChannel</TT> - it cannot back off because
 
117
 * of some other event.
 
118
 *
 
119
 * <H3><A NAME="Network">Building a CALL Channel Network</H3>
 
120
 * Network building with CALL channels is the same as building with <I>ordinary</I>
 
121
 * channels.  First construct the channels and, then, construct the processes
 
122
 * - plugging in the channels as required and running them in {@link Parallel}.
 
123
 * <P>
 
124
 * For example, the network consisting of one <I>client</I> and several <I>servers</I>:
 
125
 * <p><IMG SRC="doc-files\One2AnyCallChannel1.gif"></p>
 
126
 * where <TT>A</TT> is unchanged from its definition
 
127
 * in <A HREF="One2OneCallChannel.html#Call"><TT>One2OneCallChannel</TT></A>,
 
128
 * is implemented by:
 
129
 * <PRE>
 
130
 *     One2AnyFooChannel c = new One2AnyFooChannel ();
 
131
 * <I></I>
 
132
 *     final B2[] bServers = new B2[n_bClients];
 
133
 *     for (int i = 0; i < bServers.length; i++) {
 
134
 *       bServers[i] = new B2 (c);
 
135
 *     }
 
136
 * <I></I>
 
137
 *     new Parallel (
 
138
 *       new CSProcess[] {
 
139
 *         new A (c),
 
140
 *         new Parallel (bServers)
 
141
 *       }
 
142
 *     ).run ();
 
143
 * </PRE>
 
144
 * [Reminder: <I>XXX-any</I> channels are not broadcasters of information.
 
145
 * In the above, when <TT>A</TT> makes a CALL on <TT>c</TT>, it must not care
 
146
 * <I>which</I> of the <TT>B2</TT> servers picks it up.  The servers compete
 
147
 * with each other to service the client.]
 
148
 *
 
149
 * <H2><A NAME="Example">Example</H2>
 
150
 * Please see <A HREF="Any2AnyCallChannel.html#Example"><TT>Any2AnyCallChannel</TT></A>
 
151
 * for an example that includes many <I>clients</I> and many <I>servers</I> competing for
 
152
 * each other's attention.
 
153
 *
 
154
 * @see org.jcsp.lang.One2OneCallChannel
 
155
 * @see org.jcsp.lang.Any2OneCallChannel
 
156
 * @see org.jcsp.lang.Any2AnyCallChannel
 
157
 * @see org.jcsp.lang.Alternative
 
158
 *
 
159
 * @author P.H. Welch
 
160
 */
 
161
 
 
162
public abstract class One2AnyCallChannel implements ChannelAccept, Serializable
 
163
{
 
164
    /**
 
165
     * This is used to synchronise the calling and accepting process.
 
166
     */
 
167
    final private One2OneChannelImpl c = new One2OneChannelImpl();
 
168
 
 
169
    /**
 
170
     * This holds a reference to a <I>server</I> process so that a <I>client</I> may
 
171
     * make the call.  The reference is only valid between the {@link #join <TT>join</TT>}
 
172
     * and {@link #fork <TT>fork</TT>} elements of the standard
 
173
     * <A HREF="One2OneCallChannel.html#One2OneFooChannel">calling sequence</A>.
 
174
     * As shown in that sequence, it will need casting up to the relevant interface
 
175
     * supported by the specific CALL channel derived from this class.
 
176
     */
 
177
    protected CSProcess server;
 
178
 
 
179
    /**
 
180
     * This may be set during the standard <A HREF="One2OneCallChannel.html#One2OneFooChannel">calling sequence</A> to record
 
181
     * which method was invoked by a <I>client</I>.  It is only safe to do this between
 
182
     * the {@link #join <TT>join</TT>} and {@link #fork <TT>fork</TT>} elements of
 
183
     * that sequence.  Either <I>all</I> the CALL
 
184
     * channel methods should do this or <I>none</I> - in the latter case, its default
 
185
     * value remains as zero.  Its value is returned to a <I>server</I> as the result
 
186
     * the <I>server</I>'s invocation of {@link #accept <TT>accept</TT>}.
 
187
     */
 
188
    protected int selected = 0;
 
189
 
 
190
    /**
 
191
     * This is invoked by a <I>server</I> when it commits to accepting a CALL
 
192
     * from a <I>client</I>.  The parameter supplied must be a reference to this <I>server</I>
 
193
     * - see the <A HREF="One2OneCallChannel.html#Accept">example</A> from {@link One2OneCallChannel}.
 
194
     * It will not complete until a CALL has been made.  If the derived CALL channel has set
 
195
     * the {@link #selected} field in the way defined by the standard
 
196
     * <A HREF="One2OneCallChannel.html#One2OneFooChannel">calling sequence</A>,
 
197
     * the value returned by this method will indicate which method was called.
 
198
     *
 
199
     * @param server the <I>server</I> process receiving the CALL.
 
200
     */
 
201
    public synchronized int accept(CSProcess server)
 
202
    {
 
203
        this.server = server;
 
204
        c.read(); // ready to ACCEPT the CALL
 
205
        c.read(); // wait until the CALL is complete
 
206
        return selected;
 
207
    }
 
208
 
 
209
    /**
 
210
     * This is invoked by a <I>client</I> during the standard <A HREF="One2OneCallChannel.html#One2OneFooChannel">calling
 
211
     * sequence</A>.  It will not complete until a <I>server</I> invokes
 
212
     * an {@link #accept <TT>accept</TT>} on this channel.  In turn, that <TT>accept</TT>
 
213
     * will not complete until the <I>client</I> invokes a {@link #fork <TT>fork</TT>},
 
214
     * after having made its CALL on the <I>server</I>.
 
215
     */
 
216
    protected void join()
 
217
    {
 
218
        c.write(null);
 
219
    }
 
220
 
 
221
    /**
 
222
     * This is invoked by a <I>client</I> during the standard <A HREF="One2OneCallChannel.html#One2OneFooChannel">calling
 
223
     * sequence</A>.  A <I>server</I> must have invoked an {@link #accept <TT>accept</TT>}
 
224
     * for the <I>client</I> to have got this far in the sequence - see
 
225
     * the {@link #join <TT>join</TT>}.  This call unblocks that <TT>accept</TT>,
 
226
     * releasing the <I>server</I> and <I>client</I> to resume separate lives.
 
227
     */
 
228
    protected void fork()
 
229
    {
 
230
        c.write(null);
 
231
    }
 
232
}