erts: Add enif_term_type

This helps avoid long sequences of enif_is_xxx in code that
serializes terms (such as JSON encoders) by letting the user
switch on the type.

6 files changed, 181 insertions, 4 deletions

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index cc7452bab5..cf1994887a 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -3369,6 +3369,48 @@ if (retval & ERL_NIF_SELECT_STOP_CALLED) {
     </func>
 
     <func>
+      <name since="OTP @OTP-15640@"><ret>ErlNifTermType</ret>
+        <nametext>enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)</nametext>
+      </name>
+      <fsummary>Determine the type of a term.</fsummary>
+      <desc>
+        <p>Determines the type of the given term. The term must be an ordinary
+          Erlang term and not one of the special terms returned by
+          <seealso marker="#enif_raise_exception">
+          <c>enif_raise_exception</c></seealso>,
+          <seealso marker="#enif_schedule_nif">
+          <c>enif_schedule_nif</c></seealso>, or similar.</p>
+        <p>The following types are defined at the moment:</p>
+        <taglist>
+          <tag><c>ERL_NIF_TERM_TYPE_ATOM</c></tag>
+          <item/>
+          <tag><c>ERL_NIF_TERM_TYPE_BITSTRING</c></tag>
+          <item><p>A bitstring or binary</p></item>
+          <tag><c>ERL_NIF_TERM_TYPE_FLOAT</c></tag>
+          <item/>
+          <tag><c>ERL_NIF_TERM_TYPE_FUN</c></tag>
+          <item/>
+          <tag><c>ERL_NIF_TERM_TYPE_INTEGER</c></tag>
+          <item/>
+          <tag><c>ERL_NIF_TERM_TYPE_LIST</c></tag>
+          <item><p>A list, empty or not</p></item>
+          <tag><c>ERL_NIF_TERM_TYPE_MAP</c></tag>
+          <item/>
+          <tag><c>ERL_NIF_TERM_TYPE_PID</c></tag>
+          <item/>
+          <tag><c>ERL_NIF_TERM_TYPE_PORT</c></tag>
+          <item/>
+          <tag><c>ERL_NIF_TERM_TYPE_REFERENCE</c></tag>
+          <item/>
+          <tag><c>ERL_NIF_TERM_TYPE_TUPLE</c></tag>
+          <item/>
+        </taglist>
+        <p>Note that new types may be added in the future, so the caller must
+          be prepared to handle unknown types.</p>
+      </desc>
+    </func>
+
+    <func>
       <name since="OTP R13B04"><ret>int</ret>
         <nametext>enif_thread_create(char *name,ErlNifTid
         *tid,void * (*func)(void *),void *args,ErlNifThreadOpts
diff --git a/erts/emulator/beam/erl_nif.c b/erts/emulator/beam/erl_nif.c
index 349d9bf13a..dd9210a888 100644
--- a/erts/emulator/beam/erl_nif.c
+++ b/erts/emulator/beam/erl_nif.c
@@ -1158,6 +1158,47 @@ int enif_is_number(ErlNifEnv* env, ERL_NIF_TERM term)
     return is_number(term);
 }
 
