RFC: Replace ILuaContext with a non-blocking alternative

src/main/java/dan200/computercraft/api/lua/ICallContext.java

@@ -0,0 +1,31 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2018. This API may be redistributed unmodified and in full only.
+ * For help using the API, and posting your mods, visit the forums at computercraft.info.
+ */
+
+package dan200.computercraft.api.lua;
+
+import javax.annotation.Nonnull;
+
+/**
+ * An interface passed to peripherals and {@link ILuaObject}s by computers or turtles, providing methods that allow the
+ * method to interact with the invoking computer.
+ */
+public interface ICallContext
+{
+    /**
+     * Queue a task to be executed on the main server thread at the beginning of next tick, but do not wait for it to
+     * complete. This should be used when you need to interact with the world in a thread-safe manner but do not care
+     * about the result or you wish to run asynchronously.
+     *
+     * When the task has finished, it will enqueue a {@code task_completed} event, which takes the task id, a success
+     * value and the return values, or an error message if it failed. If you need to wait on this event, it may be
+     * better to use {@link MethodResult#onMainThread(ILuaCallable)}.
+     *
+     * @param task The task to execute on the main thread.
+     * @return The "id" of the task. This will be the first argument to the {@code task_completed} event.
+     * @throws LuaException If the task could not be queued.
+     */
+    long issueMainThreadTask( @Nonnull ILuaTask task ) throws LuaException;
+}

src/main/java/dan200/computercraft/api/lua/ILuaCallable.java

@@ -0,0 +1,31 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2018. This API may be redistributed unmodified and in full only.
+ * For help using the API, and posting your mods, visit the forums at computercraft.info.
+ */
+
+package dan200.computercraft.api.lua;
+
+import javax.annotation.Nonnull;
+
+/**
+ * A function which calls performs an action in a specific context (such as on the server thread) and returns a result.
+ *
+ * @see MethodResult#onMainThread(ILuaCallable)
+ * @see ILuaContext#executeMainThreadTask(ILuaTask)
+ */
+@FunctionalInterface
+public interface ILuaCallable
+{
+    /**
+     * Run the code within the specified context and return the result to continue with.
+     *
+     * @return The result of executing this function. Note that this may not be evaluated within the same context as
+     * this call is.
+     * @throws LuaException If you throw any exception from this function, a lua error will be raised with the
+     *                      same message as your exception. Use this to throw appropriate errors if the wrong
+     *                      arguments are supplied to your method.
+     */
+    @Nonnull
+    MethodResult execute() throws LuaException;
+}

src/main/java/dan200/computercraft/api/lua/ILuaContext.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of the public ComputerCraft API - http://www.computercraft.info
- * Copyright Daniel Ratcliffe, 2011-2017. This API may be redistributed unmodified and in full only.
+ * Copyright Daniel Ratcliffe, 2011-2018. This API may be redistributed unmodified and in full only.
  * For help using the API, and posting your mods, visit the forums at computercraft.info.
  */
 
@@ -13,8 +13,11 @@
  * An interface passed to peripherals and {@link ILuaObject}s by computers or turtles, providing methods
  * that allow the peripheral call to wait for events before returning, just like in lua. This is very useful if you need
  * to signal work to be performed on the main thread, and don't want to return until the work has been completed.
+ *
+ * This interface mostly exists for integrating with older code. One should use {@link MethodResult} instead, as this
+ * encourages an asynchronous way of interacting with Lua coroutines.
  */
-public interface ILuaContext
+public interface ILuaContext extends ICallContext
 {
     /**
      * Wait for an event to occur on the computer, suspending the thread until it arises. This method is exactly
@@ -30,8 +33,10 @@ public interface ILuaContext
      * @throws InterruptedException If the user shuts down or reboots the computer while pullEvent() is waiting for an
      *                              event, InterruptedException will be thrown. This exception must not be caught or
      *                              intercepted, or the computer will leak memory and end up in a broken state.
+     * @deprecated Use {@link MethodResult#pullEvent(String, ILuaFunction)}
      */
     @Nonnull
+    @Deprecated
     Object[] pullEvent( @Nullable String filter ) throws LuaException, InterruptedException;
 
     /**
@@ -45,8 +50,10 @@ public interface ILuaContext
      *                              an event, InterruptedException will be thrown. This exception must not be caught or
      *                              intercepted, or the computer will leak memory and end up in a broken state.
      * @see #pullEvent(String)
+     * @deprecated Use {@link MethodResult#pullEventRaw(String, ILuaFunction)}
      */
     @Nonnull
+    @Deprecated
     Object[] pullEventRaw( @Nullable String filter ) throws InterruptedException;
 
     /**
@@ -59,8 +66,10 @@ public interface ILuaContext
      *                              InterruptedException will be thrown. This exception must not be caught or
      *                              intercepted, or the computer will leak memory and end up in a broken state.
      * @see #pullEvent(String)
+     * @deprecated Use {@link MethodResult#pullEventRaw(ILuaFunction)}
      */
     @Nonnull
+    @Deprecated
     Object[] yield( @Nullable Object[] arguments ) throws InterruptedException;
 
     /**
@@ -76,22 +85,9 @@ public interface ILuaContext
      * @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended,
      *                              InterruptedException will be thrown. This exception must not be caught or
      *                              intercepted, or the computer will leak memory and end up in a broken state.
+     * @deprecated Use {@link MethodResult#onMainThread(ILuaCallable)}
      */
     @Nullable
+    @Deprecated
     Object[] executeMainThreadTask( @Nonnull ILuaTask task ) throws LuaException, InterruptedException;
-
-    /**
-     * Queue a task to be executed on the main server thread at the beginning of next tick, but do not wait for it to
-     * complete. This should be used when you need to interact with the world in a thread-safe manner but do not care
-     * about the result or you wish to run asynchronously.
-     *
-     * When the task has finished, it will enqueue a {@code task_completed} event, which takes the task id, a success
-     * value and the return values, or an error message if it failed. If you need to wait on this event, it may be
-     * better to use {@link #executeMainThreadTask(ILuaTask)}.
-     *
-     * @param task The task to execute on the main thread.
-     * @return The "id" of the task. This will be the first argument to the {@code task_completed} event.
-     * @throws LuaException If the task could not be queued.
-     */
-    long issueMainThreadTask( @Nonnull ILuaTask task ) throws LuaException;
 }

