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 Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description <T,R>
Field<R>buildField(java.util.function.Function<T,R> computeValue, T localValue)
Builds a newField
, 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 newField
, 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 newExecutionContext
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 newField
, fetching data from all the aligned neighbors. A neighbor is considered to be aligned it it has reached the exact sameDefaultTimeEfficientCodePath
. The field will always contain at least one value, namely the value of the local device.- Type Parameters:
T
- the type of the inputR
- 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 valuelocalValue
- 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 newField
, fetching data from all the aligned neighbors. A neighbor is considered to be aligned it it has reached the exact sameDefaultTimeEfficientCodePath
. 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 providedSupplier
to be executed at the end of the round for obtaining the value to be shared. This function is the base upon which theShareCall
is built.- Type Parameters:
T
- the type of the inputR
- 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 valuecurrentLocal
- the value to be used as local for this fieldtoBeSent
- aSupplier
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 typeoperation
- 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 referencevalue
- variable value
-
restrictDomain
ExecutionContext restrictDomain(Field<?> f)
Give a field, returns a newExecutionContext
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.
-
-