Document that the compiler may optimize away atoms

The following code could fail in the call to list_existing_atom/1:

  String = atom_to_list(some_atom),
  Atom = list_to_existing_atom(String)

because the compiler will rewrite the code to:

  String = "some_atom",
  Atom = list_to_existing_atom(String)

If some_atom is not used in another place, it will not exist.

The compiler could be updated to preserve the atom in this simple case,
but it would be hard to make sure that the compiler never loses atoms
that exist in the source text. It also difficult to imagine a
real world use case where this would be a problem. If an atom is
mentioned only in a way that the compiler can optimize away, is there
really any need to create the atom at all in list_to_existing_atom/1?

Therefore, it is better to place the responsibility that the atom exists
on the user of list_to_existing_atom/1. Update the documentation to
mention that the compiler may optimize away atoms.

https://bugs.erlang.org/browse/ERL-453

1 files changed, 19 insertions, 0 deletions

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 5afac46d21..2465f49581 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -432,6 +432,16 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code>
           <seealso marker="#binary_to_atom/2"><c>binary_to_atom/2</c></seealso>,
           but the atom must exist.</p>
         <p>Failure: <c>badarg</c> if the atom does not exist.</p>
+	<note>
+	  <p>Note that the compiler may optimize away atoms. For
+	  example, the compiler will rewrite
+	  <c>atom_to_list(some_atom)</c> to <c>"some_atom"</c>. If
+	  that expression is the only mention of the atom
+	  <c>some_atom</c> in the containing module, the atom will not
+	  be created when the module is loaded, and a subsequent call
+	  to <c>binary_to_existing_atom(&lt;&lt;"some_atom"&gt;&gt;, utf8)</c>
+	  will fail.</p>
+	</note>
       </desc>
     </func>
 
@@ -2478,6 +2488,15 @@ os_prompt%</pre>
           but only if there already exists such atom.</p>
         <p>Failure: <c>badarg</c> if there does not already exist an atom
           whose text representation is <c><anno>String</anno></c>.</p>
+	<note>
+	  <p>Note that the compiler may optimize away atoms. For
+	  example, the compiler will rewrite
+	  <c>atom_to_list(some_atom)</c> to <c>"some_atom"</c>. If
+	  that expression is the only mention of the atom
+	  <c>some_atom</c> in the containing module, the atom will not
+	  be created when the module is loaded, and a subsequent call
+	  to <c>list_to_existing_atom("some_atom")</c> will fail.</p>
+	</note>
       </desc>
     </func>