Deprecate KSCrashMonitor_Deadlock in favor of Watchdog monitor

- Add KSCRASH_DEPRECATED macro to KSSystemCapabilities.h
- Mark kscm_deadlock_getAPI() and kscm_setDeadlockHandlerWatchdogInterval()
  as deprecated with guidance to use KSCrashMonitor_Watchdog
- Deprecate deadlockWatchdogInterval property in KSCrashConfiguration
- Remove KSCrashMonitorTypeMainThreadDeadlock from KSCrashMonitorTypeAll
  and KSCrashMonitorTypeFatal composite types
- Set KSCrashMonitorTypeExperimental to KSCrashMonitorTypeNone
- Add pragma suppression for internal uses of deprecated APIs

Author: naftaly

Samples/Common/Sources/LibraryBridge/InstallBridge.swift

@@ -180,7 +180,7 @@ extension InstallBridge {
         (.signal, "Signal", "UNIX-style signals indicating abnormal program termination"),
         (.cppException, "C++ Exception", "Unhandled exceptions in C++ code"),
         (.nsException, "NSException", "Unhandled Objective-C exceptions"),
-        (.mainThreadDeadlock, "Main Thread Deadlock", "Situations where the main thread becomes unresponsive"),
+        (.watchdog, "Watchdog", "Hangs and watchdog timeout terminations"),
         (.memoryTermination, "Memory Termination", "Termination due to excessive memory usage"),
         (.zombie, "Zombie", "Attempts to access deallocated objects"),
         (.userReported, "User Reported", "Custom crash reports"),
@@ -194,7 +194,6 @@ extension InstallBridge {
 
         (.productionSafe, "Production-safe"),
         (.productionSafeMinimal, "Production-safe Minimal"),
-        (.experimental, "Experimental"),
 
         (.required, "Required"),
         (.optional, "Optional"),

Sources/KSCrashCore/include/KSSystemCapabilities.h

@@ -157,4 +157,16 @@
 #define KSCRASH_HAS_REACHABILITY 0
 #endif
 
+// ============================================================================
+#pragma mark - Compiler Attributes -
+// ============================================================================
+
+#ifndef KSCRASH_DEPRECATED
+#if defined(__has_attribute) && __has_attribute(deprecated)
+#define KSCRASH_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#else
+#define KSCRASH_DEPRECATED(msg)
+#endif
+#endif
+
 #endif  // HDR_KSSystemCapabilities_h

Sources/KSCrashRecording/KSCrashC.c

@@ -74,17 +74,21 @@ typedef enum {
 static const struct KSCrashMonitorMapping {
     KSCrashMonitorType type;
     KSCrashMonitorAPI *(*getAPI)(void);
-} g_monitorMappings[] = { { KSCrashMonitorTypeMachException, kscm_machexception_getAPI },
-                          { KSCrashMonitorTypeSignal, kscm_signal_getAPI },
-                          { KSCrashMonitorTypeCPPException, kscm_cppexception_getAPI },
-                          { KSCrashMonitorTypeNSException, kscm_nsexception_getAPI },
-                          { KSCrashMonitorTypeMainThreadDeadlock, kscm_deadlock_getAPI },
-                          { KSCrashMonitorTypeUserReported, kscm_user_getAPI },
-                          { KSCrashMonitorTypeSystem, kscm_system_getAPI },
-                          { KSCrashMonitorTypeApplicationState, kscm_appstate_getAPI },
-                          { KSCrashMonitorTypeZombie, kscm_zombie_getAPI },
-                          { KSCrashMonitorTypeMemoryTermination, kscm_memory_getAPI },
-                          { KSCrashMonitorTypeWatchdog, kscm_watchdog_getAPI } };
+}
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+g_monitorMappings[] = { { KSCrashMonitorTypeMachException, kscm_machexception_getAPI },
+                        { KSCrashMonitorTypeSignal, kscm_signal_getAPI },
+                        { KSCrashMonitorTypeCPPException, kscm_cppexception_getAPI },
+                        { KSCrashMonitorTypeNSException, kscm_nsexception_getAPI },
+                        { KSCrashMonitorTypeMainThreadDeadlock, kscm_deadlock_getAPI },
+                        { KSCrashMonitorTypeUserReported, kscm_user_getAPI },
+                        { KSCrashMonitorTypeSystem, kscm_system_getAPI },
+                        { KSCrashMonitorTypeApplicationState, kscm_appstate_getAPI },
+                        { KSCrashMonitorTypeZombie, kscm_zombie_getAPI },
+                        { KSCrashMonitorTypeMemoryTermination, kscm_memory_getAPI },
+                        { KSCrashMonitorTypeWatchdog, kscm_watchdog_getAPI } };
+#pragma clang diagnostic pop
 
 static const size_t g_monitorMappingCount = sizeof(g_monitorMappings) / sizeof(g_monitorMappings[0]);
 
@@ -254,7 +258,10 @@ static void handleConfiguration(KSCrashCConfiguration *configuration)
         kscrashreport_setUserInfoJSON(configuration->userInfoJSON);
     }
 #if KSCRASH_HAS_OBJC
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
     kscm_setDeadlockHandlerWatchdogInterval(configuration->deadlockWatchdogInterval);
+#pragma clang diagnostic pop
 #endif
     kstc_setSearchQueueNames(configuration->enableQueueNameSearch);
     kscrashreport_setIntrospectMemory(configuration->enableMemoryIntrospection);

Sources/KSCrashRecording/KSCrashConfiguration.m

@@ -51,7 +51,10 @@ - (instancetype)init
             _userInfoJSON = nil;
         }
 
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
         _deadlockWatchdogInterval = cConfig.deadlockWatchdogInterval;
