li.cil.oc.api.network

Annotation Type Callback

@Retention(value=RUNTIME)
@Target(value=METHOD)
public @interface Callback

This annotation can be used for methods in an Environment to mark them for exposure to computers.

Any method exposed like this can be enumerated and called from a computer that can see the node of the environment.

Note that methods annotated with this interface must have the following signature:

     Object[] f(Context context, Arguments arguments);
 

The method may return null in case it doesn't wish return anything, which is functionally equivalent to returning an empty array.

To raise an error from your callback, simply throw an exception. The convention for Lua is to return (null, "reason") for 'soft' errors, i.e. errors that are no fault of the caller. For example, passing invalid arguments will generate an exception, requesting information and the lookup of said information failing should not.

See Also:

Context, Arguments

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	direct Whether this function may be called directly from the computer's executor thread instead of from the server thread.
java.lang.String	doc A documentation string that is made available to the computers the component this callback belongs to is connected to.
int	limit The maximum number of direct calls that may be performed on this component in a single tick.
java.lang.String	value The name under which to make the callback available.

Element Detail

value

public abstract java.lang.String value

The name under which to make the callback available.

This defaults to the name of the annotated method if left empty.

Default:

""

direct

public abstract boolean direct

Whether this function may be called directly from the computer's executor thread instead of from the server thread.

You will have to ensure anything your callback does is thread safe when setting this to true. Use this for minor lookups, for example. This is mainly intended to allow functions to perform faster than when called 'synchronously' (where the call takes at least one server tick).

Keep in mind that the node Network is not thread safe! Be sure you know what you're doing if you're working with a node's network in a direct callback.

Default:

false

limit

public abstract int limit

The maximum number of direct calls that may be performed on this component in a single tick.

This can be used to throttle call speed. For example, this is used by graphics cards to limit the amount of net traffic can be generated by updating the screen they are bound to.

You should generally apply a limit if the callback allocates persisting memory (i.e. memory that isn't freed once the call returns), sends network messages, or uses any other kind of resource for which it'd be bad if it were to be used from user programs in an unchecked, unregulated manner.

Note that the limit does not apply when the method is invoked via a direct call to Component.invoke(String, Context, Object...) from the host side. Also, this limit is per-computer, so the method may be invoked more often than this per tick, if different computers call it.

An exception to that rule is Connector.changeBuffer(double), which is synchronized, so you can consume/produce power in direct calls.

Default:

2147483647

doc

public abstract java.lang.String doc

A documentation string that is made available to the computers the component this callback belongs to is connected to. This allows for ingame documentation of callbacks.

You may want to give a short description of what a method does here, but more importantly you should document the expected parameters and return type here.

Default:

""