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(MachineHost).

Method Summary

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.
void	beep(short frequency, short duration) Play a sound using the machine's built-in speaker.
void	beep(java.lang.String pattern) Utility method for playing beep codes.
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.
double	getCostPerTick() Gets the amount of energy this machine consumes per tick when it is running.
MachineHost	host() The owner of the machine, usually a tile entity hosting the machine.
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.Object[]	invoke(Value value, java.lang.String method, java.lang.Object[] args) Makes the machine call a value callback.
java.lang.String	lastError() A string with the last error message.
int	maxComponents() The maximum number of components this machine can currently support.
java.util.Map<java.lang.String,Callback>	methods(java.lang.Object value) Get a list of all methods and their annotations of the specified object.
void	onHostChanged() This must be called from the host when something relevant to the machine changes, such as a change in the amount of available memory.
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.
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.machine.Context

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

Method Detail

host

MachineHost host()

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

Returns:

the owner of the machine.

onHostChanged

void onHostChanged()

This must be called from the host when something relevant to the machine changes, such as a change in the amount of available memory.

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.

This may be null, for example when the hosting computer has no CPU installed.

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.

maxComponents

int maxComponents()

The maximum number of components this machine can currently support.

This is automatically recomputed based on the hosts internal components whenever the host calls onHostChanged().

Returns:

the maximum number of components supported.

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.

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.

beep

void beep(short frequency,
          short duration)

Play a sound using the machine's built-in speaker.

This is what's used to emit beep codes when an error occurs while trying to start the computer, for example, and what's used for playing sounds when computer.beep is called.

Be responsible in how you limit calls to this, as each call will cause a packet to be sent to all nearby clients, and will cause the receiving clients to generate the required sound sample on-the-fly. It is therefore recommended to not call this too frequently, and to limit the length of the sound to something relatively short (not longer than a few seconds at most).

The audio will be played at the machine's host's location.

Parameters:

frequency - the frequency of the tone to generate.

duration - the duration of the tone to generate, in milliseconds.

beep

void beep(java.lang.String pattern)

Utility method for playing beep codes.

The underlying functionality is similar to that of beep(short, short), except that this will play tones at a fixed frequency, and two different durations - in a pattern as defined in the passed string.

This is useful for generating beep codes, such as for boot errors. It has the advantage of only generating a single network packet, and generating a single, longer sound sample for the full pattern. As such the same considerations should be made as for beep(short, short), i.e. prefer not to use overly long patterns.

The passed pattern must consist of dots (.) and dashes (-), where a dot is short tone, and a dash is a long tone.

The audio will be played at the machine's host's location.

Parameters:

pattern - the beep pattern to play.

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.

methods

java.util.Map<java.lang.String,Callback> methods(java.lang.Object value)

Get a list of all methods and their annotations of the specified object.

The specified object can be either a Value or a Environment. This is useful for custom architectures, to allow providing a list of callback methods to evaluated programs.

Parameters:

value - the value to get the method listing for.

Returns:

the methods that can be called on the object.

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.

invoke

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

Makes the machine call a value 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 specified value.

This will will ensure that the direct call limit for individual callbacks is respected.

Parameters:

value - the value 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.

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.