+#pragma clang diagnostic pop
         _enableQueueNameSearch = cConfig.enableQueueNameSearch ? YES : NO;
         _enableMemoryIntrospection = cConfig.enableMemoryIntrospection ? YES : NO;
         _doNotIntrospectClasses = nil;
@@ -90,7 +93,10 @@ - (KSCrashCConfiguration)toCConfiguration
     config.reportStoreConfiguration = [self.reportStoreConfiguration toCConfiguration];
     config.monitors = self.monitors;
     config.userInfoJSON = self.userInfoJSON ? [self jsonStringFromDictionary:self.userInfoJSON] : NULL;
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
     config.deadlockWatchdogInterval = self.deadlockWatchdogInterval;
+#pragma clang diagnostic pop
     config.enableQueueNameSearch = self.enableQueueNameSearch;
     config.enableMemoryIntrospection = self.enableMemoryIntrospection;
     config.doNotIntrospectClasses.strings = [self createCStringArrayFromNSArray:self.doNotIntrospectClasses];
@@ -162,7 +168,10 @@ - (nonnull id)copyWithZone:(nullable NSZone *)zone
     copy.installPath = [self.installPath copyWithZone:zone];
     copy.monitors = self.monitors;
     copy.userInfoJSON = [self.userInfoJSON copyWithZone:zone];
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
     copy.deadlockWatchdogInterval = self.deadlockWatchdogInterval;
+#pragma clang diagnostic pop
     copy.enableQueueNameSearch = self.enableQueueNameSearch;
     copy.enableMemoryIntrospection = self.enableMemoryIntrospection;
     copy.doNotIntrospectClasses = self.doNotIntrospectClasses

Sources/KSCrashRecording/KSCrashReportC.c

