Add reference type and make_ref call (#657)

* Add reference type and `make_ref` call

* Add comments and in_env variant returning a ref again

* Add changelog entry

CHANGELOG.md

@@ -17,6 +17,7 @@ versions.
 - Floats can be decoded from integers (#641, fixes #603)
 - Resource types can implement and use dynamic calls on NIF version 2.16 (#635)
 - `Encoder` and `Decoder` implementations for `Box<T>` (#644)
+- `Reference` type and `env.make_ref()` function (#657)
 
 ### Fixed
 

rustler/src/lib.rs

@@ -39,7 +39,7 @@ mod term;
 pub use crate::term::Term;
 pub use crate::types::{
     Atom, Binary, Decoder, Encoder, ErlOption, ListIterator, LocalPid, MapIterator, NewBinary,
-    OwnedBinary,
+    OwnedBinary, Reference,
 };
 
 #[cfg(feature = "big_integer")]

rustler/src/types/mod.rs

@@ -2,8 +2,6 @@ use crate::{Env, Error, NifResult, Term};
 
 #[macro_use]
 pub mod atom;
-pub mod i128;
-pub mod path;
 pub use crate::types::atom::Atom;
 
 pub mod binary;
@@ -32,6 +30,13 @@ pub mod tuple;
 pub mod local_pid;
 pub use self::local_pid::LocalPid;
 
+#[doc(hidden)]
+pub mod reference;
+pub use self::reference::Reference;
+
+pub mod i128;
+pub mod path;
+
 pub mod truthy;
 
 pub mod elixir_struct;

rustler/src/types/reference.rs

@@ -0,0 +1,64 @@
+use std::ops::Deref;
+
+use crate::{Decoder, Encoder, Env, Error, NifResult, Term};
+
+use crate::sys::enif_make_ref;
+
+/// Wrapper for BEAM reference terms.
+#[derive(PartialEq, Eq, Clone, Copy)]
+pub struct Reference<'a>(Term<'a>);
+
+impl<'a> Reference<'a> {
+    /// Returns a representation of self in the given Env.
+    ///
+    /// If the term is already is in the provided env, it will be directly returned. Otherwise
+    /// the term will be copied over.
+    pub fn in_env<'b>(&self, env: Env<'b>) -> Reference<'b> {
+        Reference(self.0.in_env(env))
+    }
+}
+
+impl<'a> Deref for Reference<'a> {
+    type Target = Term<'a>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl<'a> From<Reference<'a>> for Term<'a> {
+    fn from(term: Reference<'a>) -> Self {
+        term.0
+    }
+}
+
+impl<'a> TryFrom<Term<'a>> for Reference<'a> {
+    type Error = Error;
+
+    fn try_from(term: Term<'a>) -> Result<Self, Self::Error> {
+        if term.is_ref() {
+            Ok(Reference(term))
+        } else {
+            Err(Error::BadArg)
+        }
+    }
+}
+
+impl<'a> Decoder<'a> for Reference<'a> {
+    fn decode(term: Term<'a>) -> NifResult<Self> {
+        term.try_into()
+    }
+}
+
+impl<'a> Encoder for Reference<'a> {
+    fn encode<'b>(&self, env: Env<'b>) -> Term<'b> {
+        self.0.encode(env)
+    }
+}
+
+impl<'a> Env<'a> {
+    /// Create a new reference in this environment
+    pub fn make_ref(self) -> Reference<'a> {
+        unsafe { Reference(Term::new(self, enif_make_ref(self.as_c_arg()))) }
+    }
+}

rustler_tests/lib/rustler_test.ex

@@ -103,6 +103,7 @@ defmodule RustlerTest do
   def whereis_pid(_), do: err()
   def is_process_alive(_), do: err()
   def sublists(_), do: err()
+  def make_refs(), do: err()
 
   def tuple_echo(_), do: err()
   def record_echo(_), do: err()

rustler_tests/native/rustler_test/src/test_env.rs

@@ -2,7 +2,7 @@ use rustler::env::{OwnedEnv, SavedTerm, SendError};
 use rustler::types::atom;
 use rustler::types::list::ListIterator;
 use rustler::types::LocalPid;
-use rustler::{Atom, Encoder, Env, NifResult, Term};
+use rustler::{Atom, Encoder, Env, NifResult, Reference, Term};
 use std::thread;
 
 // Send a message to several PIDs.
@@ -84,3 +84,10 @@ pub fn sublists<'a>(env: Env<'a>, list: Term<'a>) -> NifResult<Atom> {
 
     Ok(atom::ok())
 }
+
+#[rustler::nif]
+fn make_refs<'a>(env: Env<'a>) -> (bool, Reference<'a>, Reference<'a>) {
+    let first = env.make_ref();
+    let second = env.make_ref();
+    (first != second, first, second)
+}

rustler_tests/test/env_test.exs

@@ -104,4 +104,13 @@ defmodule RustlerTest.EnvTest do
     assert :error == RustlerTest.send(task.pid, :msg)
     assert :error == RustlerTest.send(task.pid, :msg)
   end
+
+  test "make_ref" do
+    {different, ref1, ref2} = RustlerTest.make_refs()
+
+    assert different
+    assert is_reference(ref1)
+    assert is_reference(ref2)
+    assert ref1 != ref2
+  end
 end