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.