Fixed condition for waiting for bot to finish (instead of returning control immediately always). Improved some metrics

Author: dgant

src/main/java/bwapi/BWClient.java

@@ -8,6 +8,7 @@
 public class BWClient {
     private final BWEventListener eventListener;
     private BotWrapper botWrapper;
+    private Client client;
     private PerformanceMetrics performanceMetrics;
 
     public BWClient(final BWEventListener eventListener) {
@@ -31,6 +32,13 @@ public PerformanceMetrics getPerformanceMetrics() {
         return performanceMetrics;
     }
 
+    /**
+     * Number of frames
+     */
+    public int framesBehind() {
+        return botWrapper == null ? 0 : client.clientData().gameData().getFrameCount() - getGame().getFrameCount();
+    }
+
     public void startGame() {
         BWClientConfiguration configuration = new BWClientConfiguration();
         startGame(configuration);
@@ -57,7 +65,7 @@ public void startGame(BWClientConfiguration configuration) {
         configuration.validate();
         botWrapper = new BotWrapper(configuration, eventListener);
 
-        Client client = new Client(configuration);
+        client = new Client(configuration);
         client.reconnect();
 
         do {
@@ -73,16 +81,16 @@ public void startGame(BWClientConfiguration configuration) {
                 }
             }
             while (liveGameData.isInGame()) {
-                performanceMetrics.totalFrameDuration.time(() -> {
-                    botWrapper.onFrame();
-                    performanceMetrics.flushSideEffects.time(() -> {
-                        getGame().sideEffects.flushTo(liveGameData);
-                    });
-                    client.update();
-                    if (!client.isConnected()) {
-                        client.reconnect();
-                    }
-                });
+                if (liveGameData.getFrameCount() > 0 || ! configuration.unlimitedFrameZero) {
+                    performanceMetrics.totalFrameDuration.startTiming();
+                }
+                botWrapper.onFrame();
+                performanceMetrics.flushSideEffects.time(() -> getGame().sideEffects.flushTo(liveGameData));
+                client.update();
+                if (!client.isConnected()) {
+                    client.reconnect();
+                }
+                performanceMetrics.totalFrameDuration.stopTiming();
             }
             botWrapper.endGame();
         } while (configuration.autoContinue);

src/main/java/bwapi/BWClientConfiguration.java

@@ -15,6 +15,16 @@ public class BWClientConfiguration {
      */
     public boolean autoContinue = false;
 
+    /**
+     * Most bot tournaments allow bots to take an indefinite amount of time on frame #0 (the first frame of the game) to analyze the map and load data,
+     * as the bot has no prior access to BWAPI or game information.
+     *
+     * This flag indicates that taking arbitrarily long on frame zero is acceptable.
+     * Performance metrics omit the frame as an outlier.
+     * Asynchronous operation will block until the bot's event handlers are complete.
+     */
+    public boolean unlimitedFrameZero = true;
+
     /**
      * Runs the bot in asynchronous mode. Asynchronous mode helps attempt to ensure that the bot adheres to real-time performance constraints.
      *
@@ -32,29 +42,14 @@ public class BWClientConfiguration {
      * If JBWAPI detects that this much time (in nanoseconds) has passed since a bot's event handlers began, returns control back to BWAPI.
      * Real-time human play typically uses the "fastest" game speed, which has 42.86ms (42,860ns) between frames.
      */
-    public int asyncFrameDurationMs = 40000;
+    public int asyncFrameDurationMs = 40;
 
     /**
      * The maximum number of frames to buffer while waiting on a bot.
      * Each frame buffered adds about 33 megabytes to JBWAPI's memory footprint.
      */
     public int asyncFrameBufferSize = 10;
 
-    /**
-     * Most bot tournaments allow bots to take an indefinite amount of time on frame #0 (the first frame of the game) to analyze the map and load data,
-     * as the bot has no prior access to BWAPI or game information.
-     *
-     * This flag causes JBWAPI to wait for the bot's event handlers to return on the first frame of the game, even if operating in asynchronous mode,
-     * respecting the time bots are typically allowed on frame 0.
-     */
-    public boolean asyncWaitOnFrameZero = true;
-
-    /**
-     * Enables collection of diagnostics.
-     * When timersEnabled, JBWAPI collects and publishes performance metrics.
-     */
-    public boolean collectPerformanceMetrics = false;
-
     /**
      * Checks that the configuration is in a valid state. Throws an IllegalArgumentException if it isn't.
      */

src/main/java/bwapi/BotWrapper.java

@@ -78,23 +78,29 @@ void onFrame() {
                 botThread.setName("JBWAPI Bot");
                 botThread.start();
             }
-            performanceMetrics.copyingToBuffer.time(frameBuffer::enqueueFrame);
+            /*
+            Add a frame to buffer
+                If buffer is full, it will wait until it has capacity
+            Wait for empty buffer OR termination condition
+             */
+            boolean isFrameZero = liveClientData.gameData().getFrameCount() == 0;
+            frameBuffer.enqueueFrame();
+            performanceMetrics.bwapiResponse.startTiming();
             frameBuffer.lockSize.lock();
             try {
-                while (frameBuffer.empty()) {
-                    performanceMetrics.bwapiResponse.startTiming();
-                    if (configuration.asyncWaitOnFrameZero && liveClientData.gameData().getFrameCount() == 0) {
+                while (!frameBuffer.empty()) {
+                    if (configuration.unlimitedFrameZero && isFrameZero) {
                         frameBuffer.conditionSize.await();
                     } else {
                         long remainingNanos = endNanos - System.nanoTime();
                         if (remainingNanos <= 0) break;
                         frameBuffer.conditionSize.awaitNanos(remainingNanos);
                     }
                 }
-                performanceMetrics.bwapiResponse.stopTiming();
             } catch(InterruptedException ignored) {
             } finally {
                 frameBuffer.lockSize.unlock();
+                performanceMetrics.bwapiResponse.stopTiming();
             }
         } else {
             handleEvents();
@@ -135,7 +141,7 @@ private Thread createBotThread() {
 
     private void handleEvents() {
         ClientData.GameData gameData = game.clientData().gameData();
-        if (gameData.getFrameCount() > 0 || ! configuration.asyncWaitOnFrameZero) {
+        if (gameData.getFrameCount() > 0 || ! configuration.unlimitedFrameZero) {
             performanceMetrics.botResponse.startTiming();
         }
         for (int i = 0; i < gameData.getEventCount(); i++) {

src/main/java/bwapi/FrameBuffer.java

@@ -119,10 +119,13 @@ void enqueueFrame() {
                 }
                 performanceMetrics.intentionallyBlocking.stopTiming();
             } finally { lockSize.unlock(); };
-            ByteBuffer dataTarget = dataBuffer.get(indexGame());
-            dataSource.rewind();
-            dataTarget.rewind();
-            dataTarget.put(dataSource);
+
+            performanceMetrics.copyingToBuffer.time(() -> {
+                ByteBuffer dataTarget = dataBuffer.get(indexGame());
+                dataSource.rewind();
+                dataTarget.rewind();
+                dataTarget.put(dataSource);
+            });
 
             lockSize.lock();
             try {

src/main/java/bwapi/PerformanceMetric.java

@@ -5,7 +5,6 @@
 public class PerformanceMetric {
     private final String name;
     private final long maxAllowed;
-    public final boolean timerEnabled;
 
     public double minValue = Long.MAX_VALUE;
     public double maxValue = Long.MIN_VALUE;
@@ -17,10 +16,9 @@ public class PerformanceMetric {
 
     private long timeStarted = 0;
 
-    PerformanceMetric(String name, long maxAllowed, boolean timerEnabled) {
+    PerformanceMetric(String name, long maxAllowed) {
         this.name = name;
         this.maxAllowed = maxAllowed;
-        this.timerEnabled = timerEnabled;
     }
 
     void time(Runnable runnable) {
@@ -30,15 +28,13 @@ void time(Runnable runnable) {
     }
 
     void startTiming() {
-        if (!timerEnabled) return;
         if (timeStarted > 0) {
             ++interrupted;
         }
         timeStarted = System.nanoTime();
     }
 
     void stopTiming() {
-        if (!timerEnabled) return;
         if (timeStarted <= 0) return;
         // Use nanosecond resolution timer, but record in units of milliseconds.
         long timeEnded = System.nanoTime();

src/main/java/bwapi/PerformanceMetrics.java

@@ -45,31 +45,24 @@ public class PerformanceMetrics {
      */
     public PerformanceMetric bwapiResponse;
 
-    /**
-     * Whether performance timers have been enabled in the JBWAPI configuration.
-     * Timers are off by default to spare performance.
-     */
-    public final boolean timersEnabled;
-
     /**
      * Time bot spends idle.
      * Applicable only in asynchronous mode.
      */
     public PerformanceMetric botIdle;
 
     public PerformanceMetrics(BWClientConfiguration configuration) {
-        timersEnabled = configuration.collectPerformanceMetrics;
         final int frameDurationBufferMs = 5;
         final int sideEffectsBufferMs = 1;
         final int realTimeFrameMs = 42;
-        totalFrameDuration = new PerformanceMetric("Total frame duration", configuration.asyncFrameDurationMs + frameDurationBufferMs, timersEnabled);
-        copyingToBuffer = new PerformanceMetric("Time copying to buffer", 5, timersEnabled);
-        intentionallyBlocking = new PerformanceMetric("Intentionally blocking", 0, timersEnabled);
-        frameBufferSize = new PerformanceMetric("Frames buffered", 0, timersEnabled);
-        flushSideEffects = new PerformanceMetric("Flush side effects", sideEffectsBufferMs , timersEnabled);
-        botResponse = new PerformanceMetric("Bot Responses", configuration.asyncFrameDurationMs, timersEnabled);
-        bwapiResponse = new PerformanceMetric("BWAPI Responses", realTimeFrameMs, timersEnabled);
-        botIdle = new PerformanceMetric("Bot idle", Long.MAX_VALUE, timersEnabled);
+        totalFrameDuration = new PerformanceMetric("Total frame duration", configuration.asyncFrameDurationMs + frameDurationBufferMs);
+        copyingToBuffer = new PerformanceMetric("Time copying to buffer", 5);
+        intentionallyBlocking = new PerformanceMetric("Intentionally blocking", 0);
+        frameBufferSize = new PerformanceMetric("Frames buffered", 0);
+        flushSideEffects = new PerformanceMetric("Flush side effects", sideEffectsBufferMs );
+        botResponse = new PerformanceMetric("Bot Responses", configuration.asyncFrameDurationMs);
+        bwapiResponse = new PerformanceMetric("BWAPI Responses", realTimeFrameMs);
+        botIdle = new PerformanceMetric("Bot idle", Long.MAX_VALUE);
     }
 
     @Override