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

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/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.
  *

Sources/KSCrashRecording/include/KSCrashMonitorType.h

@@ -71,7 +71,9 @@ enum
     /** Monitor uncaught Objective-C NSExceptions. */
     KSCrashMonitorTypeNSException        = 1 << 3,
 
-    /** Detect deadlocks on the main thread. */
+    /** Detect deadlocks on the main thread.
+     * @note Deprecated. Use KSCrashMonitorTypeWatchdog instead.
+     */
     KSCrashMonitorTypeMainThreadDeadlock = 1 << 4,
 
     /** Monitor user-reported custom exceptions. */
@@ -98,7 +100,6 @@ enum
                              KSCrashMonitorTypeSignal |
                              KSCrashMonitorTypeCPPException |
                              KSCrashMonitorTypeNSException |
-                             KSCrashMonitorTypeMainThreadDeadlock |
                              KSCrashMonitorTypeUserReported |
                              KSCrashMonitorTypeSystem |
                              KSCrashMonitorTypeApplicationState |
@@ -107,18 +108,19 @@ enum
                              KSCrashMonitorTypeWatchdog
                              ),
 
-    /** Fatal monitors track exceptions that lead to error termination of the process.. */
+    /** Fatal monitors track exceptions that lead to error termination of the process. */
     KSCrashMonitorTypeFatal = (
                                KSCrashMonitorTypeMachException |
                                KSCrashMonitorTypeSignal |
                                KSCrashMonitorTypeCPPException |
                                KSCrashMonitorTypeNSException |
-                               KSCrashMonitorTypeMainThreadDeadlock |
                                KSCrashMonitorTypeWatchdog
                                ),
 
-    /** Enable experimental monitoring options. */
-    KSCrashMonitorTypeExperimental = KSCrashMonitorTypeMainThreadDeadlock,
+    /** Enable experimental monitoring options.
+     * @note Currently empty as KSCrashMonitorTypeMainThreadDeadlock is deprecated.
+     */
+    KSCrashMonitorTypeExperimental = KSCrashMonitorTypeNone,
 
     /** Monitor options unsafe for use with a debugger. */
     KSCrashMonitorTypeDebuggerUnsafe = KSCrashMonitorTypeMachException,

Tests/KSCrashRecordingTests/KSCrashConfiguration_Tests.m

@@ -38,6 +38,9 @@ @interface KSCrashConfigurationTests : XCTestCase
 
 @implementation KSCrashConfigurationTests
 
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+
 - (void)setUp
 {
     clearCallbackData();
@@ -283,9 +286,6 @@ - (void)testCallbacksInCConfiguration
 
 #pragma mark - Backward Compatibility Tests
 
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated-declarations"
-
 static struct {
     BOOL legacyCrashNotifyCallbackCalled;
     BOOL legacyReportWrittenCallbackCalled;