105 lines
6.0 KiB
Java
105 lines
6.0 KiB
Java
/*
|
|
* This file is part of the public ComputerCraft API - http://www.computercraft.info
|
|
* Copyright Daniel Ratcliffe, 2011-2020. 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;
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
public interface ILuaContext
|
|
{
|
|
/**
|
|
* Wait for an event to occur on the computer, suspending the thread until it arises. This method is exactly
|
|
* equivalent to {@code os.pullEvent()} in lua.
|
|
*
|
|
* @param filter A specific event to wait for, or null to wait for any event.
|
|
* @return An object array containing the name of the event that occurred, and any event parameters.
|
|
* @throws LuaException If the user presses CTRL+T to terminate the current program while pullEvent() is
|
|
* waiting for an event, a "Terminated" exception will be thrown here.
|
|
*
|
|
* Do not attempt to catch this exception. You should use {@link #pullEventRaw(String)}
|
|
* should you wish to disable termination.
|
|
* @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.
|
|
*/
|
|
@Nonnull
|
|
default Object[] pullEvent( @Nullable String filter ) throws LuaException, InterruptedException
|
|
{
|
|
Object[] results = pullEventRaw( filter );
|
|
if( results.length >= 1 && results[0].equals( "terminate" ) ) throw new LuaException( "Terminated", 0 );
|
|
return results;
|
|
}
|
|
|
|
/**
|
|
* The same as {@link #pullEvent(String)}, except "terminated" events are ignored. Only use this if you want to
|
|
* prevent program termination, which is not recommended. This method is exactly equivalent to
|
|
* {@code os.pullEventRaw()} in lua.
|
|
*
|
|
* @param filter A specific event to wait for, or null to wait for any event.
|
|
* @return An object array containing the name of the event that occurred, and any event parameters.
|
|
* @throws InterruptedException If the user shuts down or reboots the computer while pullEventRaw() 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.
|
|
* @see #pullEvent(String)
|
|
*/
|
|
@Nonnull
|
|
default Object[] pullEventRaw( @Nullable String filter ) throws InterruptedException
|
|
{
|
|
return yield( new Object[] { filter } );
|
|
}
|
|
|
|
/**
|
|
* Yield the current coroutine with some arguments until it is resumed. This method is exactly equivalent to
|
|
* {@code coroutine.yield()} in lua. Use {@code pullEvent()} if you wish to wait for events.
|
|
*
|
|
* @param arguments An object array containing the arguments to pass to coroutine.yield()
|
|
* @return An object array containing the return values from coroutine.yield()
|
|
* @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.
|
|
* @see #pullEvent(String)
|
|
*/
|
|
@Nonnull
|
|
Object[] yield( @Nullable Object[] arguments ) throws InterruptedException;
|
|
|
|
/**
|
|
* Queue a task to be executed on the main server thread at the beginning of next tick, waiting for it to complete.
|
|
* This should be used when you need to interact with the world in a thread-safe manner.
|
|
*
|
|
* Note that the return values of your task are handled as events, meaning more complex objects such as maps or
|
|
* {@link ILuaObject} will not preserve their identities.
|
|
*
|
|
* @param task The task to execute on the main thread.
|
|
* @return The objects returned by {@code task}.
|
|
* @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.
|
|
*/
|
|
@Nullable
|
|
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;
|
|
}
|