references/memory-profiling.md
GitHubMemory Profiling
Contents
- Instruments Setup
- Allocations Instrument
- Leaks Instrument
- Xcode Memory Graph Debugger
- Autorelease Pool Optimization
- Memory Footprint Tracking in Code
- Quick Diagnosis Checklist
Instruments Setup
Allocations Instrument
- Xcode > Product > Profile (Cmd+I)
- Choose Allocations template
- Record, reproduce the issue, stop
Leaks Instrument
- Included in the Allocations template by default
- Runs periodic scans for unreachable memory
- Red crosses in the Leaks lane indicate detected leaks
Allocations Instrument
Key Metrics
| Metric | Meaning |
|---|---|
| All Heap Allocations | Total memory allocated on the heap |
| Live Bytes | Currently allocated (not freed) memory |
| Transient Bytes | Allocated and freed during recording |
| # Living | Count of live allocation objects |
| # Transient | Count of freed allocations |
Reading the Results
- Sort by Live Bytes to find largest memory consumers
- Sort by # Living to find most numerous allocations
- Click a category to see individual allocations with stack traces
- Persistent column shows objects that survive across generations
Generation Analysis (Mark Generation)
Track memory growth over repeated operations:
- Start recording
- Click Mark Generation to baseline
- Perform an operation (open screen, load data, etc.)
- Click Mark Generation again
- Repeat the same operation
- Compare generations - growth between identical operations = leak or unbounded cache
What to look for:
- Stable: Each generation has similar Live Bytes
- Leaking: Each generation grows - objects from previous generations persist
- Caching: Growth that plateaus after a few generations (may be intentional)
Common Memory Issues
Unbounded Cache Growth
// Bad - cache grows forever
class ImageCache {
var cache: [URL: UIImage] = [:]
func image(for url: URL) -> UIImage? {
return cache[url]
}
}
// Good - use NSCache for automatic eviction
class ImageCache {
private let cache = NSCache<NSURL, UIImage>()
init() {
cache.countLimit = 100
cache.totalCostLimit = 50 * 1024 * 1024 // 50 MB
}
func image(for url: URL) -> UIImage? {
return cache.object(forKey: url as NSURL)
}
func store(_ image: UIImage, for url: URL) {
let cost = image.cgImage.map { $0.bytesPerRow * $0.height } ?? 0
cache.setObject(image, forKey: url as NSURL, cost: cost)
}
}
Large Images Not Downsampled
// Bad - full resolution image loaded into memory
let image = UIImage(contentsOfFile: photoPath)
// 4032x3024 photo = ~48 MB in memory
// Good - downsample to display size
func downsample(imageAt url: URL, to pointSize: CGSize, scale: CGFloat) -> UIImage? {
let maxDimensionInPixels = max(pointSize.width, pointSize.height) * scale
let options: [CFString: Any] = [
kCGImageSourceCreateThumbnailFromImageAlways: true,
kCGImageSourceShouldCacheImmediately: true,
kCGImageSourceCreateThumbnailWithTransform: true,
kCGImageSourceThumbnailMaxPixelSize: maxDimensionInPixels
]
guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary)
else { return nil }
return UIImage(cgImage: cgImage)
}
Leaks Instrument
How Leaks Detection Works
- Scans heap at intervals for objects with no root references
- Detects unreachable memory - allocated but no path from stack/globals
- Does NOT detect logical leaks (reachable but never used, like unbounded caches)
Common Retain Cycle Patterns
Closure Capturing Self
// Bad - retain cycle: self -> timer -> closure -> self
class ViewModel {
var timer: Timer?
func startPolling() {
timer = Timer.scheduledTimer(withTimeInterval: 5, repeats: true) { _ in
self.refresh() // Strong capture of self
}
}
}
// Good - weak capture
timer = Timer.scheduledTimer(withTimeInterval: 5, repeats: true) { [weak self] _ in
self?.refresh()
}
Delegate Retain Cycle
// Bad - strong delegate creates cycle
protocol ServiceDelegate: AnyObject {
func didComplete()
}
class Service {
var delegate: ServiceDelegate? // Strong reference
}
class ViewModel: ServiceDelegate {
let service = Service() // ViewModel -> Service -> ViewModel
init() { service.delegate = self }
}
// Good - weak delegate
class Service {
weak var delegate: ServiceDelegate?
}
Closure in Collection
// Bad - closures in array capture self strongly
class Coordinator {
var handlers: [() -> Void] = []
func register() {
handlers.append {
self.handleEvent() // Each closure retains self
}
}
}
// Good - weak capture in each closure
handlers.append { [weak self] in
self?.handleEvent()
}
NotificationCenter (Pre-iOS 9 / Manual)
// Modern iOS/macOS: system auto-removes observers on dealloc
// But if using block-based API, the token retains the closure:
// Bad - token keeps closure alive
let token = NotificationCenter.default.addObserver(
forName: .dataChanged, object: nil, queue: .main
) { _ in
self.reload() // Retained by token
}
// Good - store and remove, or use weak self
let token = NotificationCenter.default.addObserver(
forName: .dataChanged, object: nil, queue: .main
) { [weak self] _ in
self?.reload()
}
Xcode Memory Graph Debugger
When to Use
- Leaks instrument shows leaks but you need to see why objects are retained
- You suspect retain cycles but can't find them in code review
- You need to see the full ownership graph of an object
How to Use
- Run app in Debug mode (not Profile)
- Reproduce the state where objects should be deallocated
- Click the Memory Graph button in Xcode's debug bar (looks like interconnected nodes)
- Xcode pauses and captures the heap
Reading the Graph
- Left sidebar: List of all live objects grouped by type
- Purple exclamation marks: Xcode-detected leaks / retain cycles
- Center canvas: Visual graph of object references
- Click an object to see its retain graph - who holds a strong reference to it
Debugging Tips
- Filter by your module name to ignore system objects
- Look for cycles - two objects pointing at each other
- Check backtrace in the right sidebar to see where the object was allocated
- Export the graph: File > Export Memory Graph for sharing
Enable Malloc Stack Logging
For full allocation backtraces in Memory Graph Debugger:
- Scheme > Run > Diagnostics
- Enable Malloc Stack Logging (Live Allocations Only)
- Now the right sidebar shows the exact call stack that allocated each object
Autorelease Pool Optimization
In tight loops creating Objective-C bridged objects:
// Bad - autoreleased objects accumulate until loop ends
for item in largeDataSet {
let string = item.name as NSString // Autoreleased
let data = string.data(using: .utf8) // Autoreleased
process(data)
}
// Memory spikes until loop completes and pool drains
// Good - drain pool each iteration
for item in largeDataSet {
autoreleasepool {
let string = item.name as NSString
let data = string.data(using: .utf8)
process(data)
}
}
// Memory stays flat - pool drains each iteration
When autoreleasepool Matters
- Processing large collections (1000+ items)
- Creating temporary
NSString,NSData,NSNumberobjects in loops - Image processing pipelines
- Not needed for pure Swift value types (String, Data, Array)
Memory Footprint Tracking in Code
import os
func logMemoryFootprint() {
var info = mach_task_basic_info()
var count = mach_msg_type_number_t(
MemoryLayout<mach_task_basic_info>.size / MemoryLayout<natural_t>.size
)
let result = withUnsafeMutablePointer(to: &info) {
$0.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), $0, &count)
}
}
if result == KERN_SUCCESS {
let usedMB = Double(info.resident_size) / 1_048_576
os_log("Memory footprint: %.1f MB", usedMB)
}
}
Quick Diagnosis Checklist
- Run Allocations with Generation Analysis - does memory grow across identical operations?
- Run Leaks instrument - any detected leaks?
- Check Memory Graph Debugger for retain cycles (purple warnings)
- Search for
selfin closures without[weak self]or[unowned self] - Verify delegates are declared
weak - Check
NSCacheusage instead of plain dictionaries for caches - Verify images are downsampled to display size
- Use
autoreleasepoolin tight loops with ObjC-bridged objects