Add fine::make_new_binary to streamline returning large buffers (#6)

Author: jonatanklosko

README.md

@@ -181,19 +181,15 @@ Fine provides implementations for the following types:
 > circumvented.
 >
 > Similarly, when returning large binaries, prefer creating the term
-> with `enif_make_new_binary` and returning `fine::Term`, instead of
+> with `fine::make_new_binary` and returning `fine::Term`, instead of
 > allocating an intermediary `std::string`, as shown below.
 >
 > ```c++
 > fine::Term read_data(ErlNifEnv *env) {
 >   const char *buffer = ...;
 >   uint64_t size = ...;
 >
->   ERL_NIF_TERM binary_term;
->   auto binary_data = enif_make_new_binary(env, size, &binary_term);
->   memcpy(binary_data, buffer, size);
->
->   return binary_term;
+>   return fine::make_new_binary(env, buffer, size);
 > }
 > ```
 >

include/fine.hpp

@@ -300,6 +300,22 @@ Term make_resource_binary(ErlNifEnv *env, ResourcePtr<T> resource,
       env, reinterpret_cast<void *>(resource.get()), data, size);
 }
 
+// Creates a binary term copying data from the given buffer.
+//
+// This is useful when returning large binary from a NIF and the source
+// buffer does not outlive the return.
+inline fine::Term make_new_binary(ErlNifEnv *env, const char *data,
+                                  size_t size) {
+  ERL_NIF_TERM term;
+  auto term_data = enif_make_new_binary(env, size, &term);
+  if (term_data == nullptr) {
+    throw std::runtime_error(
+        "make_new_binary failed, failed to allocate new binary");
+  }
+  memcpy(term_data, data, size);
+  return term;
+}
+
 // Decodes the given Erlang term as a value of the specified type.
 //
 // The given type must have a specialized Decoder<T> implementation.

test/c_src/finest.cpp

@@ -186,6 +186,13 @@ ErlNifPid resource_get(ErlNifEnv *, fine::ResourcePtr<TestResource> resource) {
 }
 FINE_NIF(resource_get, 0);
 
+fine::Term make_new_binary(ErlNifEnv *env) {
+  const char *buffer = "hello world";
+  size_t size = 11;
+  return fine::make_new_binary(env, buffer, size);
+}
+FINE_NIF(make_new_binary, 0);
+
 int64_t throw_runtime_error(ErlNifEnv *) {
   throw std::runtime_error("runtime error reason");
 }

test/lib/finest/nif.ex

@@ -41,6 +41,8 @@ defmodule Finest.NIF do
   def resource_create(_pid), do: err!()
   def resource_get(_resource), do: err!()
 
+  def make_new_binary(), do: err!()
+
   def throw_runtime_error(), do: err!()
   def throw_invalid_argument(), do: err!()
   def throw_other_exception(), do: err!()

test/test/finest_test.exs

@@ -234,6 +234,12 @@ defmodule FinestTest do
     end
   end
 
+  describe "make_new_binary" do
+    test "creates a binary term copying the original buffer" do
+      assert NIF.make_new_binary() == "hello world"
+    end
+  end
+
   describe "exceptions" do
     test "standard exceptions" do
       assert_raise RuntimeError, "runtime error reason", fn ->