axiom-objc-block-retain-cycles

Objective-C Block Retain Cycles

Overview

Block retain cycles are the #1 cause of Objective-C memory leaks. When a block captures self and is stored on that same object (directly or indirectly through an operation/request), you create a circular reference: self → block → self. Core principle 90% of block memory leaks stem from missing or incorrectly applied weak-strong patterns, not genuine Apple framework bugs.

Red Flags — Suspect Block Retain Cycle

If you see ANY of these, suspect a block retain cycle, not something else:

• Memory grows steadily over time during normal app use
• UIViewController instances not deallocating (verified in Instruments)
• Crash: "Sending message to deallocated instance" from network/async callback
• Network requests or animations prevent view controller from closing
• Weak reference becomes nil unexpectedly in a block
• NSLog, NSAssert, or string formatting hiding self references
• Completion handler fires after the view controller "should be gone"
• ❌ FORBIDDEN Rationalizing as "It's probably normal memory usage"
  • Memory leaks are never "normal"
  • Apps should return to baseline memory after user dismisses a screen
  • Do not rationalize this as "good enough" or "monitor it later"

Critical distinction Block retain cycles accumulate silently. A single cycle might be 100KB, but after 50 screens viewed, you have 5MB of dead memory. MANDATORY: Test on real device (oldest supported model) after fixes, not just simulator.

Mandatory First Steps

ALWAYS run these FIRST (before changing code):

// 1. Identify the leak with Allocations instrument
// In Xcode: Xcode > Open Developer Tool > Instruments
// Choose Allocations template
// Perform an action (open/close a screen with the suspected block)
// Check if memory doesn't return to baseline
// Record: "Memory baseline: X MB, after action: Y MB, still allocated: Z objects"

// 2. Use Memory Debugger to trace the cycle
// Run app, pause at suspected code location
// Debug > Debug Memory Graph
// Search for the view controller that should be deallocated
// Right-click > Show memory graph
// Look for arrows pointing back to self (the cycle)
// Record: "ViewController retained by: [operation/block/property]"

// 3. Check if block is assigned to self or self's properties
// Search for: setBlock:, completion:, handler:, callback:
// Check: Is the block stored in self.property?
// Check: Is the block passed to something that retains it (network operation)?
// Record: "Block assigned to: [property or operation]"

// 4. Search for self references in the block
// Look for: [self method], self.property, self-> access
// Look for HIDDEN self references:
//   - NSLog(@"Value: %@", self.property)
//   - NSAssert(self.isValid, @"message")
//   - Format strings: @"Name: %@", self.name
// Record: "self references found in block: [list]"

// Example output:
// Memory not returning to baseline ✓
// ViewController retained by: AFHTTPRequestOperation
// Operation retains: successBlock
// Block references self: [self updateUI], NSLog with self.property
// → DIAGNOSIS: Block retain cycle confirmed