Add support for a zero-copy Lua table

The API is entirely designed for the needs of the speaker right now, so
doesn't do much else.

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

@@ -183,6 +183,24 @@ public interface IArguments
         return (Map<?, ?>) value;
     }
 
+    /**
+     * Get an argument as a table in an unsafe manner.
+     *
+     * Classes implementing this interface may choose to implement a more optimised version which does not copy the
+     * table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that
+     * they do not access off the computer thread (and so should not be used with main-thread functions) or once the
+     * function call has finished (for instance, in callbacks).
+     *
+     * @param index The argument number.
+     * @return The argument's value.
+     * @throws LuaException If the value is not a table.
+     */
+    @Nonnull
+    default LuaTable<?, ?> getTableUnsafe( int index ) throws LuaException
+    {
+        return new ObjectLuaTable( getTable( index ) );
+    }
+
     /**
      * Get an argument as a double.
      *
@@ -314,6 +332,27 @@ public interface IArguments
         return Optional.of( (Map<?, ?>) value );
     }
 
+    /**
+     * Get an argument as a table in an unsafe manner.
+     *
+     * Classes implementing this interface may choose to implement a more optimised version which does not copy the
+     * table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that
+     * they do not access off the computer thread (and so should not be used with main-thread functions) or once the
+     * function call has finished (for instance, in callbacks).
+     *
+     * @param index The argument number.
+     * @return The argument's value, or {@link Optional#empty()} if not present.
+     * @throws LuaException If the value is not a table.
+     */
+    @Nonnull
+    default Optional<LuaTable<?, ?>> optTableUnsafe( int index ) throws LuaException
+    {
+        Object value = get( index );
+        if( value == null ) return Optional.empty();
+        if( !(value instanceof Map) ) throw LuaValues.badArgumentOf( index, "map", value );
+        return Optional.of( new ObjectLuaTable( (Map<?, ?>) value ) );
+    }
+
     /**
      * Get an argument as a double.
      *
@@ -404,4 +443,13 @@ public interface IArguments
     {
         return optTable( index ).orElse( def );
     }
+
+    /**
+     * This is called when the current function finishes, before any main thread tasks have run.
+     *
+     * Called when the current function returns, and so some values are no longer guaranteed to be safe to access.
+     */
+    default void releaseImmediate()
+    {
+    }
 }

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

@@ -51,8 +51,17 @@ public @interface LuaFunction
      * Run this function on the main server thread. This should be specified for any method which interacts with
      * Minecraft in a thread-unsafe manner.
      *
-     * @return Whether this functi
+     * @return Whether this function should be run on the main thread.
      * @see ILuaContext#issueMainThreadTask(ILuaTask)
      */
     boolean mainThread() default false;
+
+    /**
+     * Allow using "unsafe" arguments, such {@link IArguments#getTableUnsafe(int)}.
+     *
+     * This is incompatible with {@link #mainThread()}.
+     *
+     * @return Whether this function supports unsafe arguments.
+     */
+    boolean unsafe() default false;
 }

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

@@ -0,0 +1,114 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2021. 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 org.jetbrains.annotations.Nullable;
+
+import javax.annotation.Nonnull;
+import java.util.Map;
+
+import static dan200.computercraft.api.lua.LuaValues.*;
+
+public interface LuaTable<K, V> extends Map<K, V>
+{
+    /**
+     * Compute the length of the array part of this table.
+     *
+     * @return This table's length.
+     */
+    default int length()
+    {
+        int size = 0;
+        while( containsKey( (double) (size + 1) ) ) size++;
+        return size;
+    }
+
+    /**
+     * Get an array entry as an integer.
+     *
+     * @param index The index in the table, starting at 1.
+     * @return The table's value.
+     * @throws LuaException If the value is not an integer.
+     */
+    default long getLong( int index ) throws LuaException
+    {
+        Object value = get( (double) index );
+        if( !(value instanceof Number) ) throw badTableItem( index, "number", getType( value ) );
+
+        Number number = (Number) value;
+        double asDouble = number.doubleValue();
+        if( !Double.isFinite( asDouble ) ) throw badTableItem( index, "number", getNumericType( asDouble ) );
+        return number.longValue();
+    }
+
+    /**
+     * Get a table entry as an integer.
+     *
+     * @param key The name of the field in the table.
+     * @return The table's value.
+     * @throws LuaException If the value is not an integer.
+     */
+    default long getLong( String key ) throws LuaException
+    {
+        Object value = get( key );
+        if( !(value instanceof Number) ) throw badField( key, "number", getType( value ) );
+
+        Number number = (Number) value;
+        double asDouble = number.doubleValue();
+        if( !Double.isFinite( asDouble ) ) throw badField( key, "number", getNumericType( asDouble ) );
+        return number.longValue();
+    }
+
+    /**
+     * Get an array entry as an integer.
+     *
+     * @param index The index in the table, starting at 1.
+     * @return The table's value.
+     * @throws LuaException If the value is not an integer.
+     */
+    default int getInt( int index ) throws LuaException
+    {
+        return (int) getLong( index );
+    }
+
+    /**
+     * Get a table entry as an integer.
+     *
+     * @param key The name of the field in the table.
+     * @return The table's value.
+     * @throws LuaException If the value is not an integer.
+     */
+    default int getInt( String key ) throws LuaException
+    {
+        return (int) getLong( key );
+    }
+
+
+    @Nullable
+    @Override
+    default V put( K o, V o2 )
+    {
+        throw new UnsupportedOperationException( "Cannot modify LuaTable" );
+    }
+
+    @Override
+    default V remove( Object o )
+    {
+        throw new UnsupportedOperationException( "Cannot modify LuaTable" );
+    }
+
+    @Override
+    default void putAll( @Nonnull Map<? extends K, ? extends V> map )
+    {
+        throw new UnsupportedOperationException( "Cannot modify LuaTable" );
+    }
+
+    @Override
+    default void clear()
+    {
+        throw new UnsupportedOperationException( "Cannot modify LuaTable" );
+    }
+}

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

