Next: , Previous: Pure Storage, Up: GNU Emacs Internals

E.3 Garbage Collection

When a program creates a list or the user defines a new function (such as by loading a library), that data is placed in normal storage. If normal storage runs low, then Emacs asks the operating system to allocate more memory. Different types of Lisp objects, such as symbols, cons cells, small vectors, markers, etc., are segregated in distinct blocks in memory. (Large vectors, long strings, buffers and certain other editing types, which are fairly large, are allocated in individual blocks, one per object; small strings are packed into blocks of 8k bytes, and small vectors are packed into blocks of 4k bytes).

Beyond the basic vector, a lot of objects like window, buffer, and frame are managed as if they were vectors. The corresponding C data structures include the struct vectorlike_header field whose next field points to the next object in the chain: header.next.buffer points to the next buffer (which could be a killed buffer), and header.next.vector points to the next vector in a free list. If a vector is small (smaller than or equal to VBLOCK_BYTES_MAX bytes, see alloc.c), then header.next.nbytes contains the vector size in bytes.

It is quite common to use some storage for a while, then release it by (for example) killing a buffer or deleting the last pointer to an object. Emacs provides a garbage collector to reclaim this abandoned storage. The garbage collector operates by finding and marking all Lisp objects that are still accessible to Lisp programs. To begin with, it assumes all the symbols, their values and associated function definitions, and any data presently on the stack, are accessible. Any objects that can be reached indirectly through other accessible objects are also accessible.

When marking is finished, all objects still unmarked are garbage. No matter what the Lisp program or the user does, it is impossible to refer to them, since there is no longer a way to reach them. Their space might as well be reused, since no one will miss them. The second (“sweep”) phase of the garbage collector arranges to reuse them.

The sweep phase puts unused cons cells onto a free list for future allocation; likewise for symbols and markers. It compacts the accessible strings so they occupy fewer 8k blocks; then it frees the other 8k blocks. Unreachable vectors from vector blocks are coalesced to create largest possible free areas; if a free area spans a complete 4k block, that block is freed. Otherwise, the free area is recorded in a free list array, where each entry corresponds to a free list of areas of the same size. Large vectors, buffers, and other large objects are allocated and freed individually.

Common Lisp note: Unlike other Lisps, GNU Emacs Lisp does not call the garbage collector when the free list is empty. Instead, it simply requests the operating system to allocate more storage, and processing continues until gc-cons-threshold bytes have been used.

This means that you can make sure that the garbage collector will not run during a certain portion of a Lisp program by calling the garbage collector explicitly just before it (provided that portion of the program does not use so much space as to force a second garbage collection).

— Command: garbage-collect

This command runs a garbage collection, and returns information on the amount of space in use. (Garbage collection can also occur spontaneously if you use more than gc-cons-threshold bytes of Lisp data since the previous garbage collection.)

garbage-collect returns a list containing the following information: 

          ((used-conses . free-conses)
           (used-syms . free-syms)
           (used-miscs . free-miscs)
           used-string-chars
           used-vector-slots
           (used-floats . free-floats)
           (used-intervals . free-intervals)
           (used-strings . free-strings))

Here is an example: 

          (garbage-collect)
               ⇒ ((106886 . 13184) (9769 . 0)
                          (7731 . 4651) 347543 121628
                          (31 . 94) (1273 . 168)
                          (25474 . 3569))

Here is a table explaining each element:

used-conses
The number of cons cells in use.
free-conses
The number of cons cells for which space has been obtained from the operating system, but that are not currently being used.
used-syms
The number of symbols in use.
free-syms
The number of symbols for which space has been obtained from the operating system, but that are not currently being used.
used-miscs
The number of miscellaneous objects in use. These include markers and overlays, plus certain objects not visible to users.
free-miscs
The number of miscellaneous objects for which space has been obtained from the operating system, but that are not currently being used.
used-string-chars
The total size of all strings, in characters.
used-vector-slots
The total number of elements of existing vectors.
used-floats
The number of floats in use.
free-floats
The number of floats for which space has been obtained from the operating system, but that are not currently being used.
used-intervals
The number of intervals in use. Intervals are an internal data structure used for representing text properties.
free-intervals
The number of intervals for which space has been obtained from the operating system, but that are not currently being used.
used-strings
The number of strings in use.
free-strings
The number of string headers for which the space was obtained from the operating system, but which are currently not in use. (A string object consists of a header and the storage for the string text itself; the latter is only allocated when the string is created.)

If there was overflow in pure space (see Pure Storage), garbage-collect returns nil, because a real garbage collection cannot be done.

— User Option: garbage-collection-messages

If this variable is non-nil, Emacs displays a message at the beginning and end of garbage collection. The default value is nil.

— Variable: post-gc-hook

This is a normal hook that is run at the end of garbage collection. Garbage collection is inhibited while the hook functions run, so be careful writing them.

— User Option: gc-cons-threshold

The value of this variable is the number of bytes of storage that must be allocated for Lisp objects after one garbage collection in order to trigger another garbage collection. A cons cell counts as eight bytes, a string as one byte per character plus a few bytes of overhead, and so on; space allocated to the contents of buffers does not count. Note that the subsequent garbage collection does not happen immediately when the threshold is exhausted, but only the next time the Lisp evaluator is called.

The initial threshold value is 800,000. If you specify a larger value, garbage collection will happen less often. This reduces the amount of time spent garbage collecting, but increases total memory use. You may want to do this when running a program that creates lots of Lisp data.

You can make collections more frequent by specifying a smaller value, down to 10,000. A value less than 10,000 will remain in effect only until the subsequent garbage collection, at which time garbage-collect will set the threshold back to 10,000.

— User Option: gc-cons-percentage

The value of this variable specifies the amount of consing before a garbage collection occurs, as a fraction of the current heap size. This criterion and gc-cons-threshold apply in parallel, and garbage collection occurs only when both criteria are satisfied.

As the heap size increases, the time to perform a garbage collection increases. Thus, it can be desirable to do them less frequently in proportion.

The value returned by garbage-collect describes the amount of memory used by Lisp data, broken down by data type. By contrast, the function memory-limit provides information on the total amount of memory Emacs is currently using.

— Function: memory-limit

This function returns the address of the last byte Emacs has allocated, divided by 1024. We divide the value by 1024 to make sure it fits in a Lisp integer.

You can use this to get a general idea of how your actions affect the memory usage.

— Variable: memory-full

This variable is t if Emacs is nearly out of memory for Lisp objects, and nil otherwise.

— Function: memory-use-counts

This returns a list of numbers that count the number of objects created in this Emacs session. Each of these counters increments for a certain kind of object. See the documentation string for details.

— Variable: gcs-done

This variable contains the total number of garbage collections done so far in this Emacs session.

— Variable: gc-elapsed

This variable contains the total number of seconds of elapsed time during garbage collection so far in this Emacs session, as a floating point number.