Guides and Sample Code

Developer

Instruments User Guide

On This Page

Allocations Instrument

Overview

Instrument Description

The Allocations instrument captures information about memory allocation for an app. It records information from a single process only.

Supported Platforms

iOS

OS X

Related Profiling Templates

Allocations Profiling Template

Leaks Profiling Template

Zombies Profiling Template

Timeline Pane

The timeline pane displays information based on the instrument’s configuration.

Record Settings

Click the Record Settings button (image: ../Art/instruments_recordsettings_button_inline_2x.png) in the inspector pane to customize the following recording options.

Launch Configuration for All Allocations

The following Launch Configuration for All Allocations record settings are available.

Setting

Description

Discard unrecorded data upon stop

Discards all data that has been gathered, but not yet processed by the Allocations instrument once Stop is clicked. Automatically selected for the Allocations, Leaks, and Zombies profiling templates.

Discard events for freed memory

Discards any events whose memory has been released.

Only track VM allocations

Tracks only VM allocations that are gathered in VM.

Launch Configuration for Heap Allocations

The following Launch Configuration for Heap Allocations record settings are available.

Setting

Description

Record reference counts

Tracks the reference count of each object. Automatically selected for the Leaks and Zombies profiling templates.

Identify C++ Objects

Identifies any C++ objects detected.

Enable NSZombie detection

Select to display a message when a zombie is detected. Automatically selected for the Zombies profiling template only.

Recorded Types

Enable the types of objects to record. You can create and remove new rules by clicking the plus (+) and minus (-) buttons beneath the table. Initial options and their configurations include the following.

Setting

Description

*

Configured to record all types: Records all types of objects.

NS

Configured to ignore types with ‘NS’ prefixes: Does not record information for NS objects.

CF

Configured to ignore types with ‘CF’ prefixes: Does not record information for CF objects.

Malloc

Configured to ignore types with ‘Malloc’ prefixes: Does not record information for Malloc events.

Display Settings

Click the Display Settings button (image: ../Art/instruments_displaysettings_button_inline_2x.png) in the inspector pane to customize the following display settings.

Track Display Settings

These settings control how information is displayed in the timeline pane.

Setting

Description

Options

Style

How information is presented.

  • Current Bytes: The number of bytes currently allocated to the process.

  • Allocation Density: The number of allocations per millisecond.

  • Active Allocation Distribution: The amount of memory currently allocated.

Generation Analysis

Allows you to mark generations in the detail pane.

Allocation Lifespan

The following allocation lifespan display settings filter allocations in the detail pane based on their lifespan.

Setting

Description

All Allocations

Show all allocations ever created within the selected time range.

Created & Persistent

Show allocations created during the selected time range and still existing at the end of it.

Created & Destroyed

Show allocations created and destroyed within the selected time range.

Allocation Type

The following allocation type display settings filter the allocations in the detail pane based on their type.

Setting

Description

All Heap & Anonymous VM

Shows all malloc heap allocations and interesting VM regions such as graphics- and Core Data-related. Hides mapped files, dylibs, and some large reserved VM regions.

All Heap Allocations

Shows all malloc heap allocations but no VM regions.

All VM Regions

Shows all VM regions, including mapped files, dylibs, and the VM regions that include the malloc heap.

Call Tree

The following call tree display settings filter the call tree in the detail pane.

Setting

State

Separate by Category

Off by default.

Separate by Thread

Off by default.

Invert Call Tree

Off by default.

Hide System Libraries

Off by default.

Flatten Recursion

Off by default.

Call Tree Constraints

The following options filter the call tree to display calls that fall within a specific threshold based on the settings below.

Setting

State

Count

Off by default.

Bytes

Off by default.

Data Mining

Allows you to filter through the collected data for specific symbols and libraries.

Detail Pane Columns

Statistics Detail Type

The following statistics columns are available in the detail pane.

Column name

Definition

Graph

Select to display the category in the track pane.

Category

Typically a Core Foundation object, an Objective-C class, or a raw block of memory.

Bytes

The total change in allocated bytes in the selected time range.

Count

The total change in the number of allocations in the selected time range.

Persistent Bytes

The number of bytes that have been allocated, but not released, during the selected time range.

# Persistent

The number of allocations that have been allocated, but not released, during the selected time range.

Transient Bytes

The number of bytes that have been created and destroyed during the selected time range.

# Transient

The number of allocations that have been created and destroyed during the selected time range.

Total Bytes

The total number of bytes that have existed during the selected time range.

# Total

The total number of allocations that have existed during the selected time range.

# Events

The total number of all types of events that have been recorded during the selected time range.

Transient/Total Bytes

A histogram representing the number of transient bytes in relation to the total number of bytes.

Call Tree Detail Type

The following call tree columns are available in the detail pane.

Column name

Definition

Bytes Used

The amount of bytes used by the corresponding symbol.

Count

The number of times the symbol was used.

Self Bytes

The number of bytes used by the call itself.

Self %

The percentage of bytes used by the call itself.

Parent %

The percentage of bytes used by the call’s parent.

Source Path

The path to the source file that generated the call.

Category

An icon representing the category of the call.

Library

The name of the library that generated the call.

Symbol Name

The name of the symbol being called.

Allocations List Detail Type

The following allocations list columns are available in the detail pane.

Column name

Definition

#

The allocation number.

Address

The address of the memory block.

Category

The type of the object.

Identifier

The identifier for the object.

Timestamp

The time the event occurred.

Live

Denotes if the object is currently live.

Size

The size of the memory block.

Responsible Library

The library responsible for allocating the block.

Responsible Caller

The function that caused the allocation event.

Generations Detail Type

The following generations columns are available in the detail pane.

Column name

Definition

Snapshot

The name of the snapshot.

Timestamp

The time the event occurred.

Heap Growth

The amount of growth since the last snapshot.

# Persistent

The number of objects that are still living.