import java.io.*;
import java.util.*;
+/**
+ * An instance of Fleet; each Fleet consists of a collection of
+ * <tt>Ship</tt>s.
+ *
+ * <p><b>Note about instruction representation:</b> it is very
+ * important to understand that the binary representation of an
+ * instruction includes a path from the dock which will
+ * <i>dispatch</i> the instruction to the dock which will
+ * <i>execute</i> the instruction. Therefore, an instruction cannot
+ * be converted <i>to</i> binary form without supplying a
+ * <i>dispatching dock</i> so the necessary path can be computed.
+ * <b>Moreover:</b> because a given string of bits uniquely describes
+ * a path only if given along with a starting point, instructions
+ * cannot be converted <i>from</i> binary format without knowing the
+ * dispatch dock from which they are meant to be dispatched. <i>This
+ * is why the {@link readInstruction} and {@link writeInstruction}
+ * methods take a "<tt>dispatchFrom</tt>" argument.</i>
+ */
public abstract class Fleet implements Iterable<Ship> {
- /** read a machine-formatted instruction from a file (into a Java object) */
- public abstract Instruction readInstruction(DataInputStream is) throws IOException;
+ public abstract Iterator<Ship> iterator();
- /** write a machine-formatted instruction to a file (from a Java object) */
- public abstract void writeInstruction(DataOutputStream os, Instruction instr) throws IOException;
+ /** A ship is uniquely identified by its type (a string) and its ordinal; for example, Fifo[7]. */
+ public abstract Ship getShip(String type, int ordinal);
- /** ships must be returned in the same order every time -- ordering may be significant */
- public abstract Iterator<Ship> iterator();
+ /** the natural word width of this machine */
+ public abstract int getWordWidth();
+
+ /** the width of the immediate field in the "shift data latch" instruction */
+ public abstract int getShiftWidth();
+
+ /** the width of the immediate field in the "set data latch" instruction */
+ public abstract int getSetWidth();
+
+ /** FIXME: this will soon become a property of individual memories rather than the entire Fleet */
+ public abstract int getMaxCodeBagSize();
+
+ /** FIXME: this will soon become a property of individual memories rather than the entire Fleet */
+ public abstract BitVector makeCodeBagDescriptor(long offset, long length);
+
+ /**
+ * Encodes an instruction as a BitVector
+ * @instruction The instruction to encode
+ * @dispatchFrom The dock from which the instruction being written is to be dispatched (required for encoding)
+ */
+ public abstract BitVector encodeInstruction(Instruction instruction, Dock dispatchFrom);
+
+ /**
+ * Decodes an instruction from a BitVector
+ * @instruction The instruction to decode
+ * @dispatchFrom The dock from which the instructions being read are to be dispatched (required for decoding)
+ */
+ public abstract Instruction decodeInstruction(BitVector instruction, Dock dispatchFrom);
-}
\ No newline at end of file
+ /** If supported, run the given code and create a FleetProcess to interact with it. */
+ public FleetProcess run(Instruction[] program) {
+ throw new RuntimeException("class " + this.getClass().getName() + " does not implement method run()");
+ }
+}