Jika/oc2r
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add lifecycle flowchart to RPCDevice and VMDevice docs.

Browse Source
This commit is contained in:
Florian Nücke
2022-01-15 15:01:52 +01:00
parent e435262ab9
commit 65896892d7
2 changed files with 83 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
src/main/java/li/cil/oc2/api/bus/device/rpc/RPCDevice.java
View File

@@ -17,6 +17,39 @@ import java.util.List;
* <p>
* The easiest, and hence recommended, way of implementing this interface, is to use
* the {@link ObjectDevice} class.
* <p>
* The lifecycle for {@link RPCDevice}s is as follows:
* <pre>
* ┌──────────────────────────────────┐
* │VirtualMachine.isRunning() = false◄──────────────────────┐
* └────────────────┬─────────────────┘ │
* │ │
* ┌──────────▼───────────┐ │
* │VirtualMachine.start()│ │
* └──────────┬───────────┘ │
* │ │
* │ ┌──────────┐ │
* │ │Chunk Load│ ┌──────────────────┐ │
* ├───┼──────────◄────┤VMDevice.suspend()│ │
* │ │World Load│ └─────▲────────────┘ │
* │ └──────────┘ │ │
* │ │ │
* ┌────────▼───────┐ ┌─────┴──────┐ │
* ┌──────────►VMDevice.mount()│ │Chunk Unload│ │
* │ └────────┬───────┘ ┌─►────────────┤ │
* │ │ │ │World Unload│ │
* │ ┌─────────────────▼───────────────┐ │ └────────────┘ │
* │ │VirtualMachine.isRunning() = true├─┤ │
* │ └─────┬───────────────────┬───────┘ │ ┌──────────────────┐ │
* │ │ │ │ │Computer Shutdown │ │
* │ ┌─────▼──────┐ ┌──────▼───────┐ └─►──────────────────┤ │
* └─┤Device Added│ │Device Removed│ │Computer Destroyed│ │
* └────────────┘ └──────┬───────┘ └─────┬────────────┘ │
* │ │ │
* ┌────────▼─────────┐ ┌─────▼────────────┐ │
* │VMDevice.unmount()│ │VMDevice.unmount()├─┘
* └──────────────────┘ └──────────────────┘
* </pre>
*
* @see ObjectDevice
* @see li.cil.oc2.api.bus.device.provider.BlockDeviceProvider

50
src/main/java/li/cil/oc2/api/bus/device/vm/VMDevice.java
View File

@@ -16,6 +16,56 @@ import li.cil.sedna.api.device.MemoryMappedDevice;
* <p>
* To listen to lifecycle events of the VM and the device, register to the event
* bus provided via {@link VMContext#getEventBus()} in {@link #mount(VMContext)}.
* <p>
* The lifecycle for VMDevices can be depicted as such:
* <pre>
* ┌──────────────────────────────────┐
* │VirtualMachine.isRunning() = false◄────────────────────────┐
* └────────────────┬─────────────────┘ │
* │ │
* ┌──────────▼───────────┐ │
* │VirtualMachine.start()│ │
* └──────────┬───────────┘ │
* │ │
* │ ┌──────────┐ │
* │ │Chunk Load│ ┌──────────────────┐ │
* ├───┼──────────◄──┤VMDevice.suspend()◄───┐ │
* │ │World Load│ └──────────────────┘ │ │
* │ └──────────┘ │ │
* │ │ │
* ┌────────▼───────┐ ┌────┐ │ │
* ┌──────────►VMDevice.mount()◄───────┤Wait◄─────────┐ │ │
* │ └────────┬───────┘ └──▲─┘ │ │ │
* │ │ │ │ │ │
* │ │ ┌───────────────┴─────────┐ │ │ │
* │ ├──►VMDeviceLoadResult.fail()│ │ │ │
* │ │ └─────────────────────────┘ │ │ │
* │ │ │ │ │
* │ ┌──────────────▼─────────────┐ ┌──────────────┴───┐ │ │
* │ │VMDeviceLoadResult.success()│ │VMDevice.unmount()│ │ │
* │ └──────────────┬─────────────┘ └──────────────▲───┘ │ │
* │ │ │ │ │
* │ │ ┌─────────────────────┴───┐ │ │
* │ ├────────► Other VMDevice: │ │ │
* │ │ │VMDeviceLoadResult.fail()│ │ │
* │ │ └─────────────────────────┘ │ │
* │ │ │ │
* │ │ ┌────────────┐ │ │
* │ │ │Chunk Unload│ │ │
* │ │ ┌─►────────────┼─────┘ │
* │ │ │ │World Unload│ │
* │ ┌─────────────────▼───────────────┐ │ └────────────┘ │
* │ │VirtualMachine.isRunning() = true├───┤ │
* │ └─────┬───────────────────┬───────┘ │ ┌──────────────────┐ │
* │ │ │ │ │Computer Shutdown │ │
* │ ┌─────▼──────┐ ┌──────▼───────┐ └─►──────────────────┤ │
* └─┤Device Added│ │Device Removed│ │Computer Destroyed│ │
* └────────────┘ └──────┬───────┘ └─────────┬────────┘ │
* │ │ │
* ┌────────▼─────────┐ ┌─────────▼────────┐ │
* │VMDevice.unmount()│ │VMDevice.unmount()├─┘
* └──────────────────┘ └──────────────────┘
* </pre>
*
* @see li.cil.oc2.api.bus.device.provider.BlockDeviceProvider
* @see li.cil.oc2.api.bus.device.provider.ItemDeviceProvider