src/main/java/dan200/computercraft/api/lua/ILuaContextTask.java

@@ -0,0 +1,24 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2018. This API may be redistributed unmodified and in full only.
+ * For help using the API, and posting your mods, visit the forums at computercraft.info.
+ */
+
+package dan200.computercraft.api.lua;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * A function which executes using a {@link ILuaContext}.
+ *
+ * Like {@link ILuaContext}, this is not intended for use in the future - it purely exists as an argument for
+ * {@link MethodResult#withLuaContext(ILuaContextTask)}.
+ */
+@FunctionalInterface
+public interface ILuaContextTask
+{
+    @Nullable
+    @Deprecated
+    Object[] execute( @Nonnull ILuaContext context ) throws LuaException, InterruptedException;
+}

src/main/java/dan200/computercraft/api/lua/ILuaFunction.java

@@ -0,0 +1,33 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2018. This API may be redistributed unmodified and in full only.
+ * For help using the API, and posting your mods, visit the forums at computercraft.info.
+ */
+
+package dan200.computercraft.api.lua;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * A Lua function which consumes some values and returns a result.
+ *
+ * @see MethodResult#then(ILuaFunction)
+ * @see MethodResult#pullEvent(ILuaFunction)
+ * @see MethodResult#pullEventRaw(String)
+ */
+@FunctionalInterface
+public interface ILuaFunction
+{
+    /**
+     * Accept the values and return another method result.
+     *
+     * @param values The inputs for this function.
+     * @return The result of executing this function.
+     * @throws LuaException If you throw any exception from this function, a lua error will be raised with the
+     *                      same message as your exception. Use this to throw appropriate errors if the wrong
+     *                      arguments are supplied to your method.
+     */
+    @Nonnull
+    MethodResult call( @Nullable Object[] values ) throws LuaException;
+}

src/main/java/dan200/computercraft/api/lua/ILuaObject.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of the public ComputerCraft API - http://www.computercraft.info
- * Copyright Daniel Ratcliffe, 2011-2017. This API may be redistributed unmodified and in full only.
+ * Copyright Daniel Ratcliffe, 2011-2018. This API may be redistributed unmodified and in full only.
  * For help using the API, and posting your mods, visit the forums at computercraft.info.
  */
 
@@ -41,16 +41,41 @@ public interface ILuaObject
      *                  wishes to call. The integer indicates the index into the getMethodNames() table
      *                  that corresponds to the string passed into peripheral.call()
      * @param arguments The arguments for this method. See {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])}
-     *                  the possible values and conversion rules.
-     * @return An array of objects, representing the values you wish to return to the Lua program.
-     * See {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])} for the valid values and
-     * conversion rules.
+     *                  for the possible values and conversion rules.
+     * @return An array of objects, representing the values you wish to return to the Lua program. See
+     * {@link MethodResult#of(Object...)}  for the valid values and conversion rules.
      * @throws LuaException         If the task could not be queued, or if the task threw an exception.
      * @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended,
      *                              InterruptedException will be thrown. This exception must not be caught or
      *                              intercepted, or the computer will leak memory and end up in a broken state.w
      * @see IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])
