Each Prolog atom is represented internally by a unique integer, its
canonical representation, with the corresponding C type
SP_atom. This mapping between atoms and integers depends on
the execution history. Certain functions require this representation
as opposed to an SP_term_ref. It can be obtained by a special
argument type declaration when calling C from Prolog, by calling
SP_get_atom(), or by looking up an encoded string s in
the Prolog symbol table by calling SP_atom_from_string(s) which
returns the atom, or zero if the given string is malformed (is not a
valid sequence of UTF-8 encoded characters).
The encoded string containing the characters of a Prolog
atom a can be obtained by calling
SP_string_from_atom().
The length of the encoded string representing a Prolog atom
a can be obtained by calling
SP_atom_length().
Prolog atoms, and the space occupied by their print names, are
subject to garbage collection when the number of atoms has
reached a certain threshold, under the control of the agc_margin
Prolog flag, or when the atom garbage
collector is called explicitly. The atom garbage collector
will find all references to atoms from the Prolog specific memory
areas, including SP_term_refs and arguments passed from
Prolog to foreign language functions. However, atoms created by
SP_atom_from_string() and merely stored in a local variable are
endangered by garbage collection. The functions
SP_register_atom() and SP_unregister_atom()
make it
possible to protect an atom while it is in use. The operations
are implemented using reference counters to support multiple,
independent use of the same atom in different foreign
resources.