Hide and Go Leak WiKI

Welcome to the HideAndGoLeak wiki!

LeakDetective Documentation

Overview

Hide and Go Leak is a high-performance memory management framework designed for iOS, Apple TV, and macOS. It enables developers to detect memory leaks—specifically retain cycles—in real-time during the development lifecycle without incurring a significant performance penalty.

The framework works by maintaining weak references to tracked objects. If an object is expected to be deallocated but remains in memory, LeakDetective identifies the leak and provides diagnostic information.

Getting Started

To get started, simply add the swift package to your XCode Project.

If you are not familiar with this process, check Xcode’s documentation.
The Swift Package dependency is found by selecting the main project name in the files section of XCode.

Select the “Package Dependencies” tab in XCode.
Press the “+” symbol to add a new package.

Enter the URL for “HideAndGoLeak” which is:
https://github.com/veescope/HideAndGoLeak
Press the “Add Package” button.
XCode will prompt you for a target for this package. If you have multiple targets, you will need to add them later.

Select the “Add Package” button.
You should see the “Package Dependencies” under the XCode files section.

Check to make sure the package has been resolved correctly and that there are no warnings in XCode.

Core Components

MemoryObject

A wrapper class used to track individual instances. It utilizes a weak reference to ensure that the tracking mechanism itself does not contribute to a retain cycle or prevent the object from being naturally deallocated.

trackedObject: A weak reference to the object being monitored.
infoDescription: An optional string providing context about the object (e.g., class name or purpose).

LeakDetective

The primary utility class contains static methods for object tracking, cleanup, and system resource inspection.

Key Features

1. Object Tracking

Tracking is initiated by passing an object to the detective. The framework generates a unique identifier based on the object's memory address.

Method	Description
`trackObject(_:description:)`	Starts tracking an object and returns its unique memory address identifier.
`trackObject(_:uniqueName:description:)`	Tracks an object using a custom key. Returns `false` if an object with that name already exists and is still in memory (indicating a leak).
`trackObjectDebugOnly(_:)`	Executes tracking only in `#DEBUG` builds.

2. Leak Detection Logic

The framework identifies leaks by checking if a previously tracked unique name is still associated with an active object. If trackObject(uniqueName:) is called and finds the old instance still exists, it flags a potential retain cycle.

3. System Inspection

Beyond individual objects, LeakDetective provides insight into global system resources:

RAM Usage: Calculates free, used, and percentage of RAM utilized by the application.
Disk Space: Reports available disk space on the device.
Memory Footprint: The all() method provides a summary of all currently tracked objects and calculates their total size in bytes using malloc_size.

Implementation Example

To detect a leak in a parent-child relationship (a common source of retain cycles), use the unique name tracking method:import LeakDetective

class MyClass {

var child: MyChildClass?

init() {

    self.child \= MyChildClass(parent: self)

    

    // If trackObject returns false, the previous instance of "MyClass" leaked

    if \!LeakDetective.trackObject(self, uniqueName: "MyClass") {

        fatalError("Leak detected in \\(\#function) line \\(\#line)")

    }

}

}

class MyChildClass {

var parent: MyClass? // Potential retain cycle if not 'weak'

init(parent: MyClass) {

    self.parent \= parent

}

}

API Reference: System Statistics

Property	Type	Description
`freeRAM`	`UInt64`	Total virtual memory size is currently free.
`usedRAM`	`UInt64`	Internal and compressed memory used by the task.
`percentageRAMUsed`	`Double`	Ratio of used RAM to total (used + free) RAM.
`freeDiskSpace`	`UInt64`	Available volume capacity for important usage.

Cleanup & Maintenance

LeakDetective includes automatic and manual cleanup routines to ensure the tracking dictionary does not grow indefinitely:

removeFreedObjects(): Iterates through tracked items and removes any where the weak reference has become nil.
removeObject(_:): Manually stops tracking a specific instance.
trackObjectFreeing(_:time:): Tracks an object and automatically checks if it has been leaked after a specified TimeInterval.

Navigation Menu