Package gov.nasa.jpl.aerie.merlin.protocol.driver

Interface Initializer

public interface Initializer
An interface to the driver during model instantiation.

An Initializer allows models to allocate storage for simulation-aware state, which is the only mutable state that can safely be shared among stateful cells that can be read and updated from Tasks. The model must not interact with an Initializer beyond the scope in which it was received.

Models can also export resources (time-varying values) and topics (streams of discrete events) via this interface. These observable outputs of the model provide feedback to users, displaying the effect on the model of the input directives and configuration. Observing the behavior of resources and topics is very nearly the whole point of simulating a model, so it is essential to register these outputs for clients to make use of.

In a future revision of this API, exportation of resources and topics may be moved to the ModelType interface, so that the existence and shape of these outputs cannot vary with model configuration.

  • Method Summary

    Modifier and Type
    Method
    Description
    <Event, Effect, State>
    CellId<State>
    allocate(State initialState, CellType<Effect,State> cellType, Function<Event,Effect> interpretation, Topic<Event> topic)
    Allocates a stateful cell with the given initial state, which may evolve over time and under effects.
    void
    daemon(TaskFactory<?> factory)
    Registers a specification for a top-level "daemon" task to be spawned at the beginning of simulation.
    <State> State
    getInitialState(CellId<State> cellId)
    Gets the current state of the cell with the given ID.
    void
    resource(String name, Resource<?> resource)
    Registers a model resource whose value over time is observable by the environment.
    <Event> void
    topic(String name, Topic<Event> topic, OutputType<Event> outputType)
    Registers a stream of events (a "topic") observable by the environment.

  • Method Details

    • getInitialState

      <State> State getInitialState(CellId<State> cellId)
      Gets the current state of the cell with the given ID.

      Since cells cannot be mutated during initialization, this method always returns the initial state provided to allocate(Object, CellType, Function, Topic) for the given cell ID.

      Type Parameters:
      State - The type of state held by the cell.
      Parameters:
      cellId - The ID of the cell to query.
      Returns:
      The current state of the cell.

    • allocate

      <Event, Effect, State> CellId<State> allocate(State initialState, CellType<Effect,State> cellType, Function<Event,Effect> interpretation, Topic<Event> topic)
      Allocates a stateful cell with the given initial state, which may evolve over time and under effects. The cell is automatically subscribed to the provided topic, whose events are interpreted as effects by the given function.

      All mutable state referenced by a model must be allocated via this method. In turn, this method returns CellIds, which identify the cell to the driver in future read/write interactions. This makes it possible to give each concurrent task a transactional view of the model state, to resolve any concurrent effects on state in a coherent way, and to identify which resources need to be recomputed based on when the cells they are computed from are updated.

      The given CellType describes how concurrent effects resolve into coherent updates to the cell's state, and how time causes the state to evolve autonomously. The given Topic and associated interpretation function describe how a particular class of events influences this cell. In the future, it may become possible to subscribe a cell to zero or multiple topics, in which case this method will likely factor into separate actions for allocation and subscription.

      Type Parameters:
      Event - The type of event streamed over the given topic.
      Effect - The type of effect accepted by the given cell type.
      State - The type of state managed by the given cell type.
      Parameters:
      initialState - The initial state of the cell.
      cellType - A specification of the cell's behavior over time and under effects.
      interpretation - An interpretation of events as effects on this particular cell.
      topic - A stream of events to subscribe this cell to.
      Returns:
      A unique token identifying the allocated cell.

    • daemon

      void daemon(TaskFactory<?> factory)
      Registers a specification for a top-level "daemon" task to be spawned at the beginning of simulation.

      Daemon tasks are so-named in analogy to the "daemon" processes of UNIX, which are background processes that monitor system state and take action on some condition or periodic schedule. Merlin's daemon tasks are much the same: tasks that exist on the model's behalf, rather than as reactions to environmental stimuli, which may model some system upkeep behavior on some condition or periodic schedule.

      The return value from a daemon task is discarded and ignored.

      Parameters:
      factory - A factory for constructing instances of the daemon task.

    • resource

      void resource(String name, Resource<?> resource)
      Registers a model resource whose value over time is observable by the environment.
      Parameters:
      name - The name of the resource, unique amongst all resources.
      resource - The method to use to observe the value of the resource.

    • topic

      <Event> void topic(String name, Topic<Event> topic, OutputType<Event> outputType)
      Registers a stream of events (a "topic") observable by the environment.
      Type Parameters:
      Event - The type of data carried by events on the topic.
      Parameters:
      name - The name of the topic, unique amongst all topics.
      topic - The identifier associated to each event on the topic.
      outputType - A description of the type of data carried by events on the topic.