File 1076-erts-Clarify-caller_env-arguments-in-erl_nif_doc.patch of Package erlang
From 3c4ddfb9eb44921fd883d261207d47338420c810 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Wed, 4 Nov 2020 13:28:03 +0100
Subject: [PATCH] erts: Clarify 'caller_env' arguments in erl_nif_doc
---
erts/doc/src/erl_nif.xml | 58 +++++++++++++++++++++++++++-------------
1 file changed, 39 insertions(+), 19 deletions(-)
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index bcc7bc3e93..d2a1581e35 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -660,7 +660,7 @@ int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
it can only be passed on to API functions. Three types of environments
exist:</p>
<taglist>
- <tag>Process bound environment</tag>
+ <tag><marker id="proc_bound_env"/>Process bound environment</tag>
<item>
<p>Passed as the first argument to all NIFs. All function arguments
passed to a NIF belong to that environment. The return value from
@@ -671,7 +671,7 @@ int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
returns. It is thus useless and dangerous to store pointers to
process bound environments between NIF calls.</p>
</item>
- <tag>Callback environment</tag>
+ <tag><marker id="callback_env"/>Callback environment</tag>
<item>
<p>Passed as the first argument to all the non-NIF callback functions
(<seealso marker="#load"><c>load</c></seealso>,
@@ -685,7 +685,7 @@ int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
returned. Terms may be created in this environment but they will
only be accessible during the callback.</p>
</item>
- <tag>Process independent environment</tag>
+ <tag><marker id="proc_indep_env"/>Process independent environment</tag>
<item>
<p>Created by calling <seealso marker="#enif_alloc_env">
<c>enif_alloc_env</c></seealso>. This environment can be
@@ -1006,7 +1006,9 @@ typedef struct {
<name since="OTP R14B"><ret>ErlNifEnv *</ret><nametext>enif_alloc_env()</nametext></name>
<fsummary>Create a new environment.</fsummary>
<desc>
- <p>Allocates a new process independent environment. The environment can
+ <p>
+ Allocates a new <seealso marker="#proc_indep_env">process
+ independent environment</seealso>. The environment can
be used to hold terms that are not bound to any process. Such terms
can later be copied to a process environment with
<seealso marker="#enif_make_copy"><c>enif_make_copy</c></seealso> or
@@ -1253,8 +1255,12 @@ typedef struct {
<c>enif_monitor_process</c></seealso>. Argument <c>obj</c> is a pointer
to the resource holding the monitor and <c>*mon</c> identifies the
monitor.</p>
- <p>Argument <c>caller_env</c> is the environment of the calling process
- or callback. Must only be NULL if calling from a custom thread.</p>
+ <p>
+ Argument <c>caller_env</c> is the environment of the calling thread
+ (<seealso marker="#proc_bound_env">process bound</seealso> or
+ <seealso marker="#callback_env">callback</seealso> environment) or
+ <c>NULL</c> if calling from a custom thread not spawned by ERTS.
+ </p>
<p>Returns <c>0</c> if the monitor was successfully identified and removed.
Returns a non-zero value if the monitor could not be identified, which means
it was either</p>
@@ -2659,8 +2665,12 @@ enif_map_iterator_destroy(env, &iter);</code>
<seealso marker="#enif_compare_monitors"><c>enif_compare_monitors</c></seealso>.
A monitor is automatically removed when it triggers or when
the resource is deallocated.</p>
- <p>Argument <c>caller_env</c> is the environment of the calling process
- or callback. Must only be NULL if calling from a custom thread.</p>
+ <p>
+ Argument <c>caller_env</c> is the environment of the calling thread
+ (<seealso marker="#proc_bound_env">process bound</seealso> or
+ <seealso marker="#callback_env">callback</seealso> environment) or
+ <c>NULL</c> if calling from a custom thread not spawned by ERTS.
+ </p>
<p>Returns <c>0</c> on success, < 0 if no <c>down</c> callback is
provided, and > 0 if the process is no longer alive.</p>
<p>This function is only thread-safe when the emulator with SMP support
@@ -3263,7 +3273,7 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) {
<p>Initializes the <seealso marker="#ErlNifPid"><c>ErlNifPid</c></seealso>
variable at <c>*pid</c> to represent the calling process.</p>
<p>Returns <c>pid</c> if successful, or NULL if <c>caller_env</c> is not
- a <seealso marker="#ErlNifEnv">process bound environment</seealso>.</p>
+ a <seealso marker="#proc_bound_env">process bound environment</seealso>.</p>
</desc>
</func>
@@ -3275,8 +3285,12 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) {
<p>Sends a message to a process.</p>
<taglist>
<tag><c>caller_env</c></tag>
- <item>The environment of the calling process or callback. Must be <c>NULL</c>
- only if calling from a custom thread not spawned by ERTS.</item>
+ <item>
+ The environment of the calling thread
+ (<seealso marker="#proc_bound_env">process bound</seealso> or
+ <seealso marker="#callback_env">callback</seealso> environment) or
+ <c>NULL</c> if calling from a custom thread not spawned by ERTS.
+ </item>
<tag><c>*to_pid</c></tag>
<item>The pid of the receiving process. The pid is to refer to a
process on the local node.</item>
@@ -3604,15 +3618,18 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) {
<func>
<name since="OTP 20.0"><ret>int</ret>
- <nametext>enif_whereis_pid(ErlNifEnv *env,
+ <nametext>enif_whereis_pid(ErlNifEnv *caller_env,
ERL_NIF_TERM name, ErlNifPid *pid)</nametext></name>
<fsummary>Looks up a process by its registered name.</fsummary>
<desc>
<p>Looks up a process by its registered name.</p>
<taglist>
- <tag><c>env</c></tag>
- <item>The environment of the calling process. Must be <c>NULL</c>
- only if calling from a created thread.</item>
+ <tag><c>caller_env</c></tag>
+ <item>The environment of the calling thread
+ (<seealso marker="#proc_bound_env">process bound</seealso> or
+ <seealso marker="#callback_env">callback</seealso> environment) or
+ <c>NULL</c> if calling from a custom thread not spawned by
+ ERTS.</item>
<tag><c>name</c></tag>
<item>The name of a registered process, as an atom.</item>
<tag><c>*pid</c></tag>
@@ -3632,15 +3649,18 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) {
<func>
<name since="OTP 20.0"><ret>int</ret>
- <nametext>enif_whereis_port(ErlNifEnv *env,
+ <nametext>enif_whereis_port(ErlNifEnv *caller_env,
ERL_NIF_TERM name, ErlNifPort *port)</nametext></name>
<fsummary>Looks up a port by its registered name.</fsummary>
<desc>
<p>Looks up a port by its registered name.</p>
<taglist>
- <tag><c>env</c></tag>
- <item>The environment of the calling process. Must be <c>NULL</c>
- only if calling from a created thread.</item>
+ <tag><c>caller_env</c></tag>
+ <item>The environment of the calling thread
+ (<seealso marker="#proc_bound_env">process bound</seealso> or
+ <seealso marker="#callback_env">callback</seealso> environment) or
+ <c>NULL</c> if calling from a custom thread not spawned by
+ ERTS.</item>
<tag><c>name</c></tag>
<item>The name of a registered port, as an atom.</item>
<tag><c>*port</c></tag>
--
2.26.2