@@ -102,6 +102,34 @@ public final class LuaValues
         return new LuaException( "bad argument #" + (index + 1) + " (" + expected + " expected, got " + actual + ")" );
     }
 
+    /**
+     * Construct a table item exception, from an expected and actual type.
+     *
+     * @param index    The index into the table, starting from 1.
+     * @param expected The expected type for this table item.
+     * @param actual   The provided type for this table item.
+     * @return The constructed exception, which should be thrown immediately.
+     */
+    @Nonnull
+    public static LuaException badTableItem( int index, @Nonnull String expected, @Nonnull String actual )
+    {
+        return new LuaException( "table item #" + index + " is not " + expected + " (got " + actual + ")" );
+    }
+
+    /**
+     * Construct a field exception, from an expected and actual type.
+     *
+     * @param key      The name of the field.
+     * @param expected The expected type for this table item.
+     * @param actual   The provided type for this table item.
+     * @return The constructed exception, which should be thrown immediately.
+     */
+    @Nonnull
+    public static LuaException badField( String key, @Nonnull String expected, @Nonnull String actual )
+    {
+        return new LuaException( "field " + key + " is not " + expected + " (got " + actual + ")" );
+    }
+
     /**
      * Ensure a numeric argument is finite (i.e. not infinite or {@link Double#NaN}.
      *

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

@@ -5,10 +5,12 @@
  */
 package dan200.computercraft.api.lua;
 
+import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Objects;
+import java.util.Optional;
 
 /**
  * An implementation of {@link IArguments} which wraps an array of {@link Object}.
@@ -16,6 +18,8 @@ import java.util.Objects;
 public final class ObjectArguments implements IArguments
 {
     private static final IArguments EMPTY = new ObjectArguments();
+
+    private boolean released = false;
     private final List<Object> args;
 
     @Deprecated
@@ -63,4 +67,34 @@ public final class ObjectArguments implements IArguments
     {
         return args.toArray();
     }
+
+    @Nonnull
+    @Override
+    public LuaTable<?, ?> getTableUnsafe( int index ) throws LuaException
+    {
+        if( released )
+        {
+            throw new IllegalStateException( "Cannot use getTableUnsafe after IArguments has been released" );
+        }
+
+        return IArguments.super.getTableUnsafe( index );
+    }
+
+    @Nonnull
+    @Override
+    public Optional<LuaTable<?, ?>> optTableUnsafe( int index ) throws LuaException
+    {
+        if( released )
+        {
+            throw new IllegalStateException( "Cannot use optTableUnsafe after IArguments has been released" );
+        }
+
+        return IArguments.super.optTableUnsafe( index );
+    }
+
+    @Override
+    public void releaseImmediate()
+    {
+        released = true;
+    }
 }

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

@@ -0,0 +1,73 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2021. 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.Collection;
+import java.util.Collections;
+import java.util.Map;
+import java.util.Set;
+
+public class ObjectLuaTable implements LuaTable<Object, Object>
+{
+    private final Map<Object, Object> map;
+
+    public ObjectLuaTable( Map<?, ?> map )
+    {
+        this.map = Collections.unmodifiableMap( map );
+    }
+
+    @Override
+    public int size()
+    {
+        return map.size();
+    }
+
+    @Override
+    public boolean isEmpty()
+    {
+        return map.isEmpty();
+    }
+
+    @Override
+    public boolean containsKey( Object o )
+    {
+        return map.containsKey( o );
+    }
+
+    @Override
+    public boolean containsValue( Object o )
+    {
+        return map.containsKey( o );
+    }
+
+    @Override
+    public Object get( Object o )
+    {
+        return map.get( o );
+    }
+
+    @Nonnull
+    @Override
+    public Set<Object> keySet()
+    {
+        return map.keySet();
+    }
+
+    @Nonnull
+    @Override
+    public Collection<Object> values()
+    {
+        return map.values();
+    }
+
+    @Nonnull
+    @Override
+    public Set<Entry<Object, Object>> entrySet()
+    {
+        return map.entrySet();
+    }
+}