9.4.2 Atoms and functors

The following functions provide for communication using atoms and functors.

atom_t PL_new_atom(const char *)

Return an atom handle for the given C-string. This function always succeeds. The returned handle is valid as long as the atom is referenced (see section 9.4.2.1).

const char* PL_atom_chars(atom_t atom)

Return a C-string for the text represented by the given atom. The returned text will not be changed by Prolog. It is not allowed to modify the contents, not even `temporary' as the string may reside in read-only memory. The returned string becomes invalid if the atom is garbage collected (see section 9.4.2.1). Foreign functions that require the text from an atom passed in a term_t normally use PL_get_atom_chars() or PL_get_atom_nchars().

functor_t PL_new_functor(atom_t name, int arity)

Returns a functor identifier, a handle for the name/arity pair. The returned handle is valid for the entire Prolog session.

atom_t PL_functor_name(functor_t f)

Return an atom representing the name of the given functor.

int PL_functor_arity(functor_t f)

Return the arity of the given functor.

9.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 8), 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.^{112Otherwise 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.