+     * @deprecated Use {@link #callMethod(ICallContext, int, Object[])} instead.
      */
     @Nullable
+    @Deprecated
     Object[] callMethod( @Nonnull ILuaContext context, int method, @Nonnull Object[] arguments ) throws LuaException, InterruptedException;
+
+    /**
+     * Called when a user calls one of the methods that this object implements. This works the same as
+     * {@link IPeripheral#callMethod(IComputerAccess, ICallContext, int, Object[])}}. See that method for detailed
+     * documentation.
+     *
+     * @param context   The context of the current call.
+     * @param method    An integer identifying which of the methods from getMethodNames() the computercraft
+     *                  wishes to call. The integer indicates the index into the getMethodNames() table
+     *                  that corresponds to the string passed into peripheral.call()
+     * @param arguments The arguments for this method. See {@link IPeripheral#callMethod(IComputerAccess, ICallContext, int, Object[])}
+     *                  for the possible values and conversion rules.
+     * @return The result of calling this method. Use {@link MethodResult#empty()} to return nothing or
+     * {@link MethodResult#of(Object...)} to return several values.
+     * @throws LuaException If the task could not be queued, or if the task threw an exception.
+     * @see IPeripheral#callMethod(IComputerAccess, ICallContext, int, Object[])
+     * @see MethodResult
+     */
+    @Nonnull
+    @SuppressWarnings({ "deprecation" })
+    default MethodResult callMethod( @Nonnull ICallContext context, int method, @Nonnull Object[] arguments ) throws LuaException
+    {
+        return MethodResult.withLuaContext( lua -> callMethod( lua, method, arguments ) );
+    }
 }

src/main/java/dan200/computercraft/api/lua/LuaContextResultEvaluator.java

@@ -0,0 +1,105 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2018. This API may be redistributed unmodified and in full only.
+ * For help using the API, and posting your mods, visit the forums at computercraft.info.
+ */
+
+package dan200.computercraft.api.lua;
+
+import javax.annotation.Nonnull;
+import java.util.ArrayDeque;
+import java.util.Deque;
+
+/**
+ * Evaluates {@link MethodResult}s within a {@link ILuaContext}.
+ *
+ * @see MethodResult#evaluate(ILuaContext)
+ * @see MethodResult#withLuaContext(ILuaContextTask)
+ * @deprecated This should not be used except to interface between the two call call systems.
+ */
+@Deprecated
+class LuaContextResultEvaluator
+{
+    @Deprecated
+    public static Object[] evaluate( @Nonnull ILuaContext context, @Nonnull MethodResult future ) throws LuaException, InterruptedException
+    {
+        Deque<ILuaFunction> callbacks = null;
+        while( true )
+        {
+            if( future instanceof MethodResult.AndThen )
+            {
+                MethodResult.AndThen then = ((MethodResult.AndThen) future);
+
+                // Thens are "unwrapped", being pushed onto a stack
+                if( callbacks == null ) callbacks = new ArrayDeque<>();
+                callbacks.addLast( then.getCallback() );
+
+                future = then.getPrevious();
+                if( future == null ) throw new NullPointerException( "Null result from " + then.getCallback() );
+            }
+            else if( future instanceof MethodResult.Immediate )
+            {
+                Object[] values = ((MethodResult.Immediate) future).getResult();
+
+                // Immediate values values will attempt to call the previous "then", or return if nothing 
+                // else needs to be done.
+                ILuaFunction callback = callbacks == null ? null : callbacks.pollLast();
+                if( callback == null ) return values;
+
+                future = callback.call( values );
+                if( future == null ) throw new NullPointerException( "Null result from " + callback );
+            }
+            else if( future instanceof MethodResult.OnEvent )
+            {
+                MethodResult.OnEvent onEvent = (MethodResult.OnEvent) future;
+
+                // Poll for an event, and then call the previous "then" or return if nothing else needs 
+                // to be done. 
+                Object[] values = onEvent.isRaw() ? context.pullEventRaw( onEvent.getFilter() ) : context.pullEvent( onEvent.getFilter() );
+
+                ILuaFunction callback = callbacks == null ? null : callbacks.pollLast();
+                if( callback == null ) return values;
+
+                future = callback.call( values );
+                if( future == null ) throw new NullPointerException( "Null result from " + callback );
+            }
+            else if( future instanceof MethodResult.OnMainThread )
+            {
+                MethodResult.OnMainThread onMainThread = (MethodResult.OnMainThread) future;
+
+                // Evaluate our task on the main thread and mark it as the next future to evaluate.
+                Reference temporary = new Reference();
+                context.executeMainThreadTask( () -> {
+                    temporary.value = onMainThread.getTask().execute();
+                    return null;
+                } );
+
+                future = temporary.value;
+                if( future == null ) throw new NullPointerException( "Null result from " + onMainThread.getTask() );
+            }
+            else if( future instanceof MethodResult.WithLuaContext )
+            {
+                MethodResult.WithLuaContext withContext = (MethodResult.WithLuaContext) future;
+
+                // Run the task, and then call the previous "then" or return if nothing else
+                // needs to be done. 
+                Object[] values = withContext.getConsumer().execute( context );
+
+                ILuaFunction callback = callbacks == null ? null : callbacks.pollLast();
+                if( callback == null ) return values;
+
+                future = callback.call( values );
+                if( future == null ) throw new NullPointerException( "Null result from " + callback );
+            }
+            else
+            {
+                throw new IllegalStateException( "Unknown MethodResult " + future );
+            }
+        }
+    }
+
+    private static class Reference
+    {
+        MethodResult value;
+    }
+}