Package li.cil.oc2.api.bus

Interface DeviceBusElement

All Superinterfaces:
DeviceBus
All Known Subinterfaces:
BlockDeviceBusElement
public interface DeviceBusElement extends DeviceBus
Represents a single connection point on a device bus.

The only way for DeviceBusElements to be added to a bus is for a DeviceBusController to detect them during a scan.

When discovered during a scan, the controller will then use the devices connected to this element.

This interface is relevant when implementing means to extend the bus, e.g. to provide a custom cable implementation or some kind of device container.

Implementations must call DeviceBus.scheduleScan() when they become invalid, e.g. due to being in a chunk that is being unloaded or the block they are defined by being destroyed or the block face they were available through no longer offering the element.

  • Method Details

    • addController

      void addController(DeviceBusController controller)
      Registers a controller with this bus element.

      This will be called by DeviceBusControllers when scanning.

      Bus elements can have multiple controllers at the same time. This is used by controllers to detect each other on the bus.

      When DeviceBus.scheduleScan() is called, DeviceBusController.scheduleBusScan() must be called for each registered controller.

      Parameters:
      controller - the controller to add.

    • removeController

      void removeController(DeviceBusController controller)
      Unregisters a controller from this bus element.
      Parameters:
      controller - the controller to remove.

    • getControllers

      Collection<DeviceBusController> getControllers()
      Get the bus controllers of the buses this element is on, if any.
      Returns:
      the bus controllers.

    • getNeighbors

      Optional<Collection<Invalidatable<DeviceBusElement>>> getNeighbors()
      Returns a stream of adjacent bus elements.

      May return Optional.empty() when the neighbors cannot be determined at this time. This is typically the case when an adjacent block is currently not loaded. Not to be confused with an empty stream, which simply means the element has no neighbors.

      Returns:
      the adjacent bus elements, if possible.

    • getLocalDevices

      Collection<Device> getLocalDevices()
      Returns the list of devices connected specifically by this element.

      This differs from DeviceBus.getDevices() in such that DeviceBus.getDevices() will return all devices connected to the controller, if this element is registered with a controller.

      This method is called by the DeviceBusController the element is registered with when the global list of devices is rebuilt, e.g. after a call to DeviceBusController.scanDevices().

      Returns:
      the devices that have been added to this element.

    • getDeviceIdentifier

      Optional<UUID> getDeviceIdentifier(Device device)
      Returns an identifier unique to the specified device.

      This id must persist over save/load to prevent code in a running VM losing track of the device. Note that some device types (e.g. RPCDevices) require for an ID to be provided for them to work at all.

      It is possible for multiple devices to have the same identifier. Typically, this means they represent a view on the same underlying object. How this is handled depends on the device type and may or may not be supported.

      Only devices retrieved by calling getLocalDevices() should be passed to this method.

      Parameters:
      device - the device to obtain the ID for.
      Returns:
      the stable id for the specified device.

    • invalidateDevices

      default void invalidateDevices()
      Called when the machine this element belongs to changes architecture, meaning devices managed by this bus element have to be recreated because their providers may return a different device based on the new architecture.

    • getEnergyConsumption

      default double getEnergyConsumption()
      Returns the energy consumption of this bus element.

      Energy cost of a single bus element may vary depending on its configuration. For example, bus cables will also take into account the number of installed bus interfaces. Internal bus elements used to connect item devices will take into account the energy consumption of any connected item devices.

      Block devices that require a running amount of energy should use regular means of having energy injected into them. The device bus is not intended for nor communicated as something that transfers power.

      Returns:
      the complexity of this bus element.