ThreadWrapper

This file defines the ThreadWrapper class, which manages IPC (Inter-Process Communication) between the main process and worker threads in the @sodacore/core library. It is responsible for importing and managing the lifecycle of thread modules, handling IPC messages, managing a queue for asynchronous responses, and ensuring graceful startup and shutdown of threads.

---

Features

• Module Importing: Dynamically imports and instantiates the thread module from a given filename.
• Lifecycle Management: Calls onInit, onStart, and onStop lifecycle methods on the thread module if they exist.
• IPC Handling: Listens for IPC messages from the main process and routes them to the appropriate handler or module method.
• Queue Management: Maintains a queue of pending IPC requests and resolves them when responses are received or time out.
• Graceful Shutdown: Handles process signals and ensures the thread is stopped cleanly.

---

Usage

import ThreadWrapper from './module/thread';

const thread = new ThreadWrapper('/path/to/thread-module.js');
await thread.init();
await thread.start();
// ... handle IPC as needed
await thread.stop();

---

API

Constructor

constructor(protected filename: string)

• filename: The path to the file containing the thread module to load.

---

Methods

async init(): Promise<void>

Imports and instantiates the thread module. Calls its onInit method if present.

async start(): Promise<void>

Calls the onStart method of the thread module if present.

async stop(): Promise<void>

Clears the queue and timer, and calls the onStop method of the thread module if present.

async handleIpc(message: IThreadMessage): Promise<void>

Handles incoming IPC messages:

• Routes control commands (prefixed with @) to handleIpcCommand.
• Resolves queued promises for result messages.
• For other messages, calls the module's onIpc method and sends the response.

createIpcCallback(uid: string, item: IThreadQueueItem): void

Adds a new item to the IPC queue with a timestamp for timeout tracking.

private handleQueueTimeout(): void

Checks the queue for items that have timed out and resolves their promises with null.

private async handleIpcCommand(message: IThreadMessage): Promise<void>

Handles built-in IPC commands:

• @init: Imports registry data, initializes the module, and sends a result.
• @start: Starts the module and sends a result.
• @stop: Initiates a graceful shutdown and exits the process.

---

How It Works

1. Initialization: Creates a timer to check for queue timeouts and sets up IPC event listeners for process messages and signals.

2. IPC Handling: Listens for messages from the main process. Handles control commands, result messages, and forwards other messages to the thread module.

3. Queue Management: Keeps track of pending IPC requests and resolves them when a response is received or when they time out.

4. Lifecycle: Handles initialization, starting, and stopping of the thread module, including cleanup and process exit.

---

Notes

• The thread module must export a class with optional onInit, onStart, onStop, and onIpc methods.
• The queue ensures that asynchronous IPC requests are resolved or timed out properly.
• The wrapper listens for SIGINT and beforeExit to ensure a graceful shutdown.
• This class is used internally by the thread bootstrap process and is not intended for direct use in application code.