= Heap Utilization =

'''[Function]'''

`heap-utilization` `&key` (''stream'' `*debug-io*`) (''gc-first'' `t`) (''area'' `nil`) (''unit'' `nil`) (''sort'' `:size`) (''classes'' `nil`) (''start'' `nil`) (''threshold'' `(and classes 0.0005)`)


`heap-utilization` walks the lisp heap, collects information about the objects stored on the heap, and prints a report of the results to ''stream''.  It shows the number of objects of each type, the logical size (i.e. the size of the data part of the object) and the physical size (the logical size plus any header and padding bytes).

If ''gc-first'' is true (the default), does a full gc before scanning the heap.

If ''classes'' is true, classifies objects by class rather than just basic type.

''area'' can be used to restrict the walk to one memory area or a list of areas.  Some possible values are `:dynamic`, `:static`, `:managed-static`, `:readonly`.  By default, all areas (including stacks) are examined.

''sort'' can be one of `:count`, `:logical-size`, or `:physical-size` to sort output by count or size.

''unit'' can be one of `:kb` `:mb` or `:gb` to show sizes in units other than bytes.

If ''start'' is non-nil, it should be an object returned by `get-allocation-sentinel`; only 
objects at higher address are scanned (i.e. roughly, only objects allocated after it).

If ''threshold'' is non-nil, it should be a number between 0 and 1.  All types whose share of the heap is less than ''threshold'' will be lumped together in an "All Others" line rather than being listed individually.

{{{
Welcome to Clozure Common Lisp Version 1.5-dev-r13388  (LinuxX8664)! 
? (heap-utilization) 
Object type                             Count     Logical size   Physical size   % of Heap 
                                                   (in bytes)      (in bytes) 
FUNCTION                                12835         6344288         6497264      27.44% 
SIMPLE-BASE-STRING                      51815         3158092         3897648      16.46% 
SIMPLE-VECTOR                           25291         2509672         2820800      11.91% 
CONS                                   168420         2694720         2694720      11.38% 
SYMBOL                                  41357         2315992         2646848      11.18% 
HASH-VECTOR                                82         2121952         2123264       8.97% 
STRUCTURE                               15955          656104          902192       3.81% 
SIMPLE-UNSIGNED-WORD-VECTOR              5310          699566          762048       3.22% 
SLOT-VECTOR                              4850          417608          479104       2.02% 
SIMPLE-SIGNED-WORD-VECTOR                   2          266480          266512       1.13% 
SIMPLE-UNSIGNED-BYTE-VECTOR              3941          147087          199920       0.84% 
INTERNAL-STRUCTURE                       2717          141776          165664       0.70% 
INSTANCE                                 4387          105288          140384       0.59% 
BIT-VECTOR                                549           45095           53536       0.23% 
LOCK                                      130            6240            8320       0.04% 
MACPTR                                    159            5912            7184       0.03% 
BIGNUM                                    112            4160            5712       0.02% 
SIMPLE-UNSIGNED-DOUBLEWORD-VECTOR           1            4088            4096       0.02% 
BASIC-STREAM                               33            1296            1744       0.01% 
DOUBLE-FLOAT                               75             600            1200       0.01% 
PACKAGE                                    15             960            1200       0.01% 
POPULATION                                 22             536             720       0.00% 
POOL                                       23             184             368       0.00% 
VALUE-CELL                                 19             152             304       0.00% 
SIMPLE-UNSIGNED-LONG-VECTOR                 3              72              96       0.00% 
COMPLEX                                     1              16              32       0.00% 
Total                                  338104        21647936        23680880     100.00% 
}}}