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     /** FIXME: this will soon become a property of individual memories rather than the entire Fleet */
  40     public abstract int getMaxCodeBagSize();
  41
  42     /** FIXME: this will soon become a property of individual memories rather than the entire Fleet */
  43     public abstract BitVector makeCodeBagDescriptor(long offset, long length);
  44
  45     /**
  46      *  Encodes an instruction as a BitVector
  47      *   @instruction  The instruction to encode
  48      *   @dispatchFrom The dock from which the instruction being written is to be dispatched (required for encoding)
  49      */
  50     public abstract BitVector   encodeInstruction(Instruction instruction, Dock dispatchFrom);
  51
  52     /**
  53      *  Decodes an instruction from a BitVector
  54      *   @instruction  The instruction to decode
  55      *   @dispatchFrom The dock from which the instructions being read are to be dispatched (required for decoding)
  56      */
  57     public abstract Instruction decodeInstruction(BitVector instruction, Dock dispatchFrom);
  58
  59     /** If supported, run the given code and create a FleetProcess to interact with it. */
  60     public FleetProcess run(Instruction[] program) {
  61         throw new RuntimeException("class " + this.getClass().getName() + " does not implement method run()");
  62     }
  63
  64     /** Assumes that the system property "fleet.impl" holds the name of a subclass to instantiate */
  65     public static Fleet getDefaultImpl() {
  66         String impl = System.getProperty("fleet.impl");
  67         if (impl==null) throw new RuntimeException("You must invoke the JVM with -Dfleet.impl=<impl>");
  68         try {
  69             return (Fleet)Class.forName(impl).newInstance();
  70         } catch (Exception e) {
  71             throw new RuntimeException(e);
  72         }
  73     }
  74
  75 }