Co‐routine Threading

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

Review the threads.lua files in any of the four applications using threading for how that particular devices uses it. Shared memory is always defined in startup.lua near the start of the main function entry point.