Function: garbage-collect

garbage-collect is an interactive function defined in alloc.c.

Signature

(garbage-collect)

Documentation

Reclaim storage for Lisp objects no longer needed.

Garbage collection happens automatically if you cons more than gc-cons-threshold bytes of Lisp data since previous garbage collection. garbage-collect normally returns a list with info on amount of space in use, where each entry has the form (NAME SIZE USED FREE), where:
- NAME is a symbol describing the kind of objects this entry represents,
- SIZE is the number of bytes used by each one,
- USED is the number of those objects that were found live in the heap,
- FREE is the number of those objects that are not live but that Emacs
  keeps around for future allocations (maybe because it does not know how
  to return them to the OS).

However, if there was overflow in pure space, and Emacs was dumped using the "unexec" method, garbage-collect returns nil, because real GC can't be done.

Note that calling this function does not guarantee that absolutely all unreachable objects will be garbage-collected. Emacs uses a mark-and-sweep garbage collector, but is conservative when it comes to collecting objects in some circumstances.

For further details, see Info node (elisp)Garbage Collection.

View in manual

Probably introduced at or before Emacs version 1.10.

Key Bindings

Source Code

// Defined in /usr/src/emacs/src/alloc.c
{
  if (garbage_collection_inhibited)
    return Qnil;

  specpdl_ref count = SPECPDL_INDEX ();
  specbind (Qsymbols_with_pos_enabled, Qnil);
  garbage_collect ();
  unbind_to (count, Qnil);
  struct gcstat gcst = gcstat;

  Lisp_Object total[] = {
    list4 (Qconses, make_fixnum (sizeof (struct Lisp_Cons)),
	   make_int (gcst.total_conses),
	   make_int (gcst.total_free_conses)),
    list4 (Qsymbols, make_fixnum (sizeof (struct Lisp_Symbol)),
	   make_int (gcst.total_symbols),
	   make_int (gcst.total_free_symbols)),
    list4 (Qstrings, make_fixnum (sizeof (struct Lisp_String)),
	   make_int (gcst.total_strings),
	   make_int (gcst.total_free_strings)),
    list3 (Qstring_bytes, make_fixnum (1),
	   make_int (gcst.total_string_bytes)),
    list3 (Qvectors,
	   make_fixnum (header_size + sizeof (Lisp_Object)),
	   make_int (gcst.total_vectors)),
    list4 (Qvector_slots, make_fixnum (word_size),
	   make_int (gcst.total_vector_slots),
	   make_int (gcst.total_free_vector_slots)),
    list4 (Qfloats, make_fixnum (sizeof (struct Lisp_Float)),
	   make_int (gcst.total_floats),
	   make_int (gcst.total_free_floats)),
    list4 (Qintervals, make_fixnum (sizeof (struct interval)),
	   make_int (gcst.total_intervals),
	   make_int (gcst.total_free_intervals)),
    list3 (Qbuffers, make_fixnum (sizeof (struct buffer)),
	   make_int (gcst.total_buffers)),

#ifdef DOUG_LEA_MALLOC
    list4 (Qheap, make_fixnum (1024),
	   make_int ((mallinfo ().uordblks + 1023) >> 10),
	   make_int ((mallinfo ().fordblks + 1023) >> 10)),
#endif
  };
  return CALLMANY (Flist, total);
}