Module messaging

Communication with the terminal user or webserver uses POSIX message queues. This is a platform-specific feature and hence uses conditional compilation. The communication is always initiated externally. The module processes the input and forwards it to the respective thread via the channel. The control application does not respond to any request sent to the message queue. Provides the Inter-Process Communication (IPC) bridge for external control.

This module is responsible for listening to a POSIX message queue for commands sent from external processes (e.g., the command-line utility aquarium_control or the web server). It acts as the central point of dispatcher, translating these external messages into internal commands and forwarding them to the appropriate application threads (like Refill, Heating, Feed, etc.).

This entire module is conditionally compiled and is only available on target_os = "linux".

Key Components

• Messaging Struct: The core component that holds the POSIX message queue connection and runs the main dispatch loop.

• Message Struct: A simple data structure representing the raw command received from the message queue containing a domain, command, and parameters.

• execute() Method: The main loop of the Messaging thread. It performs the following:

  1. Listens for incoming byte messages on the POSIX queue.
  2. Parses the raw bytes into a Message struct.
  3. Interprets the message’s domain (e.g., Refill, Heating) and command.
  4. Sends the corresponding InternalCommand to the target thread via its channel.
  5. Listens for Quit and Terminate signals from the signal_handler for graceful shutdown.

Design and Architecture

The Messaging module serves as a crucial bridge between the running application and the outside world, allowing for dynamic control without restarting the service.

• Decoupling: It decouples the internal workings of the application from the specifics of the external control mechanism.
• Centralized Dispatch: All external commands flow through this single point, making the control flow easy to understand and debug.
• Robustness: It includes logic to handle unknown domains or commands gracefully by logging a warning and ignoring the message.

Example Message Flow

1. An external script sends a byte message to the /aquarium_control POSIX message queue. The message contains bytes representing: domain=HEATING, command=STOP.
2. The Messaging::execute() loop receives these bytes.
3. It parses the bytes into a Message struct.
4. It matches the domain to MessagingDomain::Heating and the command to InternalCommand::Stop.
5. It sends InternalCommand::Stop to the Heating thread’s channel.
6. The Heating thread receives the command and stops its operation.

The mermaid diagram in the Messaging struct documentation provides a visual overview of the communication paths.

Structs

Message

Stores the content of the message and provides functionality for testing.

Messaging

Struct provides data structure and implementation for IPC message queue communication. Thread communication of this component is as follows: