You will need [https://admin.fedoraproject.org/updates/gdb-7.2-7.fc14 gdb-7.2-7.fc14] or later when attaching to a process (rather than starting the process within gdb), due to [https://bugzilla.redhat.com/show_bug.cgi?id=634660 bug 634660]

DONE:

DONE:

Line 133:

Line 135:

{|

{|

!Domain !! Meaning of 'kind'

!Domain !! Meaning of 'kind'

+

|-

+

| <code>C</code> || ''string data'' signifies a NUL-terminated string

|-

|-

| <code>python</code> ||the python class

| <code>python</code> ||the python class

Line 140:

Line 144:

| <code>pyarena</code> ||Python's optimized memory allocator

| <code>pyarena</code> ||Python's optimized memory allocator

|-

|-

−

| <code>uncategorized/code> || (none; gdb-heap wasn't able to identify what this is used for)

+

| <code>uncategorized</code> || (none; gdb-heap wasn't able to identify what this is used for)

|-

|-

| <code>C++</code> ||the C++ class (disabled for now in Fedora 14's gdb-heap; the heuristic needs to be optimized)

| <code>C++</code> ||the C++ class (disabled for now in Fedora 14's gdb-heap; the heuristic needs to be optimized)

gdb-heap provides a "history" feature, somewhat analogous to a revision-control system such as git

+

gdb-heap provides a "history" feature, somewhat analogous to a revision-control system such as git, although the data is merely stored within the gdb process (it does not persist to disk, and is lost when gdb exits)

+

<code>heap label</code> allows you to take a named snapshot of the current state of the heap.

<pre>

<pre>

−

(gdb) heap label

+

(gdb) heap label "about to 'import sys'"

+

Blocks retrieved 10000

+

2,626,416 allocated, in 18716 blocks

+

(gdb) cont

+

>>> import sys

+

Ctrl+C

+

(gdb) heap label "after 'import sys'"

+

Blocks retrieved 10000

+

2,626,688 allocated, in 18720 blocks

</pre>

</pre>

−

allows you to take a named snapshot of the current state of the heap.

+

<code>heap log</code> shows you all such named snapshots:

−

+

<pre>

<pre>

(gdb) heap log

(gdb) heap log

−

</pre>

+

Label 2 ""after 'import sys'"" at 2010-09-16 18:01:17.879123

+

2,626,688 allocated, in 18720 blocks

−

shows you all such named snapshots

+

+272 bytes, +4 blocks

+

Label 1 ""about to 'import sys'"" at 2010-09-16 17:55:17.030709

+

2,626,416 allocated, in 18716 blocks

+

</pre>

+

+

<code>heap diff</code> allows you to compare dynamic memory allocations between two different states: either those in the log, or with the current state.

<pre>

<pre>

(gdb) heap diff

(gdb) heap diff

−

</pre>

+

Blocks retrieved 10000

+

Changes from "about to 'import sys'" to current

+

+272 bytes, +4 blocks

−

allows you to compare dynamic memory allocations between two different states: either those in the log, or with the current state.

The command allows you to get a breakdown of how that process is using dynamic memory.

It allows for unplanned memory usage debugging: if a process unexpectedly starts using large amounts of memory you can attach to it with gdb, and use the heap command to figure out where the memory is going. You should also be able to use it on core dumps.

Ensure that all results look correct, and that there are no Python tracebacks within gdb.

Ideally the amount of "uncategorized" data should not be a substantial proportion of the overall size of the dynamically-allocated memory; if it is, then that may be a bug.

Ideally the command should not take too long to run. The more blocks of memory that are "live" within a process, the longer it will take to analyze the usage. Crude timings suggest it can analyze about 5000 allocations per second, so if you have a process with 300,000 allocations, it could take a minute to analyze them.

As you can see, gdb-heap will attempt to categorize the chunks of dynamically-allocated memory that it finds. It shows you how many blocks of memory of each category it found, with the categories sorted by the number of bytes of RAM that they're using.

The categorization is divided into three parts:

domain: high-level grouping e.g. "python", "C++", etc

kind: type information, appropriate to the domain e.g. a class/type

detail: additional detail (e.g. the size of a buffer, or a note that this python string is actually bytecode)

Some domains:

Domain

Meaning of 'kind'

C

string data signifies a NUL-terminated string

python

the python class

cpython

C structure/type (implementation detail within Python)

pyarena

Python's optimized memory allocator

uncategorized

(none; gdb-heap wasn't able to identify what this is used for)

C++

the C++ class (disabled for now in Fedora 14's gdb-heap; the heuristic needs to be optimized)

GType

the GLib type/GObject class, within the GTK+ stack (not yet present Fedora 14's gdb-heap; in upstream git, but needs to be made robust and optimized)

You can see in the above example that much of the memory is taken up by python strings (the "str" type), but a considerable amount is also occupied by implementation details of python dictionaries (the "PyDictEntry tables").

There are numerous subcommands. heap is integrated into gdb's tab-completion, so that you can see the available commands with the TAB key:

gdb-heap provides a "history" feature, somewhat analogous to a revision-control system such as git, although the data is merely stored within the gdb process (it does not persist to disk, and is lost when gdb exits)

heap label allows you to take a named snapshot of the current state of the heap.

"heap all" shows a detailed, low-level report on all dynamically-allocated chunks of memory. This is a simple loop through memory, typically showing you the large allocations first (implemented via "mmap"), then the smaller ones (implemented within the "sbrk" region).

It reports the start/end of each region, along with book-keeping information about the block.

There's a baseline of functionality that I'm developing on top of Fedora 13's gdb.

The gdb-heap code peeks around inside the internals of the glibc heap implementation, violating encapsulation (rather by definition for a debugger), so if that changes, corresponding changes will need to be made to gdb-heap.

Some features require additional work in gdb, which I've filed RFE bugs for. Naturally this will require coordination with gdb to ensure that they land in Fedora 14:

The gdb debugger has been extended with new commands that make it easier to track down and fix excessive memory usage within programs and libraries. This functionality was created by Fedora contributor David Malcolm, and we believe it is unique to Fedora 14.