6.4.2 Atoms in C

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.