wrapper utility for handling diagnostic messages

Author: planetchili

IntelPresentMon/PresentMonAPI2/PresentMonDiagnostics.h

@@ -6,6 +6,14 @@
 extern "C" {
 #endif
 
+	// Debug Diagnostic Layer (EXPERIMENTAL)
+	// this sub-library interface enables users of the PresentMon API
+	// to get detail feedback about issues such as errors in API usage
+	// or suboptimal usage patterns
+	// It gives more information than can be communicated in error codes
+	// and it gives feedback in situations where there are errors in API
+	// usage but they are handled permissively rather than hard-failing
+
 	enum PM_DIAGNOSTIC_LEVEL
 	{
 		PM_DIAGNOSTIC_LEVEL_NONE = 0,
@@ -62,8 +70,8 @@ extern "C" {
 	{
 		// ignore all messages greater than filterLevel
 		PM_DIAGNOSTIC_LEVEL filterLevel;
-		// bitmask of destinations to transmit diagnostics to
-		PM_DIAGNOSTIC_OUTPUT_FLAGS outputFlags;
+		// bitmask of PM_DIAGNOSTIC_OUTPUT_FLAGS destinations to transmit diagnostics to
+		int outputFlags;
 		// array of subsystems, ignore all not in this array (set as nullptr to accept all)
 		PM_DIAGNOSTIC_SUBSYSTEM* pSubsystems;
 		// number of elements in above array of subsystems
@@ -77,9 +85,9 @@ extern "C" {
 	};
 
 	// all pmDiagnostic functions must NOT be invoked concurrently
-	// the only exception is pmDiagnosticSignalWaiter which can be called concurrently with the other functions
-	// from any number of threads
-	// ideally, after setup is completed only one thread shfould be calling the get/dequeue/wait functions
+	// the only exceptions are pmDiagnosticSignalWaiter which can be called concurrently with the other functions
+	// from any number of threads, and pmDiagnosticEnqueueMessage similarly
+	// ideally, after setup is completed only one thread should be calling the get/dequeue/wait functions
 
 	// initialize and configure the diagnostic system; passing in nullptr yield default config
 	PRESENTMON_API2_EXPORT PM_STATUS pmDiagnosticSetup(const PM_DIAGNOSTIC_CONFIGURATION* pConfig);

IntelPresentMon/PresentMonAPIWrapper/DiagnosticHandler.cpp

@@ -0,0 +1,79 @@
+#include "DiagnosticHandler.h"
+#include "../PresentMonAPIWrapperCommon/Exception.h"
+#include <thread>
+#include <atomic>
+#include <semaphore>
+#include <chrono>
+
+namespace pmapi
+{
+	namespace
+	{
+		class DiagnosticHandlerImpl
+		{
+		public:
+			DiagnosticHandlerImpl(std::function<void(const PM_DIAGNOSTIC_MESSAGE&)> callback)
+			{
+				if (callback) {
+					worker_ = std::jthread{ [this, callback = std::move(callback)] {
+						try {
+							constructionSema_.release();
+							while (auto res = pmDiagnosticWaitForMessage(0)) {
+								if (res == PM_DIAGNOSTIC_WAKE_REASON_MESSAGE_AVAILABLE) {
+									PM_DIAGNOSTIC_MESSAGE* pMsg = nullptr;
+									pmDiagnosticDequeueMessage(&pMsg);
+									if (pMsg) {
+										callback(*pMsg);
+										pmDiagnosticFreeMessage(pMsg);
+									}
+								}
+								else {
+									break;
+								}
+							}
+						}
+						catch (...) {}
+					} };
+					// block caller until the worker thread is up and running
+					constructionSema_.acquire();
+				}
+			}
+			~DiagnosticHandlerImpl()
+			{
+				pmDiagnosticUnblockWaitingThread();
+			}
+		private:
+			std::binary_semaphore constructionSema_{ 0 };
+			std::jthread worker_;
+		};
+	}
+	DiagnosticHandler::DiagnosticHandler(
+		PM_DIAGNOSTIC_LEVEL filterLevel,
+		int outputFlags,
+		std::function<void(const PM_DIAGNOSTIC_MESSAGE&)> callback,
+		std::span<PM_DIAGNOSTIC_SUBSYSTEM> allowList,
+		bool enableTimestamp,
+		bool enableTrace,
+		bool enableLocation,
+		int gracePeriodMs
+	) : gracePeriodMs_{ gracePeriodMs } {
+		const PM_DIAGNOSTIC_CONFIGURATION config{
+			.filterLevel = filterLevel,
+			.outputFlags = outputFlags,
+			.pSubsystems = allowList.data(),
+			.nSubsystems = (uint32_t)allowList.size(),
+			.enableTimestamp = enableTimestamp,
+			.enableTrace = enableTrace,
+			.enableLocation = enableLocation,
+		};
+		if (pmDiagnosticSetup(&config) != PM_STATUS_SUCCESS) {
+			throw Exception{ "Failure setting up diagnostic layer" };
+		}
+		pImpl = std::make_shared<DiagnosticHandlerImpl>(std::move(callback));
+	}
+	DiagnosticHandler::~DiagnosticHandler()
+	{
+		using namespace std::chrono_literals;
+		std::this_thread::sleep_for(gracePeriodMs_ * 1ms);
+	}
+}

IntelPresentMon/PresentMonAPIWrapper/DiagnosticHandler.h

@@ -0,0 +1,40 @@
+#pragma once
+#include "../PresentMonAPI2/PresentMonDiagnostics.h"
+#include <span>
+#include <functional>
+#include <memory>
+
+namespace pmapi
+{
+	// DiagnosticHandler is simplifies the process of setting up the debug diagnostic layer
+	// when you supply a callback, this class will spawn a thread to process messages from
+	// the diagnostic queue (sleeping while none are available)
+	// make sure that any resources accessed by this callback are done so in a thread-safe manner
+	// and refrain from retaining references to the message as it is destroyed after handling
+	class DiagnosticHandler
+	{
+	public:
+		DiagnosticHandler(
+			// ignore all messages greater than filterLevel
+			PM_DIAGNOSTIC_LEVEL filterLevel = PM_DIAGNOSTIC_LEVEL_WARNING,
+			// bitmask of destinations to transmit diagnostics to
+			int outputFlags = PM_DIAGNOSTIC_OUTPUT_FLAGS_DEBUGGER,
+			// callback that will process messages received into the queue
+			std::function<void(const PM_DIAGNOSTIC_MESSAGE&)> callback = {},
+			// span of subsystems to allow, ignore all not in this span (empty span to accept all)
+			std::span<PM_DIAGNOSTIC_SUBSYSTEM> allowList = {},
+			// capture timestamps as a string and add to all non-queue outputs
+			bool enableTimestamp = true,
+			// capture stack traces as a string when available (typically for error-level messages)
+			bool enableTrace = false,
+			// capture source file and line number as a string
+			bool enableLocation = false,
+			// add a grace period to wait for final messages before destroying diagnostics (ms)
+			int gracePeriodMs = 50
+		);
+		~DiagnosticHandler();
+	private:
+		std::shared_ptr<void> pImpl;
+		int gracePeriodMs_;
+	};
+}

IntelPresentMon/PresentMonAPIWrapper/FixedQuery.h

@@ -12,7 +12,7 @@
 #include <cassert>
 
 
-// The FrameQueryContainer gives a simple way to define/register/poll queries and access the results in the specific
+// The FixedQueryContainer gives a simple way to define/register/poll queries and access the results in the specific
 // use case where you have a fixed set of metrics you want to poll that is known at compile-time
 // Example usage for dynamic query:
 

IntelPresentMon/PresentMonAPIWrapper/PresentMonAPIWrapper.vcxproj

@@ -12,6 +12,7 @@
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="BlobContainer.cpp" />
+    <ClCompile Include="DiagnosticHandler.cpp" />
     <ClCompile Include="DynamicQuery.cpp" />
     <ClCompile Include="FixedQuery.cpp" />
     <ClCompile Include="FrameQuery.cpp" />
@@ -21,6 +22,7 @@
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="BlobContainer.h" />
+    <ClInclude Include="DiagnosticHandler.h" />
     <ClInclude Include="DynamicQuery.h" />
     <ClInclude Include="FrameQuery.h" />
     <ClInclude Include="PresentMonAPIWrapper.h" />

IntelPresentMon/PresentMonAPIWrapper/PresentMonAPIWrapper.vcxproj.filters

@@ -36,6 +36,9 @@
     <ClCompile Include="FixedQuery.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="DiagnosticHandler.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="PresentMonAPIWrapper.h">
@@ -62,5 +65,8 @@
     <ClInclude Include="StaticQuery.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="DiagnosticHandler.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
   </ItemGroup>
 </Project>

IntelPresentMon/SampleClient/LogDemo.cpp

@@ -20,13 +20,27 @@
 #include "Verbose.h"
 #include "LogSetup.h"
 #include "../PresentMonAPI2/Internal.h"
-#include "../PresentMonAPI2/PresentMonDiagnostics.h"
+#include "../PresentMonAPIWrapper/DiagnosticHandler.h"
 
 using namespace std::chrono_literals;
 using namespace pmon::util;
 
 PM_DEFINE_EX(LogDemoException);
 
+const char* GetLevelName(PM_DIAGNOSTIC_LEVEL lvl) {
+	switch (lvl) {
+	case PM_DIAGNOSTIC_LEVEL_NONE: return "None";
+	case PM_DIAGNOSTIC_LEVEL_FATAL: return "Fatal";
+	case PM_DIAGNOSTIC_LEVEL_ERROR: return "Error";
+	case PM_DIAGNOSTIC_LEVEL_WARNING: return "Warning";
+	case PM_DIAGNOSTIC_LEVEL_INFO: return "Info";
+	case PM_DIAGNOSTIC_LEVEL_PERFORMANCE: return "Performance";
+	case PM_DIAGNOSTIC_LEVEL_DEBUG: return "Debug";
+	case PM_DIAGNOSTIC_LEVEL_VERBOSE: return "Verbose";
+	default: return "Unknown";
+	}
+}
+
 void f2() {
 	pmlog_error();
 }
@@ -45,12 +59,16 @@ void RunLogDemo(int mode)
 {
 	p2sam::LogChannelManager zLogMan_;
 	p2sam::ConfigureLogging();
-	{
-		PM_DIAGNOSTIC_CONFIGURATION cfg{};
-		cfg.filterLevel = PM_DIAGNOSTIC_LEVEL_INFO;
-		cfg.outputFlags = PM_DIAGNOSTIC_OUTPUT_FLAGS_DEBUGGER;
-		pmDiagnosticSetup(&cfg);
-	}
+
+	// example of setting up diagnostic layer and custom diagnostic message handling
+	pmapi::DiagnosticHandler dh{
+		PM_DIAGNOSTIC_LEVEL_INFO,
+		PM_DIAGNOSTIC_OUTPUT_FLAGS_DEBUGGER | PM_DIAGNOSTIC_OUTPUT_FLAGS_QUEUE,
+		[](const PM_DIAGNOSTIC_MESSAGE& msg) { std::cout <<
+			std::format("[PMON {}] <{}> {}\n", GetLevelName(msg.level),
+				msg.pTimestamp ? msg.pTimestamp : "", msg.pText);
+		}
+	};
 
 	pmapi::Session sesh;
 
@@ -233,15 +251,4 @@ void RunLogDemo(int mode)
 	else {
 		std::cout << "unknown mode for log demo" << std::endl;
 	}
-	std::thread{ [&] {
-		std::this_thread::sleep_for(2000ms);
-		std::cout << "set me free" << std::endl;
-		pmDiagnosticUnblockWaitingThread();
-	} }.detach();
-	while (pmDiagnosticWaitForMessage(0) == PM_DIAGNOSTIC_WAKE_REASON_MESSAGE_AVAILABLE) {
-		PM_DIAGNOSTIC_MESSAGE* pMsg = nullptr;
-		pmDiagnosticDequeueMessage(&pMsg);
-		std::cout << pMsg->pText << std::endl;
-		pmDiagnosticFreeMessage(pMsg);
-	}
 }