Repository navigation
Developer Architecture Core
Last updated: v0.6.0
GridLock handles extreme data concurrency by separating process coordination, memory reading, and security into distinct C++ components.
GridLock's entry point and primary event loop are managed here:
-
src/main.cpp&GridLockApp.cpp: Bootstraps theQApplication, configures the Wayland QPA (QT_QPA_PLATFORM=wayland), and initializes the core singleton managers before mounting theMainWindow. -
VersionManager.cpp(v0.6.0): A lightweight singleton exposing the build-system-generated version constants.meson.buildis the single source of truth for version numbers. At configure time, Meson processessrc/core/VersionConfig.hpp.inviaconfigure_file(), substituting@VERSION_MAJOR@,@VERSION_MINOR@, and@VERSION_PATCH@tokens. All UI components and the--versionCLI flag consumeVersionManager::instance()->versionString()rather than hardcoded literals.# meson.build (excerpt) version_conf = configuration_data() version_conf.set('VERSION_MAJOR', version_split[0]) version_conf.set('VERSION_MINOR', version_split[1]) version_conf.set('VERSION_PATCH', version_split[2]) configure_file( input : 'src/core/VersionConfig.hpp.in', output : 'VersionConfig.hpp', configuration : version_conf )
-
GdbRankCoordinator.cpp: The heart of the debugger. Manages an asynchronous subprocess pool. It routes multiplexed GDB/MI (Machine Interface) commands to the correct MPI rank, parsing the async JSON/Tuple responses back into Qt Signals. -
DapCoordinator.cpp: Implements the Debug Adapter Protocol (DAP) overstdin/stdout. Handles state requests, stack trace formatting, and JSON-RPC bridging. -
LspCoordinator.cpp: Spawns and manages a localclangdinstance. Provides semantic intelligence (hovers, go-to-definition) constrained to the user's workspace to prevent scope leaks.
Reading memory via standard ptrace for large matrices is computationally unviable. We bypass the debugger entirely for raw dumps:
-
NativeMemoryReader.cpp: Uses Linuxprocess_vm_readvto perform zero-copy reads directly from the target PID's virtual memory space into GridLock's memory space. -
MemoryBoundsValidator.cpp: Ensures that requested read lengths and base pointers do not page fault or read outside the target's.dataor.bsssegments, preventing cascading crashes. -
MemoryExporter.cpp: Takes validated memory buffers and converts them efficiently to.csvmatrices or binary blobs on disk.
Because GridLock interacts with remote execution environments and processes user input as commands, strict sanitization is enforced:
-
MiSanitizer.cpp: Intercepts all outgoing GDB/MI commands. Validates that the abstract syntax tree depth does not exceed max nesting 32 and the payload does not exceed 64KB. Prevents buffer overflow attacks against the underlying parser. -
TelemetryObfuscator.cpp: Ensures diagnostic data sent over the network is masked. Implements MTU padding and constant-time flushing to defend against side-channel traffic analysis.
-
SpackManager.cpp: Queries the target environment forspack env listand resolves dependency paths, injecting them into the localized run environment. -
MockHpcBackend.cpp: A critical abstraction used in CI/TDD. Simulates a multi-node SLURM cluster to validate rank coordination logic without requiring physical HPC hardware.
To maintain high responsiveness when dealing with HPC workloads and strict ASAN compliance, GridLock enforces strict threading rules:
-
No UI Blocking: Never perform blocking I/O, heavy JSON parsing, or
process_vm_readvsyscalls on the main GUI thread. -
Use QtConcurrent: All background workloads (like parsing large DAP payloads or reading matrices) must be dispatched via
QtConcurrent::run. - Strict Signal/Slot Boundary: Worker threads must never touch QWidgets directly. They must communicate results back to the main thread exclusively via Qt Signals (queued connections).
ConfigManager implements a two-tier override system to support both global user preferences and project-local settings without conflict.
| Priority | Source | Path |
|---|---|---|
| 1 (Highest) | Project-local override | <workspace_root>/.gridlock/workspace.toml |
| 2 (Fallback) | Global XDG user config | ~/.config/gridlock/config.toml |
Resolution logic (called on session load and ConfigManager::instance()->reload()):
// ConfigManager.cpp (simplified)
void ConfigManager::reload(const QString& workspaceRoot) {
// 1. Always load the global baseline first
loadFromFile(xdgConfigPath());
// 2. If a project-local override exists, merge it on top
QString localPath = workspaceRoot + "/.gridlock/workspace.toml";
if (QFile::exists(localPath)) {
mergeFromFile(localPath); // project values win on key collision
}
}This design means a project can ship a .gridlock/workspace.toml in source control to enforce a specific lldb-dap path, MPI rank count, or argument template without touching the developer's global ~/.config/gridlock/config.toml.
Prior to v0.6.0, a target crash (e.g., SIGFPE, segfault) during a DAP session would cause the IDE to silently hang — the debug adapter process would exit but the UI would never receive a terminal state transition.
In v0.6.0, DapCoordinator explicitly handles stopped events where reason is "exception":
Signal emitted:
// DapCoordinator.hpp
signals:
void targetCrashed(const QString& exceptionDescription);Dispatch logic in DapCoordinator.cpp:
void DapCoordinator::handleStoppedEvent(const QJsonObject& body) {
const QString reason = body["reason"].toString();
if (reason == "exception") {
QString desc = body.value("description").toString("Fatal exception");
emit targetCrashed(desc);
terminateSession(); // clean up the adapter process
return;
}
// ... normal stopped handling (breakpoint, step, etc.)
}MainWindow connection:
connect(m_dapCoordinator, &DapCoordinator::targetCrashed,
this, [this](const QString& desc) {
QMessageBox::critical(this, tr("Target Crashed"),
tr("The debug target terminated with a fatal exception:\n\n%1\n\n"
"The debug session has been closed.").arg(desc));
});This guarantees the UI always reaches a clean idle state after a crash, rather than waiting indefinitely for a terminated event that will never arrive.
GridLock Repository | Releases | Report an Issue | Roadmap | Accessibility | License (MIT)
Documentation mirrored from docs/ on master.
User Guides
Architecture & Plan
Developer Docs