From a66cc184e8e5cbe96bd18f282a9b5ac550f5937f Mon Sep 17 00:00:00 2001
From: Bartosz Taudul <wolf@nereid.pl>
Date: Sun, 30 Aug 2026 16:52:34 +0200
Subject: [PATCH] Annotate the file sections.

---
 monitor/src/monitor.cpp | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/monitor/src/monitor.cpp b/monitor/src/monitor.cpp
index c9f3cb0b..ece60a12 100644
--- a/monitor/src/monitor.cpp
+++ b/monitor/src/monitor.cpp
@@ -1,3 +1,9 @@
+// tracy-monitor: profile a process that was not built with the Tracy client.
+// Launch mode: tracy-monitor [OPTIONS] program [args...]; attach mode:
+// tracy-monitor [OPTIONS] -p PID | -n NAME. Runs the standard Tracy client in
+// "external mode". With TRACY_ON_DEMAND, samples are captured only while a
+// Tracy server is connected. See --help for usage and permission requirements.
+//
 #include <dirent.h>
 #include <errno.h>
 #include <fcntl.h>
@@ -46,7 +52,7 @@ static volatile sig_atomic_t s_shouldQuit = 0;
 static pid_t s_targetPid = 0;
 static bool s_isForked = false;
 
-static void SignalHandler( int sig )
+static void SignalHandler( int /*sig*/ )
 {
     s_shouldQuit = 1;
     if( s_isForked && s_targetPid != 0 )
@@ -76,6 +82,8 @@ static bool ProcessIsAlive( pid_t pid )
     return state && state[1] == ' ' && state[2] != 'Z' && state[2] != '\0';
 }
 
+// --- capability probes --------------------------------------------------
+
 static const char* GetTraceFsPath()
 {
     static char path[ 4096 ];
@@ -168,6 +176,8 @@ static bool CanReadRapl()
     return ok;
 }
 
+// --- sampling preflight ---------------------------------------------------
+
 // verify the per-CPU pid-filtered event mechanism the client relies on:
 // perf_event_open(attr, target, cpu) with a direct mmap of the event's ring
 // (the normal client's own topology); exclude_kernel=1 so it works at any
@@ -306,6 +316,8 @@ static bool PreflightSamplingEvent( pid_t pid, bool& kernelFrames, bool& hwStats
     return true;
 }
 
+// --- reporting --------------------------------------------------------------
+
 static const char* FormatHz( int hz )
 {
     static char buf[32];
@@ -405,6 +417,8 @@ static void PrintStartupReport( bool kernelFrames, bool hwStats, int hwErrno )
     fflush( stdout );
 }
 
+// --- attach mode ---------------------------------------------------------------
+
 static int FindPidsByComm( const char* name, pid_t* outPids, int maxPids )
 {
     int count = 0;
@@ -490,6 +504,7 @@ static int RunAttached( pid_t pid )
         tracy::ShutdownProfiler();
         return 1;
     }
+
     if( !VerifyClientListening() )
     {
         if( const char* port = getenv( "TRACY_PORT" ) )
@@ -506,7 +521,7 @@ static int RunAttached( pid_t pid )
 
     PrintStartupReport( kernelFrames, hwStats, hwErrno );
 
-    // Wait for the target process to exit, or for a signal
+    // never signal the target: attach mode must leave it running when we quit
     while( !s_shouldQuit && ProcessIsAlive( pid ) )
     {
         usleep( 100000 );  // 100ms poll
@@ -525,6 +540,8 @@ static int RunAttached( pid_t pid )
     return 0;
 }
 
+// --- launch mode ---------------------------------------------------------------
+
 static int RunForked( int argc, char** argv )
 {
     pid_t childPid = fork();
@@ -738,6 +755,8 @@ static int RunForked( int argc, char** argv )
     return 0;
 }
 
+// --- CLI --------------------------------------------------------------------
+
 static void PrintUsage( const char* progName )
 {
     printf( "tracy-monitor %i.%i.%i / %s\n\n", tracy::Version::Major, tracy::Version::Minor, tracy::Version::Patch, tracy::GitRef );