add Fleet.getDefaultImpl() and use it in Makefile

[fleet.git] / src / edu / berkeley / fleet / api / Fleet.java

diff --git a/src/edu/berkeley/fleet/api/Fleet.java b/src/edu/berkeley/fleet/api/Fleet.java
index c40b2db..0e9700c 100644 (file)
--- a/src/edu/berkeley/fleet/api/Fleet.java
+++ b/src/edu/berkeley/fleet/api/Fleet.java
@@ -2,37 +2,74 @@ package edu.berkeley.fleet.api;
 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();
 
-    /**
-     *  Compute the value that should go in the MACHINE-addressed
-     *  "offset" field of a literal given BYTE-addressed origin and
-     *  target
-     */ 
-    public abstract int computeOffset(int origin, int target);
+    /** 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);
+    
     /**
-     *  Compute the value that should go in the "offset" field of a
-     *  literal given BYTE-addressed origin and MACHINE-addressed
-     *  target
-     */ 
-    public abstract int computeTarget(int origin, int offset);
+     *  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);
 
     /**
-     *  This interface marks Fleets which can create ships on the fly, like the fleeterpreter;
-     *  if available, the parser will use this interface to create ships out of #ship definitions.
+     *  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 static interface WithDynamicShips {
-        public Ship createShip(String shiptype, String shipname);
+    public abstract Instruction decodeInstruction(BitVector instruction, Dock dispatchFrom);
+
+    /** 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()");
+    }
+
+    /** Assumes that the system property "fleet.impl" holds the name of a subclass to instantiate */
+    public static Fleet getDefaultImpl() {
+        String impl = System.getProperty("fleet.impl");
+        if (impl==null) throw new RuntimeException("You must invoke the JVM with -Dfleet.impl=<impl>");
+        try {
+            return (Fleet)Class.forName(impl).newInstance();
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
     }
 
-}
\ No newline at end of file
+}