Details of Atom Registration

The functions that register and unregister atoms are in fact using reference counting to keep track of atoms that have been registered. As a result, it is safe to combine your code with libraries and code others have written. If the other code has been careful to register and unregister its atoms as appropriate, atoms will not be reclaimed until everyone has unregistered them.

Of course, it is possible when writing code that needs to register atoms that errors could occur. Atoms that are registered too many times simply will not be garbage collected until they are fully unregistered. However, atoms that aren't registered when they should be may be reclaimed on atom garbage collection. One normally doesn't need to think about the reference counting going on in QP_register_atom() and QP_unregister_atom(), but some understanding of its details could prove helpful when debugging.

To help you diagnose problems with registering and unregistering atoms, QP_register_atom() and QP_unregister_atom() both normally return the current reference count for the atom. If an error occurs, e.g. a nonexistent atom is registered or unregistered, QP_ERROR is returned.

An unregistered atom has a reference count of 0. Unregistering an atom that is unregistered is a no-op; in this case, QP_unregister_atom() returns 0. A permanent atom has a reference count of 128. In addition, if an atom is simultaneously registered 128 times, it becomes permanent. (An atom with 128 distinct references is an unlikely candidate for reclamation!) Registering or unregistering an atom that is permanent is also a no-op; QP_register_atom() and QP_unregister_atom() return 128.

Various safeguards enable you to detect when an atom may have been reclaimed prematurely. An atom that has been reclaimed and has not yet been reused appears as the special system atom '$anon', which cannot match any user atom (even a user-supplied '$anon', which will be a distinct atom). However, once an atom's space is reused, any references to the old atom will now see only the new atom. It is not possible to detect that an atom has been reused once the reuse occurs.