Introduce IWorkMonitor into the public API

This effectively acts as a public interface to canExecuteExternal() and
consumeTime(). It's hopefully sufficiently general that we can mess
around with the backend as much as we like in the future.

One thing to note here is that this is based on a polling API, as it's
largely intended for people running work every tick. It would be
possible to adapt this with callbacks for when work is available,
etc..., but that was not needed immediately.

This also removes IComputerOwned, as Plethora no longer needs it.

src/main/java/dan200/computercraft/api/peripheral/IComputerAccess.java

@@ -9,6 +9,8 @@ package dan200.computercraft.api.peripheral;
 import dan200.computercraft.api.ComputerCraftAPI;
 import dan200.computercraft.api.filesystem.IMount;
 import dan200.computercraft.api.filesystem.IWritableMount;
+import dan200.computercraft.api.lua.ILuaContext;
+import dan200.computercraft.api.lua.ILuaTask;
 import net.minecraft.world.World;
 
 import javax.annotation.Nonnull;
@@ -179,7 +181,7 @@ public interface IComputerAccess
     }
 
     /**
-     * Get a reachable peripheral with the given attachement name. This is a equivalent to
+     * Get a reachable peripheral with the given attachment name. This is a equivalent to
      * {@link #getAvailablePeripherals()}{@code .get(name)}, though may be more performant.
      *
      * @param name The peripheral's attached name
@@ -191,4 +193,23 @@ public interface IComputerAccess
     {
         return null;
     }
+
+    /**
+     * Get a {@link IWorkMonitor} for tasks your peripheral might execute on the main (server) thread.
+     *
+     * This should be used to ensure your peripheral integrates with ComputerCraft's monitoring and limiting of how much
+     * server time each computer consumes. You should not need to use this if you use
+     * {@link ILuaContext#issueMainThreadTask(ILuaTask)} - this is intended for mods with their own system for running
+     * work on the main thread.
+     *
+     * Please note that the returned implementation is <em>not</em> thread-safe, and should only be used from the main
+     * thread.
+     *
+     * @return The work monitor for the main thread, or {@code null} if this computer does not have one.
+     */
+    @Nullable
+    default IWorkMonitor getMainThreadMonitor()
+    {
+        return null;
+    }
 }

src/main/java/dan200/computercraft/api/peripheral/IWorkMonitor.java

@@ -0,0 +1,68 @@
+/*
+ * This file is part of ComputerCraft - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2019. Do not distribute without permission.
+ * Send enquiries to dratcliffe@gmail.com
+ */
+
+package dan200.computercraft.api.peripheral;
+
+import javax.annotation.Nonnull;
+import java.util.Objects;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Monitors "work" associated with a computer, keeping track of how much a computer has done, and ensuring every
+ * computer receives a fair share of any processing time.
+ *
+ * This is primarily intended for work done by peripherals on the main thread (such as on a tile entity's tick), but
+ * could be used for other purposes (such as complex computations done on another thread).
+ *
+ * Before running a task, one should call {@link #canWork()} to determine if the computer is currently allowed to
+ * execute work. If that returns true, you should execute the task and use {@link #trackWork(long, TimeUnit)} to inform
+ * the monitor how long that task took.
+ *
+ * Alternatively, use {@link #runWork(Runnable)} to run and keep track of work.
+ *
+ * @see IComputerAccess#getMainThreadMonitor()
+ */
+public interface IWorkMonitor
+{
+    /**
+     * If the owning computer is currently allowed to execute work.
+     *
+     * @return If we can execute work right now.
+     */
+    boolean canWork();
+
+    /**
+     * Inform the monitor how long some piece of work took to execute.
+     *
+     * @param time The time some task took to run
+     * @param unit The unit that {@code time} was measured in.
+     */
+    void trackWork( long time, @Nonnull TimeUnit unit );
+
+    /**
+     * Run a task if possible, and inform the monitor of how long it took.
+     *
+     * @param runnable The task to run.
+     * @return If the task was actually run (namely, {@link #canWork()} returned {@code true}).
+     */
+    default boolean runWork( @Nonnull Runnable runnable )
+    {
+        Objects.requireNonNull( runnable, "runnable should not be null" );
+        if( !canWork() ) return false;
+
+        long start = System.nanoTime();
+        try
+        {
+            runnable.run();
+        }
+        finally
+        {
+            trackWork( System.nanoTime() - start, TimeUnit.NANOSECONDS );
+        }
+
+        return true;
+    }
+}