12.4.2 Atoms and functors
All Application Manual Name SummaryHelp

  • Documentation
    • Reference manual
      • Foreign Language Interface
        • The Foreign Include File
          • Atoms and functors
            • PL_new_atom()
            • PL_new_atom_mbchars()
            • PL_atom_mbchars()
            • PL_atom_chars()
            • PL_atom_index()
            • PL_atom_from_index()
            • PL_new_functor()
            • PL_register_functor()
            • PL_unregister_functor()
            • PL_functor_name()
            • PL_functor_arity()
            • Atoms and atom garbage collection
              • PL_register_atom()
              • PL_unregister_atom()
    • Packages

12.4.2.1 Atoms and atom garbage collection

With the introduction of atom garbage collection in version 3.3.0, atoms no longer live as long as the process. Instead, their lifetime is guaranteed only as long as they are referenced. In the single-threaded version, atom garbage collections are only invoked at the call-port. In the multithreaded version (see chapter 10), they appear asynchronously, except for the invoking thread.

For dealing with atom garbage collection, two additional functions are provided:

void PL_register_atom(atom_t atom)
Increment the reference count of the atom by one. PL_new_atom() performs this automatically, returning an atom with a reference count of at least one.220Otherwise asynchronous atom garbage collection might destroy the atom before it is used.
void PL_unregister_atom(atom_t atom)
Decrement the reference count of the atom. If the reference count drops below zero, an assertion error is raised.

Please note that the following two calls are different with respect to atom garbage collection:

PL_unify_atom_chars(t, "text");
PL_unify_atom(t, PL_new_atom("text"));

The latter increments the reference count of the atom text, which effectively ensures the atom will never be collected. It is advised to use the *_chars() or *_nchars() functions whenever applicable.

Passing atoms to other threads An atom obtained from a term, e.g., using PL_get_atom(), may be a local atom of the calling thread. This is the case for a new atom created by PL_unify_chars() and friends, by read_term/2 or PL_chars_to_term(), and for blobs of a type with PL_BLOB_LOCAL (see section 12.4.10.1). Such an atom is reclaimed by the owning thread as soon as its own stacks no longer reference it, regardless of whether another thread uses the handle. Foreign code that hands an atom_t to another thread, e.g., by storing it in a C variable, a queue or a data structure that is shared between threads, must call PL_register_atom() before doing so. PL_register_atom() turns the atom into an ordinary atom, which the atom garbage collector protects as long as any thread references it. The other thread may therefore call PL_unregister_atom() as soon as the atom is reachable from one of its own term references, e.g., after PL_put_atom(). Strictly, this was always required, but before local atoms existed the omission was usually harmless because the global atom garbage collector scans the stacks of all threads. Without the registration, the other thread may use an atom that has been reclaimed, which leads to wrong results or a crash. Debug builds of SWI-Prolog report the use of another thread's local atom through the foreign language interface as an API error.