Package org.protelis.vm.impl

Class AbstractExecutionContext<S extends AbstractExecutionContext<S>>

  • Type Parameters:
    S - self-type. Subclasses must parameterize AbstractExecutionContext with themselves, and return themselves in instance(). This forces a compiler check on the type of instanced contexts, ensuring (if no foolish cast is used) that restricted contexts have all the methods available in the main ExecutionContext. For instance, if your class is MyContext, it should be written as MyContext extends AbstractExecutionContext<MyContext>.
    All Implemented Interfaces:
    ExecutionContext
    public abstract class AbstractExecutionContext<S extends AbstractExecutionContext<S>>
extends java.lang.Object
implements ExecutionContext
    Partial implementation of ExecutionContext, containing functionality expected to be shared between most implementations. Instantiations of Protelis should generally extend this class.

    • Constructor Detail

      • AbstractExecutionContext

        protected AbstractExecutionContext​(ExecutionEnvironment execenv,
                                   NetworkManager netmgr)
        Create a new AbstractExecutionContext with a default, time-efficient code path factory.
        Parameters:
        execenv - The execution environment
        netmgr - Abstract network interface to be used

      • AbstractExecutionContext

        protected AbstractExecutionContext​(ExecutionEnvironment executionEnvironment,
                                   NetworkManager networkManager,
                                   CodePathFactory codePathFactory)
        Create a new AbstractExecutionContext with the specified CodePathFactory. Subclasses which want to use hashing or other means to encode CodePaths can call this constructor, e.g.: 
         super(executionEnvironment, networkManager, new HashingCodePathFactory(Hashing.sha256()));
        Parameters:
        executionEnvironment - The execution environment
        networkManager - Abstract network interface to be used
        codePathFactory - The code path factory to use

    • Method Detail

      • buildField

        public final <T,​R> Field<R> buildField​(java.util.function.Function<T,​R> computeValue,
                                             T localValue)
        Description copied from interface: ExecutionContext
        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.
        Specified by:
        buildField in interface ExecutionContext
        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

        public final <T,​R> Field<R> buildFieldDeferred​(java.util.function.Function<T,​R> computeValue,
                                                     T currentLocal,
                                                     java.util.function.Supplier<T> toBeSent)
        Description copied from interface: ExecutionContext
        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.
        Specified by:
        buildFieldDeferred in interface ExecutionContext
        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

        public final void commit()
        Description copied from interface: ExecutionContext
        Called just after the VM is executed, to finalize information of the execution for the environment.
        Specified by:
        commit in interface ExecutionContext

      • commitRecursively

        protected final void commitRecursively()
        recursively commits on restricted contexts.

      • getDeltaTime

        public java.lang.Number getDeltaTime()
        Specified by:
        getDeltaTime in interface ExecutionContext
        Returns:
        the current time, relative to last round

      • getFunctions

        protected final java.util.Map<Reference,​?> getFunctions()
        Support for first-class functions by returning the set of currently accessible functions.
        Returns:
        Map from function name to function objects

      • getNetworkManager

        protected final NetworkManager getNetworkManager()
        Accessor for abstract network interface.
        Returns:
        Current abstract network interface

      • getPersistent

        public final <P> P getPersistent​(java.util.function.Supplier<P> ifAbsent)
        Description copied from interface: ExecutionContext
        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.
        Specified by:
        getPersistent in interface ExecutionContext
        Type Parameters:
        P - type of the value
        Parameters:
        ifAbsent - replacement
        Returns:
        the value

      • getVariable

        public final java.lang.Object getVariable​(Reference name)
        Description copied from interface: ExecutionContext
        Look up the value of a variable from the local environment.
        Specified by:
        getVariable in interface ExecutionContext
        Parameters:
        name - The variable to be looked up
        Returns:
        Value of the variable, or null if it cannot be found.

      • getStoredState

        public final java.util.Map<CodePath,​java.lang.Object> getStoredState()
        Returns:
        a view on the state stored in this context.

      • instance

        protected abstract S instance()
        Produce a child execution context, for encapsulated evaluation of sub-programs.
        Returns:
        Child execution context

      • newCallStackFrame

        public final void newCallStackFrame​(byte... id)
        Specified by:
        newCallStackFrame in interface ExecutionContext
        Parameters:
        id - stack frame type

      • newCallStackFrame

        public final void newCallStackFrame​(int... id)
        Specified by:
        newCallStackFrame in interface ExecutionContext
        Parameters:
        id - stack frame type

      • putVariable

        public final void putVariable​(Reference name,
                              java.lang.Object value)
        Description copied from interface: ExecutionContext
        Puts a variable value, overwriting the previous one, if any.
        Specified by:
        putVariable in interface ExecutionContext
        Parameters:
        name - variable reference
        value - variable value

      • runInNewStackFrame

        public final <T> T runInNewStackFrame​(int id,
                                      java.util.function.Function<ExecutionContext,​T> operation)
        Specified by:
        runInNewStackFrame in interface ExecutionContext
        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

      • setGloballyAvailableReferences

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

      • setPersistent

        public final void setPersistent​(java.lang.Object o)
        Description copied from interface: ExecutionContext
        Stores a value to be used in future rounds via getPersistent.
        Specified by:
        setPersistent in interface ExecutionContext
        Parameters:
        o - the value to store

      • setup

        public final void setup()
        Description copied from interface: ExecutionContext
        Called just before the VM is executed, to enable and preparations needed in the environment.
        Specified by:
        setup in interface ExecutionContext