Co‐routine Threading

Warning

This page's documentation is currently being updated as part of #680. Some information may be inaccurate.

Application Pseudo-Threading

All applications except for the Supervisor utilize co-routines to act as a multi-threading system. There is one "main" co-routine on each of those devices that is responsible for handling the OS event queue, and then auxiliary co-routines for handling various tasks.

This setup provides two key benefits to the different sub-groups of threaded devices, those that run Mekanism API calls and those that perform long-running graphics render tasks.

Main "Thread"

Main threads are always responsible for handling peripheral disconnect/reconnects, receiving modem messages, handling mouse events, stopping the system on terminate events, and handling watchdog, loop clock, and other timer events. OS pullEvent or pullEventRaw consumes all events in a co-routine, so having a single thread perform this central loop management while others can block on peripheral calls prevents the loss of events.

The main thread communicates with the others via "shared memory" that includes flags, objects, and message queues. These message queues can contain simple integer alerts, communications frames or packets, or other arbitrary data.

Mekanism Co-routine Advantages

For the first group, the co-routine threading allows auxiliary co-routines to run commands that would consume the event queue, usually the Mekanism API calls. Bringing those functions out of the main co-routine means that it can always catch all the incoming events, rather than some of them being consumed by Mekanism functions waiting for task_complete events.

Additionally, in any given peripheral query, all functions are called in parallel co-routines to try to resolve all checks in a single server tick. The RPS functions this way, along with all the Mekanism RTUs, to quickly check status values rather than taking entire seconds to perform a single update query.

Graphics Render Advantages

For the second group, the co-routine threading allows long-running graphics render tasks that yield often to run in a separate co-routine, allowing the main event handler to continue to process timer events and communications messages, preventing the system from locking up relative to the other devices in the network while it completes a render. This is used by the Coordinator to launch the initial multi-display render task from blank, and by the Pocket computer to launch apps fresh.

Application Termination

Note that terminate events (triggered by ctrl + T or the terminate button) are sometimes caught while doing peripheral related commands, due to receiving a terminate before the command has completed with task_complete. The PPM records this with a flag as it catches that error, then the main thread checks if the PPM detected that they system should terminate.

Application Implementations

Reactor PLC

The Reactor PLC has 5 co-routines running via the ComputerCraft parallel API:

• Main Thread
• RPS Thread
• Communications Tx (Transmit) Thread
• Communications Rx (Receive) Thread
• Setpoint Control Thread

Main Thread

The PLC main thread is responsible for timer events, modem messages, peripheral connections and disconnections, mouse events, and terminate events. To instruct other threads, it sends information across command and data queues to prevent blocking the main thread. For example, it can trip a timeout RPS trip due to a watchdog event via smem.q.mq_rps.push_command(MQ__RPS_CMD.TRIP_TIMEOUT), which passes an RPS command across the message queue object that the RPS thread can look for. It also pushes parsed packets to the communications Rx queue as it receives modem messages, and updates device status and peripheral references on peripheral connect/disconnect events.

RTU Gateway

Coordinator

Pocket