Guides and Sample Code

Developer

Instruments User Guide

Find Memory Leaks

The Leaks profiling template uses the Allocations and Leaks instruments to measure general memory usage in your app and check for leaks—memory that has been allocated to objects that are no longer referenced and reachable.

To look for memory leaks
  1. Launch Instruments.

  2. In the profiling template selection dialog that appears, click Leaks.

  3. Choose your device and app from the target device and process lists.

  4. Click Choose to create a trace document.

  5. Click the Record button (image: ../Art/inline_record_button_2x.png) in the toolbar (or press Command-R) to begin recording.

  6. Use your app normally.

  7. Watch the Leaks instrument in the timeline pane for leaks. A leak appears as a red bar.

  8. Click the Leaks instrument in the timeline pane to display leak-related information in the detail pane.

  9. Choose Call Tree from the detail type list in the navigation bar of the detail pane.

    A list of method calls related to any detected leaks is displayed.

  10. Press Command-2 to show the display settings area of the inspector pane.

  11. Under the Call Tree display settings, select Invert Call Tree and Hide System Libraries.

    The most recent method calls are shown first. It also helps narrow down the list of method calls to ones made by your app. Method calls made by your app are colored black and preceded by a user code icon (image: ../Art/inline_usercode_icon_2x.png).

  12. In the call tree, select a method call you want to investigate.

  13. Press Command-3 to display a stack trace for the selected method call in the extended detail area of the inspector.

  14. Double-click the method call in the stack trace to display its code in Instruments.

  15. Click the Xcode button (image: ../Art/inline_xcode_2x.png) at the top of the detail pane to open the code in Xcode for review and editing.

To investigate a leaked object using a backtrace
  1. Click the Leaks instrument in the timeline pane to display leak-related information in the detail pane.

  2. Choose Leaks from the detail type list in the navigation bar of the detail pane.

    A list of leaked objects by backtrace is displayed.

    The Leaks by Backtrace view aggregates all of the leaked blocks by their allocation point, because a single mistake in source code can result in multiple runtime leaks as the code is executed repeatedly.

  3. Select an object you want to investigate.

  4. Click the focus arrow (image: ../Art/icon_detail_pane_gotoarrow_2x.png) next to the object’s memory address to display the memory history of the object in the detail pane, along with corresponding reference counts and method calls.

  5. Press Command-3 to display a stack trace for the selected object in the extended detail area of the inspector.

  6. Click the Collapse button (image: ../Art/inline_hidesystemcalls_button_2x.png) in the extended detail area to hide system calls in the stack trace. This makes it easier to locate your app’s methods.

  7. Double-click a method in the stack trace to display its code in Instruments.

  8. Click the Xcode button (image: ../Art/inline_xcode_2x.png) at the top of the detail pane to open the code in Xcode for review and editing.

After you open Xcode to see the code that is creating the leak, the cause of the leak may still be unclear. The Leaks instrument allows you to see the cycle that is creating the leak by using the Cycles & Roots option in the detail pane.

To investigate a leaked object using cycles and roots
  1. Click the Leaks instrument in the timeline pane to display leak-related information in the detail pane.

  2. Choose Cycles & Roots from the detail type list in the navigation bar of the detail pane.

    A list of leaked objects by cycle is displayed.

  3. Select an object you want to investigate.

  4. If available, view the object graph for the object.

  5. Click the focus arrow (image: ../Art/icon_detail_pane_gotoarrow_2x.png) next to the object to display the memory history of the object in the detail pane, along with corresponding reference counts and method calls.

  6. Press Command-3 to display a stack trace for the selected object in the extended detail area of the inspector.

  7. Click the Collapse button (image: ../Art/inline_hidesystemcalls_button_2x.png) in the extended detail area to hide system calls in the stack trace. This makes it easier to locate your app’s methods.

  8. Double-click a method in the stack trace to display its code in Instruments.

  9. Click the Xcode button (image: ../Art/inline_xcode_2x.png) at the top of the detail pane to open the code in Xcode for review and editing.

To investigate a leak using the call tree
  1. Click the Leaks instrument in the timeline pane to display leak-related information in the detail pane.

  2. Select Call Tree from the detail type list in the navigation bar of the detail pane.

    A list of method calls related to any detected leaks is displayed.

  3. Press Command-2 to show the display settings area in the inspector pane.

  4. Under the Call Tree display settings, select Invert Call Tree and Hide System Libraries.

    The most recent method calls are shown first. It also helps narrow down the list of method calls to ones made by your app. Method calls made by your app are colored black and preceded by a user code icon (image: ../Art/inline_usercode_icon_2x.png).

  5. Select a method call you want to investigate.

  6. Press Command-3 to display a stack trace for the selected method call in the extended detail area of the inspector.

  7. Double-click the method call in the stack trace to display its code in Instruments.

  8. Click the Xcode button (image: ../Art/inline_xcode_2x.png) at the top of the detail pane to open the code in Xcode for review and editing.

Although Instruments can help you detect memory leaks, you still need to look carefully through the related memory history and your code in order to identify and resolve the problem. The following scenarios are common causes of leaks:

  • Retain has been called on an object without a corresponding release call when the object is no longer referenced.

  • An object has been allocated and initialized with APIs that don’t cause the object to autorelease.

  • If a leak isn’t an object, you may be calling an API that assumes ownership of a malloc-created memory block, and you are missing a corresponding call to free().