Timescale comments

Author: prdoyle

bosk-mongo/src/main/java/works/bosk/drivers/mongo/MongoDriverSettings.java

@@ -15,10 +15,16 @@ public class MongoDriverSettings {
 	String database;
 
 	/**
-	 * The general responsiveness of the system. Changes to the database will be
-	 * "noticed" in about this many milliseconds, and other time-related behaviours
-	 * will be scaled accordingly. Lower values are more responsive, while higher
-	 * values are more efficient because they'll do less polling.
+	 * The general responsiveness of the system under unusual circumstances.
+	 * Changes to the database connectivity and status will be "noticed"
+	 * in about this many milliseconds, and other time-related behaviours
+	 * are scaled accordingly.
+	 * Lower values recover more quickly, but will also give up sooner
+	 * and cause more network traffic;
+	 * higher values are more patient and efficient, but slower to recover.
+	 * <p>
+	 * Under normal circumstances, the system responds promptly
+	 * and efficiently regardless of this setting.
 	 * <p>
 	 * For test cases,
 	 *
@@ -32,6 +38,9 @@ public class MongoDriverSettings {
 	 *         to avoid spurious test failures.
 	 *     </li>
 	 * </ul>
+	 *
+	 * In Bosk's own tests, we use even more extreme values to ensure
+	 * this works across a wide range of values.
 	 */
 	@Default int timescaleMS = 1000;
 

bosk-mongo/src/test/java/works/bosk/drivers/mongo/internal/MongoDriverRecoveryTest.java

@@ -136,7 +136,7 @@ void initialOutage_recovers() throws InvalidTypeException, InterruptedException,
 
 		LOGGER.debug("Wait and check that the state updates");
 		// With FLUSH this succeeds almost immediately.
-		// With WAIT it is artificially delayed.
+		// With WAIT, it is artificially delayed.
 		waitFor(driver);
 		try (var _ = bosk.readContext()) {
 			assertEquals(initialState, bosk.rootReference().value(),
@@ -253,6 +253,9 @@ void revisionDeleted_recovers() throws InterruptedException, IOException {
 		Bosk<TestEntity> bosk = new Bosk<>(boskName(getClass().getSimpleName()), TestEntity.class, AbstractMongoDriverTest::initialRoot, BoskConfig.<TestEntity>builder().driverFactory(driverFactory).build());
 
 		try (var _ = bosk.readContext()) {
+			// This can fail on very short timescales; see testRecovery.
+			// This isn't related to the revision deletion issues described above
+			// and shouldn't really be grounds for removing this test.
 			assertEquals(beforeState, bosk.rootReference().value());
 		}
 
@@ -320,6 +323,9 @@ private void testRecovery(Runnable disruptiveAction, Function<TestEntity, TestEn
 		Bosk<TestEntity> bosk = new Bosk<>(boskName(getClass().getSimpleName()), TestEntity.class, AbstractMongoDriverTest::initialRoot, BoskConfig.<TestEntity>builder().driverFactory(driverFactory).build());
 
 		try (var _ = bosk.readContext()) {
+			// Note: with very short timescales, this assertion can fail because the newly created bosk
+			// times out trying to read the database contents and instead uses AbstractMongoDriverTest::initialRoot.
+			// This is actually valid behaviour for a sufficiently impatient user.
 			assertEquals(beforeState, bosk.rootReference().value());
 		}