LeakCanary万字源码解析，干货满满

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.squareup.leakcanary.objectwatcher" >

    <uses-sdk android:minSdkVersion="14" />

    <application>
        <provider
            android:name="leakcanary.internal.MainProcessAppWatcherInstaller"
            android:authorities="${applicationId}.leakcanary-installer"
            android:enabled="@bool/leak_canary_watcher_auto_install"
            android:exported="false" />
    </application>

</manifest>

internal class MainProcessAppWatcherInstaller : ContentProvider() {

  override fun onCreate(): Boolean {
    val application = context!!.applicationContext as Application
    AppWatcher.manualInstall(application)
    return true
  }

    ...
}

// 定义一个名为manualInstall的函数，该函数是LeakCanary库中的一个内部类AppWatcherInstaller的扩展函数
@JvmOverloads
fun manualInstall(
    // 接收应用程序的上下文对象（Application）
    application: Application,
    // 默认值为5秒，表示在应用程序退出时保留LeakCanary观察器的时间（以毫秒为单位）
    retainedDelayMillis: Long = TimeUnit.SECONDS.toMillis(5),
// 监视器列表
watchersToInstall: List<InstallableWatcher> = appDefaultWatchers(application)
) {
    //确保当前线程是主线程
    checkMainThread()
    // 检查是否已经安装了LeakCanary观察器，如果已经安装，则抛出一个IllegalStateException异常
    if (isInstalled) {
        throw IllegalStateException(
            "AppWatcher already installed, see exception cause for prior install call", installCause
        )
    }
    // 调用check()方法来检查retainedDelayMillis是否大于等于0，如果不是，则抛出一个异常
    check(retainedDelayMillis >= 0) {
        "retainedDelayMillis $retainedDelayMillis must be at least 0 ms"
    }
    // 设置保留延迟时间
    this.retainedDelayMillis = retainedDelayMillis
    // 如果应用程序处于可调试构建状态，则调用LogcatSharkLog.install()方法进行日志记录
    if (application.isDebuggableBuild) {
        LogcatSharkLog.install()
    }
}
// 加载LeakCanaryDelegate并设置AppWatcher.objectWatcher
LeakCanaryDelegate.loadLeakCanary(application)

watchersToInstall.forEach {
    it.install() // 安装传入的每个可安装的观察者（Watcher）
  }

// 将installCause设置了一个RuntimeException异常
    installCause = RuntimeException("manualInstall() first called here")

@Suppress("UNCHECKED_CAST") // 忽略未经检查的类型转换警告
val loadLeakCanary by lazy { // 懒加载单例对象
    try {
        // 通过反射获取leakcanary.internal.InternalLeakCanary类的INSTANCE字段
        val leakCanaryListener = Class.forName("leakcanary.internal.InternalLeakCanary")
        leakCanaryListener.getDeclaredField("INSTANCE")
            .get(null) as (Application) -> Unit // 强制类型转换，将获取到的对象转换为(Application) -> Unit类型
    } catch (ignored: Throwable) {
        NoLeakCanary // 如果发生异常，进入NoLeakCanary执行空方法
    }
}

object NoLeakCanary : (Application) -> Unit, OnObjectRetainedListener {
    override fun invoke(application: Application) {
    }

    override fun onObjectRetained() {
    }
  }

override fun invoke(application: Application) {
    _application = application

    // 检查是否运行在Debuggable Build中，用于开发时检测内存泄漏
    checkRunningInDebuggableBuild()

    // 向AppWatcher的对象监视器添加一个监听器，用于监测对象的保留情况
    AppWatcher.objectWatcher.addOnObjectRetainedListener(this)

    // 创建垃圾回收触发器
    val gcTrigger = GcTrigger.Default

    // 获取配置提供者
    val configProvider = { LeakCanary.config }

    // 创建处理线程
    val handlerThread = HandlerThread(LEAK_CANARY_THREAD_NAME)
    handlerThread.start()
    val backgroundHandler = Handler(handlerThread.looper)

    // 创建HeapDumpTrigger实例，用于触发堆转储操作
    heapDumpTrigger = HeapDumpTrigger(
        application, backgroundHandler, AppWatcher.objectWatcher, gcTrigger, configProvider
    )

    // 注册应用程序可见性监听器，用于在应用程序可见性更改时触发堆转储
    application.registerVisibilityListener { applicationVisible ->
                                            this.applicationVisible = applicationVisible
                                            heapDumpTrigger.onApplicationVisibilityChanged(applicationVisible)
                                           }

    // 注册应用程序已恢复的活动监听器
    registerResumedActivityListener(application)

    // 添加动态快捷方式到应用程序(金丝雀)
    addDynamicShortcut(application)

    // 在主线程上发布一个任务，使得日志在Application.onCreate()之后输出。  
    // We post so that the log happens after Application.onCreate()  
    mainHandler.post {
        // 在后台线程上发布一个任务，因为HeapDumpControl.iCanHasHeap()检查一个共享的偏好设置，  
        // 这会阻塞直到加载完成，从而导致StrictMode违规。  
        // https://github.com/square/leakcanary/issues/1981  
        // We post to a background handler because HeapDumpControl.iCanHasHeap() checks a shared pref  
        // which blocks until loaded and that creates a StrictMode violation.  
        SharkLog.d {
        when (val iCanHasHeap = HeapDumpControl.iCanHasHeap()) {
            is Yup -> application.getString(R.string.leak_canary_heap_dump_enabled_text)
            is Nope -> application.getString(
                R.string.leak_canary_heap_dump_disabled_text, iCanHasHeap.reason()
            )
        }
        }
    }
}

