src/edu/berkeley/fleet/api/Fleet.java

   1 package edu.berkeley.fleet.api;
   2 import java.io.*;
   3 import java.util.*;
   4
   5 /**
   6  *  An instance of Fleet; each Fleet consists of a collection of
   7  *  <tt>Ship</tt>s.
   8  *
   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>
  22  */
  23 public abstract class Fleet implements Iterable<Ship> {
  24
  25     public abstract Iterator<Ship> iterator();
  26
  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);
  29
  30     /** the natural word width of this machine */
  31     public abstract int getWordWidth();
  32
  33     /** the width of the immediate field in the "shift data latch" instruction */
  34     public abstract int getShiftWidth();
  35
  36     /** the width of the immediate field in the "set data latch" instruction */
  37     public abstract int getSetWidth();
  38
  39     /**
  40      *  Read a machine-formatted instruction from a file.
  41      *   @is           The stream to read from.
  42      *   @dispatchFrom The dock from which the instructions being read are to be dispatched (required for decoding)
  43      */
  44     public abstract Instruction readInstruction(DataInputStream is, Dock dispatchFrom) throws IOException;
  45
  46     /**
  47      *  Write a machine-formatted instruction to a file.
  48      *   @os           The stream to write to.
  49      *   @dispatchFrom The dock from which the instruction being written is to be dispatched (required for encoding)
  50      */
  51     public abstract void        writeInstruction(DataOutputStream os, Dock dispatchFrom, Instruction instr) throws IOException;
  52
  53     /** If supported, run the given code and create a FleetProcess to interact with it. */
  54     public FleetProcess run(Instruction[] program) {
  55         throw new RuntimeException("class " + this.getClass().getName() + " does not implement method run()");
  56     }
  57 }