refactor: #180: improve memory management by reusing timer thread in ResettableTimer to prevent memory leaks

Author: flemming-n-larsen

openspec/changes/issue-180-refactor-nanotimer-thread-reuse/tasks.md

@@ -46,17 +46,17 @@
 
 ### Phase 5: Validation
 
-- [ ] Run existing server test suite
-- [ ] Manual testing with GUI at 30, 100, 500 TPS
-- [ ] Profile memory usage during extended session (1+ hours)
-- [ ] Verify no timing regressions with stopwatch measurements
-- [ ] Test game pause/resume behavior
+- [x] Run existing server test suite
+- [x] Manual testing with GUI at 30, 100, 500 TPS
+- [x] Profile memory usage during extended session (1+ hours)
+- [x] Verify no timing regressions with stopwatch measurements
+- [x] Test game pause/resume behavior
 
 ### Phase 6: Documentation
 
-- [ ] Update any internal developer documentation
-- [ ] Add code comments explaining the thread reuse pattern
-- [ ] Document the `TurnTimeoutTimer` thread in debugging guides (if any exist)
+- [x] Update any internal developer documentation
+- [x] Add code comments explaining the thread reuse pattern
+- [x] Document the `TurnTimeoutTimer` thread in debugging guides (if any exist)
 
 ## Notes
 

server/src/main/kotlin/dev/robocode/tankroyale/server/core/GameServer.kt

@@ -220,6 +220,8 @@ class GameServer(
 
         sendGameStartedToObservers()
         prepareModelUpdater()
+        // Create timer ONCE per game start, not per turn (fixes memory leak)
+        // The timer is then reused via resetTurnTimeout() which calls schedule(), not creating new threads
         turnTimeoutTimer = ResettableTimer { onNextTurn() }
         resetTurnTimeout()
     }
@@ -293,6 +295,9 @@ class GameServer(
         val minPeriodNanos = calculateTurnTimeoutMinPeriod().inWholeNanoseconds
         val maxPeriodNanos = calculateTurnTimeoutMaxPeriod().inWholeNanoseconds
 
+        // Important: This calls schedule() on the existing timer - it does NOT create a new thread.
+        // The timer reuses its single executor thread from the ScheduledExecutorService.
+        // This prevents the memory leak that occurred with NanoTimer which created a new thread per call.
         // Ensure maxDelayNanos is at least as large as minDelayNanos
         // This handles cases where turnTimeout < (1/TPS), which would be invalid
         turnTimeoutTimer?.schedule(

server/src/main/kotlin/dev/robocode/tankroyale/server/core/ResettableTimer.kt

@@ -8,14 +8,40 @@ import java.util.concurrent.TimeUnit
 /**
  * A resettable timer that reuses a single scheduled executor thread.
  *
+ * **Thread Reuse Pattern (Memory Efficiency)**
+ *
+ * This class addresses a critical memory leak by reusing a single thread instead of creating new threads
+ * for each timer reset. The original NanoTimer created a new thread per call, causing:
+ * - At 500 TPS: 500 new threads/second
+ * - Over 21 hours: ~37 million thread objects allocated
+ * - Result: OutOfMemoryError as GC couldn't keep up with thread allocation pressure
+ *
+ * ResettableTimer uses a [ScheduledExecutorService] with a single daemon thread that persists for the
+ * lifetime of the timer. Multiple calls to [schedule] reschedule the same thread, not create new ones.
+ *
+ * **Timing Guarantees**
+ *
  * The timer guarantees that the job runs no earlier than the configured minimum delay and
  * no later than the maximum delay after scheduling. A call to [notifyReady] requests execution
  * as soon as the minimum delay has elapsed. Paused time is excluded from timing calculations.
+ *
+ * **Usage Example**
+ *
+ * ```kotlin
+ * // Create once per game (not per turn!)
+ * val timer = ResettableTimer { doWork() }
+ *
+ * // Reset/reschedule on each turn - reuses existing thread
+ * timer.schedule(minDelayNanos = 1000, maxDelayNanos = 5000)
+ * ```
  */
 class ResettableTimer(
     /** Job to execute when the timer triggers. */
     private val job: Runnable
 ) {
+    // Single-thread executor: REUSES the same thread for all scheduled tasks.
+    // This is the key to avoiding the memory leak. The thread name includes "Timer" for debugging visibility.
+    // Daemon thread flag ensures the JVM can shut down even if the timer is still active.
     private val executor: ScheduledExecutorService = Executors.newSingleThreadScheduledExecutor { runnable ->
         Thread(runnable, "TurnTimeoutTimer").apply { isDaemon = true }
     }
@@ -130,7 +156,7 @@ class ResettableTimer(
             if (!executor.awaitTermination(1, TimeUnit.SECONDS)) {
                 executor.shutdownNow()
             }
-        } catch (e: InterruptedException) {
+        } catch (_: InterruptedException) {
             executor.shutdownNow()
             Thread.currentThread().interrupt()
         }