Finish the implementation of TimedAssistantProvider and add TimedDoerProvider and MatrixTimedDoer to support scheduling.

Also rename to third person tense the methods that return a `Duty`/`Task` and require the returned `Duty`/`Task` be triggered in order for the method's intended action to be performed.

Add the `PruebaTimed` to test the scheduling work. Curiously it had a single bug (a `wait` that had to be an `await`). I can't believe it!
Surely there are more bugs I will find later, as always.

Author: Guido Gustavo Pollitzer

build.sbt

@@ -9,7 +9,7 @@ lazy val root = (project in file("."))
 	)
 
 ThisBuild / libraryDependencies ++= Seq(
-	"readren" %% "taskflow-core" % "0.2.3-SNAPSHOT",
+	"readren" %% "taskflow-core" % "0.2.4-SNAPSHOT",
 	"org.typelevel" %% "scalacheck-effect" % "1.0.4" % Test,
 	"org.typelevel" %% "scalacheck-effect-munit" % "1.0.4" % Test
 )

checked/src/main/scala/pruebas/PruebaChecked.scala

@@ -30,7 +30,7 @@ object PruebaChecked {
 
 		val matrix = new Matrix("testChecked", matrixAide)
 
-		matrix.spawn[Cmd](RegularRf) { parent =>
+		matrix.spawns[Cmd](RegularRf) { parent =>
 			val cb: CheckedBehavior[Cmd, MyException] =
 				CheckedBehavior.factory[Cmd, MyException, NeverException] {
 					case cmd: DoWork =>

src/main/scala/core/AbstractMatrix.scala

@@ -38,7 +38,7 @@ abstract class AbstractMatrix(val name: String) { thisMatrix =>
 	def provideDefaultDoer: MatrixDoer
 
 	/** thread-safe */
-	def spawn[U](
+	def spawns[U](
 		childFactory: ReactantFactory,
 		childDoer: MatrixDoer = provideDefaultDoer
 	)(
@@ -47,7 +47,7 @@ abstract class AbstractMatrix(val name: String) { thisMatrix =>
 		using isSignalTest: IsSignalTest[U]
 	): doer.Duty[ReactantRelay[U]] = {
 		doer.Duty.mineFlat { () =>
-			spawner.createReactant[U](childFactory, childDoer, isSignalTest, initialBehaviorBuilder)
+			spawner.createsReactant[U](childFactory, childDoer, isSignalTest, initialBehaviorBuilder)
 		}
 	}
 

src/main/scala/core/Reactant.scala

@@ -89,13 +89,13 @@ abstract class Reactant[U](
 	def initialize(): doer.Duty[this.type] = { // send Started signal after all the vals and vars have been initialized
 		doer.checkWithin()
 		assert(currentBehavior == null)
-		selfStart(false, initialBehaviorBuilder).map(_ => thisReactant) // TODO considerar hacer que selfStart devuelva Duty[this.type] para evitar este 'map`  del final. Esto requiere que selfStop, selfRestar, stayIdleUntilNextMessageArrive, y otros que ahora devuelven Duty[Unit] también hagan lo mismo.
+		selfStarts(false, initialBehaviorBuilder).map(_ => thisReactant) // TODO considerar hacer que selfStarts devuelva Duty[this.type] para evitar este 'map`  del final. Esto requiere que selfStop, selfRestar, stayIdleUntilNextMessageArrive, y otros que ahora devuelven Duty[Unit] también hagan lo mismo.
 	}
 
 	/** Starts or restarts this [[Reactant]].
 	 * Should be called only once and within the [[doer]].
 	 * */
-	private def selfStart(comesFromRestart: Boolean, behaviorBuilder: ReactantRelay[U] => Behavior[U]): doer.Duty[Unit] = {
+	private def selfStarts(comesFromRestart: Boolean, behaviorBuilder: ReactantRelay[U] => Behavior[U]): doer.Duty[Unit] = {
 		doer.checkWithin()
 		currentBehavior = behaviorBuilder(thisReactant)
 		val handleResult = handleSignal(if comesFromRestart then isSignalTest.restarted else isSignalTest.started)
@@ -106,12 +106,12 @@ abstract class Reactant[U](
 			case ToStop =>
 				selfStop()
 			case tr: ToRestart[U @unchecked] =>
-				selfRestart(tr.stopChildren, tr.restartBehaviorBuilder)
+				selfRestarts(tr.stopChildren, tr.restartBehaviorBuilder)
 		}
 	}
 
 	/** Should be called withing the [[doer]]. */
-	override def spawn[V](
+	override def spawns[V](
 		childReactantFactory: ReactantFactory,
 		childDoer: MatrixDoer
 	)(
@@ -126,26 +126,26 @@ abstract class Reactant[U](
 				childrenRelays = spawner.childrenView
 				spawner
 			}(alreadyBuiltSpawner => alreadyBuiltSpawner)
-			.createReactant[V](childReactantFactory, childDoer, isSignalTest, initialChildBehaviorBuilder)
+			.createsReactant[V](childReactantFactory, childDoer, isSignalTest, initialChildBehaviorBuilder)
 	}
 
 	/** The children of this [[Reactant]] by serial number.
 	 *
-	 * Should be called withing the [[doer]]. */
+	 * Calls must be within the [[doer]]. */
 	override def children: MapView[Long, ReactantRelay[?]] = {
 		doer.checkWithin()
 		childrenRelays
 	}
 
-	/** should be called within the [[doer]]. */
-	private final def selfRestart(stopChildren: Boolean, restartBehaviorBuilder: ReactantRelay[U] => Behavior[U]): doer.Duty[Unit] = {
+	/** Calls must be within the [[doer]]. */
+	private final def selfRestarts(stopChildren: Boolean, restartBehaviorBuilder: ReactantRelay[U] => Behavior[U]): doer.Duty[Unit] = {
 		doer.checkWithin()
 
 		def restartMe(): doer.Duty[Unit] = {
 			// send RestartReceived signal
 			val hr = handleSignal(isSignalTest.restartReceived)
 			mapHrToDecision(hr) match {
-				case ToContinue => selfStart(true, restartBehaviorBuilder)
+				case ToContinue => selfStarts(true, restartBehaviorBuilder)
 				case ToStop =>
 					// if the `handleSignal` responds `Stop` to the `RestartReceived` signal, then the restart is canceled and the reactant is stopped instead, which provokes the signal handler be called again with a `StopReceived` signal.
 					selfStop()
@@ -154,17 +154,17 @@ abstract class Reactant[U](
 					val stopsChildrenIfInstructed =
 						if tr.stopChildren && !stopChildren then {
 							oSpawner.fold(doer.dutyReadyUnit) { spawner =>
-								spawner.stopChildren()
+								spawner.stopsChildren()
 							}
 						}
 						else doer.dutyReadyUnit
-					stopsChildrenIfInstructed.flatMap(_ => selfStart(true, tr.restartBehaviorBuilder))
+					stopsChildrenIfInstructed.flatMap(_ => selfStarts(true, tr.restartBehaviorBuilder))
 			}
 		}
 
 		if stopChildren then {
 			oSpawner.fold(restartMe()) { spawner =>
-				spawner.stopChildren().flatMap(_ => restartMe())
+				spawner.stopsChildren().flatMap(_ => restartMe())
 			}
 		} else restartMe()
 	}
@@ -184,7 +184,7 @@ abstract class Reactant[U](
 						mapHrToDecision(currentBehavior.handle(stoppedSignal)) match {
 							case ToContinue => ()
 							case ToStop => selfStop()
-							case tr: ToRestart[U @unchecked] => selfRestart(tr.stopChildren, tr.restartBehaviorBuilder).triggerAndForget(true)
+							case tr: ToRestart[U @unchecked] => selfRestarts(tr.stopChildren, tr.restartBehaviorBuilder).triggerAndForget(true)
 						}
 					}
 				}
@@ -261,7 +261,7 @@ abstract class Reactant[U](
 			isReadyToProcessMsg = false
 			activeWatchSubscriptions.forEach { (k, v) => v.foreach(_.unsubscribe()) }
 			oSpawner.fold(stopMe()) { spawner =>
-				spawner.stopChildren().trigger(true)(_ => stopMe())
+				spawner.stopsChildren().trigger(true)(_ => stopMe())
 			}
 		}
 		stopCovenant.subscriptableDuty
@@ -358,12 +358,12 @@ abstract class Reactant[U](
 		finalDecision match {
 			case ToContinue => beReadyToProcess()
 			case ToStop => selfStop()
-			case tr: ToRestart[U @unchecked] => selfRestart(tr.stopChildren, tr.restartBehaviorBuilder).triggerAndForget(true)
+			case tr: ToRestart[U @unchecked] => selfRestarts(tr.stopChildren, tr.restartBehaviorBuilder).triggerAndForget(true)
 		}
 	}
 
 
-	override def diagnose: doer.Duty[ReactantDiagnostic] =
+	override def diagnoses: doer.Duty[ReactantDiagnostic] =
 		doer.Duty.mine { () =>
 			val childrenDiagnostic = children.map(_._2.staleDiagnose).toArray
 			ReactantDiagnostic(thisReactant.isReadyToProcessMsg, thisReactant.isMarkedToStop, thisReactant.stopWasStarted, inbox.size, inbox.iterator, childrenDiagnostic)

src/main/scala/core/ReactantFactory.scala

@@ -5,9 +5,9 @@ import readren.taskflow.Doer
 
 trait ReactantFactory {
 
-	/** Creates a new [[Reactant]].
+	/** Creates a [[Duty]] that creates a new [[Reactant]].
 	 * The implementation should be thread-safe, doing its job withing the received [[MatrixDoer]]. */
-	def createReactant[U, MD <: MatrixDoer](
+	def createsReactant[U, MD <: MatrixDoer](
 		id: Reactant.SerialNumber,
 		progenitor: Spawner[?],
 		reactantDoer: MD,

src/main/scala/core/ReactantRelay.scala

@@ -22,8 +22,8 @@ abstract class ReactantRelay[-U] {
 	 * This method is thread-safe. */
 	def isMarkedToBeStopped: Boolean
 
-	/** Should be called withing the [[doer]]. */
-	def spawn[V](
+	/** Calls must be within the [[doer]]. */
+	def spawns[V](
 		childFactory: ReactantFactory,
 		childDoer: MatrixDoer = doer.matrix.provideDefaultDoer
 	)(
@@ -32,7 +32,7 @@ abstract class ReactantRelay[-U] {
 		using isSignalTest: IsSignalTest[V]
 	): doer.Duty[ReactantRelay[V]]
 
-	/** Should be called within the [[doer]]. */
+	/** Calls must be within the [[doer]]. */
 	def children: MapView[Long, ReactantRelay[?]]
 
 	/**
@@ -49,7 +49,7 @@ abstract class ReactantRelay[-U] {
 	 * 
 	 * This duty is the same as the returned by the [[stop]] method.
 	 * 
- 	 * This method is thread-safe but some methods of the returned [[SubscriptableDuty]] require being called withing the [[doer]]. */
+ 	 * This method is thread-safe but some methods of the returned [[SubscriptableDuty]] require being called within the [[doer]]. */
 	def stopDuty: doer.SubscriptableDuty[Unit]
 
 	/** Registers this [[Reactant]] to be notified with the specified signal when the given `watchedReactant` is fully stopped.
@@ -71,7 +71,7 @@ abstract class ReactantRelay[-U] {
 	def watch[SS <: U](watchedReactant: ReactantRelay[?], stoppedSignal: SS, univocally: Boolean = true, subscriptionCompleted: Maybe[doer.Covenant[Unit]] = Maybe.empty): Maybe[WatchSubscription]
 
 	/** Provides diagnostic information about the current instance. */
-	def diagnose: doer.Duty[ReactantDiagnostic]
+	def diagnoses: doer.Duty[ReactantDiagnostic]
 
 	/** Provides diagnostic information about the current instance that may be stale due to cache visibility issues across processor cores. */
 	def staleDiagnose: ReactantDiagnostic

src/main/scala/core/Spawner.scala

@@ -11,26 +11,27 @@ object Spawner {
 }
 
 /** A progenitor of [[Reactant]]s.
- * @param doer the [[MatrixDoer]] within which the mutable members of this class are mutated; and the [[Doer]] that contains the [[Duty]] returned by [[createReactant]].
+ * @param doer the [[MatrixDoer]] within which the mutable members of this class are mutated; and the [[Doer]] that contains the [[Duty]] returned by [[createsReactant]].
  * If this [[Spawner]] has an owner then the [[MatrixDoer]] referred by this parameter should be the same as the assigned to the `owner`.
  * @param initialReactantSerial child reactants' serial will start at this value. Allows to distribute the load of [[MatrixDoer]] more evenly among siblings.
  * @tparam MD the singleton type of the [[MatrixDoer]] assigned to the `owner`.
  * */
 class Spawner[+MD <: MatrixDoer](val owner: Maybe[Reactant[?]], val doer: MD, initialReactantSerial: Reactant.SerialNumber) { thisSpawner =>
 	assert(owner.fold(true)(_.doer eq doer))
 
-	/** Should be accessed only within the [[doer]] */
+	/** Access must be within the [[doer]]. */
 	private var reactantSerialSequencer: Reactant.SerialNumber = initialReactantSerial
 
-	/** Should be accessed within the [[doer]] only. */
+	/** Access must be within the [[doer]]. */
 	private val children: mutable.LongMap[Reactant[?]] = mutable.LongMap.empty
 
 	/** A view of the children that aren't fully stopped.
-	 * Should be accessed withing the [[doer]]. */
+	 * Access must be within the [[doer]]. */
 	val childrenView: MapView[Long, Reactant[?]] = children.view
 
-	/** Should be called withing the [[doer]] only. */
-	def createReactant[U](
+	/**Creates a [[Duty]] that creates a new [[Reactant]].
+	 * Calls must be within the [[doer]]. */
+	def createsReactant[U](
 		childFactory: ReactantFactory, 
 		childDoer: MatrixDoer, 
 		isSignalTest: IsSignalTest[U], 
@@ -39,22 +40,22 @@ class Spawner[+MD <: MatrixDoer](val owner: Maybe[Reactant[?]], val doer: MD, in
 		doer.checkWithin()
 		reactantSerialSequencer += 1
 		val reactantSerial = reactantSerialSequencer
-		childFactory.createReactant(reactantSerial, thisSpawner, childDoer, isSignalTest, initialBehaviorBuilder)
+		childFactory.createsReactant(reactantSerial, thisSpawner, childDoer, isSignalTest, initialBehaviorBuilder)
 			.onBehalfOf(doer)
 			.map { reactant =>
 				children.addOne(reactantSerial, reactant)
 				reactant
 			}
 	}
 
-	/** should be called withing the doer */
-	def stopChildren(): doer.Duty[Array[Unit]] = {
+	/** Calls must be within the [[doer]]. */
+	def stopsChildren(): doer.Duty[Array[Unit]] = {
 		doer.checkWithin()
 		val stopDuties = childrenView.values.map(child => doer.Duty.foreign(child.doer)(child.stop()))
 		doer.Duty.sequenceToArray(stopDuties)
 	}
 
-	/** should be called withing the doer */
+	/** Calls must be within the [[doer]]. */
 	def removeChild(childSerial: Long): Unit = {
 		doer.checkWithin()
 		children -= childSerial

src/main/scala/providers/CloseableDoerProvidersManager.scala renamed to src/main/scala/providers/ShutdownAbleDpd.scala

@@ -10,7 +10,9 @@ import readren.taskflow.Doer
 import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.{ConcurrentHashMap, TimeUnit}
 
-class CloseableDoerProvidersManager extends DoerProvidersManager, ShutdownAble {
+/** An implementation of the [[DoerProvidersManager]] trait that is [[ShutdownAble]].
+ * Call to methods inherited from [[ShutdownAble]] are propagated to all the [[DoerProvider]] instances managed by this instance, provided the [[DoerProvider]] are [[ShutdownAble]].  */
+class ShutdownAbleDpd extends DoerProvidersManager, ShutdownAble {
 
 	private val registeredProviders: ConcurrentHashMap[DoerProviderDescriptor[?, ?], DoerProvider[?]] = new ConcurrentHashMap()
 	private val wasShutdown: AtomicBoolean = new AtomicBoolean(false)
@@ -22,7 +24,7 @@ class CloseableDoerProvidersManager extends DoerProvidersManager, ShutdownAble {
 			if wasShutdown.get() then null
 			else descriptor.build(this)
 		}).asInstanceOf[DP]
-		if provider == null then throw new IllegalStateException(s"A ${getTypeName[CloseableDoerProvidersManager]} instance was asked to build a new instances of ${getTypeName[DoerProvider[D]]} after it was shutdown.")
+		if provider == null then throw new IllegalStateException(s"A ${getTypeName[ShutdownAbleDpd]} instance was asked to build a new instances of ${getTypeName[DoerProvider[D]]} after it was shutdown.")
 		else provider
 	}