diff options
Diffstat (limited to 'opendc-core/src')
7 files changed, 257 insertions, 257 deletions
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt index 199e1701..10a89704 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt @@ -8,57 +8,57 @@ package com.atlarge.opendc.simulator * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ interface Bootstrap<M> { - /** - * Bootstrap a model `M` for a kernel in the given context. - * - * @param context The context to bootstrap to model in. - * @return The initialised model for the simulation. - */ - fun bootstrap(context: Context<M>): M + /** + * Bootstrap a model `M` for a kernel in the given context. + * + * @param context The context to bootstrap to model in. + * @return The initialised model for the simulation. + */ + fun bootstrap(context: Context<M>): M - /** - * A context for the bootstrap of some model type `M` that allows the model to register the entities of the model to - * the simulation kernel. - * - * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) - */ - interface Context<out M> { - /** - * Register the given entity to the simulation kernel. - * - * @param entity The entity to register. - * @return `true` if the entity had not yet been registered, `false` otherwise. - */ - fun register(entity: Entity<*, M>): Boolean + /** + * A context for the bootstrap of some model type `M` that allows the model to register the entities of the model to + * the simulation kernel. + * + * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) + */ + interface Context<out M> { + /** + * Register the given entity to the simulation kernel. + * + * @param entity The entity to register. + * @return `true` if the entity had not yet been registered, `false` otherwise. + */ + fun register(entity: Entity<*, M>): Boolean - /** - * Deregister the given entity from the simulation kernel. - * - * @param entity The entity to deregister. - * @return `true` if the entity had not yet been unregistered, `false` otherwise. - */ - fun deregister(entity: Entity<*, M>): Boolean + /** + * Deregister the given entity from the simulation kernel. + * + * @param entity The entity to deregister. + * @return `true` if the entity had not yet been unregistered, `false` otherwise. + */ + fun deregister(entity: Entity<*, M>): Boolean - /** - * Schedule a message for processing by a [Context]. - * - * @param message The message to schedule. - * @param destination The destination of the message. - * @param sender The sender of the message. - * @param delay The amount of time to wait before processing the message. - */ - fun schedule(message: Any, destination: Entity<*, *>, sender: Entity<*, *>? = null, delay: Duration = 0) - } + /** + * Schedule a message for processing by a [Context]. + * + * @param message The message to schedule. + * @param destination The destination of the message. + * @param sender The sender of the message. + * @param delay The amount of time to wait before processing the message. + */ + fun schedule(message: Any, destination: Entity<*, *>, sender: Entity<*, *>? = null, delay: Duration = 0) + } - companion object { - /** - * Create a [Bootstrap] procedure using the given block to produce a bootstrap for a model of type `M`. - * - * @param block The block to produce the bootstrap. - * @return The bootstrap procedure that has been built. - */ - fun <M> create(block: (Context<M>) -> M): Bootstrap<M> = object : Bootstrap<M> { - override fun bootstrap(context: Context<M>) = block(context) - } - } + companion object { + /** + * Create a [Bootstrap] procedure using the given block to produce a bootstrap for a model of type `M`. + * + * @param block The block to produce the bootstrap. + * @return The bootstrap procedure that has been built. + */ + fun <M> create(block: (Context<M>) -> M): Bootstrap<M> = object : Bootstrap<M> { + override fun bootstrap(context: Context<M>) = block(context) + } + } } diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt index c4e906dd..c89bdb59 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt @@ -24,7 +24,7 @@ package com.atlarge.opendc.simulator -import java.util.Queue +import java.util.* /** * This interface provides a context for simulation of [Entity] instances, by defining the environment in which the @@ -34,123 +34,123 @@ import java.util.Queue * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ interface Context<S, out M> { - /** - * The model of simulation in which the entity exists. - */ - val model: M - - /** - * The current point in simulation time. - */ - val time: Instant - - /** - * The duration between the current point in simulation time and the last point in simulation time where the - * [Entity] has done some work. This means the `run()` co-routine has been resumed. - */ - val delta: Duration - - /** - * The observable state of the entity bound to this scope. - */ - var state: S - - /** - * The observable state of an [Entity] in simulation, which is provided by the simulation context. - */ - val <E : Entity<S, *>, S> E.state: S - - /** - * Interrupt an [Entity] process in simulation. - * - * If an [Entity] process has been suspended, the suspending call will throw an [Interrupt] object as a result of - * this call. - * Make sure the [Entity] process actually has error handling in place, so it won't take down the whole [Entity] - * process as result of the interrupt. - */ - suspend fun Entity<*, *>.interrupt() - - /** - * Suspend the [Context] of the [Entity] in simulation for the given duration of simulation time before resuming - * execution and drop all messages that are received during this period. - * - * A call to this method will not make the [Context] sleep for the actual duration of time, but instead suspend - * the process until the no more messages at an earlier point in time have to be processed. - * - * @param duration The duration of simulation time to hold before resuming execution. - */ - suspend fun hold(duration: Duration) - - /** - * Suspend the [Context] of the [Entity] in simulation for the given duration of simulation time before resuming - * execution and push all messages that are received during this period to the given queue. - * - * A call to this method will not make the [Context] sleep for the actual duration of time, but instead suspend - * the process until the no more messages at an earlier point in time have to be processed. - * - * @param duration The duration of simulation time to wait before resuming execution. - * @param queue The mutable queue to push the messages to. - */ - suspend fun hold(duration: Duration, queue: Queue<Any>) - - /** - * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is - * empty. The execution is resumed after the head of the mailbox is removed after which the message [Envelope] is - * transformed through `transform` to return the transformed result. - * - * @param transform The block to transform the message with in an envelope context, providing access to the sender - * of the message. - * @return The transformed message. - */ - suspend fun <T> receive(transform: suspend Envelope<*>.(Any) -> T): T - - /** - * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is - * empty. The execution is either resumed after the head of the mailbox is removed after which the message - * [Envelope] is transformed through `transform` to return the transformed result or the timeout has been reached. - * - * @param timeout The duration to wait before resuming execution. - * @param transform The block to transform the message with in an envelope context, providing access to the sender - * of the message. - * @return The processed message or `null` if the timeout was reached. - */ - suspend fun <T> receive(timeout: Duration, transform: suspend Envelope<*>.(Any) -> T): T? - - /** - * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is - * empty. The execution is resumed after the head of the mailbox is removed and returned. - * - * @return The received message. - */ - suspend fun receive(): Any = receive { it } - - /** - * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is - * empty. The execution is either resumed after the head of the mailbox is removed and returned or when the timeout - * has been reached. - * - * @return The received message or `null` if the timeout was reached. - */ - suspend fun receive(timeout: Duration): Any? = receive(timeout) { it } - - /** - * Send the given message to the specified entity, without providing any guarantees about the actual delivery of - * the message. - * - * @param msg The message to send. - * @param delay The amount of time to wait before the message should be received by the entity. - */ - suspend fun Entity<*, *>.send(msg: Any, delay: Duration = 0) - - /** - * Send the given message to the specified entity, without providing any guarantees about the actual delivery of - * the message. - * - * @param msg The message to send. - * @param sender The sender of the message. - * @param delay The amount of time to wait before the message should be received by the entity. - */ - suspend fun Entity<*, *>.send(msg: Any, sender: Entity<*, *>, delay: Duration = 0) + /** + * The model of simulation in which the entity exists. + */ + val model: M + + /** + * The current point in simulation time. + */ + val time: Instant + + /** + * The duration between the current point in simulation time and the last point in simulation time where the + * [Entity] has done some work. This means the `run()` co-routine has been resumed. + */ + val delta: Duration + + /** + * The observable state of the entity bound to this scope. + */ + var state: S + + /** + * The observable state of an [Entity] in simulation, which is provided by the simulation context. + */ + val <E : Entity<S, *>, S> E.state: S + + /** + * Interrupt an [Entity] process in simulation. + * + * If an [Entity] process has been suspended, the suspending call will throw an [Interrupt] object as a result of + * this call. + * Make sure the [Entity] process actually has error handling in place, so it won't take down the whole [Entity] + * process as result of the interrupt. + */ + suspend fun Entity<*, *>.interrupt() + + /** + * Suspend the [Context] of the [Entity] in simulation for the given duration of simulation time before resuming + * execution and drop all messages that are received during this period. + * + * A call to this method will not make the [Context] sleep for the actual duration of time, but instead suspend + * the process until the no more messages at an earlier point in time have to be processed. + * + * @param duration The duration of simulation time to hold before resuming execution. + */ + suspend fun hold(duration: Duration) + + /** + * Suspend the [Context] of the [Entity] in simulation for the given duration of simulation time before resuming + * execution and push all messages that are received during this period to the given queue. + * + * A call to this method will not make the [Context] sleep for the actual duration of time, but instead suspend + * the process until the no more messages at an earlier point in time have to be processed. + * + * @param duration The duration of simulation time to wait before resuming execution. + * @param queue The mutable queue to push the messages to. + */ + suspend fun hold(duration: Duration, queue: Queue<Any>) + + /** + * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is + * empty. The execution is resumed after the head of the mailbox is removed after which the message [Envelope] is + * transformed through `transform` to return the transformed result. + * + * @param transform The block to transform the message with in an envelope context, providing access to the sender + * of the message. + * @return The transformed message. + */ + suspend fun <T> receive(transform: suspend Envelope<*>.(Any) -> T): T + + /** + * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is + * empty. The execution is either resumed after the head of the mailbox is removed after which the message + * [Envelope] is transformed through `transform` to return the transformed result or the timeout has been reached. + * + * @param timeout The duration to wait before resuming execution. + * @param transform The block to transform the message with in an envelope context, providing access to the sender + * of the message. + * @return The processed message or `null` if the timeout was reached. + */ + suspend fun <T> receive(timeout: Duration, transform: suspend Envelope<*>.(Any) -> T): T? + + /** + * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is + * empty. The execution is resumed after the head of the mailbox is removed and returned. + * + * @return The received message. + */ + suspend fun receive(): Any = receive { it } + + /** + * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is + * empty. The execution is either resumed after the head of the mailbox is removed and returned or when the timeout + * has been reached. + * + * @return The received message or `null` if the timeout was reached. + */ + suspend fun receive(timeout: Duration): Any? = receive(timeout) { it } + + /** + * Send the given message to the specified entity, without providing any guarantees about the actual delivery of + * the message. + * + * @param msg The message to send. + * @param delay The amount of time to wait before the message should be received by the entity. + */ + suspend fun Entity<*, *>.send(msg: Any, delay: Duration = 0) + + /** + * Send the given message to the specified entity, without providing any guarantees about the actual delivery of + * the message. + * + * @param msg The message to send. + * @param sender The sender of the message. + * @param delay The amount of time to wait before the message should be received by the entity. + */ + suspend fun Entity<*, *>.send(msg: Any, sender: Entity<*, *>, delay: Duration = 0) } /** @@ -159,21 +159,21 @@ interface Context<S, out M> { * @param T The shape of the message inside the envelope. * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ -interface Envelope<out T: Any> { - /** - * The message in this envelope. - */ - val message: T - - /** - * The sender of the message. - */ - val sender: Entity<*, *>? - - /** - * The destination of the message. - */ - val destination: Entity<*, *> +interface Envelope<out T : Any> { + /** + * The message in this envelope. + */ + val message: T + + /** + * The sender of the message. + */ + val sender: Entity<*, *>? + + /** + * The destination of the message. + */ + val destination: Entity<*, *> } /** @@ -181,4 +181,4 @@ interface Envelope<out T: Any> { * * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ -object Interrupt: Throwable("The entity process has been interrupted by another entity") +object Interrupt : Throwable("The entity process has been interrupted by another entity") diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt index 800f2f1d..56704c5d 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt @@ -37,8 +37,8 @@ package com.atlarge.opendc.simulator * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ interface Entity<out S, in M> { - /** - * The initial state of the entity. - */ - val initialState: S + /** + * The initial state of the entity. + */ + val initialState: S } diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt index 30280657..e8b4d988 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt @@ -8,20 +8,20 @@ package com.atlarge.opendc.simulator * @param M The shape of the model in which the process exists. * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ -interface Process<S, in M>: Entity<S, M> { - /** - * This method is invoked to start the simulation a process. - * - * This method is assumed to be running during a simulation, but should hand back control to the simulator at - * some point by suspending the process. This allows other processes to do work at the current point in time of the - * simulation. - * Suspending the process can be achieved by calling suspending method in the context: - * - [Context.hold] - Hold for `n` units of time before resuming execution. - * - [Context.receive] - Wait for a message to be received in the mailbox of the [Entity] before resuming - * execution. - * - * If this method exits early, before the simulation has finished, the entity is assumed to be shutdown and its - * simulation will not run any further. - */ - suspend fun Context<S, M>.run() +interface Process<S, in M> : Entity<S, M> { + /** + * This method is invoked to start the simulation a process. + * + * This method is assumed to be running during a simulation, but should hand back control to the simulator at + * some point by suspending the process. This allows other processes to do work at the current point in time of the + * simulation. + * Suspending the process can be achieved by calling suspending method in the context: + * - [Context.hold] - Hold for `n` units of time before resuming execution. + * - [Context.receive] - Wait for a message to be received in the mailbox of the [Entity] before resuming + * execution. + * + * If this method exits early, before the simulation has finished, the entity is assumed to be shutdown and its + * simulation will not run any further. + */ + suspend fun Context<S, M>.run() } diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt index 3eee0f67..29b3bdee 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt @@ -25,8 +25,8 @@ package com.atlarge.opendc.simulator.kernel import com.atlarge.opendc.simulator.Bootstrap -import com.atlarge.opendc.simulator.Instant import com.atlarge.opendc.simulator.Entity +import com.atlarge.opendc.simulator.Instant /** * A message based discrete event simulation kernel. @@ -41,39 +41,39 @@ import com.atlarge.opendc.simulator.Entity * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ interface Kernel<out M> { - /** - * The model in which the simulation runs. - */ - val model: M + /** + * The model in which the simulation runs. + */ + val model: M - /** - * The simulation time. - */ - var time: Instant + /** + * The simulation time. + */ + var time: Instant - /** - * The observable state of an [Entity] in simulation, which is provided by the simulation context. - */ - val <E : Entity<S, *>, S> E.state: S + /** + * The observable state of an [Entity] in simulation, which is provided by the simulation context. + */ + val <E : Entity<S, *>, S> E.state: S - /** - * Step through one cycle in the simulation. This method will process all events in a single tick, update the - * internal clock and then return the control to the user. - */ - fun step() + /** + * Step through one cycle in the simulation. This method will process all events in a single tick, update the + * internal clock and then return the control to the user. + */ + fun step() - /** - * Run a simulation over the specified model. - * This method will step through multiple cycles in the simulation until no more message exist in the queue. - */ - fun run() + /** + * Run a simulation over the specified model. + * This method will step through multiple cycles in the simulation until no more message exist in the queue. + */ + fun run() - /** - * Run a simulation over the specified model, stepping through cycles until the specified clock tick has - * occurred. The control is then handed back to the user. - * - * @param until The point in simulation time at which the simulation should be paused and the control is handed - * back to the user. - */ - fun run(until: Instant) + /** + * Run a simulation over the specified model, stepping through cycles until the specified clock tick has + * occurred. The control is then handed back to the user. + * + * @param until The point in simulation time at which the simulation should be paused and the control is handed + * back to the user. + */ + fun run(until: Instant) } diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt index 93667eb8..30abb7ca 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt @@ -32,11 +32,11 @@ import com.atlarge.opendc.simulator.Bootstrap * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ interface KernelFactory { - /** - * Create a simulation over the given model facilitated by this simulation kernel. - * - * @param bootstrap The bootstrap procedure to bootstrap the simulation with. - * @return A [Kernel] instance to control the simulation. - */ - fun <M> create(bootstrap: Bootstrap<M>): Kernel<M> + /** + * Create a simulation over the given model facilitated by this simulation kernel. + * + * @param bootstrap The bootstrap procedure to bootstrap the simulation with. + * @return A [Kernel] instance to control the simulation. + */ + fun <M> create(bootstrap: Bootstrap<M>): Kernel<M> } diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt index 88b606fd..92d56be1 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt @@ -24,8 +24,8 @@ package com.atlarge.opendc.simulator.platform -import com.atlarge.opendc.simulator.kernel.KernelFactory import com.atlarge.opendc.simulator.Duration +import com.atlarge.opendc.simulator.kernel.KernelFactory /** * A blueprint for a reproducible simulation in a pre-defined setting. @@ -33,20 +33,20 @@ import com.atlarge.opendc.simulator.Duration * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ interface Experiment<out T> { - /** - * Run the experiment on the specified kernel implementation. - * - * @param factory The factory to create the simulation kernel with. - * @return The result of the experiment. - */ - fun run(factory: KernelFactory): T + /** + * Run the experiment on the specified kernel implementation. + * + * @param factory The factory to create the simulation kernel with. + * @return The result of the experiment. + */ + fun run(factory: KernelFactory): T - /** - * Run the experiment on the specified kernel implementation. - * - * @param factory The factory to create the simulation kernel with. - * @param timeout The maximum duration of the experiment before returning to the caller. - * @return The result of the experiment or `null`. - */ - fun run(factory: KernelFactory, timeout: Duration): T? + /** + * Run the experiment on the specified kernel implementation. + * + * @param factory The factory to create the simulation kernel with. + * @param timeout The maximum duration of the experiment before returning to the caller. + * @return The result of the experiment or `null`. + */ + fun run(factory: KernelFactory, timeout: Duration): T? } |