Module org.praxislive.script
Package org.praxislive.script

Interface StackFrame

All Known Implementing Classes:
AbstractSingleCallFrame, InlineCommand.InlineStackFrame, ScriptStackFrame
public interface StackFrame
A StackFrame used within the script executor pointing to the currently executing command. A StackFrame is created for each execution of a Command using Command.createStackFrame(org.praxislive.script.Namespace, java.util.List).

A StackFrame should always start off in StackFrame.State.Incomplete. The script executor will call process(org.praxislive.script.Env). During processing the StackFrame may evaluate a result, make one or more Calls, or create a child StackFrame (eg. from evaluation of another command).

If a Call has been made, the state should remain incomplete. Any returning call will be passed into postResponse(org.praxislive.core.Call).

If a child StackFrame has been returned, the result of its processing will be passed into postResponse(org.praxislive.script.StackFrame.State, java.util.List).

Once a response has been posted, the script executor will check if the StackFrame is still marked incomplete. If it is still incomplete, the executor will call process(org.praxislive.script.Env) again. If it has any other state, the state and result will be posted up to the parent StackFrame if there is one, or returned as the script result.

  • Method Details

    • getState

      StackFrame.State getState()
      Get the current state of this StackFrame.
      Returns:
      current state

    • process

      StackFrame process(Env env)
      Process the StackFrame. After processing, the StackFrame should have made one or more Calls, returned a child StackFrame, or moved out of the Incomplete state.

      Process may be called multiple times if the state is still incomplete after this method returns and a response has been posted.

      Parameters:
      env - processing environment
      Returns:
      child StackFrame or null

    • postResponse

      void postResponse(Call call)
      Used by the script executor to post the result of a Call. The StackFrame should validate the match ID of the response call against any pending calls before processing the call state or arguments.

      If the state is still incomplete after a response is posted, process(org.praxislive.script.Env) will be called again.

      Parameters:
      call - response call
      Throws:
      IllegalStateException - if the state is not incomplete or a call response is not expected

    • postResponse

      void postResponse(StackFrame.State state, List<Value> args)
      Used by the script executor to post the result of a child StackFrame returned by process(org.praxislive.script.Env).

      If the state is still incomplete after a response is posted, process(org.praxislive.script.Env) will be called again.

      Parameters:
      state - the completion state of the child stack frame
      args - the result of the child stack frame
      Throws:
      IllegalStateException - if the state is not incomplete or a child stack frame result is not expected

    • result

      List<Value> result()
      Access the result of this StackFrame.
      Returns:
      result
      Throws:
      IllegalStateException - if the state is incomplete

    • andThen

      default StackFrame andThen(Function<List<Value>,StackFrame> stage)
      Combine this StackFrame with another created from the result of this StackFrame. The returned StackFrame will execute the frames in turn.

      The default implementation returns a private implementation of a compound stackframe. If this method is called on an existing compound stack frame, then the stage function will be added to that and this will be returned.

      Parameters:
      stage - function to create next stack frame from result
      Returns:
      compound stackframe

    • andThenMap

      default StackFrame andThenMap(UnaryOperator<List<Value>> mapper)
      Map the result of this StackFrame with the provided mapping function before returning a result or using andThen(java.util.function.Function).

      The default implementation calls andThen(java.util.function.Function) with a function that creates a private implementation of a mapping StackFrame.

      Parameters:
      mapper - map value list
      Returns:
      mapping stackframe

    • call

      static StackFrame call(ControlAddress to, Value arg)
      Create a StackFrame that makes a call to the provided control and returns the result.
      Parameters:
      to - control address
      arg - single argument
      Returns:
      stackframe

    • call

      static StackFrame call(ControlAddress to, List<Value> args)
      Create a StackFrame that makes a call to the provided control and returns the result.
      Parameters:
      to - control address
      args - arguments
      Returns:
      stackframe

    • serviceCall

      static StackFrame serviceCall(Class<? extends Service> service, String control, Value arg)
      Create a StackFrame that makes a call to the provided Service and returns the result. The first implementation of the service found in the Env lookup will be used.
      Parameters:
      service - type of service
      control - id of control on service
      arg - single argument
      Returns:
      stackframe
      Throws:
      ServiceUnavailableException - if no implementation of the service is found

    • serviceCall

      static StackFrame serviceCall(Class<? extends Service> service, String control, List<Value> args)
      Create a StackFrame that makes a call to the provided Service and returns the result. The first implementation of the service found in the Env lookup will be used.
      Parameters:
      service - type of service
      control - id of control on service
      args - arguments
      Returns:
      stackframe
      Throws:
      ServiceUnavailableException - if no implementation of the service is found

    • async

      static StackFrame async(TaskService.Task task)
      Create a StackFrame that executes the provided task asynchronously in the default TaskService and returns the result.
      Parameters:
      task - task to execute
      Returns:
      stackframe