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 SP_register_atom()
and
SP_unregister_atom()
, but some understanding of its details could
prove helpful when debugging.
To help you diagnose problems with registering
and unregistering atoms, SP_register_atom()
and
SP_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, SP_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, SP_unregister_atom()
returns 0. A permanent atom has a
reference count of 256. In addition, if an atom is simultaneously
registered 256 times, it becomes permanent. (An atom with 256 distinct
references is an unlikely candidate for reclamation!)
Registering or unregistering an atom that
is permanent is also a no-op; SP_register_atom()
and
SP_unregister_atom()
return 256.