@@ -1322,7 +1322,10 @@ static void writeError(const KSCrashReportWriter *const writer, const char *cons
                 writer->addStringElement(writer, KSCrashField_Name, crash->CPPException.name);
             }
             writer->endContainer(writer);
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
         } else if (isCrashOfMonitorType(crash, kscm_deadlock_getAPI())) {
+#pragma clang diagnostic pop
             writer->addStringElement(writer, KSCrashField_Type, KSCrashExcType_Deadlock);
 
         } else if (isCrashOfMonitorType(crash, kscm_memory_getAPI())) {

Sources/KSCrashRecording/Monitors/KSCrashMonitor_Deadlock.h

@@ -24,7 +24,15 @@
 // THE SOFTWARE.
 //
 
-/* Catches deadlocks in threads and queues.
+/**
+ * @file KSCrashMonitor_Deadlock.h
+ * @brief Catches deadlocks in threads and queues.
+ *
+ * @deprecated This monitor is deprecated. Use KSCrashMonitor_Watchdog instead,
+ * which provides better hang detection, watchdog timeout reporting, and an
+ * observer API for monitoring hang state changes.
+ *
+ * @see KSCrashMonitor_Watchdog.h
  */
 
 #ifndef HDR_KSCrashMonitor_Deadlock_h
@@ -38,16 +46,23 @@ extern "C" {
 
 #include "KSCrashMonitorAPI.h"
 #include "KSCrashNamespace.h"
+#include "KSSystemCapabilities.h"
 
 /** Set the interval between watchdog checks on the main thread.
  * Default is 5 seconds.
  *
  * @param value The number of seconds between checks (0 = disabled).
+ *
+ * @deprecated Use KSCrashMonitor_Watchdog instead.
  */
+KSCRASH_DEPRECATED("Use KSCrashMonitor_Watchdog instead")
 void kscm_setDeadlockHandlerWatchdogInterval(double value);
 
 /** Access the Monitor API.
+ *
+ * @deprecated Use kscm_watchdog_getAPI() from KSCrashMonitor_Watchdog.h instead.
  */
+KSCRASH_DEPRECATED("Use kscm_watchdog_getAPI() instead")
 KSCrashMonitorAPI *kscm_deadlock_getAPI(void);
 
 #ifdef __cplusplus

Sources/KSCrashRecording/Monitors/KSCrashMonitor_Deadlock.m

@@ -119,7 +119,10 @@ - (void)__attribute__((noreturn)) handleDeadlock
     kssc_initWithMachineContext(&stackCursor, KSSC_MAX_STACK_DEPTH, &machineContext);
 
     KSLOG_DEBUG(@"Filling out context.");
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
     kscm_fillMonitorContext(crashContext, kscm_deadlock_getAPI());
+#pragma clang diagnostic pop
     crashContext->registersAreValid = false;
     crashContext->offendingMachineContext = &machineContext;
     crashContext->stackCursor = &stackCursor;

Sources/KSCrashRecording/Monitors/KSCrashMonitor_Watchdog.m

@@ -201,6 +201,10 @@ @implementation KSHangMonitor
 // Returns the current task role (foreground, background, etc).
 static int TaskRole(void)
 {
+#if TARGET_OS_TV || TARGET_OS_WATCH
+    // task_policy_get is not available on tvOS or watchOS
+    return TASK_UNSPECIFIED;
+#else
     task_category_policy_data_t policy;
     mach_msg_type_number_t count = TASK_CATEGORY_POLICY_COUNT;
     boolean_t getDefault = NO;
@@ -209,6 +213,7 @@ static int TaskRole(void)
         task_policy_get(mach_task_self(), TASK_CATEGORY_POLICY, (task_policy_t)&policy, &count, &getDefault);
 
     return kr == KERN_SUCCESS ? policy.role : TASK_UNSPECIFIED;
+#endif
 }
 
 - (instancetype)initWithRunLoop:(CFRunLoopRef)runLoop threshold:(NSTimeInterval)threshold

Sources/KSCrashRecording/include/KSCrashCConfiguration.h

@@ -124,6 +124,9 @@ typedef struct {
      * this value, including application startup. You may need to initialize your
      * application on a different thread or set this to a higher value until initialization
      * is complete.
+     *
+     * @note Deprecated. Use `KSCrashMonitorTypeWatchdog` in the `monitors` field instead.
+     * The watchdog monitor provides better hang detection with a fixed 250ms threshold.
      */
     double deadlockWatchdogInterval;
 

Sources/KSCrashRecording/include/KSCrashConfiguration.h

@@ -76,8 +76,12 @@ NS_ASSUME_NONNULL_BEGIN
  * this value, including application startup. You may need to initialize your
  * application on a different thread or set this to a higher value until initialization
  * is complete.
+ *
+ * @note Deprecated. Use `KSCrashMonitorTypeWatchdog` in the `monitors` property instead.
+ * The watchdog monitor provides better hang detection with a fixed 250ms threshold.
  */
-@property(nonatomic, assign) double deadlockWatchdogInterval;
+@property(nonatomic, assign) double deadlockWatchdogInterval
+    __attribute__((deprecated("Use KSCrashMonitorTypeWatchdog in monitors instead.")));
 
 /** If true, attempt to fetch dispatch queue names for each running thread.
  *