+ErlNifTermType enif_term_type(ErlNifEnv* env, ERL_NIF_TERM term) {
+    (void)env;
+
+    switch (tag_val_def(term)) {
+    case ATOM_DEF:
+        return ERL_NIF_TERM_TYPE_ATOM;
+    case BINARY_DEF:
+        return ERL_NIF_TERM_TYPE_BITSTRING;
+    case FLOAT_DEF:
+        return ERL_NIF_TERM_TYPE_FLOAT;
+    case EXPORT_DEF:
+    case FUN_DEF:
+        return ERL_NIF_TERM_TYPE_FUN;
+    case BIG_DEF:
+    case SMALL_DEF:
+        return ERL_NIF_TERM_TYPE_INTEGER;
+    case LIST_DEF:
+    case NIL_DEF:
+        return ERL_NIF_TERM_TYPE_LIST;
+    case MAP_DEF:
+        return ERL_NIF_TERM_TYPE_MAP;
+    case EXTERNAL_PID_DEF:
+    case PID_DEF:
+        return ERL_NIF_TERM_TYPE_PID;
+    case EXTERNAL_PORT_DEF:
+    case PORT_DEF:
+        return ERL_NIF_TERM_TYPE_PORT;
+    case EXTERNAL_REF_DEF:
+    case REF_DEF:
+        return ERL_NIF_TERM_TYPE_REFERENCE;
+    case TUPLE_DEF:
+        return ERL_NIF_TERM_TYPE_TUPLE;
+    default:
+        /* tag_val_def() aborts on its own when passed complete garbage, but
+         * it's possible that the user has given us garbage that just happens
+         * to match something that tag_val_def() accepts but we don't, like
+         * binary match contexts. */
+        ERTS_INTERNAL_ERROR("Invalid term passed to enif_term_type");
+    }
+}
+
 static void aligned_binary_dtor(struct enif_tmp_obj_t* obj)
 {
     erts_free_aligned_binary_bytes_extra((byte*)obj, obj->allocator);
diff --git a/erts/emulator/beam/erl_nif.h b/erts/emulator/beam/erl_nif.h
index 3fd1a8fd4c..a599511c78 100644
--- a/erts/emulator/beam/erl_nif.h
+++ b/erts/emulator/beam/erl_nif.h
@@ -55,6 +55,7 @@
 ** 2.14: 21.0 add enif_ioq_peek_head, enif_(mutex|cond|rwlock|thread)_name
 **                enif_vfprintf, enif_vsnprintf, enif_make_map_from_arrays
 ** 2.15: 22.0 ERL_NIF_SELECT_CANCEL, enif_select_(read|write)
+**            enif_term_type
 */
 #define ERL_NIF_MAJOR_VERSION 2
 #define ERL_NIF_MINOR_VERSION 15
@@ -63,7 +64,7 @@
  * with ticket syntax like "erts-@OTP-12345@", or a temporary placeholder
  * between two @ like "erts-@MyName@", if you don't know what a ticket is.
  */
-#define ERL_NIF_MIN_ERTS_VERSION "erts-@OTP-15095@ (OTP-22)"
+#define ERL_NIF_MIN_ERTS_VERSION "erts-@OTP-15095 OTP-15640@ (OTP-22)"
 
 /*
  * The emulator will refuse to load a nif-lib with a major version
@@ -282,6 +283,26 @@ typedef enum {
     ERL_NIF_IOQ_NORMAL = 1
 } ErlNifIOQueueOpts;
 
+typedef enum {
+    ERL_NIF_TERM_TYPE_ATOM = 1,
+    ERL_NIF_TERM_TYPE_BITSTRING = 2,
+    ERL_NIF_TERM_TYPE_FLOAT = 3,
+    ERL_NIF_TERM_TYPE_FUN = 4,
+    ERL_NIF_TERM_TYPE_INTEGER = 5,
+    ERL_NIF_TERM_TYPE_LIST = 6,
+    ERL_NIF_TERM_TYPE_MAP = 7,
+    ERL_NIF_TERM_TYPE_PID = 8,
+    ERL_NIF_TERM_TYPE_PORT = 9,
+    ERL_NIF_TERM_TYPE_REFERENCE = 10,
+    ERL_NIF_TERM_TYPE_TUPLE = 11,
+
+    /* This is a dummy value intended to coax the compiler into warning about
+     * unhandled values in a switch even if all the above values have been
+     * handled. We can add new entries at any time so the user must always
+     * have a default case. */
+    ERL_NIF_TERM_TYPE__MISSING_DEFAULT_CASE__READ_THE_MANUAL = -1
+} ErlNifTermType;
+
 /*
  * Return values from enif_thread_type(). Negative values
  * reserved for specific types of non-scheduler threads.
diff --git a/erts/emulator/beam/erl_nif_api_funcs.h b/erts/emulator/beam/erl_nif_api_funcs.h
index 8ab454c8dd..d57f6ec97c 100644
--- a/erts/emulator/beam/erl_nif_api_funcs.h
+++ b/erts/emulator/beam/erl_nif_api_funcs.h
@@ -215,6 +215,8 @@ ERL_NIF_API_FUNC_DECL(ERL_NIF_TERM,enif_make_monitor_term,(ErlNifEnv* env, const
 ERL_NIF_API_FUNC_DECL(void,enif_set_pid_undefined,(ErlNifPid* pid));
 ERL_NIF_API_FUNC_DECL(int,enif_is_pid_undefined,(const ErlNifPid* pid));
 
+ERL_NIF_API_FUNC_DECL(ErlNifTermType,enif_term_type,(ErlNifEnv* env, ERL_NIF_TERM term));
+
 /*
 ** ADD NEW ENTRIES HERE (before this comment) !!!
 */
@@ -401,6 +403,7 @@ ERL_NIF_API_FUNC_DECL(int,enif_is_pid_undefined,(const ErlNifPid* pid));
 #  define enif_make_monitor_term ERL_NIF_API_FUNC_MACRO(enif_make_monitor_term)
 #  define enif_set_pid_undefined ERL_NIF_API_FUNC_MACRO(enif_set_pid_undefined)
 #  define enif_is_pid_undefined ERL_NIF_API_FUNC_MACRO(enif_is_pid_undefined)
