feat(): Allow creating database snapshots

Add a `create_snapshot` function, that creates a RocksDB database
snapshot from the given database handle and returns it.

There's a pretty fantastic amount of horribly unsafe Rust going on here
- primarily caused by the fact that the rust-rocksdb snapshot type is,
unlike Iterator or ColumnFamily or any of the other types that really
*should* be, parametrized by the lifetime of a borrowed reference to its
owner database. The abstraction provided by Rustler doesn't allow
non-static lifetime-parametrized struct types to be returned back to
Erlang as resources, for some technical type-mismatch reasons but also
practically because relying on the Erlang garbage collector to free our
stuff doesn't fit at *all* with rust's lifetime model.

The workaround here is to use `mem::transmute` (I told you it was
crazy...) to turn the snapshot reference from a `Snapshot<'a>` to a
`Snapshot<'static>`, and pass *that*, along with a held ARC reference to
the owning DB, to Erlang, and then when the Erlang GC decides it's time
to free the snapshot, go *back* to a first unbounded, then elided
lifetime to force the snapshot to be dropped.

I've done some cursory checking and regular operation (creating a
snapshot from a process then letting that process die) appears to not
leak the snapshots, but we should keep an eye on this to make sure we
don't have any leaks (or worse) in the future.

As a further note, the bit that parses out the argument for the NIFs
that now accept *either* a DB or a snapshot is a little mucky - that
should be revisited at a later date to see if we can clean it up a
little.

Author: glittershark

lib/rox.ex

@@ -4,7 +4,7 @@ defmodule Rox do
 
   """
 
-  alias __MODULE__.{DB,ColumnFamily,Native,Utils,Cursor}
+  alias __MODULE__.{DB, ColumnFamily, Native, Utils, Cursor, Snapshot}
 
   @type compaction_style :: :level | :universal | :fifo | :none
   @type compression_type :: :snappy | :zlib | :bzip2 | :lz4 | :lz4h | :none
@@ -139,6 +139,20 @@ defmodule Rox do
     end
   end
 
+  @doc """
+  Creates a point-in-time snapshot of the given `DB`.
+
+  Snapshots are read only views of the database at a point in time - no changes to the database will
+  be reflected in the view of the snapshot.
+
+  """
+  @spec create_snapshot(DB.t) :: {:ok, Snapshot.t} | {:error, any}
+  def create_snapshot(db) do
+    with {:ok, snapshot} <- Native.create_snapshot(db.resource) do
+      {:ok, Snapshot.wrap_resource(db, snapshot)}
+    end
+  end
+
   @doc """
   Create a column family in `db` with `name` and `opts`.
 
@@ -151,17 +165,23 @@ defmodule Rox do
   end
 
   @doc """
-  Gets an existing `ColumnFamily.t` from the database.
+  Gets an existing `ColumnFamily.t` from the database or snapshot.
 
-  The column family must have been created via `create_cf/2` or from `open/3` with the `auto_create_column_families` option.
+  The column family must have been created via `create_cf/2` or from `open/3` with the
+  `auto_create_column_families` option.
 
   """
-  @spec cf_handle(DB.t, ColumnFamily.name) :: {:ok, ColumnFamily.t} | {:error, any}
+  @spec cf_handle(DB.t | Snapshot.t, ColumnFamily.name) :: {:ok, ColumnFamily.t} | {:error, any}
   def cf_handle(%DB{resource: raw_db} = db, name) do
     with {:ok, result} <- Native.cf_handle(raw_db, name) do
       {:ok, ColumnFamily.wrap_resource(db, result, name)}
     end
   end
+  def cf_handle(%Snapshot{db: %DB{resource: raw_db}} = snapshot, name) do
+    with {:ok, result} <- Native.cf_handle(raw_db, name) do
+      {:ok, ColumnFamily.wrap_resource(snapshot, result, name)}
+    end
+  end
 
 
   @doc """
@@ -181,15 +201,19 @@ defmodule Rox do
 
 
   @doc """
-  Get a key/value pair in the databse or column family with the specified `key`.
+  Get a key/value pair in the given column family of the given snapshot or database with the
+  specified `key`.
 
   Optionally takes a list of `read_options`.
 
   For non-binary terms that were stored, they will be automatically decoded.
 
   """
-  @spec get(DB.t | ColumnFamily.t, key, read_options) :: {:ok, binary} | {:ok, value} | :not_found | {:error, any}
-  def get(db_or_cf, key, opts \\ [])
+  @spec get(DB.t | ColumnFamily.t | Snapshot.t, key, read_options)
+    :: {:ok, value}
+     | :not_found
+     | {:error, any}
+  def get(db_snapshot_or_cf, key, opts \\ [])
   def get(%DB{resource: db}, key, opts) when is_binary(key) and is_list(opts) do
     Native.get(db, key, to_map(opts))
     |> Utils.decode
@@ -198,6 +222,10 @@ defmodule Rox do
     Native.get_cf(db, cf, key, to_map(opts))
     |> Utils.decode
   end
+  def get(%Snapshot{resource: snapshot}, key, opts) when is_binary(key) and is_list(opts) do
+    Native.get(snapshot, key, to_map(opts))
+    |> Utils.decode
+  end
 
   @doc """
   Returns a `Cursor.t` which will iterate records from the provided database or
