File 0676-Add-best-practice-for-atoms-in-NIFs.patch of Package erlang

From ab6bd0fc077142dfef51b5fc9863d97e3cbf17a1 Mon Sep 17 00:00:00 2001
From: Attila Rajmund Nohl <attila.rajmund.nohl@otpbank.hu>
Date: Thu, 16 Feb 2023 19:03:51 +0100
Subject: [PATCH] Add best practice for atoms in NIFs

Mention that atoms created in load are available in all environments.
The best practice is to pre-create all of them before usage, make sure
this best practice is included in the documentation.

Also fixed a "has" that should have been a "have".

Use full example for pre-created atoms and use _atom suffix for variable
names in the example (atom_ prefix would make variable name expansion in
IDEs less than useful).

Co-authored-by: Sverker Eriksson <sverker@erlang.org>
---
 erts/doc/src/erl_nif.xml | 36 +++++++++++++++++++++++++++++++-----
 1 file changed, 31 insertions(+), 5 deletions(-)

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index c8d4f32300..1e4cd2aa7b 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -171,11 +171,37 @@ $> erl
           to query terms, like <c>enif_is_atom</c>, <c>enif_is_identical</c>,
           and <c>enif_compare</c>.</p>
         <p>All terms of type <c>ERL_NIF_TERM</c> belong to an environment of
-          type <seecref marker="#ErlNifEnv"><c>ErlNifEnv</c></seecref>. The
-          lifetime of a term is controlled by the lifetime of its environment
-          object. All API functions that read or write terms has the
-          environment that the term belongs to as the first function
-          argument.</p>
+          type <seecref marker="#ErlNifEnv"><c>ErlNifEnv</c></seecref>,
+          except atoms created during loading (by callbacks
+          <seecref marker="#load"><c>load</c></seecref> or
+          <seecref marker="#upgrade"><c>upgrade</c></seecref>). The lifetime of
+          a term is controlled by the lifetime of its environment object. All
+          API functions that read or write terms have the environment that the
+          term belongs to as the first function argument. However, the atoms
+          created during loading can be referred as a term in any <c>ErlNifEnv</c>.
+          That is, the best practice it to create all your atoms during
+          loading and store them in static/global variables, for example:</p>
+          <code type="none"><![CDATA[
+#include <erl_nif.h>
+
+ERL_NIF_TERM world_atom;
+
+static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)
+{
+    world_atom = enif_make_atom(env, "world");
+    return 0;
+}
+
+static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
+{
+    ERL_NIF_TERM hello_string = enif_make_string(env, "Hello", ERL_NIF_LATIN1);
+    return enif_make_tuple2(env, hello_string, world_atom);
+}
+
+static ErlNifFunc nif_funcs[] = { { "hello", 0, hello } };
+
+ERL_NIF_INIT(niftest, nif_funcs, load, NULL, NULL, NULL)
+]]></code>
       </item>
       <tag>Binaries</tag>
       <item>
-- 
2.35.3