+#  define enif_term_type ERL_NIF_API_FUNC_MACRO(enif_term_type)
 
 /*
 ** ADD NEW ENTRIES HERE (before this comment)
diff --git a/erts/emulator/test/nif_SUITE.erl b/erts/emulator/test/nif_SUITE.erl
index 4a0ad9c1d5..2309f844b9 100644
--- a/erts/emulator/test/nif_SUITE.erl
+++ b/erts/emulator/test/nif_SUITE.erl
@@ -65,7 +65,8 @@
          nif_whereis/1, nif_whereis_parallel/1,
          nif_whereis_threaded/1, nif_whereis_proxy/1,
          nif_ioq/1,
-         pid/1
+         pid/1,
+         nif_term_type/1
 	]).
 
 -export([many_args_100/100]).
@@ -105,7 +106,8 @@ all() ->
      nif_phash2,
      nif_whereis, nif_whereis_parallel, nif_whereis_threaded,
      nif_ioq,
-     pid].
+     pid,
+     nif_term_type].
 
 groups() ->
     [{G, [], api_repeaters()} || G <- api_groups()]
@@ -3392,6 +3394,41 @@ pid(Config) ->
     {false, _} = get_local_pid_nif(undefined),
     ok.
 
+nif_term_type(Config) ->
+    ensure_lib_loaded(Config),
+
+    atom = term_type_nif(atom),
+
+    bitstring = term_type_nif(<<1:1>>),
+    bitstring = term_type_nif(<<1:8>>),
+
+    float = term_type_nif(0.0),
+
+    'fun' = term_type_nif(fun external:function/1),
+    'fun' = term_type_nif(fun(A) -> A end),
+    'fun' = term_type_nif(fun id/1),
+
+    integer = term_type_nif(1 bsl 1024),        %Bignum.
+    integer = term_type_nif(1),
+
+    list = term_type_nif([list]),
+    list = term_type_nif([]),
+
+    LargeMap = maps:from_list([{N, N} || N <- lists:seq(1, 256)]),
+    map = term_type_nif(LargeMap),
+    map = term_type_nif(#{ small => map }),
+
+    pid = term_type_nif(self()),
+
+    Port = open_port({spawn,echo_drv},[eof]),
+    port = term_type_nif(Port),
+    port_close(Port),
+
+    reference = term_type_nif(make_ref()),
+
+    tuple = term_type_nif({}),
+
+    ok.
 
 id(I) -> I.
 
@@ -3507,5 +3544,7 @@ set_pid_undefined_nif() -> ?nif_stub.
 is_pid_undefined_nif(_) -> ?nif_stub.
 compare_pids_nif(_, _) -> ?nif_stub.
 
+term_type_nif(_) -> ?nif_stub.
+
 nif_stub_error(Line) ->
     exit({nif_not_loaded,module,?MODULE,line,Line}).
diff --git a/erts/emulator/test/nif_SUITE_data/nif_SUITE.c b/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
index 0d5d900d31..1906384af4 100644
--- a/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
+++ b/erts/emulator/test/nif_SUITE_data/nif_SUITE.c
@@ -3583,6 +3583,36 @@ static ERL_NIF_TERM compare_pids_nif(ErlNifEnv* env, int argc, const ERL_NIF_TER
     return enif_make_int(env, enif_compare_pids(&a, &b));
 }
 
+static ERL_NIF_TERM term_type_nif(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
+{
+    switch (enif_term_type(env, argv[0])) {
+    case ERL_NIF_TERM_TYPE_ATOM:
+        return enif_make_atom(env, "atom");
+    case ERL_NIF_TERM_TYPE_BITSTRING:
+        return enif_make_atom(env, "bitstring");
+    case ERL_NIF_TERM_TYPE_FLOAT:
+        return enif_make_atom(env, "float");
+    case ERL_NIF_TERM_TYPE_FUN:
+        return enif_make_atom(env, "fun");
+    case ERL_NIF_TERM_TYPE_INTEGER:
+        return enif_make_atom(env, "integer");
+    case ERL_NIF_TERM_TYPE_LIST:
+        return enif_make_atom(env, "list");
+    case ERL_NIF_TERM_TYPE_MAP:
+        return enif_make_atom(env, "map");
+    case ERL_NIF_TERM_TYPE_PID:
+        return enif_make_atom(env, "pid");
+    case ERL_NIF_TERM_TYPE_PORT:
+        return enif_make_atom(env, "port");
+    case ERL_NIF_TERM_TYPE_REFERENCE:
+        return enif_make_atom(env, "reference");
+    case ERL_NIF_TERM_TYPE_TUPLE:
+        return enif_make_atom(env, "tuple");
+    default:
+        return enif_make_badarg(env);
+    }
+}
+
 static ErlNifFunc nif_funcs[] =
 {
     {"lib_version", 0, lib_version},
@@ -3690,7 +3720,8 @@ static ErlNifFunc nif_funcs[] =
     {"make_pid_nif", 1, make_pid_nif},
     {"set_pid_undefined_nif", 0, set_pid_undefined_nif},
     {"is_pid_undefined_nif", 1, is_pid_undefined_nif},
-    {"compare_pids_nif", 2, compare_pids_nif}
+    {"compare_pids_nif", 2, compare_pids_nif},
+    {"term_type_nif", 1, term_type_nif}
 };
 
 ERL_NIF_INIT(nif_SUITE,nif_funcs,load,NULL,upgrade,unload)