Package org.protelis.vm

Interface ExecutionContext

  • All Known Subinterfaces:
    LocalizedDevice, SpatiallyEmbeddedDevice<D>, TimeAwareDevice<D>
    All Known Implementing Classes:
    AbstractExecutionContext
    public interface ExecutionContext
    Interface between a ProtelisVM and environment in which it is executing. The ExecutionContext is responsible for three things: 1. Tracking local persistent state from evaluation to evaluation 2. Tracking evaluation state shared by neighbors 3. The state of the device in its external environment (time, space, sensors, etc.)

    • Method Detail

      • buildField

        <T,​R> Field<R> buildField​(java.util.function.Function<T,​R> computeValue,
                                T localValue)
        Builds a new Field, fetching data from all the aligned neighbors. A neighbor is considered to be aligned it it has reached the exact same DefaultTimeEfficientCodePath. The field will always contain at least one value, namely the value of the local device.
        Type Parameters:
        T - the type of the input
        R - the type of the output
        Parameters:
        computeValue - a function that will be applied to localValue and the equivalents shared from neighbors in the process of constructing this field: the field consists of the values returned from applying computeValue to each of device's value
        localValue - the local value for this field
        Returns:
        a new Field containing the local device value and the values for any of the aligned neighbors

      • buildFieldDeferred

        <T,​R> Field<R> buildFieldDeferred​(java.util.function.Function<T,​R> computeValue,
                                        T currentLocal,
                                        java.util.function.Supplier<T> toBeSent)
        Builds a new Field, fetching data from all the aligned neighbors. A neighbor is considered to be aligned it it has reached the exact same DefaultTimeEfficientCodePath. The field will always contain at least one value, namely the value of the local device. The deferred version does not immediately schedule the local value for being sent away. Rather, it schedules the provided Supplier to be executed at the end of the round for obtaining the value to be shared. This function is the base upon which the ShareCall is built.
        Type Parameters:
        T - the type of the input
        R - the type of the output
        Parameters:
        computeValue - a function that will be applied to localValue and the equivalents shared from neighbors in the process of constructing this field: the field consists of the values returned from applying computeValue to each of device's value
        currentLocal - the value to be used as local for this field
        toBeSent - a Supplier which will be used to compute the local value for this field that will get exported at the end of the round
        Returns:
        a new Field containing the local device value and the values for any of the aligned neighbors

      • commit

        void commit()
        Called just after the VM is executed, to finalize information of the execution for the environment.

      • getCurrentTime

        java.lang.Number getCurrentTime()
        Returns:
        the current device time, absolute

      • getDeltaTime

        java.lang.Number getDeltaTime()
        Returns:
        the current time, relative to last round

      • getDeviceUID

        DeviceUID getDeviceUID()
        Returns:
        The unique identifier for the device where execution is taking place.

      • getPersistent

        <S> S getPersistent​(java.util.function.Supplier<S> ifAbsent)
        Gets a value that survives across rounds. If a value was stored at the previous iteration, then the previous value is returned. Otherwise, the alternative value is computed via isAbsent and stored for the future.
        Type Parameters:
        S - type of the value
        Parameters:
        ifAbsent - replacement
        Returns:
        the value

      • getVariable

        java.lang.Object getVariable​(Reference reference)
        Look up the value of a variable from the local environment.
        Parameters:
        reference - The variable to be looked up
        Returns:
        Value of the variable, or null if it cannot be found.

      • newCallStackFrame

        void newCallStackFrame​(byte... id)
        Parameters:
        id - stack frame type

      • newCallStackFrame

        void newCallStackFrame​(int... id)
        Parameters:
        id - stack frame type

      • runInNewStackFrame

        <T> T runInNewStackFrame​(int id,
                         java.util.function.Function<ExecutionContext,​T> operation)
        Type Parameters:
        T - the return type
        Parameters:
        id - stack frame type
        operation - the operation to run in the new context
        Returns:
        the result of the evaluation

      • nextRandomDouble

        double nextRandomDouble()
        Obtain a system-independent (pseudo)random number.
        Returns:
        a uniformly distributed value between 0.0 and 1.0

      • putMultipleVariables

        void putMultipleVariables​(java.util.Map<Reference,​?> map)
        Pushes multiple variables.
        Parameters:
        map - the variables to push

      • putVariable

        void putVariable​(Reference name,
                 java.lang.Object value)
        Puts a variable value, overwriting the previous one, if any.
        Parameters:
        name - variable reference
        value - variable value

      • restrictDomain

        ExecutionContext restrictDomain​(Field<?> f)
        Give a field, returns a new ExecutionContext whose domain is the same of the field one.
        Parameters:
        f - the field
        Returns:
        the restricted domain

      • returnFromCallFrame

        void returnFromCallFrame()
        returns from the last frame.

      • setGloballyAvailableReferences

        void setGloballyAvailableReferences​(java.util.Map<Reference,​?> knownFunctions)
        Used internally to support first-class functions by make the functions of a program accessible for reflection at runtime.
        Parameters:
        knownFunctions - Collection of accessible functions, associating function name and value.

      • setPersistent

        void setPersistent​(java.lang.Object o)
        Stores a value to be used in future rounds via getPersistent.
        Parameters:
        o - the value to store

      • setup

        void setup()
        Called just before the VM is executed, to enable and preparations needed in the environment.