1 package edu.berkeley.fleet.api;
6 * An instance of Fleet; each Fleet consists of a collection of
9 * <p><b>Note about instruction representation:</b> it is very
10 * important to understand that the binary representation of an
11 * instruction includes a path from the dock which will
12 * <i>dispatch</i> the instruction to the dock which will
13 * <i>execute</i> the instruction. Therefore, an instruction cannot
14 * be converted <i>to</i> binary form without supplying a
15 * <i>dispatching dock</i> so the necessary path can be computed.
16 * <b>Moreover:</b> because a given string of bits uniquely describes
17 * a path only if given along with a starting point, instructions
18 * cannot be converted <i>from</i> binary format without knowing the
19 * dispatch dock from which they are meant to be dispatched. <i>This
20 * is why the {@link readInstruction} and {@link writeInstruction}
21 * methods take a "<tt>dispatchFrom</tt>" argument.</i>
23 public abstract class Fleet implements Iterable<Ship> {
25 public abstract Iterator<Ship> iterator();
27 /** A ship is uniquely identified by its type (a string) and its ordinal; for example, Fifo[7]. */
28 public abstract Ship getShip(String type, int ordinal);
30 /** the natural word width of this machine */
31 public abstract int getWordWidth();
34 * Read a machine-formatted instruction from a file.
35 * @is The stream to read from.
36 * @dispatchFrom The dock from which the instructions being read are to be dispatched (required for decoding)
38 public abstract Instruction readInstruction(DataInputStream is, Dock dispatchFrom) throws IOException;
41 * Write a machine-formatted instruction to a file.
42 * @os The stream to write to.
43 * @dispatchFrom The dock from which the instruction being written is to be dispatched (required for encoding)
45 public abstract void writeInstruction(DataOutputStream os, Dock dispatchFrom, Instruction instr) throws IOException;
47 /** If supported, run the given code and create a FleetProcess to interact with it. */
48 public FleetProcess run(Instruction[] program) {
49 throw new RuntimeException("class " + this.getClass().getName() + " does not implement method run()");