Repository navigation
Tutorial
This tutorial walks through the 7 bundled MPI debugging showcase programs in tutorial/, followed by step-by-step guides for comparing process memory across ranks (DIFF RANKS), exporting raw memory slices (EXPORT), looking up offline man pages and Zeal docsets (F1), and managing system/HPC packages (PACKAGE MANAGER).

GridLock ships with 7 self-contained C++ MPI programs in tutorial/ that exercise common distributed bugs, memory layouts, and telemetry views:
| Example Source | Toolbar TARGET: Entry |
Primary Bug / Feature Demonstrated | Recommended Breakpoint |
|---|---|---|---|
tutorial/deadlock_ring.cpp |
deadlock_ring (MPI) |
8-rank synchronous MPI_Send ring deadlock |
Line 34 (MPI_Send) |
tutorial/inspection_demo.cpp |
inspection_demo (MPI) |
Deeply nested structs & rank-filtered conditional breakpoints | Line 19 (data[i].coords.x = ...) |
tutorial/collective_mismatch.cpp |
collective_mismatch (MPI) |
Even ranks call MPI_Bcast while odd ranks hit MPI_Barrier
|
Line 46 (if (rank % 2 == 0)) |
tutorial/ghost_cell_drift.cpp |
ghost_cell_drift (MPI) |
1D Jacobi stencil exchange (MPI_Sendrecv) with NaN injection on step 3 |
Line 69 (stencil_center = ...) |
tutorial/heap_imbalance.cpp |
heap_imbalance (MPI) |
Quadratically scaled per-rank heap allocation & recursion depth | Line 41 (leaf_checksum = ...) |
tutorial/tag_mismatch_stall.cpp |
tag_mismatch_stall (MPI) |
Point-to-point tag mismatch (send_tag = 100 vs expected_tag = 200) |
Line 53 (MPI_Send) / Line 61 (MPI_Recv) |
tutorial/simd_struct_watch.cpp |
simd_struct_watch (MPI) |
16-byte aligned SimdMatrixPacket (0xCAFE...) & raw memory export |
Line 60 (MPI_Allreduce) |
-
Directly from the GridLock Toolbar:
- Launch GridLock (
./builddir/gridlock). - Open the
TARGET:dropdown on the top toolbar and select any of the 7 showcase entries (for example,collective_mismatch (MPI)orghost_cell_drift (MPI)). - Set
RANKS (-np):to8(or4). - Click
⚙ Build(or pressCtrl+B) to compiletutorial/<name>.cppintotutorial/<name>withmpicxx -g -O0inside the integrated terminal, or click▶ Run Targetto let GridLock compile on demand and launch the session automatically.
- Launch GridLock (
-
Manual Command-Line Compilation:
for src in tutorial/deadlock_ring.cpp tutorial/inspection_demo.cpp \ tutorial/collective_mismatch.cpp tutorial/ghost_cell_drift.cpp \ tutorial/heap_imbalance.cpp tutorial/tag_mismatch_stall.cpp \ tutorial/simd_struct_watch.cpp; do mpicxx -g -O0 "$src" -o "${src%.cpp}" done
tutorial/deadlock_ring.cpp sets up a ring topology where every rank sends a 16,384-integer buffer (send_buf) to next_rank = (rank + 1) % size before posting the matching MPI_Recv from prev_rank = (rank + size - 1) % size:
std::vector<int> send_buf(16384, rank * 10 + 1);
std::vector<int> recv_buf(16384, 0);
MPI_Send(send_buf.data(), static_cast<int>(send_buf.size()), MPI_INT,
next_rank, tag, MPI_COMM_WORLD);
MPI_Recv(recv_buf.data(), static_cast<int>(recv_buf.size()), MPI_INT,
prev_rank, tag, MPI_COMM_WORLD, MPI_STATUS_IGNORE);Because the 64 KB buffer exceeds the typical MPI eager threshold, every rank blocks inside MPI_Send waiting for its neighbor to enter MPI_Recv.
- Select
deadlock_ring (MPI)inTARGET:, setRANKS (-np):to8, and click▶ Run Target. - Step or continue past
MPI_Inituntil execution blocks insideMPI_Sendat line 34. - Check
SERVER RACKon the right sidebar: all 8 rank slivers (R0–R7) indicate a stalled communication state. - Click
MPIon the bottom tool rail (Alt+3) to openMPI Diagnostics. TheDEADLOCK ANALYZERtab displays the circular wait-for chain (Rank 0 -> Rank 1 -> ... -> Rank 7 -> Rank 0). - In the
Disassemblypane (MAP (CFG)mode), inspect the[R0..R7]badges clustered on the basic block callingMPI_Send. Replace theMPI_Send/MPI_Recvpair withMPI_Sendrecv, save (Ctrl+S), and rebuild (⚙ Build).

tutorial/inspection_demo.cpp populates an array of nested structs (DeeplyNested data[3]) with rank-dependent values:
for (int i = 0; i < 3; i++) {
data[i].id = i;
for (int j = 0; j < 5; j++) data[i].values[j] = (rank + 1) * (i * j);
data[i].coords.x = (rank == 0) ? (i * 1.1f) : (i * 1.5f);
data[i].coords.y = (rank == 0) ? (i * 2.2f) : (i * 2.5f);
data[i].coords.z = (rank == 0) ? (i * 3.3f) : (i * 3.5f);
}- Select
inspection_demo (MPI)inTARGET:to opentutorial/inspection_demo.cpp. - Right-click the editor gutter on line 19 (
data[i].coords.x = ...) to open the Conditional Breakpoint Popover.

- Set Suspend Scope to Focused Rank Only (or All MPI Ranks) and type
data[i].coords.in the Condition field.ClangdLspClientqueriesclangdand suggestsx,y, andz. Complete the expression as:rank == 3 && data[i].coords.x > 0.0f
- Press
Enterand click▶ Run Target. Execution skips iterationi == 0(wherecoords.x == 0.0f) and pauses on iterationi == 1whendata[1].coords.xevaluates to1.5f. - Expand
datain the top-rightVARIABLEStab to inspectdata[0],data[1], anddata[2], including nestedvalues[5]andcoords.{x,y,z}fields.
tutorial/collective_mismatch.cpp branches on rank parity (rank % 2 == 0): even ranks call MPI_Bcast while odd ranks execute MPI_Barrier(MPI_COMM_WORLD).
if (rank % 2 == 0) {
cfg.rank_branch_tag = 100 + rank;
MPI_Bcast(&cfg.broadcast_seed, 1, MPI_INT, 0, MPI_COMM_WORLD);
} else {
cfg.rank_branch_tag = 200 + rank;
MPI_Barrier(MPI_COMM_WORLD);
}- Select
collective_mismatch (MPI)inTARGET:, setRANKS (-np):to8, and set a breakpoint on line 46 (if (rank % 2 == 0)). - Click
▶ Run Targetand step once (↷ Step Inst) into the branch. - Observe the
Disassemblypane inMAP (CFG)mode: even ranks ([R0, R2, R4, R6]) follow the true edge into the basic block callingMPI_Bcast, while odd ranks ([R1, R3, R5, R7]) follow the false edge into the basic block callingMPI_Barrier. - Open
MPI Diagnosticsin the bottom dock to inspect the mismatched collective call primitives across ranks.
tutorial/ghost_cell_drift.cpp performs a 5-step 1D Jacobi heat stencil exchange (MPI_Sendrecv) with periodic ring neighbors. On iteration step == 3, faulty_rank (Rank 2) injects std::numeric_limits<double>::quiet_NaN() into its right ghost boundary:
if (step == 3 && rank == faulty_rank) {
send_right = std::numeric_limits<double>::quiet_NaN();
}- Select
ghost_cell_drift (MPI)inTARGET:and set a breakpoint on line 69 (stencil_center = domain[domain.size() / 2];). - Switch to the top-right
WATCHtab (DifferentialGrid) and addstep,left_ghost,right_ghost, andstencil_center. - Click
▶ Run Targetand continue across timesteps:- On
step == 0..2, all ranks show finite temperature values. - On
step == 3, Rank 3'sleft_ghostturnsnanimmediately after receiving Rank 2's corrupted boundary value. - On
step == 4, thenanvalue spreads into neighboring interior stencil cells.
- On
tutorial/heap_imbalance.cpp scales each rank's std::vector<double> heap_buffer quadratically with (rank + 1) * (rank + 1) and recurses to a rank-dependent stack depth target_stack_depth = 2 + rank * 2 inside recurseWithStackFrame().
- Select
heap_imbalance (MPI)inTARGET:and set a breakpoint on line 41 (const double leaf_checksum = ...). - Click
▶ Run TargetwithRANKS (-np):set to8. - Click through
R0toR7in theSERVER RACKdock while watching the bottom status bar ribbon (ARCH: x86_64 | MPI RANK: ... | STACK: ... | HEAP: ... | RAM: ... | CPU: ...):- Higher ranks report deeper stack usage (
STACK) from additional recursive frames and larger heap allocations (HEAP). - You can switch between absolute memory units (
MB / GB) and percentages (%) inEdit -> Preferences -> Debugger(Status Bar Telemetry Format).
- Higher ranks report deeper stack usage (
In tutorial/tag_mismatch_stall.cpp, Rank 0 sends a TelemetryPacket to Rank 1 with send_tag = 100, whereas Rank 1 calls MPI_Recv waiting on expected_tag = 200:
// Rank 0 (line 53):
MPI_Send(&pkt, sizeof(TelemetryPacket), MPI_BYTE, 1, send_tag /* 100 */, MPI_COMM_WORLD);
// Rank 1 (line 61):
MPI_Recv(&pkt, sizeof(TelemetryPacket), MPI_BYTE, 0, expected_tag /* 200 */, MPI_COMM_WORLD, &status);- Select
tag_mismatch_stall (MPI)inTARGET:, set breakpoints on line 53 and line 61, and click▶ Run Target. - Add
send_tag,expected_tag, andpkt.payload_tagto theWATCHtab (DifferentialGrid) or inspect them inVARIABLESwhen switching between Rank 0 and Rank 1. - Open
MPI Diagnosticsto see Rank 1 blocked inMPI_Recvwaiting on tag200while Rank 0 sent tag100and Ranks 2–7 have already reachedMPI_Finalize.
tutorial/simd_struct_watch.cpp populates a 16-byte aligned SimdMatrixPacket containing a 4-byte signature ({0xCA, 0xFE, rank, world_size}), a packet ID, a 64-bit lane flag word, and a 4x4 float matrix:
struct alignas(16) SimdMatrixPacket {
uint8_t magic[4]; // {0xCA, 0xFE, rank, world_size}
uint32_t packet_id; // 0x1000 + rank
uint64_t flags; // 0xABCD000000000000ULL | rank
float matrix[4][4]; // 4x4 row-major transformation matrix
double lane_Norms[4]; // Per-row Euclidean norm accumulator
};- Select
simd_struct_watch (MPI)inTARGET:, set a breakpoint on line 60 (MPI_Allreduce), and click▶ Run Target. - In the
VARIABLEStab, expandpacketto inspectmagic,packet_id,flags, andmatrix[0..3][0..3]. - Open
MEMORY VIEWin the bottom dock and type&packet(or its hex address) intoAddr:to inspect the raw 16-byte aligned header starting withCA FE.
When debugging distributed simulations (ghost_cell_drift.cpp, simd_struct_watch.cpp, or inspection_demo.cpp), you can compare raw process memory between any two ranks directly in MEMORY VIEW (MemView):
-
Open Memory View:
- Click
Debugon the bottom tool rail and select theMEMORY VIEWtab.
- Click
-
Configure Address, Length, and Data Type:
- In
Addr:, enter a symbol reference or hex address (such as&packet,&domain[0],&matrix[0], or0x404000). - In
Bytes:, select or enter the byte count to read (for example,256). - In
Type:, pick how values are formatted (Hex,Int32,Float64, etc.).
- In
-
Select Ranks and Diff (
DIFF RANKS):- Set
Base:to0andTarget:to2(or any rank pair you want to compare). - Click
DIFF RANKS.MemoryDifferreads the memory window from both rank processes viaprocess_vm_readvand highlights every byte offset where Rank 2 diverges from Rank 0.
- Set
While paused at a breakpoint, you can save the currently inspected memory slice to disk for offline verification, regression testing, or comparison across runs:
- Pause execution at a breakpoint (such as line 60 of
tutorial/simd_struct_watch.cpp) and load the target buffer inMEMORY VIEW(Addr:+Bytes:). - Click the
EXPORTbutton on the right side of theMEMORY VIEWtoolbar. - Choose an output file path in the save dialog to write the captured memory range (
AddrthroughAddr + Bytes) to disk. - If you have modified instructions (
Ctrl+Shift+PinDisassemblyView) or raw bytes (Ctrl+EinMemView), you can also write out a full patched ELF executable viaFile -> Export Patched Binary.
GridLock includes an offline documentation viewer (Reference Manual / ReferenceManualWidget) so you can look up C/C++ library functions, MPI routines, Linux system calls, and assembly instructions without leaving the debugger:
-
Instant Contextual Lookup (
F1):- Place the cursor on any C/C++ call,
MPI_*routine (MPI_Sendrecv,MPI_Bcast,MPI_Allreduce), system call, or x86_64/ARM64 assembly mnemonic (movsd,endbr64,je,callq) inSourceCodeVieworDisassemblyViewand pressF1. - GridLock opens the
Docscategory on the bottom tool rail and displays the matching page from your indexed Zeal.docsetbundles or systemmanpages.
- Place the cursor on any C/C++ call,
-
Configuring & Indexing Docsets (
Edit -> Preferences -> Docsets):- Open
Edit -> Preferences (Ctrl+,)and selectDocsetsin the left sidebar. - Add or browse custom Zeal docset directories (defaulting to
~/.local/share/Zeal/Zeal/docsets) and download or re-index C, C++, and MPI.docsetarchives (DocsetManagerqueries the SQLitesearchIndextable directly).
- Open
The PACKAGE MANAGER tab (HpcConsoleWidget) lets you search, inspect, and install system and HPC debugging dependencies without switching to an external terminal:

-
Open the Package Manager:
- Click
MPIon the bottom tool rail and select thePACKAGE MANAGERtab.
- Click
-
Search System & HPC Backends:
- GridLock detects installed package managers automatically (
pacman,dnf,apt,zypper,rpm,spack,conan, andeb). - Type a query such as
gdb,lldb,openmpi,mpich,clangd,valgrind, orzealinto the search bar and pressEnter(or clickRefresh).
- GridLock detects installed package managers automatically (
-
Filter & Switch Views (
Table|List|Raw):- Filter packages by All, Installed Only, or Available, and switch between sortable Table columns, compact List cards, or Raw CLI output.
GridLock Repository | Releases | Report an Issue | Roadmap | Accessibility | License (MIT)
Documentation mirrored from docs/ on master.
User Guides
Architecture & Plan
Developer Docs