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(-)
(limited to 'erts/doc/src')
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