internal class VisibilityTracker(
    private val listener: (Boolean) -> Unit
) : Application.ActivityLifecycleCallbacks by noOpDelegate(), BroadcastReceiver() {

    ...

    override fun onActivityStarted(activity: Activity) {
        startedActivityCount++
        if (!hasVisibleActivities && startedActivityCount == 1) {
            hasVisibleActivities = true
            updateVisible()
        }
    }

    override fun onActivityStopped(activity: Activity) {
        if (startedActivityCount > 0) {
            startedActivityCount--
        }
        if (hasVisibleActivities && startedActivityCount == 0 && !activity.isChangingConfigurations) {
            hasVisibleActivities = false
            updateVisible()
        }
    }

   ...

private val lifecycleCallbacks =
object : Application.ActivityLifecycleCallbacks by noOpDelegate() {
    override fun onActivityDestroyed(activity: Activity) {
        reachabilityWatcher.expectWeaklyReachable(
            activity, "${activity::class.java.name} received Activity#onDestroy() callback"
        )
    }
}

class FragmentAndViewModelWatcher(
  private val application: Application,
  private val reachabilityWatcher: ReachabilityWatcher
) : InstallableWatcher {

  // 定义一个列表来存储Fragment销毁时的回调函数
  private val fragmentDestroyWatchers: List<(Activity) -> Unit> = run {
    val fragmentDestroyWatchers = mutableListOf<(Activity) -> Unit>()

    if (SDK_INT >= O) {
      // 添加Android O版本及以上的Fragment销毁回调函数
      fragmentDestroyWatchers.add(
        AndroidOFragmentDestroyWatcher(reachabilityWatcher)
      )
    }

    // 获取指定名称的Fragment销毁回调函数，并将其添加到列表中
    getWatcherIfAvailable(
      ANDROIDX_FRAGMENT_CLASS_NAME,
      ANDROIDX_FRAGMENT_DESTROY_WATCHER_CLASS_NAME,
      reachabilityWatcher
    )?.let {
      fragmentDestroyWatchers.add(it)
    }

    // 获取指定名称的Support版本Fragment销毁回调函数，并将其添加到列表中
    getWatcherIfAvailable(
      ANDROID_SUPPORT_FRAGMENT_CLASS_NAME,
      ANDROID_SUPPORT_FRAGMENT_DESTROY_WATCHER_CLASS_NAME,
      reachabilityWatcher
    )?.let {
      fragmentDestroyWatchers.add(it)
    }
    fragmentDestroyWatchers
  }

  // 定义一个实现了Application.ActivityLifecycleCallbacks接口的对象，用于监听Activity的生命周期事件
  private val lifecycleCallbacks =
    object : Application.ActivityLifecycleCallbacks by noOpDelegate() {
      override fun onActivityCreated(
        activity: Activity,
        savedInstanceState: Bundle?
      ) {
        // 遍历fragmentDestroyWatchers列表中的每个回调函数，并将当前Activity实例传递给它们
        for (watcher in fragmentDestroyWatchers) {
          watcher(activity)
        }
      }
    }

 ...

  // 定义一个辅助方法，用于获取指定名称的Fragment和Watcher对象
  private fun getWatcherIfAvailable(
    fragmentClassName: String,
    watcherClassName: String,
    reachabilityWatcher: ReachabilityWatcher
  ): ((Activity) -> Unit)? {

    return if (classAvailable(fragmentClassName) &&
      classAvailable(watcherClassName)) {
      // 尝试获取指定名称的Fragment和Watcher对象，并返回一个lambda表达式，该表达式接受一个Activity实例作为参数，并调用指定的Watcher对象的相应方法
      val watcherConstructor =
        Class.forName(watcherClassName).getDeclaredConstructor(ReachabilityWatcher::class.java)
      @Suppress("UNCHECKED_CAST")
      watcherConstructor.newInstance(reachabilityWatcher) as (Activity) -> Unit
    } else {
      // 如果无法获取到指定的Fragment和Watcher对象，则返回null
      null
    }
  }

  // 定义一个辅助方法，用于检查指定的类是否可用
  private fun classAvailable(className: String): Boolean {
    return try {
      Class.forName(className)
      true
    } catch (e: Throwable) {
      // 通常情况下，我们会期望能够加载指定的类。但是，在某些情况下（例如Android Support库的版本问题），我们可能会遇到ClassNotFoundException异常。在这种情况下，我们只能假设该类不可用，并返回false。
      false
    }
  }
}

internal class AndroidXFragmentDestroyWatcher(
    private val reachabilityWatcher: ReachabilityWatcher
) : (Activity) -> Unit {

// 定义一个对象 fragmentLifecycleCallbacks，继承自 FragmentManager.FragmentLifecycleCallbacks，用于监听 Fragment 的生命周期事件
private val fragmentLifecycleCallbacks = object : FragmentManager.FragmentLifecycleCallbacks() {

    // 当 Fragment 创建时调用
    override fun onFragmentCreated(
        fm: FragmentManager,
        fragment: Fragment,
        savedInstanceState: Bundle?
    ) {
        // 将当前 Fragment 和 reachabilityWatcher 传递给 ViewModelClearedWatcher 的 install 方法
        ViewModelClearedWatcher.install(fragment, reachabilityWatcher)
    }

    // 当 Fragment 的视图被销毁时调用
    override fun onFragmentViewDestroyed(
        fm: FragmentManager,
        fragment: Fragment
    ) {
        // 获取 Fragment 的视图
        val view = fragment.view
        // 如果视图不为空，检查其是否可以弱引用访问，以确保在 Fragment 销毁时清除对视图的引用，防止内存泄漏
        if (view != null) {
            reachabilityWatcher.expectWeaklyReachable(
                view, "${fragment::class.java.name} received Fragment#onDestroyView() callback " +
                "(references to its views should be cleared to prevent leaks)"
            )
        }
    }

    // 当 Fragment 销毁时调用
    override fun onFragmentDestroyed(
        fm: FragmentManager,
        fragment: Fragment
    ) {
        // 检查 Fragment 是否可以弱引用访问，以确保在销毁时清除对其的引用，防止内存泄漏
        reachabilityWatcher.expectWeaklyReachable(
            fragment, "${fragment::class.java.name} received Fragment#onDestroy() callback"
        )
    }
}

// 重写 invoke 方法，接收一个 Activity 对象作为参数
override fun invoke(activity: Activity) {
    // 如果传入的 Activity 是 FragmentActivity 类型，则获取其对应的 supportFragmentManager
    if (activity is FragmentActivity) {
        val supportFragmentManager = activity.supportFragmentManager
        // 使用 supportFragmentManager 注册 fragmentLifecycleCallbacks 对象，并设置为 true，表示在回调执行完毕后会自动移除
        supportFragmentManager.registerFragmentLifecycleCallbacks(fragmentLifecycleCallbacks, true)
        // 将 activity 和 reachabilityWatcher 传递给 ViewModelClearedWatcher 的 install 方法
        ViewModelClearedWatcher.install(activity, reachabilityWatcher)
    }
    }
}

internal class ViewModelClearedWatcher(
storeOwner: ViewModelStoreOwner, // ViewModelStoreOwner 类型，用于获取 ViewModelStore
private val reachabilityWatcher: ReachabilityWatcher // ReachabilityWatcher 类型，用于检查 ViewModel 是否可以弱引用访问
) : ViewModel() {

    // 获取 ViewModelStore 中的 mMap 字段，该字段是一个 Map，存储了所有的 ViewModel
    private val viewModelMap: Map<String, ViewModel>? = try {
        val storeClass = ViewModelStore::class.java
        val mapField = try {
            storeClass.getDeclaredField("map")
        } catch (exception: NoSuchFieldException) {
        // 如果找不到 mMap 字段，使用原来的 mMap 字段
        storeClass.getDeclaredField("mMap")
    }
    mapField.isAccessible = true
    @Suppress("UNCHECKED_CAST")
    mapField[storeOwner.viewModelStore] as Map<String, ViewModel>
} catch (ignored: Exception) {
    SharkLog.d(ignored) { "Could not find ViewModelStore map of view models" }
    null
}

// 当 ViewModel 被清除时，会调用此方法
override fun onCleared() {
    viewModelMap?.values?.forEach { viewModel ->
                                   // 检查每个 ViewModel 是否可以弱引用访问，如果不可以，打印日志
                                   reachabilityWatcher.expectWeaklyReachable(
                                       viewModel, "${viewModel::class.java.name} received ViewModel#onCleared() callback"
                                   )
                                  }
}

companion object {
    fun install(
        storeOwner: ViewModelStoreOwner, // ViewModelStoreOwner 类型，用于获取 ViewModelStore
        reachabilityWatcher: ReachabilityWatcher // ReachabilityWatcher 类型，用于检查 ViewModel 是否可以弱引用访问
    ) {
    val provider = ViewModelProvider(storeOwner, object : Factory {
        @Suppress("UNCHECKED_CAST")
        override fun <T : ViewModel?> create(modelClass: Class<T>): T =
        ViewModelClearedWatcher(storeOwner, reachabilityWatcher) as T
    })
    provider.get(ViewModelClearedWatcher::class.java)
}
}
}

class RootViewWatcher(
    private val reachabilityWatcher: ReachabilityWatcher
) : InstallableWatcher {

// 定义一个内部类 OnRootViewAddedListener，用于处理根视图添加事件
private val listener = OnRootViewAddedListener { rootView ->
                                                // 根据根视图的类型（PHONE_WINDOW、POPUP_WINDOW、TOOLTIP、TOAST、UNKNOWN）判断是否需要追踪
                                                val trackDetached = when(rootView.windowType) {
    PHONE_WINDOW -> {
        // 如果根视图是Activity类型，则不追踪；如果是Dialog类型，则根据资源文件中的设置决定是否追踪；其他类型默认追踪
        when (rootView.phoneWindow?.callback?.wrappedCallback) {
            is Activity -> false
            is Dialog -> {
                // 使用应用上下文资源避免NotFoundException
                val resources = rootView.context.applicationContext.resources
                resources.getBoolean(R.bool.leak_canary_watcher_watch_dismissed_dialogs)
            }
            else -> true
        }
    }
    // Android小部件会保留分离的弹出窗口实例
    POPUP_WINDOW -> false
    TOOLTIP, TOAST, UNKNOWN -> true
}
                                                // 如果需要追踪，则为根视图添加一个附加状态更改监听器
                                                if (trackDetached) {
                                                    rootView.addOnAttachStateChangeListener(object : OnAttachStateChangeListener {

                                                        // 定义一个Runnable对象，用于在根视图从窗口分离时检查视图是否被追踪
                                                        val watchDetachedView = Runnable {
                                                            reachabilityWatcher.expectWeaklyReachable(
                                                                rootView, "${rootView::class.java.name} received View#onDetachedFromWindow() callback"
                                                            )
                                                        }

                                                        // 当根视图附加到窗口时，移除观察者
                                                        override fun onViewAttachedToWindow(v: View) {
                                                            mainHandler.removeCallbacks(watchDetachedView)
                                                        }

                                                        // 当根视图从窗口分离时，执行观察者
                                                        override fun onViewDetachedFromWindow(v: View) {
                                                            mainHandler.post(watchDetachedView)
                                                        }
                                                    })
                                                }
                                               }

@SuppressLint("PrivateApi")
class ServiceWatcher(private val reachabilityWatcher: ReachabilityWatcher) : InstallableWatcher {

  // 存储需要被销毁的服务引用
  private val servicesToBeDestroyed = WeakHashMap<IBinder, WeakReference<Service>>()

  // 获取ActivityThread类的实例
  private val activityThreadClass by lazy { Class.forName("android.app.ActivityThread") }

  // 获取ActivityThread类的实例的方法
  private val activityThreadInstance by lazy {
    activityThreadClass.getDeclaredMethod("currentActivityThread").invoke(null)!!
  }

  // 获取ActivityThread类的服务映射
  private val activityThreadServices by lazy {
    val mServicesField =
      activityThreadClass.getDeclaredField("mServices").apply { isAccessible = true }

    @Suppress("UNCHECKED_CAST")
    mServicesField[activityThreadInstance] as Map<IBinder, Service>
  }

  // 定义回调函数变量
  private var uninstallActivityThreadHandlerCallback: (() -> Unit)? = null
  private var uninstallActivityManager: (() -> Unit)? = null

  override fun install() {
    // 检查是否已经在监听服务
    checkMainThread()
    check(uninstallActivityThreadHandlerCallback == null) {
      "ServiceWatcher already installed"
    }
    check(uninstallActivityManager == null) {
      "ServiceWatcher already installed"
    }
    try {
      // 替换ActivityThread的Handler回调函数
      swapActivityThreadHandlerCallback { mCallback ->
        uninstallActivityThreadHandlerCallback = {
          swapActivityThreadHandlerCallback {
            mCallback
          }
        }
        // 处理消息的回调函数
        Handler.Callback { msg ->
          // 防止崩溃，检查msg.obj是否为IBinder类型
          if (msg.obj !is IBinder) {
            return@Callback false
          }

          // 如果消息为STOP_SERVICE，则处理服务销毁
          if (msg.what == STOP_SERVICE) {
            val key = msg.obj as IBinder
            activityThreadServices[key]?.let {
              onServicePreDestroy(key, it)
            }
          }
          mCallback?.handleMessage(msg) ?: false
        }
      }
      // 替换ActivityManager接口代理
      swapActivityManager { activityManagerInterface, activityManagerInstance ->
        uninstallActivityManager = {
          swapActivityManager { _, _ ->
            activityManagerInstance
          }
        }
        Proxy.newProxyInstance(
          activityManagerInterface.classLoader, arrayOf(activityManagerInterface)
        ) { _, method, args ->
          if (METHOD_SERVICE_DONE_EXECUTING == method.name) {
            val token = args!![0] as IBinder
            if (servicesToBeDestroyed.containsKey(token)) {
              onServiceDestroyed(token)
            }
          }
          try {
            if (args == null) {
              method.invoke(activityManagerInstance)
            } else {
              method.invoke(activityManagerInstance, *args)
            }
          } catch (invocationException: InvocationTargetException) {
            throw invocationException.targetException
          }
        }
      }
    } catch (ignored: Throwable) {
      SharkLog.d(ignored) { "Could not watch destroyed services" }
    }
  }

  override fun uninstall() {
    // 检查是否在主线程
    checkMainThread()
    // 取消ActivityManager的代理
    uninstallActivityManager?.invoke()
    // 取消ActivityThread的Handler回调函数的安装
    uninstallActivityThreadHandlerCallback?.invoke()
    // 清空变量值
    uninstallActivityManager = null
    uninstallActivityThreadHandlerCallback = null
  }

  // 服务预销毁的回调函数
  private fun onServicePreDestroy(
    token: IBinder,
    service: Service
  ) {
    // 将服务引用添加到待销毁列表中
    servicesToBeDestroyed[token] = WeakReference(service)
  }

  // 服务销毁的回调函数
  private fun onServiceDestroyed(token: IBinder) {
    // 从待销毁列表中移除服务引用，并通知reachabilityWatcher服务即将被销毁
    servicesToBeDestroyed.remove(token)?.also { serviceWeakReference ->
      serviceWeakReference.get()?.let { service ->
        reachabilityWatcher.expectWeaklyReachable(
          service, "${service::class.java.name} received Service#onDestroy() callback"
        )
      }
    }
  }

  // 替换ActivityThread的Handler回调函数的工具方法
  private fun swapActivityThreadHandlerCallback(swap: (Handler.Callback?) -> Handler.Callback?) {
    // ...省略部分代码...
  }

  // 替换ActivityManager接口代理的工具方法
  private fun swapActivityManager(swap: (Class<*>, Any) -> Any) {
    // ...省略部分代码...
  }
}

@Synchronized override fun expectWeaklyReachable(
    watchedObject: Any,
    description: String
) {
    // 如果观察器被禁用，则直接返回
    if (!isEnabled()) {
        return
    }

    // 移除已经成为弱引用的对象
    removeWeaklyReachableObjects()

    // 生成一个随机的唯一标识符作为对象的键
    val key = UUID.randomUUID().toString()

    // 获取当前的系统启动时间
    val watchUptimeMillis = clock.uptimeMillis()

    // 创建一个KeyedWeakReference对象，用于观察被观察对象
    val reference = KeyedWeakReference(watchedObject, key, description, watchUptimeMillis, queue)

    // 打印日志，记录被追踪的对象信息
    SharkLog.d {
        "Watching " +
        (if (watchedObject is Class<*>) watchedObject.toString() else "instance of ${watchedObject.javaClass.name}") +
        (if (description.isNotEmpty()) " ($description)" else "") +
        " with key $key"
    }

    // 将KeyedWeakReference对象添加到被观察对象的映射中
    watchedObjects[key] = reference

    // 在后台线程执行将对象标记为已保留的操作
    checkRetainedExecutor.execute {
        moveToRetained(key)
    }
}

// 标记对象为已保留的操作
@Synchronized private fun moveToRetained(key: String) {
    // 移除已经成为弱引用的对象
    removeWeaklyReachableObjects()

    // 获取指定键的弱引用对象
    val retainedRef = watchedObjects[key]

    // 如果找到了指定键的对象
    if (retainedRef != null) {
        // 更新对象的保留时间
        retainedRef.retainedUptimeMillis = clock.uptimeMillis()

        // 触发对象被保留的监听器
        onObjectRetainedListeners.forEach { it.onObjectRetained() }
    }
}

// 移除已成为弱引用的对象
private fun removeWeaklyReachableObjects() {
    // 弱引用对象会在对象变为弱引用可达状态时入队，但在最终化或垃圾回收之前
    // 实际上并没有发生。因此，这里从队列中移除弱引用对象。
    var ref: KeyedWeakReference?
    do {
    ref = queue.poll() as KeyedWeakReference?
    if (ref != null) {
        // 从监测的对象集合中移除该对象
        watchedObjects.remove(ref.key)
    }
} while (ref != null)
}

// 重写 onObjectRetained() 方法，用于在对象被保留时执行操作
override fun onObjectRetained() = scheduleRetainedObjectCheck()

fun scheduleRetainedObjectCheck() {
// 如果 heapDumpTrigger 已经初始化，则调用其 scheduleRetainedObjectCheck() 方法进行保留对象检查
if (this::heapDumpTrigger.isInitialized) {
    heapDumpTrigger.scheduleRetainedObjectCheck()
}
}


fun scheduleRetainedObjectCheck(delayMillis: Long = 0L) {
    // 获取当前计划检查的时间
    val checkCurrentlyScheduledAt = checkScheduledAt

    // 如果当前已经有计划进行检查，则直接返回
    if (checkCurrentlyScheduledAt > 0) {
        return
    }

    // 更新计划检查的时间为当前系统时间加上延迟时间
    checkScheduledAt = SystemClock.uptimeMillis() + delayMillis

    // 使用 Handler 在延迟时间后执行检查操作
    backgroundHandler.postDelayed({
        // 将计划检查的时间重置为 0
        checkScheduledAt = 0

        // 调用 checkRetainedObjects() 方法进行保留对象检查
        checkRetainedObjects()
    }, delayMillis)
}

private fun checkRetainedObjects() {
    // 判断当前应用是否具有堆权限
    val iCanHasHeap = HeapDumpControl.iCanHasHeap()

    // 获取配置信息
    val config = configProvider()

    if (iCanHasHeap is Nope) {
        // 如果无法进行堆检查，则执行以下操作
        if (iCanHasHeap is NotifyingNope) {
            // 在通知无法进行堆检查之前，先检查是否还有保留对象
            var retainedReferenceCount = objectWatcher.retainedObjectCount

            if (retainedReferenceCount > 0) {
                // 运行垃圾回收
                gcTrigger.runGc()
                retainedReferenceCount = objectWatcher.retainedObjectCount
            }

            // 获取无法进行堆检查的原因
            val nopeReason = iCanHasHeap.reason()
            // 判断是否需要进行堆检查
            val wouldDump = !checkRetainedCount(
                retainedReferenceCount, config.retainedVisibleThreshold, nopeReason
            )

            if (wouldDump) {
                // 如果需要堆检查，则执行以下操作
                val uppercaseReason = nopeReason[0].toUpperCase() + nopeReason.substring(1)
                // 发送无法进行堆检查的通知
                onRetainInstanceListener.onEvent(DumpingDisabled(uppercaseReason))
                // 显示保留对象数量的通知
                showRetainedCountNotification(
                    objectCount = retainedReferenceCount,
                    contentText = uppercaseReason
                )
            }
        } else {
            // 输出无法进行堆检查的日志
            SharkLog.d {
                application.getString(
                    R.string.leak_canary_heap_dump_disabled_text, iCanHasHeap.reason()
                )
            }
        }
        return
    }

    // 获取保留对象的数量
    var retainedReferenceCount = objectWatcher.retainedObjectCount

    if (retainedReferenceCount > 0) {
        // 运行垃圾回收
        gcTrigger.runGc()
        retainedReferenceCount = objectWatcher.retainedObjectCount
    }

    // 判断是否需要进行堆检查
    if (checkRetainedCount(retainedReferenceCount, config.retainedVisibleThreshold)) return

        // 获取当前时间
        val now = SystemClock.uptimeMillis()
    // 计算距离上次堆检查的时间间隔
    val elapsedSinceLastDumpMillis = now - lastHeapDumpUptimeMillis
    // 如果时间间隔小于等待时间间隔，则执行以下操作
    if (elapsedSinceLastDumpMillis < WAIT_BETWEEN_HEAP_DUMPS_MILLIS) {
        // 发送堆发生事件的通知
        onRetainInstanceListener.onEvent(DumpHappenedRecently)
        // 显示保留对象数量的通知
        showRetainedCountNotification(
            objectCount = retainedReferenceCount,
            contentText = application.getString(R.string.leak_canary_notification_retained_dump_wait)
        )
        // 重新安排保留对象检查任务
        scheduleRetainedObjectCheck(
            delayMillis = WAIT_BETWEEN_HEAP_DUMPS_MILLIS - elapsedSinceLastDumpMillis
        )
        return
    }

    // 取消保留对象数量的通知
    dismissRetainedCountNotification()
    // 根据应用是否可见，设置堆的可见性
    val visibility = if (applicationVisible) "visible" else "not visible"
    // 进行堆检查，并返回结果
    dumpHeap(
        retainedReferenceCount = retainedReferenceCount,
        retry = true,
        reason = "$retainedReferenceCount retained objects, app is $visibility"
    )
}

private fun checkRetainedCount(
    retainedKeysCount: Int, // 保留对象的数量
    retainedVisibleThreshold: Int, // 保留对象的可见阈值
    nopeReason: String? = null 
): Boolean {
    val countChanged = lastDisplayedRetainedObjectCount != retainedKeysCount // 判断保留对象数量是否发生变化
    lastDisplayedRetainedObjectCount = retainedKeysCount // 更新上次显示的保留对象数量
    if (retainedKeysCount == 0) { // 如果保留对象数量为0
        if (countChanged) { // 如果保留对象数量发生变化
            SharkLog.d { "All retained objects have been garbage collected" } // 输出日志，表示所有保留对象已经被垃圾回收
            onRetainInstanceListener.onEvent(NoMoreObjects) // 发送没有更多对象的通知
            showNoMoreRetainedObjectNotification() // 显示没有更多保留对象的通知
        }
        return true // 返回true，表示需要进行堆检查
    }

    val applicationVisible = applicationVisible // 获取应用是否可见的状态
    val applicationInvisibleLessThanWatchPeriod = applicationInvisibleLessThanWatchPeriod // 获取应用在不可见状态下的时间是否小于观察周期

    if (countChanged) { // 如果保留对象数量发生变化
        val whatsNext = if (applicationVisible) { // 如果应用可见
            if (retainedKeysCount < retainedVisibleThreshold) { // 如果保留对象数量小于可见阈值
                "not dumping heap yet (app is visible & < $retainedVisibleThreshold threshold)" // 输出日志，表示暂时不需要进行堆检查
            } else {
                if (nopeReason != null) { // 如果无法进行堆检查的原因不为空
                    "would dump heap now (app is visible & >=$retainedVisibleThreshold threshold) but $nopeReason" // 输出日志，表示现在可以进行堆检查，但是有无法进行堆检查的原因
                } else {
                    "dumping heap now (app is visible & >=$retainedVisibleThreshold threshold)" // 输出日志，表示现在可以进行堆检查
                }
            }
        } else if (applicationInvisibleLessThanWatchPeriod) { // 如果应用不可见且在不可见状态下的时间小于观察周期
            val wait =
            AppWatcher.retainedDelayMillis - (SystemClock.uptimeMillis() - applicationInvisibleAt) // 计算需要等待的时间
            if (nopeReason != null) { // 如果无法进行堆检查的原因不为空
                "would dump heap in $wait ms (app just became invisible) but $nopeReason" // 输出日志，表示现在可以进行堆检查，但是有无法进行堆检查的原因
            } else {
                "dumping heap in $wait ms (app just became invisible)" // 输出日志，表示现在可以进行堆检查
            }
        } else { // 如果应用不可见且在不可见状态下的时间大于等于观察周期
            if (nopeReason != null) { // 如果无法进行堆检查的原因不为空
                "would dump heap now (app is invisible) but $nopeReason" // 输出日志，表示现在可以进行堆检查，但是有无法进行堆检查的原因
            } else {
                "dumping heap now (app is invisible)" // 输出日志，表示现在可以进行堆检查
            }
        }

        SharkLog.d {
            val s = if (retainedKeysCount > 1) "s" else "" // 如果保留对象数量大于1，添加s后缀
            "Found $retainedKeysCount object$s retained, $whatsNext" // 输出日志，显示保留对象数量和下一步操作
        }
    }

    if (retainedKeysCount < retainedVisibleThreshold) { // 如果保留对象数量小于可见阈值
        if (applicationVisible || applicationInvisibleLessThanWatchPeriod) { // 如果应用可见或者应用在不可见状态下的时间小于观察周期
            if (countChanged) { // 如果保留对象数量发生变化
                onRetainInstanceListener.onEvent(BelowThreshold(retainedKeysCount)) // 发送低于阈值的事件
            }
            showRetainedCountNotification( // 显示保留计数通知
                objectCount = retainedKeysCount, // 保留对象数量
                contentText = application.getString(R.string.leak_canary_notification_retained_visible, retainedVisibleThreshold) // 内容文本为可见阈值的字符串资源
            )
            scheduleRetainedObjectCheck(delayMillis = WAIT_FOR_OBJECT_THRESHOLD_MILLIS) // 安排进行保留对象检查
            return true // 返回true，表示进行检查
        }
    }
    return false // 返回false，表示不需要进行检查
}

/**
  *返回保留对象的数量，即不可弱访问且已监视足够长的时间以被视为保留的监视对象的数量。
  */
val retainedObjectCount: Int
@Synchronized get() {
    removeWeaklyReachableObjects()
    return watchedObjects.count { it.value.retainedUptimeMillis != -1L }
}

fun interface GcTrigger {

    ...

    object Default : GcTrigger {
        override fun runGc() {
            Runtime.getRuntime()
            .gc()
            enqueueReferences()
            System.runFinalization()
        }

        private fun enqueueReferences() {
            Thread.sleep(100)
        } catch (e: InterruptedException) {
            throw AssertionError()
        }
        }
    }
}

val eventListeners: List<EventListener> = listOf(
    LogcatEventListener,
    ToastEventListener,
    // 一个懒加载的委托事件监听器，根据InternalLeakCanary.formFactor的值来决定使用哪个事件监听器
    LazyForwardingEventListener {
    if (InternalLeakCanary.formFactor == TV) TvEventListener else NotificationEventListener
        },
        // 根据不同的条件，为eventListeners列表添加不同的事件监听器
        when {
        //WorkerManager 多进程分析
        RemoteWorkManagerHeapAnalyzer.remoteLeakCanaryServiceInClasspath ->
        RemoteWorkManagerHeapAnalyzer
        //WorkManager 异步分析
        WorkManagerHeapAnalyzer.validWorkManagerInClasspath -> WorkManagerHeapAnalyzer
        //异步线程分析
        else -> BackgroundThreadHeapAnalyzer
    }
    )

fun runAnalysisBlocking(
    heapDumped: HeapDump,
    isCanceled: () -> Boolean = { false },
progressEventListener: (HeapAnalysisProgress) -> Unit
): HeapAnalysisDone<*> {
...

// 获取堆转储文件、持续时间和原因
val heapDumpFile = heapDumped.file

val heapDumpReason = heapDumped.reason

// 根据堆转储文件是否存在进行堆分析
val heapAnalysis = if (heapDumpFile.exists()) {
    analyzeHeap(heapDumpFile, progressListener, isCanceled)
} else {
    missingFileFailure(heapDumpFile)
}

// 根据堆分析结果进行处理
val fullHeapAnalysis = when (heapAnalysis) {
    ...
}

// 更新进度，表示正在生成报告
progressListener.onAnalysisProgress(REPORTING_HEAP_ANALYSIS)

// 在数据库中记录分析结果
val analysisDoneEvent = ScopedLeaksDb.writableDatabase(application) { db ->
                                                                     val id = HeapAnalysisTable.insert(db, heapAnalysis)
                                                                     when (fullHeapAnalysis) {
    is HeapAnalysisSuccess -> {
        val showIntent = LeakActivity.createSuccessIntent(application, id)
        val leakSignatures = fullHeapAnalysis.allLeaks.map { it.signature }.toSet()
        val leakSignatureStatuses = LeakTable.retrieveLeakReadStatuses(db, leakSignatures)
        val unreadLeakSignatures = leakSignatureStatuses.filter { (_, read) ->
                                                                 !read
                                                                }.keys.toSet()
        HeapAnalysisSucceeded(
            heapDumped.uniqueId,
            fullHeapAnalysis,
            unreadLeakSignatures,
            showIntent
        )
    }
    is HeapAnalysisFailure -> {
        val showIntent = LeakActivity.createFailureIntent(application, id)
        HeapAnalysisFailed(heapDumped.uniqueId, fullHeapAnalysis, showIntent)
    }
}
                                                                    }

// 触发堆分析完成的监听器
LeakCanary.config.onHeapAnalyzedListener.onHeapAnalyzed(fullHeapAnalysis)

return analysisDoneEvent
}

private fun analyzeHeap(
    heapDumpFile: File,
    progressListener: OnAnalysisProgressListener,
    isCanceled: () -> Boolean
): HeapAnalysis {
    ...
    // Shark 堆快照分析器
    val heapAnalyzer = HeapAnalyzer(progressListener)
    ...
    // 构建对象图信息
    val sourceProvider = ConstantMemoryMetricsDualSourceProvider(ThrowingCancelableFileSourceProvider(heapDumpFile)
                                                                 val graph = sourceProvider.openHeapGraph(proguardMapping = proguardMappingReader?.readProguardMapping())
    ...
    // 开始分析
    heapAnalyzer.analyze(
        heapDumpFile = heapDumpFile,
        graph = graph,
        leakingObjectFinder = config.leakingObjectFinder, // 默认是 KeyedWeakReferenceFinder
        referenceMatchers = config.referenceMatchers, // 默认是 AndroidReferenceMatchers
        computeRetainedHeapSize = config.computeRetainedHeapSize, // 默认是 true
        objectInspectors = config.objectInspectors, // 默认是 AndroidObjectInspectors
        metadataExtractor = config.metadataExtractor // 默认是 AndroidMetadataExtractor
    )
}

fun analyze(
    heapDumpFile: File, // 堆内存转储文件
    graph: HeapGraph, // 表示堆内存结构的HeapGraph对象
    leakingObjectFinder: LeakingObjectFinder, // 用于查找泄漏对象的LeakingObjectFinder实例
    referenceMatchers: List<ReferenceMatcher> = emptyList(), // 类和实例引用匹配器列表
computeRetainedHeapSize: Boolean = false, // 是否计算保留的堆大小
objectInspectors: List<ObjectInspector> = emptyList(), // 用于检查对象类型的ObjectInspector对象列表
metadataExtractor: MetadataExtractor = MetadataExtractor.NO_OP // 用于提取元数据的MetadataExtractor实例
): HeapAnalysis { // 返回一个HeapAnalysis对象
    val analysisStartNanoTime = System.nanoTime() // 记录分析开始时的纳秒时间

    // 创建一个DelegatingObjectReferenceReader实例，负责读取类、实例和数组引用
    val referenceReader = DelegatingObjectReferenceReader(
        ...
    )

    // 调用另一个重载版本的analyze函数，传入所有参数以及刚刚创建的referenceReader
    return analyze(
        heapDumpFile,
        graph,
        leakingObjectFinder,
        referenceMatchers,
        computeRetainedHeapSize,
        objectInspectors,
        metadataExtractor,
        referenceReader
    ).run {
        // 计算分析持续时间（以毫秒为单位），并根据结果的类型更新HeapAnalysis对象的analysisDurationMillis字段
        val updatedDurationMillis = since(analysisStartNanoTime)
        when (this) {
            is HeapAnalysisSuccess -> copy(analysisDurationMillis = updatedDurationMillis)
            is HeapAnalysisFailure -> copy(analysisDurationMillis = updatedDurationMillis)
        }
    }
}

private fun FindLeakInput.analyzeGraph(
    metadataExtractor: MetadataExtractor, // 元数据提取器
    leakingObjectFinder: LeakingObjectFinder, // 泄漏对象查找器
    heapDumpFile: File, // 堆内存转储文件
    analysisStartNanoTime: Long // 分析开始时的纳秒时间
): HeapAnalysisSuccess {
// 监听器进度更新
listener.onAnalysisProgress(EXTRACTING_METADATA)
// 从图中提取元数据
val metadata = metadataExtractor.extractMetadata(graph)

// 查找所有保留但未引用的弱引用实例
val retainedClearedWeakRefCount = KeyedWeakReferenceFinder.findKeyedWeakReferences(graph)
.count { it.isRetained && !it.hasReferent }

// 如果存在保留但未引用的弱引用实例，将其计数添加到元数据中
// 这种情况很少发生，因为我们通常在堆转储之前删除所有已清除的弱引用
val metadataWithCount = if (retainedClearedWeakRefCount > 0) {
    metadata + ("Count of retained yet cleared" to "$retainedClearedWeakRefCount KeyedWeakReference instances")
} else {
    metadata
}

// 监听器进度更新
listener.onAnalysisProgress(FINDING_RETAINED_OBJECTS)
// 查找泄漏对象的ID
val leakingObjectIds = leakingObjectFinder.findLeakingObjectIds(graph)

// 根据泄漏对象ID查找泄漏情况（应用程序泄漏、库泄漏和不可达对象）
val (applicationLeaks, libraryLeaks, unreachableObjects) = findLeaks(leakingObjectIds)

// 返回分析成功的结果，包括堆内存转储文件、创建时间、分析持续时间、元数据、泄漏情况等信息
return HeapAnalysisSuccess(
    heapDumpFile = heapDumpFile,
    createdAtTimeMillis = System.currentTimeMillis(),
    analysisDurationMillis = since(analysisStartNanoTime),
    metadata = metadataWithCount,
    applicationLeaks = applicationLeaks,
    libraryLeaks = libraryLeaks,
    unreachableObjects = unreachableObjects
)
}


private fun FindLeakInput.findLeaks(leakingObjectIds: Set<Long>): LeaksAndUnreachableObjects {
                                    // 创建一个PathFinder实例，用于在图中查找从垃圾回收根节点到泄漏对象的路径
                                    val pathFinder = PathFinder(graph, listener, referenceReader, referenceMatchers)
// 使用PathFinder实例查找从垃圾回收根节点到泄漏对象的路径
val pathFindingResults =
pathFinder.findPathsFromGcRoots(leakingObjectIds, computeRetainedHeapSize)

// 查找不可达对象
val unreachableObjects = findUnreachableObjects(pathFindingResults, leakingObjectIds)

// 对找到的最短路径进行去重处理
val shortestPaths =
deduplicateShortestPaths(pathFindingResults.pathsToLeakingObjects)

// 通过最短路径检查对象
val inspectedObjectsByPath = inspectObjects(shortestPaths)

// 如果找到了支配树，计算保留大小；否则返回null
val retainedSizes =
if (pathFindingResults.dominatorTree != null) {
    computeRetainedSizes(inspectedObjectsByPath, pathFindingResults.dominatorTree)
} else {
    null
}
// 根据最短路径、检查过的对象和保留大小构建泄漏跟踪信息
val (applicationLeaks, libraryLeaks) = buildLeakTraces(
    shortestPaths, inspectedObjectsByPath, retainedSizes
)
// 返回泄漏和不可达对象的结果
return LeaksAndUnreachableObjects(applicationLeaks, libraryLeaks, unreachableObjects)
}

private fun FindLeakInput.inspectObjects(shortestPaths: List<ShortestPath>): List<List<InspectedObject>> {
    ...

    return leakReportersByPath.map { leakReporters ->
      computeLeakStatuses(leakReporters)
    }
  }

private fun computeLeakStatuses(leakReporters: List<ObjectReporter>): List<InspectedObject> {
    ...

    for ((index, reporter) in leakReporters.withIndex()) {
        val resolvedStatusPair =
        resolveStatus(reporter, leakingWins = index == lastElementIndex).let { statusPair ->
                                                                              if (index == lastElementIndex) {
            // The last element should always be leaking.
            when (statusPair.first) {
                LEAKING -> statusPair
                UNKNOWN -> LEAKING to "This is the leaking object"
                NOT_LEAKING -> LEAKING to "This is the leaking object. Conflicts with ${statusPair.second}"
            }
        } else statusPair
                                                                             }

        ...

        for (i in 0 until lastNotLeakingElementIndex) {
            val (leakStatus, leakStatusReason) = leakStatuses[i]
            val nextNotLeakingIndex = generateSequence(i + 1) { index ->
                                                               if (index < lastNotLeakingElementIndex) index + 1 else null
                                                              }.first { index ->
                                                                       leakStatuses[index].first == NOT_LEAKING
                                                                      }

            // Element is forced to NOT_LEAKING
            val nextNotLeakingName = simpleClassNames[nextNotLeakingIndex]
            leakStatuses[i] = when (leakStatus) {
                UNKNOWN -> NOT_LEAKING to "$nextNotLeakingName↓ is not leaking"
                NOT_LEAKING -> NOT_LEAKING to "$nextNotLeakingName↓ is not leaking and $leakStatusReason"
                LEAKING -> NOT_LEAKING to "$nextNotLeakingName↓ is not leaking. Conflicts with $leakStatusReason"
            }
        }

        if (firstLeakingElementIndex < lastElementIndex - 1) {
            // We already know the status of firstLeakingElementIndex and lastElementIndex
            for (i in lastElementIndex - 1 downTo firstLeakingElementIndex + 1) {
                val (leakStatus, leakStatusReason) = leakStatuses[i]
                val previousLeakingIndex = generateSequence(i - 1) { index ->
                                                                    if (index > firstLeakingElementIndex) index - 1 else null
                                                                   }.first { index ->
                                                                            leakStatuses[index].first == LEAKING
                                                                           }

                // Element is forced to LEAKING
                val previousLeakingName = simpleClassNames[previousLeakingIndex]
                leakStatuses[i] = when (leakStatus) {
                    UNKNOWN -> LEAKING to "$previousLeakingName↑ is leaking"
                    LEAKING -> LEAKING to "$previousLeakingName↑ is leaking and $leakStatusReason"
                    NOT_LEAKING -> throw IllegalStateException("Should never happen")
                }
            }
        }

...
val reachabilityString = when (leakingStatus) {
    UNKNOWN -> extra("UNKNOWN")
    NOT_LEAKING -> "NO" + extra(" (${leakingStatusReason})")
    LEAKING -> "YES" + extra(" (${leakingStatusReason})")
}
...

// 是否为怀疑对象
fun referencePathElementIsSuspect(index: Int): Boolean {
    return  when (referencePath[index].originObject.leakingStatus) {
        UNKNOWN -> true
        NOT_LEAKING -> index == referencePath.lastIndex || referencePath[index + 1].originObject.leakingStatus != NOT_LEAKING
        else -> false
    }
}