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 in blocks of 1k bytes. Each block is used for one
type of Lisp object, so symbols, cons cells, markers, etc., are
segregated in distinct blocks in memory. (Vectors, long strings,
buffers and certain other editing types, which are fairly large, are
allocated in individual blocks, one per object, while small strings are
packed into blocks of 8k 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. (This name is traditional, but "garbage recycler" might be a
more intuitive metaphor for this facility.)
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. Vectors, buffers, windows, and other large objects are
individually allocated and freed using `malloc' and `free'.
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.)
- 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', meaning there are no such messages.
- 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 400,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.
The value return 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.