feat: Add initial interface for parallel simulations

This change adds the initial interface design for parallel simulations,
which requires explicit synchronization between actors in order to
establish consistent virtual time between them.

2 files changed, 42 insertions, 0 deletions

diff --git a/odcsim-core/src/main/kotlin/com/atlarge/odcsim/ActorContext.kt b/odcsim-core/src/main/kotlin/com/atlarge/odcsim/ActorContext.kt
index b10287ad..deccedd1 100644
--- a/odcsim-core/src/main/kotlin/com/atlarge/odcsim/ActorContext.kt
+++ b/odcsim-core/src/main/kotlin/com/atlarge/odcsim/ActorContext.kt
@@ -56,4 +56,41 @@ interface ActorContext<T : Any> {
      * @return `true` if the ref points to a child actor, otherwise `false`.
      */
     fun stop(child: ActorRef<*>): Boolean
+
+    /**
+     * Synchronize the local virtual time of this target with the other referenced actor's local virtual time.
+     *
+     * By default, actors are not guaranteed to be synchronized, meaning that for some implementations, virtual time may
+     * drift between different actors. Synchronization between two actors ensures that virtual time remains consistent
+     * between at least the two actors.
+     *
+     * Be aware that this method may cause a jump in virtual time in order to get consistent with [target].
+     * Furthermore, please note that synchronization might incur performance degradation and should only be used
+     * when necessary.
+     *
+     * @param target The reference to the target actor to synchronize with.
+     */
+    fun sync(target: ActorRef<*>)
+
+    /**
+     * Desynchronize virtual time between two actors if possible.
+     *
+     * Please note that this method only provides a hint to the [ActorSystem] that it may drop synchronization between
+     * the actors, but [ActorSystem] is not compelled to actually do so (i.e. in the case where synchronization is
+     * always guaranteed).
+     *
+     * Furthermore, if [target] is already desychronized, the method should return without error. [ActorContext.isSync]
+     * may be used to determine if an actor is synchronized.
+     *
+     * @param target The reference to the target actor to desynchronize with.
+     */
+    fun unsync(target: ActorRef<*>)
+
+    /**
+     * Determine whether this actor and [target] are synchronized in virtual time.
+     *
+     * @param target The target to check for synchronization.
+     * @return `true` if [target] is synchronized with this actor, `false` otherwise.
+     */
+    fun isSync(target: ActorRef<*>): Boolean
 }
diff --git a/odcsim-core/src/main/kotlin/com/atlarge/odcsim/ActorRef.kt b/odcsim-core/src/main/kotlin/com/atlarge/odcsim/ActorRef.kt
index 3f01e409..bc81813b 100644
--- a/odcsim-core/src/main/kotlin/com/atlarge/odcsim/ActorRef.kt
+++ b/odcsim-core/src/main/kotlin/com/atlarge/odcsim/ActorRef.kt
@@ -36,6 +36,11 @@ interface ActorRef<in T : Any> {
     /**
      * Send the specified message to the actor referenced by this [ActorRef].
      *
+     * Please note that callees must guarantee that messages are sent strictly in increasing time.
+     * If so, this method guarantees that:
+     * - A message will never be received earlier than specified
+     * - A message might arrive later than specified if the two actors are not synchronized.
+     *
      * @param msg The message to send to the referenced actor.
      * @param after The delay after which the message should be received by the actor.
      */