net.sandius.rembulan.runtime

Interface ExecutionContext

All Superinterfaces:

MetatableAccessor, MetatableProvider, StateContext, TableFactory

public interface ExecutionContext
extends StateContext

An interface to the execution context of a Lua call.

This is the interface to the runtime environment in which Lua calls are executed, providing the mechanisms for including coroutine switching and the (optional) cooperative scheduler.

Note: Lua functions are not guaranteed to receive the same ExecutionContext instance between an invoke and a subsequent resume. Functions should therefore not retain the reference to the ExecutionContext that outlives an invoke or resume.

Note: The behaviour of the methods in this interface is undefined when invoked outside a Lua function invoke/resume.

Method Summary

Modifier and Type	Method and Description
Coroutine.Status	getCoroutineStatus(Coroutine coroutine) Returns the status of coroutine as seen from the perspective of this execution context.
Coroutine	getCurrentCoroutine() Returns the current coroutine.
ReturnBuffer	getReturnBuffer() Returns the return buffer used in this execution context.
boolean	isInMainCoroutine() Returns true if the current coroutine (as returned by getCurrentCoroutine()) is the main coroutine.
Coroutine	newCoroutine(LuaFunction function) Returns a new coroutine with the body function.
void	pause() (Unconditionally) pauses the execution.
void	pauseIfRequested() Pauses the execution if the according to the scheduler this call should be paused.
void	registerTicks(int ticks) Informs the scheduler that the current task is about to consume or has consumed ticks virtual ticks.
void	resume(Coroutine coroutine, Object[] args) Resumes the given coroutine coroutine, passing the arguments args to it.
void	resumeAfter(AsyncTask task) Resumes the current call after the asynchronous task task has been completed.
void	yield(Object[] args) Yields control to the coroutine resuming the current coroutine, passing the arguments args to it.

Methods inherited from interface net.sandius.rembulan.MetatableAccessor

setBooleanMetatable, setFunctionMetatable, setLightUserdataMetatable, setMetatable, setNilMetatable, setNumberMetatable, setStringMetatable, setThreadMetatable

Methods inherited from interface net.sandius.rembulan.MetatableProvider

getBooleanMetatable, getFunctionMetatable, getLightUserdataMetatable, getMetatable, getNilMetatable, getNumberMetatable, getStringMetatable, getThreadMetatable

Methods inherited from interface net.sandius.rembulan.TableFactory

newTable, newTable

Method Detail

getReturnBuffer

ReturnBuffer getReturnBuffer()

Returns the return buffer used in this execution context.

This is the mechanism by which Lua functions may return values (see e.g. ReturnBuffer.setToContentsOf(Object[])), or indicate that the return value is the result of a tail call (by e.g. ReturnBuffer.setToCallWithContentsOf(Object, Object[])).

The return values of Lua calls initiated from this execution context will also be stored in a return buffer accessible by this method (e.g. by ReturnBuffer.getAsArray() or ReturnBuffer.get(int)).

Note: the return buffer instance may change between subsequent invokes and resumes of the same function. The reference to the ReturnBuffer instance should therefore not be retained by the executed function beyond the scope of a single invoke or resume.

Returns:

the return buffer used in this execution context

getCurrentCoroutine

Coroutine getCurrentCoroutine()

Returns the current coroutine.

Returns:

the current coroutine

isInMainCoroutine

boolean isInMainCoroutine()

Returns true if the current coroutine (as returned by getCurrentCoroutine()) is the main coroutine.

Returns:

true if the current coroutine is the main coroutine

getCoroutineStatus

Coroutine.Status getCoroutineStatus(Coroutine coroutine)

Returns the status of coroutine as seen from the perspective of this execution context.

Parameters:

coroutine - the target coroutine, must not be null

Returns:

the status of coroutine from the perspective of this execution context

Throws:

NullPointerException - if coroutine is null

newCoroutine

Coroutine newCoroutine(LuaFunction function)

Returns a new coroutine with the body function.

The coroutine will be initialised in the suspended state. To resume the coroutine, use resume(Coroutine, Object[]).

Parameters:

function - coroutine body, must not be null

Returns:

a new (suspended) coroutine with the body function

Throws:

NullPointerException - if function is null

resume

void resume(Coroutine coroutine,
            Object[] args)
     throws UnresolvedControlThrowable

Resumes the given coroutine coroutine, passing the arguments args to it. This method throws an UnresolvedControlThrowable: non-local control changes are expected to be resolved by the caller of this method.

The reference to the array args is not retained by the execution context; args may therefore be freely re-used by the caller.

Parameters:

coroutine - the coroutine to be resumed, must not be null

args - arguments to be passed to coroutine, must not be null

Throws:

UnresolvedControlThrowable - the control throwable for this coroutine switch

NullPointerException - if coroutine or args is null

IllegalCoroutineStateException - when coroutine cannot be resumed

yield

void yield(Object[] args)
    throws UnresolvedControlThrowable

Yields control to the coroutine resuming the current coroutine, passing the arguments args to it. This method throws an UnresolvedControlThrowable: non-local control changes are expected to be resolved by the caller of this method.

The reference to the array args is not retained by the execution context; args may therefore be freely re-used by the caller.

Parameters:

args - arguments to be passed to the resuming coroutine, must not be null

Throws:

UnresolvedControlThrowable - the control throwable for this coroutine switch

NullPointerException - if args is null

IllegalCoroutineStateException - when yielding from a non-yieldable coroutine

resumeAfter

void resumeAfter(AsyncTask task)
          throws UnresolvedControlThrowable

Resumes the current call after the asynchronous task task has been completed. This method throws an UnresolvedControlThrowable: non-local control changes are expected to be resolved by the caller of this method.

In order to mark task as completed, the task must call AsyncTask.ContinueCallback.finished().

Parameters:

task - the task to be executed, must not be null

Throws:

UnresolvedControlThrowable - the control throwable for this control change

NullPointerException - if task is null

registerTicks

void registerTicks(int ticks)

Informs the scheduler that the current task is about to consume or has consumed ticks virtual ticks.

This method only registers ticks with the scheduler. In order to pause the execution if the scheduler indicates that it should be paused, use pauseIfRequested().

The behaviour of this method is undefined if ticks is negative.

Parameters:

ticks - number of ticks to be registered with the scheduler, must not be negative

pauseIfRequested

void pauseIfRequested()
               throws UnresolvedControlThrowable

Pauses the execution if the according to the scheduler this call should be paused. This method throws an UnresolvedControlThrowable: non-local control changes are expected to be resolved by the caller of this method.

To pause execution unconditionally, use pause().

Throws:

UnresolvedControlThrowable - the control throwable for this control change

pause

void pause()
    throws UnresolvedControlThrowable

(Unconditionally) pauses the execution. This method throws an UnresolvedControlThrowable: non-local control changes are expected to be resolved by the caller of this method.

Throws:

UnresolvedControlThrowable - the control throwable for this control change