li.cil.oc.api.machine

Interface Machine

All Superinterfaces:

Context, Environment, ManagedEnvironment, Persistable

public interface Machine
extends ManagedEnvironment, Context

This interface allows interacting with a Machine obtained via the factory method Machine.create(Owner, Class). It is primarily intended to be used by custom Architecture implementations.

Method Summary

Methods

Modifier and Type	Method and Description
void	addUser(java.lang.String name) Add a player to the machine's list of users, by username.
Architecture	architecture() The underlying architecture of the machine.
int	componentCount() The number of connected components.
java.util.Map<java.lang.String,java.lang.String>	components() The list of components attached to this machine.
double	cpuTime() The time spent running the underlying architecture in execution threads, i.e.
boolean	crash(java.lang.String message) Crashes the computer.
java.lang.String	documentation(java.lang.String address, java.lang.String method) Retrieves the docstring for the specified method of the specified component.
double	getCostPerTick() Gets the amount of energy this machine consumes per tick when it is running.
java.lang.Object[]	invoke(java.lang.String address, java.lang.String method, java.lang.Object[] args) Makes the machine call a component callback.
java.lang.String	lastError() A string with the last error message.
Owner	owner() The owner of the machine, usually a tile entity hosting the machine.
Signal	popSignal() Tries to pop a signal from the queue and returns it.
boolean	removeUser(java.lang.String name) Removes a player as a user from this machine, by username.
java.lang.String	romAddress() The address of the file system that holds the machine's read only data (rom).
void	setCostPerTick(double value) Sets the amount of energy this machine consumes per tick when it is running.
java.lang.String	tmpAddress() The address of the file system that holds the machine's temporary files (tmpfs).
double	upTime() The time that has passed since the machine was started, in seconds.
java.lang.String[]	users() The list of users registered on this machine.
long	worldTime() The current world time.

Methods inherited from interface li.cil.oc.api.network.ManagedEnvironment

canUpdate, update

Methods inherited from interface li.cil.oc.api.network.Environment

node, onConnect, onDisconnect, onMessage

Methods inherited from interface li.cil.oc.api.Persistable

load, save

Methods inherited from interface li.cil.oc.api.network.Context

address, canInteract, isPaused, isRunning, node, pause, signal, start, stop

Method Detail

owner

Owner owner()

The owner of the machine, usually a tile entity hosting the machine.

Returns:

the owner of the machine.

architecture

Architecture architecture()

The underlying architecture of the machine.

This is what actually evaluates code running on the machine, where the machine class itself serves as a scheduler.

Returns:

the architecture of this machine.

components

java.util.Map<java.lang.String,java.lang.String> components()

The list of components attached to this machine.

This maps address to component type/name. Note that the list may not immediately reflect changes after components were added to the network, since such changes are cached in an internal list of 'added components' that are processed in the machine's update logic (i.e. server tick).

This list is kept up-to-date automatically, do not mess with it.

Returns:

the list of attached components.

componentCount

int componentCount()

The number of connected components.

This number can differ from components().size(), since this is the number of actually connected components, which is used to determine whether the component limit has been exceeded, for example. It takes into account components added but not processed, yet (see also components()).

Returns:

the number of connected components.

getCostPerTick

double getCostPerTick()

Gets the amount of energy this machine consumes per tick when it is running.

Returns:

the energy consumed per tick by the machine.

setCostPerTick

void setCostPerTick(double value)

Sets the amount of energy this machine consumes per tick when it is running.

Parameters:

value - the energy consumed per tick by the machine.

romAddress

java.lang.String romAddress()

The address of the file system that holds the machine's read only data (rom). This file system is populated based on the backing resource file systems specified for the machines architecture via Machine.addRomResource(Class, java.util.concurrent.Callable, String). This may return null if the creation of the file system failed.

Use this in a custom architecture to allow code do differentiate the tmpfs from other file systems, for example.

Returns:

the address of the rom component, or null.

tmpAddress

java.lang.String tmpAddress()

The address of the file system that holds the machine's temporary files (tmpfs). This may return null if either the creation of the file system failed, or if the size of the tmpfs has been set to zero in the config.

Use this in a custom architecture to allow code do differentiate the tmpfs from other file systems, for example.

Returns:

the address of the tmpfs component, or null.

lastError

java.lang.String lastError()

A string with the last error message.

The error string is set either when the machine crashes (see the crash(String) method), or when it fails to start (which, technically, is also a crash).

When the machine started, this is reset to null.

Returns:

the last error message, or null.

worldTime

long worldTime()

The current world time. This is updated each tick and provides a thread safe way to access the world time for architectures.

This is equivalent to owner().world().getWorldTime().

Returns:

the current world time.

upTime

double upTime()

The time that has passed since the machine was started, in seconds.

Note that this is actually measured in world time, so the resolution is pretty limited. This is done to avoid 'time skips' when leaving the game and coming back later, resuming a persisted machine.

cpuTime

double cpuTime()

The time spent running the underlying architecture in execution threads, i.e. the time spent in Architecture.runThreaded(boolean) since the machine was last started, in seconds.

crash

boolean crash(java.lang.String message)

Crashes the computer.

This is exactly the same as Context.stop(), except that it also sets the error message in the machine. This message can be seen when the Analyzer is used on computer cases, for example.

Parameters:

message - the message to set.

Returns:

true if the computer switched to the stopping state.

popSignal

Signal popSignal()

Tries to pop a signal from the queue and returns it.

Signals are stored in a FIFO queue of limited size. This method is / must be called by architectures regularly to process the queue.

Returns:

a signal or null if the queue was empty.

invoke

java.lang.Object[] invoke(java.lang.String address,
                        java.lang.String method,
                        java.lang.Object[] args)
                          throws java.lang.Exception

Makes the machine call a component callback.

This is intended to be used from architectures, but may be useful in other scenarios, too. It will make the machine call the method with the specified name on the attached component with the specified address.

This will perform a visibility check, ensuring the component can be seen from the machine. It will also ensure that the direct call limit for individual callbacks is respected.

Parameters:

address - the address of the component to call the method on.

method - the name of the method to call.

args - the list of arguments to pass to the callback.

Returns:

a list of results returned by the callback, or null.

Throws:

LimitReachedException - when the called method supports direct calling, but the number of calls in this tick has exceeded the allowed limit.

java.lang.IllegalArgumentException - if there is no such component.

java.lang.Exception - if the callback throws an exception.

documentation

java.lang.String documentation(java.lang.String address,
                             java.lang.String method)

Retrieves the docstring for the specified method of the specified component. This is the string set in a method's Callback annotation.

Parameters:

address - the address of the component.

method - the name of the method.

Returns:

the docstring for that method.

users

java.lang.String[] users()

The list of users registered on this machine.

This list is used for Context.canInteract(String). Exposed for informative purposes only, for example to expose it to user code. Note that the returned array is a copy of the internal representation of the user list. Changing it has no influence on the actual list.

Returns:

the list of registered users.

addUser

void addUser(java.lang.String name)
             throws java.lang.Exception

Add a player to the machine's list of users, by username.

This requires for the player to be online.

Parameters:

name - the name of the player to add as a user.

Throws:

java.lang.Exception - if

• There are already too many users.
• The player is already registered.
• The provided name is too long.
• The player is not online.

removeUser

boolean removeUser(java.lang.String name)

Removes a player as a user from this machine, by username.

Unlike when adding players, the player does not have to be online to be removed from the list.

Parameters:

name - the name of the player to remove.

Returns:

whether the player was removed from the user list.