4.10.7.4 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, then 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 are not registered when they should be may be reclaimed on atom garbage collection. One normally does not 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, then 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, then 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.