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 Summary

Modifier and Type	Method and Description
<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.
<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.
void	commit() Called just after the VM is executed, to finalize information of the execution for the environment.
java.lang.Number	getCurrentTime()
java.lang.Number	getDeltaTime()
DeviceUID	getDeviceUID()
ExecutionEnvironment	getExecutionEnvironment()
<S> S	getPersistent(java.util.function.Supplier<S> ifAbsent) Gets a value that survives across rounds.
java.lang.Object	getVariable(Reference reference) Look up the value of a variable from the local environment.
void	newCallStackFrame(byte... id)
void	newCallStackFrame(int... id)
double	nextRandomDouble() Obtain a system-independent (pseudo)random number.
void	putMultipleVariables(java.util.Map<Reference,?> map) Pushes multiple variables.
void	putVariable(Reference name, java.lang.Object value) Puts a variable value, overwriting the previous one, if any.
ExecutionContext	restrictDomain(Field<?> f) Give a field, returns a new ExecutionContext whose domain is the same of the field one.
void	returnFromCallFrame() returns from the last frame.
<T> T	runInNewStackFrame(int id, java.util.function.Function<ExecutionContext,T> operation)
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.
void	setPersistent(java.lang.Object o) Stores a value to be used in future rounds via getPersistent.
void	setup() Called just before the VM is executed, to enable and preparations needed in the environment.

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.

getExecutionEnvironment

ExecutionEnvironment getExecutionEnvironment()

Returns:

The current ExecutionEnvironment

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.