@@ -226,6 +254,11 @@ defmodule Rox do
       Cursor.wrap_resource(resource, mode)
     end
   end
+  def stream(%Snapshot{resource: snapshot}, mode) do
+    with {:ok, resource} <- Native.iterate(snapshot, mode) do
+      Cursor.wrap_resource(resource, mode)
+    end
+  end
 
 
   @doc """

lib/rox/column_family.ex

@@ -1,20 +1,22 @@
 defmodule Rox.ColumnFamily do
   @moduledoc """
   Struct module representing a handle for a column family within a database.
-  
+
   For working with the column family, see the functions in the top level
   `Rox` module.
-  
+
   Implements the `Collectable` and `Enumerable` protocols.
 
   """
 
-  alias Rox.DB
+  alias Rox.{DB, Snapshot}
 
   @typedoc "A reference to a RocksDB column family"
   @type t :: %__MODULE__{
-    db_resource: binary, cf_resource: binary,
-    db_reference: reference, name: binary,
+    db_resource: binary,
+    cf_resource: binary,
+    db_reference: reference,
+    name: binary,
   }
   defstruct [:db_reference, :db_resource, :cf_resource, :name]
 
@@ -23,8 +25,19 @@ defmodule Rox.ColumnFamily do
   @doc false
   def wrap_resource(%DB{resource: db_resource, reference: db_reference}, resource, name) do
     %__MODULE__{
-      db_resource: db_resource, db_reference: db_reference,
-      cf_resource: resource, name: name
+      db_resource: db_resource,
+      db_reference: db_reference,
+      cf_resource: resource,
+      name: name
+    }
+  end
+
+  def wrap_resource(%Snapshot{resource: db_resource, reference: db_reference}, resource, name) do
+    %__MODULE__{
+      db_resource: db_resource,
+      db_reference: db_reference,
+      cf_resource: resource,
+      name: name
     }
   end
 

lib/rox/db.ex

@@ -1,10 +1,10 @@
 defmodule Rox.DB do
   @moduledoc """
   Struct module representing a handle for a database.
-  
+
   For working with the database, see the functions in the top
   level `Rox` module.
-  
+
   Implements the `Collectable` and `Enumerable` protocols.
 
   """

lib/rox/native.ex

@@ -11,6 +11,14 @@ defmodule Rox.Native do
     end
   end
 
+  def create_snapshot(_) do
+    case :erlang.phash2(1, 1) do
+      0 -> raise "Nif not loaded"
+      1 -> {:ok, ""}
+      2 -> {:error, ""}
+    end
+  end
+
   def count(_) do
     case :erlang.phash2(1, 1) do
       0 -> raise "Nif not loaded"

lib/rox/snapshot.ex

@@ -0,0 +1,58 @@
+defmodule Rox.Snapshot do
+  @moduledoc """
+  Struct module representing a handle for a database snapshot.
+
+  Snapshots support all read operations that a `Rox.DB` supports, and implement `Enumerable`, but
+  not `Collectable`
+
+  """
+
+  alias Rox.DB
+
+
+
+  @typedoc "A reference to a RocksDB database snapshot"
+  @type t :: %__MODULE__{
+    resource: binary,
+    reference: reference,
+    db: DB.t
+  }
+
+  @enforce_keys [:resource, :reference, :db]
+  defstruct [
+    :resource,
+    :reference,
+    :db
+  ]
+
+  @doc false
+  def wrap_resource(%DB{} = db, resource) do
+    %__MODULE__{resource: resource, reference: make_ref(), db: db}
+  end
+
+  defimpl Inspect do
+    import Inspect.Algebra
+
+    def inspect(handle, opts) do
+      "#Rox.Snapshot<#{to_doc(handle.reference, opts)}>"
+    end
+  end
+
+  defimpl Enumerable do
+    def count(snapshot), do: {:ok, Rox.count(snapshot)}
+
+    def member?(snapshot, {key, val}) do
+      with {:ok, stored_val} <- Rox.get(snapshot, key) do
+        stored_val == {:ok, val}
+      else
+        _ -> {:ok, false}
+      end
+    end
+    def member?(_, _), do: {:ok, false}
+
+    def reduce(snapshot, cmd, fun) do
+      Rox.stream(snapshot)
+      |> Enumerable.reduce(cmd, fun)
+    end
+  end
+end