From 84e13543aaed5ddb0b5f34f9d88d579f829358ee Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Tue, 5 Sep 2017 14:43:54 +0200 Subject: erts: Update docs for enif_make_resource to include new defined properties in OTP-20 regarding comparison and serialization. --- erts/doc/src/erl_nif.xml | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 5a69bed34c..50e07f019e 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -206,7 +206,7 @@ ok enif_make_resource. The term returned by enif_make_resource is opaque in nature. - It can be stored and passed between processes on the same node, but + It can be stored and passed between processes, but the only real end usage is to pass it back as an argument to a NIF. The NIF can then call enif_get_resource and get back a pointer to the @@ -1952,10 +1952,33 @@ typedef enum { details, see the example of creating and returning a resource object in the User's Guide.

-

Notice that the only defined behavior of using a resource term in - an Erlang program is to store it and send it between processes on the - same node. Other operations, such as matching or - term_to_binary, have unpredictable (but harmless) results.

+ +

Since ERTS 9.0 (OTP-20.0), resource terms have a defined behavior + when compared and serialized through term_to_binary or passed + between nodes.

+ + +

Two resource terms will compare equal iff they + would yield the same resource object pointer when passed to + enif_get_resource.

+
+ +

A resoure term can be serialized with term_to_binary and later + be fully recreated if the resource object is still alive when + binary_to_term is called. A stale resource term will be + returned from binary_to_term if the resource object has + been deallocated. enif_get_resource + will return false for stale resource terms.

+

The same principles of serialization apply when passing + resource terms in messages to remote nodes and back again. A + resource term will act stale on all nodes except the node where + its resource object is still alive in memory.

+
+
+

Before ERTS 9.0 (OTP-20.0), all resource terms did + compare equal to each other and to empty binaries (<<>>). + If serialized, they would be recreated as plain empty binaries.

+
-- cgit v1.2.3