EventSim/Developers Guide/Simulation Modules

Extension Point for Simulation Modules

A simulation module is an Eclipse Plug-In that extends the edu.kit.ipd.sdq.eventsim.module extension point. The extension point's properties are described below.

A simulation module example is provided at https://svnserver.informatik.kit.edu/i43/svn/code/Palladio/Addons/EventSim/trunk/edu.kit.ipd.sdq.eventsim.extensionexample.

guice_module: Defining and Overriding Guice Bindings (Optional)

A Guice binding maps a type (e.g. an interface) to a concrete implementation. The binding determines the concrete implementation that Guice will provide when an object requests injection. Bindings are defined in Guice modules.

The guice_module extension property can be used to define such a Guice module for your simulation module. This Guice module allows to override existing bindings of simulation modules with a lower priority. Take care if using multiple simulation modules with the same priority: overriding will also occur but the order is not defined.

priority: Defines Precedence of Bindings and Traversal Strategies

Guice bindings of simulation modules are established in the order of their priority value, starting with the lowest priority. This allows simulation modules with a larger priority to override the bindings previously established by a lower-priority simulation module.

Traversal strategies defined by lower-priority simulation modules can be overriden in the same way.

EventSim's default simulation modules have the priority 0.

launch_contribution: Contribute UI Controls to Launch Configuration Dialog (Optional)

Allows to contribute custom UI control to the EventSim tab in the Eclipse Launch Configuration dialog. The contributed controls appear when selecting the respective simulation module.

Expects an implementation of edu.kit.ipd.sdq.eventsim.module.AbstractLaunchContribution.

entry_point: Defines the Simulation Module's Entry Point (Optional)

In the simulation_module extension element, choose for the entry_point extension property a class that implements SimulationModuleEntryPoint.

The entry_point property is optional. There can be at most one entry point per simulation module.

With the following entry point implementation, EventSim will call your init() method in the simulation preparation phase:

package mymodule;

import javax.inject.Inject;

import edu.kit.ipd.sdq.eventsim.api.ISimulationMiddleware;
import edu.kit.ipd.sdq.eventsim.api.events.SimulationPrepareEvent;
import edu.kit.ipd.sdq.eventsim.modules.SimulationModuleEntryPoint;

public class MyModuleEntryPoint implements SimulationModuleEntryPoint {

    // inject additional dependencies here, or via constructor injection when the constructor needs that dependency

    @Inject
    public MyModuleEntryPoint(ISimulationMiddleware middleware) {
        // call init in the simulation preparation phase
        middleware.registerEventHandler(SimulationPrepareEvent.class, e -> init());
    }
    
    private void init() {
        // ...
    }
    
}

simulation_strategy: Extending and Overriding Simulation Behaviour

Expects an implementation of edu.kit.ipd.sdq.eventsim.interpreter.SimulationStrategy.

A simulation strategy is responsible for simulating the behaviour of a specific action type that occurs in RD-SEFFs or usage models. Each simulation modules bundles one or more simulation strategy (as children of the simulation_module extension element).

It is common for simulation strategies to request access to various objects via injection, including the simulation configuration, the model under simulation, or the random-number generator. A starting point for injection is provided in the section below.

Decorating Strategies

A decorating strategy is a simulation strategy that extends an existing simulation strategy by decorating the existing strategy. This is useful to change or modify the simulation behaviour of existing action types:

public class MinimalDecoratingSimulationStrategy
        implements DecoratingSimulationStrategy<AbstractAction, Request> {

    private SimulationStrategy<AbstractAction, Request> decorated;

    @Override
    public void decorate(SimulationStrategy<AbstractAction, Request> decorated) {
        this.decorated = decorated;
    }

    @Override
    public void simulate(AbstractAction action, Request request, Consumer<TraversalInstruction> onFinishCallback) {
        /////////////////////////////////////////////////////////
        // do something *before* decorated simulation strategy //
        /////////////////////////////////////////////////////////

        // delegate simulation to decorated strategy
        decorated.simulate(action, request, traversalInstruction -> {
            ////////////////////////////////////////////////////////
            // do something *after* decorated simulation strategy //
            ////////////////////////////////////////////////////////

            // pass-though traversal instruction returned by decorated strategy
            onFinishCallback.accept(traversalInstruction);
        });
    }

}

Base Strategies

A base strategy is a simulation strategy without the capability to decorate other simulation strategies. Base strategies provide the main simulation behaviour for an action type.

Candidates for Injection

The following provides a non-exhaustive list of injection candidates that are "safe" (proven to work) to inject into a traversal strategy:

• edu.kit.ipd.sdq.eventsim.api.IPassiveResource
• edu.kit.ipd.sdq.eventsim.api.IActiveResource
• edu.kit.ipd.sdq.eventsim.api.ISystem
• edu.kit.ipd.sdq.eventsim.api.IWorkload
• edu.kit.ipd.sdq.eventsim.api.ISimulationMiddleware
• edu.kit.ipd.sdq.eventsim.api.PCMModel: the PCM model under simulation
• edu.kit.ipd.sdq.eventsim.api.ISimulationConfiguration: the simulation configuration as specified in the launch configuration
• de.uka.ipd.sdq.simulation.abstractsimengine.ISimulationModel
• edu.kit.ipd.sdq.eventsim.system.interpreter.SeffBehaviourInterpreter
• de.uka.ipd.sdq.probfunction.math.IRandomGenerator
• edu.kit.ipd.sdq.eventsim.command.PCMModelCommandExecutor
• edu.kit.ipd.sdq.eventsim.system.entities.RequestFactory