room

room Function

Summary

Print information about the state of internal memory and its management.

Package

common-lisp

Signature

room &optional x

Arguments

`x`⇩	One of `nil`, `t`, or the keyword `:default`. Additionally in 64-bit LispWorks only, `x` can be the keyword `:full`.

Description

The function room provides statistics on the current state of the memory, including the amount of space currently allocated, and the amount available for allocation.

As outlined in the Common Lisp HyperSpec, room takes an optional argument which controls the level of detail it produces.

The output of room differs between 32-bit and 64-bit LispWorks, and is described separately below.

Output of room in 32-bit LispWorks

If x is nil, a summary of the total allocation in the entire heap (in kilobytes) is produced. The "allocated" figure only represents the amount of space allocated in heap segments that are writable, as opposed to read-only segments that hold some of the system code such as the garbage collector (GC) itself. The free space figure covers all the free space in all segments. To obtain these values programmatically, call room-values.

If x is not supplied, room additionally prints information on the distribution of space between the generations of the heap.

If x is t, a breakdown of allocation in the individual segments of each generation is produced. Each segment is identified by its start address in memory. For each segment there is a free space threshold (the "minimum free space")—when the available space in the segment falls below this value, the GC takes action to attempt to free more space in this segment.

Two statistics about promotion are also reported on a per-segment basis: the number of sweeps that an object must survive in this generation before becoming eligible for promotion, and the total volume of objects that have survived for that long and are consequently awaiting promotion to the next generation. These statistics are not relevant for static segments, which are indicated as "static".

room prints numbers in decimal format, except for the segment start addresses which it prints in hexadecimal format.

Output of room in 64-bit LispWorks

The last line of the output of room is always a line containing the total allocated amount (memory occupied by live objects) and the total size (memory that LispWorks has allocated from the OS) (the "total line"). Both numbers are given in decimal followed parenthetically by the same number in hexadecimal. Above the total line is information for each generation.

If x is nil, room does not print any information about generations.

If x is not supplied, room prints the amount allocated for each generation in decimal.

If x is :full, room prints for each generation the amount allocated, both in decimal and in hexadecimal, and then the allocated amount of each allocation type in which there is any allocation in this generation.

If x is t, room behaves as if x is :full, and also prints information about the segments in this generation. For each segment it prints the allocation type and the start and end address for allocation in this segment.

Note that information for segments does not correspond to the allocated size, because not all the area in the segment is currently allocated.

See 11.4 Memory Management in 64-bit LispWorks for a description of allocation types and segments.

Output of room in the Mobile GC

(room) and (room :default) prints the allocated and free sizes according to these types:

Cons	cons object only.
Other	All other objects, except static objects and large objects (> 1 MB).
Static	Static objects.
Large	Large objects (> 1 MB). Note: this threshold may change in the future, but it is fixed in the current version.

The Cons and Other segments are divided according to their generation and there may also some permanent segments (as a result of a call to make-current-allocation-permanent, make-object-permanent or make-permanent-simple-vector).

In addition, LispWorks also holds some reserved segments that are used during GC, and room prints the size of these too.

(room t) also prints the segments for each type. For each segment, it prints the start and end addresses (in hex), the allocated area, and whether there is a free "hole" in the middle of it. For the Large and Static segments, it also prints the generation number of each segment. Permanent Static and Large segments have generation number 3.

See 11.5.2 Mobile GC technical details for more technical details.

Notes

The segments information is useful for debugging problems with memory management, but for analysis of application allocation (room :full) gives enough information. Especially for very large images, there are many segments, so the output of (room t) is very large and not so useful (except for debugging).

Examples

CL-USER 22 > (room nil)
 
Total Size 39424K, Allocated 32591K, Free 6461K
 
CL-USER 23 > (room)
 Generation 0:  Total Size 4394K, Allocated 952K, Free 3433K 
 Generation 1:  Total Size 1397K, Allocated 795K, Free 589K 
 Generation 2:  Total Size 4292K, Allocated 2172K, Free 2111K 
 Generation 3:  Total Size 29009K, Allocated 28885K, Free 112K 
 
Total Size 39424K, Allocated 32805K, Free 6247K
 
CL-USER 24 > (room t)
 Generation 0:  Total Size 4394K, Allocated 1004K, Free 3382K 
          Segment 2008EC80: Total Size 507K, Allocated 353K, Free 149K
                    minimum free space 64K, 
                      Awaiting promotion = 23K, sweeps before promotion =10
          Segment 222B4498: Total Size 3886K, Allocated 650K, Free 3232K
                    minimum free space 0K, 
                      Awaiting promotion = 51K, sweeps before promotion =2
 Generation 1:  Total Size 1397K, Allocated 795K, Free 589K 
          Segment 2070DC18: Total Size 68K, Allocated 64K, Free 0K
                    minimum free space 3K, 
                      Awaiting promotion = 0K, sweeps before promotion =4
          Segment 21D84498: Total Size 1088K, Allocated 613K, Free 470K
                    minimum free space 0K, 
                      Awaiting promotion = 0K, sweeps before promotion =4
          Segment 200528D8: Total Size 240K, Allocated 118K, Free 118K
                    minimum free space 0K, static
 Generation 2:  Total Size 4292K, Allocated 2172K, Free 2111K 
          Segment 21E94498: Total Size 4224K, Allocated 2107K, Free 2111K
                    minimum free space 0K, 
                      Awaiting promotion = 0K, sweeps before promotion =4
          Segment 20E7DC18: Total Size 68K, Allocated 64K, Free 0K
                    minimum free space 117K, 
                      Awaiting promotion = 0K, sweeps before promotion =4
 Generation 3:  Total Size 29009K, Allocated 28885K, Free 112K 
          Segment 2071EC90: Total Size 7547K, Allocated 7543K, Free 0K
                    minimum free space 0K, 
                      Awaiting promotion = 0K, sweeps before promotion =10
          Segment 20E8EC90: Total Size 15318K, Allocated 15201K, Free 112K
                    minimum free space 0K, 
                      Awaiting promotion = 0K, sweeps before promotion =10
          Segment 2010DC18: Total Size 6144K, Allocated 6139K, Free 0K
                    minimum free space 3K, 
                      Awaiting promotion = 0K, sweeps before promotion =10
 
Total Size 39424K, Allocated 32857K, Free 6195K