diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..46ca6ec --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +/_build +/_native +/bench +/cover +/deps +/doc +erl_crash.dump +*.ez diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..1a03060 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,9 @@ +language: elixir +elixir: + - 1.2.1 + - 1.1.1 +otp_release: + - 18.2 + - 18.1 +script: + - mix test --trace diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..45546bf --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2016 Isaac Whitfield + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ef52b0b --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# Stash +[![Build Status](https://travis-ci.org/zackehh/stash.svg?branch=master)](https://travis-ci.org/zackehh/stash) + +A very small wrapping implementation around ETS, providing a more user-friendly key/value interface for new users. Takes care of setting up a new ETS table as needed with a default set of options to avoid having to deal with configurations. This library is meant as a fast way to use ETS without anything flashy, so don't expect many features over what's already here (which isn't much, intentionally). + +## Installation + +This package can be installed via Hex, just add stash to your list of dependencies in `mix.exs`: + +```elixir +def deps do + [{:stash, "~> 1.0.0"}] +end +``` + +## Quick Usage + +It's straightforward to get going: + +```elixir +iex(1)> Stash.set(:my_cache, "my_key", "my_value") +true +iex(2)> Stash.get(:my_cache, "my_key") +"my_value" +iex(3)> Stash.delete(:my_cache, "my_key") +true +iex(4)> Stash.get(:my_cache, "my_key") +nil +``` + +For further examples, as well as the rest of the API, please see the [documentation](http://hexdocs.pm/stash/Stash.html). + +## A Note On Table Configuration + +By default, Stash will create a table with the following configuration: + +```elixir +[ + { :read_concurrency, true }, + { :write_concurrency, true }, + :public, + :set, + :named_table +] +``` + +If you **don't** wish to have this configuration, please create your ETS table in advance of using Stash to access it. However keep in mind that Stash is written with the assumption that you're using either a `set` or `ordered_set`, so it's best to stick to those. The defaults should be ok in most cases, so unless you're already thinking that you want a setting changed above, you're probably fine. + +## Persistence + +A neat little feature is the ability to persist a cache to disk, by calling `Stash.persist/2`. This will move your ETS tables into DTS, allowing you to reload after your process has died. This is not kept in sync due to the overhead involved, so it might be an idea to schedule persistance if you rely on it. To reload, call `Stash.load/2`. + +```elixir +iex(1)> Stash.set(:my_cache, "key", "value") +true +iex(2)> Stash.size(:my_cache) +1 +iex(3)> Stash.persist(:my_cache, "/tmp/my_persistence_file") +:ok +iex(4)> Stash.delete(:my_cache, "key") +true +iex(5)> Stash.size(:my_cache) +0 +iex(6)> Stash.load(:my_cache, "/tmp/my_persistence_file") +:ok +iex(7)> Stash.size(:my_cache) +1 +iex(1)> Stash.get(:my_cache, "key") +"value" +``` + +## Issues/Contributions + +If you spot any issues with the implementation, please file an [issue](http://github.com/zackehh/stash/issues) or even a PR. Like I mentioned above, not too many features will make it into this lib as it's a small wrapping library, nothing special. + +Make sure to test your changes though! + +```bash +$ mix test --trace +``` diff --git a/lib/stash.ex b/lib/stash.ex new file mode 100644 index 0000000..2e9d5a9 --- /dev/null +++ b/lib/stash.ex @@ -0,0 +1,265 @@ +defmodule Stash do + use Stash.Macros + + @doc """ + Retrieves a value from the cache. + + ## Examples + + iex> Stash.set(:my_cache, "key", "value") + iex> Stash.get(:my_cache, "key") + "value" + + iex> Stash.get(:my_cache, "missing_key") + nil + + """ + @spec get(atom, any) :: any + deft get(cache, key) do + case :ets.lookup(cache, key) do + [{ ^key, value }] -> value + _unrecognised_val -> nil + end + end + + @doc """ + Retrieves all keys from the cache, and returns them as an (unordered) list. + + ## Examples + + iex> Stash.set(:my_cache, "key1", "value1") + iex> Stash.set(:my_cache, "key2", "value2") + iex> Stash.set(:my_cache, "key3", "value3") + iex> Stash.keys(:my_cache) + [ "key2", "key1", "key3" ] + + iex> Stash.keys(:empty_cache) + [] + + """ + @spec keys(atom) :: [any] + deft keys(cache) do + :ets.foldr(fn({ key, _value }, keys) -> + [key|keys] + end, [], cache) + end + + @doc """ + Sets a value in the cache against a given key. + + ## Examples + + iex> Stash.set(:my_cache, "key", "value") + true + + """ + @spec set(atom, any, any) :: true + deft set(cache, key, value) do + :ets.insert(cache, { key, value }) + end + + @doc """ + Increments a key directly in the cache by `count`. If the key does not exist + it is set to `initial` before **then** being incremented. + + ## Examples + + iex> Stash.set(:my_cache, "key", 1) + iex> Stash.inc(:my_cache, "key") + 2 + + iex> Stash.inc(:my_cache, "key", 2) + 4 + + iex> Stash.inc(:my_cache, "missing_key", 1) + 1 + + iex> Stash.inc(:my_cache, "a_missing_key", 1, 5) + 6 + + """ + @spec inc(atom, any, number, number) :: number + def inc(cache, key, count \\ 1, initial \\ 0) + deft inc(cache, key, count, initial) + when is_number(count) and is_number(initial) do + :ets.update_counter( + cache, key, { 2, count }, { key, initial } + ) + end + + @doc """ + Removes a value from the cache. + + ## Examples + + iex> Stash.set(:my_cache, "key", "value") + iex> Stash.get(:my_cache, "key") + "value" + + iex> Stash.delete(:my_cache, "key") + true + + iex> Stash.get(:my_cache, "key") + nil + + """ + @spec delete(atom, any) :: true + deft delete(cache, key), do: :ets.delete(cache, key) + + @doc """ + Removes a key from the cache, whilst also returning the last known value. + + ## Examples + + iex> Stash.set(:my_cache, "key", "value") + iex> Stash.remove(:my_cache, "key") + "value" + + iex> Stash.get(:my_cache, "key") + nil + + iex> Stash.remove(:my_cache, "missing_key") + nil + + """ + @spec remove(atom, any) :: any + deft remove(cache, key) do + case :ets.take(cache, key) do + [{ ^key, value }] -> value + _unrecognised_val -> nil + end + end + + @doc """ + Removes all items in the cache. + + ## Examples + + iex> Stash.set(:my_cache, "key1", "value1") + iex> Stash.set(:my_cache, "key2", "value2") + iex> Stash.set(:my_cache, "key3", "value3") + iex> Stash.size(:my_cache) + 3 + + iex> Stash.clear(:my_cache) + true + + iex> Stash.size(:my_cache) + 0 + + """ + @spec clear(atom) :: true + deft clear(cache), do: :ets.delete_all_objects(cache) + + @doc """ + Returns information about the backing ETS table. + + ## Examples + + iex> Stash.info(:my_cache) + [read_concurrency: true, write_concurrency: true, compressed: false, + memory: 1361, owner: #PID<0.126.0>, heir: :none, name: :my_cache, size: 2, + node: :nonode@nohost, named_table: true, type: :set, keypos: 1, + protection: :public] + + """ + @spec info(atom) :: [ { atom, any } ] + deft info(cache), do: :ets.info(cache) + + @doc """ + Checks whether the cache is empty. + + ## Examples + + iex> Stash.set(:my_cache, "key1", "value1") + iex> Stash.set(:my_cache, "key2", "value2") + iex> Stash.set(:my_cache, "key3", "value3") + iex> Stash.empty?(:my_cache) + false + + iex> Stash.clear(:my_cache) + true + + iex> Stash.empty?(:my_cache) + true + + """ + @spec empty?(atom) :: true | false + deft empty?(cache), do: size(cache) == 0 + + @doc """ + Determines whether a given key exists inside the cache. + + ## Examples + + iex> Stash.set(:my_cache, "key", "value") + iex> Stash.exists?(:my_cache, "key") + true + + iex> Stash.exists?(:my_cache, "missing_key") + false + + """ + @spec exists?(atom, any) :: true | false + deft exists?(cache, key), do: :ets.member(cache, key) + + @doc """ + Determines the size of the cache. + + ## Examples + + iex> Stash.set(:my_cache, "key1", "value1") + iex> Stash.set(:my_cache, "key2", "value2") + iex> Stash.set(:my_cache, "key3", "value3") + iex> Stash.size(:my_cache) + 3 + + """ + @spec size(atom) :: number + deft size(cache), do: info(cache)[:size] + + @doc """ + Loads a cache into memory from DTS storage. + + ## Examples + + iex> Stash.load(:my_cache, "/tmp/temporary.dat") + :ok + + """ + @spec load(atom, binary) :: atom + deft load(cache, path) when is_binary(path) do + case :dets.open_file(path, gen_dts_args(cache)) do + { :ok, ^path } -> + :dets.to_ets(path, cache) + :dets.close(path) + error_state -> error_state + end + end + + @doc """ + Persists a cache onto disk to allow reload after the process dies. + + ## Examples + + iex> Stash.persist(:my_cache, "/tmp/temporary.dat") + :ok + + """ + @spec persist(atom, binary) :: atom + deft persist(cache, path) when is_binary(path) do + case :dets.open_file(path, gen_dts_args(cache)) do + { :ok, ^path } -> + :dets.from_ets(path, cache) + :dets.close(path) + error_state -> error_state + end + end + + # Generates the arguments for a DTS table based on a passed in ETS table + defp gen_dts_args(cache) do + info = info(cache) + [ keypos: info[:keypos], type: info[:type] ] + end + +end diff --git a/lib/stash/macros.ex b/lib/stash/macros.ex new file mode 100644 index 0000000..e82ef24 --- /dev/null +++ b/lib/stash/macros.ex @@ -0,0 +1,67 @@ +defmodule Stash.Macros do + @moduledoc false + # A collection of Macros used to define internal function headers + # and should not be used from outside this library (because they + # make a lot of assumptions) + + defmacro deft(args, do: body) do + { args, func_name, ctx, guards } = parse_args(args) + + cache = { :cache, ctx, nil } + + body = quote do + cache = unquote(cache) + if :ets.info(cache) == :undefined do + :ets.new(cache, [ + { :read_concurrency, true }, + { :write_concurrency, true }, + :public, + :set, + :named_table + ]) + end + unquote(body) + end + + remainder = + args |> Enum.reverse |> Enum.reduce([], fn({ name, ctx, other }, state) -> + case name do + :cache -> state + nvalue -> + [{ "_" <> to_string(nvalue) |> String.to_atom, ctx, other } | state] + end + end) + + quote do + def unquote(func_name)(unquote_splicing([cache|remainder])) when not is_atom(unquote(cache)) do + raise ArgumentError, message: "Invalid ETS table name provided, got: #{inspect unquote(cache)}" + end + + if unquote(guards != nil) do + def unquote(func_name)(unquote_splicing(args)) when unquote(guards) do + unquote(body) + end + else + def unquote(func_name)(unquote_splicing(args)) do + unquote(body) + end + end + end + end + + defmacro __using__(_opts) do + quote do + import unquote(__MODULE__) + end + end + + defp parse_args(args) do + case args do + { :when, _, [ { func_name, ctx, args }, guards ] } -> + { args, func_name, ctx, guards } + { func_name, ctx, args } -> + { args, func_name, ctx, nil } + end + end + +end diff --git a/mix.exs b/mix.exs new file mode 100644 index 0000000..5a46322 --- /dev/null +++ b/mix.exs @@ -0,0 +1,64 @@ +defmodule Stash.Mixfile do + use Mix.Project + + @url_docs "http://hexdocs.pm/stash" + @url_github "https://github.com/zackehh/stash" + + def project do + [ + app: :stash, + name: "Stash", + description: "Simple ETS backed key/value store for Elixir", + package: %{ + files: [ + "lib", + "mix.exs", + "LICENSE", + "README.md" + ], + licenses: [ "MIT" ], + links: %{ + "Docs" => @url_docs, + "GitHub" => @url_github + }, + maintainers: [ "Isaac Whitfield" ] + }, + version: "1.0.0", + elixir: "~> 1.1", + deps: deps, + docs: [ + extras: [ "README.md" ], + source_ref: "master", + source_url: @url_github + ] + ] + end + + # Configuration for the OTP application + # + # Type "mix help compile.app" for more information + def application do + [applications: [:logger]] + end + + # Dependencies can be Hex packages: + # + # {:mydep, "~> 0.3.0"} + # + # Or git/path repositories: + # + # {:mydep, git: "https://github.com/elixir-lang/mydep.git", tag: "0.1.0"} + # + # Type "mix help deps" for more examples and options + defp deps do + [ + # documentation + { :earmark, "~> 0.2.1", optional: true, only: :docs }, + { :ex_doc, "~> 0.11.3", optional: true, only: :docs }, + # testing + { :benchfella, "~> 0.3.1", optional: true, only: :test }, + { :benchwarmer, "~> 0.0.2", optional: true, only: :test }, + { :exprof, "~> 0.2.0", optional: true, only: :test } + ] + end +end diff --git a/mix.lock b/mix.lock new file mode 100644 index 0000000..b6b23b8 --- /dev/null +++ b/mix.lock @@ -0,0 +1,14 @@ +%{"benchfella": {:hex, :benchfella, "0.3.1"}, + "benchwarmer": {:hex, :benchwarmer, "0.0.2"}, + "certifi": {:hex, :certifi, "0.3.0"}, + "earmark": {:hex, :earmark, "0.2.1"}, + "ex_doc": {:hex, :ex_doc, "0.11.4"}, + "excoveralls": {:hex, :excoveralls, "0.4.6"}, + "exjsx": {:hex, :exjsx, "3.2.0"}, + "exprintf": {:hex, :exprintf, "0.1.6"}, + "exprof": {:hex, :exprof, "0.2.0"}, + "hackney": {:hex, :hackney, "1.4.8"}, + "idna": {:hex, :idna, "1.0.3"}, + "jsx": {:hex, :jsx, "2.6.2"}, + "mimerl": {:hex, :mimerl, "1.0.2"}, + "ssl_verify_hostname": {:hex, :ssl_verify_hostname, "1.0.5"}} diff --git a/test/stash_test.exs b/test/stash_test.exs new file mode 100644 index 0000000..a1e7f50 --- /dev/null +++ b/test/stash_test.exs @@ -0,0 +1,97 @@ +defmodule StashTest do + use ExUnit.Case + + @test_cache :my_test_cache + @test_file "/tmp/stash_test_file" + + setup do + Stash.clear(@test_cache) + Enum.each(1..1000, fn(x) -> + Stash.set(@test_cache, "key#{x}", "value#{x}") + end) + File.rm_rf!(@test_file) + :ok + end + + test "deft macro cannot accept non-atom caches" do + assert_raise ArgumentError, "Invalid ETS table name provided, got: \"test\"", fn -> + Stash.get("test", "key") + end + end + + test "test specific key retrieval" do + Enum.each(1..1000, fn(x) -> + assert(Stash.get(@test_cache, "key#{x}") == "value#{x}") + end) + end + + test "test key deletion" do + Enum.each(1..1000, fn(x) -> + assert(Stash.delete(@test_cache, "key#{x}")) + assert(Stash.size(@test_cache) == 1000 - x) + end) + end + + test "test empty checking" do + assert(!Stash.empty?(@test_cache)) + assert(Stash.clear(@test_cache)) + assert(Stash.empty?(@test_cache)) + end + + test "test key exists" do + Enum.each(1..1000, fn(x) -> + assert(Stash.exists?(@test_cache, "key#{x}")) + end) + assert(!Stash.exists?(@test_cache, "key1001")) + end + + test "test key increment" do + assert(Stash.set(@test_cache, "key", 1)) + assert(Stash.inc(@test_cache, "key") == 2) + assert(Stash.inc(@test_cache, "key", 2) == 4) + assert(Stash.inc(@test_cache, "keyX", 5, 5) == 10) + end + + test "test key list retrieval" do + keys = Stash.keys(@test_cache) + assert(keys |> Enum.count == 1000) + end + + test "test key removal" do + Enum.each(1..1000, fn(x) -> + assert(Stash.remove(@test_cache, "key#{x}") == "value#{x}") + assert(Stash.size(@test_cache) == 1000 - x) + end) + end + + test "test key being set" do + assert(Stash.set(@test_cache, "key", "value")) + assert(Stash.get(@test_cache, "key") == "value") + end + + test "test size retrieval" do + assert(Stash.size(@test_cache) == 1000) + end + + test "test clearing" do + assert(Stash.size(@test_cache) == 1000) + assert(Stash.clear(@test_cache)) + assert(Stash.size(@test_cache) == 0) + end + + test "test persistance and loading" do + assert(Stash.clear(@test_cache)) + assert(Stash.empty?(@test_cache)) + Enum.each(1..5, fn(x) -> + Stash.set(@test_cache, "key#{x}", "value#{x}") + end) + assert(Stash.size(@test_cache) == 5) + assert(Stash.persist(@test_cache, @test_file) == :ok) + + assert(Stash.clear(@test_cache)) + assert(Stash.empty?(@test_cache)) + assert(Stash.load(@test_cache, @test_file) == :ok) + assert(Stash.size(@test_cache) == 5) + end + +end diff --git a/test/test_helper.exs b/test/test_helper.exs new file mode 100644 index 0000000..869559e --- /dev/null +++ b/test/test_helper.exs @@ -0,0 +1 @@ +ExUnit.start()