[#189] Nebulex v3 initial draft

- Ok/Error tuple Cache API - Remove deprecated module `Nebulex.Hook` - Use `NimbleOptions` for defining and validating cache options - Replace `Mock` with `Mimic` - Move adapters to separate repos - All commands optionally support a dynamic cache as the first argument - Deprecate `Nebulex.Adapter.Stats` in favor of `Nebulex.Adapter.Info` - Rename the Telemetry metadata field from `:function_name` to `:command` - Support dynamic cache in decorators - Evaluate the `:cache` option for decorated functions in runtime
cabol · Jun 12, 2023 · d55a53a · d55a53a
1 parent 974f54e
commit d55a53a
Show file tree

Hide file tree

Showing 120 changed files with 7,433 additions and 11,882 deletions.
diff --git a/.credo.exs b/.credo.exs
@@ -117,9 +117,9 @@
         ## Refactoring Opportunities
         #
         {Credo.Check.Refactor.CondStatements, []},
-        {Credo.Check.Refactor.CyclomaticComplexity, []},
+        {Credo.Check.Refactor.CyclomaticComplexity, [max_complexity: 40]},
         {Credo.Check.Refactor.FunctionArity, []},
-        {Credo.Check.Refactor.LongQuoteBlocks, [max_line_count: 300, ignore_comments: true]},
+        {Credo.Check.Refactor.LongQuoteBlocks, [max_line_count: 200]},
         # {Credo.Check.Refactor.MapInto, []},
         {Credo.Check.Refactor.MatchInCondition, []},
         {Credo.Check.Refactor.NegatedConditionsInUnless, []},

diff --git a/.formatter.exs b/.formatter.exs
@@ -1,5 +1,15 @@
 locals_without_parens = [
+  # Nebulex.Utils
+  unwrap_or_raise: 1,
+  wrap_ok: 1,
+  wrap_error: 1,
+  wrap_error: 2,
+
+  # Nebulex.Cache.Utils
+  defcacheapi: 2,
+
   # Nebulex.Caching
+  dynamic_cache: 2,
   keyref: 1,
   keyref: 2,
 

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -32,9 +32,6 @@ jobs:
             otp: 23.x
             os: 'ubuntu-20.04'
             inch-report: true
-          - elixir: 1.9.x
-            otp: 22.x
-            os: 'ubuntu-20.04'
 
     env:
       GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
@@ -87,27 +84,23 @@ jobs:
         if: ${{ matrix.style }}
 
       - name: Run tests
-        run: |
-          epmd -daemon
-          mix test --trace
+        run: mix test
         if: ${{ !matrix.coverage }}
 
       - name: Run tests with coverage
-        run: |
-          epmd -daemon
-          mix coveralls.github
+        run: mix coveralls.github
         if: ${{ matrix.coverage }}
 
       - name: Run sobelow
-        run: mix sobelow --exit --skip
+        run: mix sobelow --skip --exit Low
         if: ${{ matrix.sobelow }}
 
       - name: Restore PLT Cache
         uses: actions/cache@v3
         id: plt-cache
         with:
           path: priv/plts
-          key: ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-plt-v1
+          key: ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-plt-v3-1
         if: ${{ matrix.dialyzer }}
 
       - name: Create PLTs

diff --git a/.gitignore b/.gitignore
@@ -37,3 +37,4 @@ erl_crash.dump
 /priv
 .sobelow*
 /config
+Elixir*
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,115 +4,6 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [v2.5.1](https://github.com/cabol/nebulex/tree/v2.5.1) (2023-05-27)
-
-[Full Changelog](https://github.com/cabol/nebulex/compare/v2.5.0...v2.5.1)
-
-**Merged pull requests:**
-
-- Fix `nil` check in `Nebulex.Adapters.Multilevel.get/3`
-  [#205](https://github.com/cabol/nebulex/pull/205)
-  ([1100x1100](https://github.com/1100x1100))
-- `mix nbx.gen.cache` example fixed
-  [#204](https://github.com/cabol/nebulex/pull/204)
-  ([hissssst](https://github.com/hissssst))
-
-## [v2.5.0](https://github.com/cabol/nebulex/tree/v2.5.0) (2023-05-13)
-
-[Full Changelog](https://github.com/cabol/nebulex/compare/v2.4.2...v2.5.0)
-
-**Implemented enhancements:**
-
-- Support for functions that can set TTL in Decorator similar to Match
-  [#200](https://github.com/cabol/nebulex/issues/200)
-- Improve default match function in decorators to cover more scenarios
-  [#177](https://github.com/cabol/nebulex/issues/177)
-- Adapters implementation guide
-  [#96](https://github.com/cabol/nebulex/issues/96)
-
-**Fixed bugs:**
-
-- Issue with keys set to `false` when calling `get_all` in local adapter
-  [#187](https://github.com/cabol/nebulex/issues/187)
-
-**Closed issues:**
-
-- Is there any way to get the size of the cache?
-  [#203](https://github.com/cabol/nebulex/issues/203)
-- Where to use load/2, dump/2
-  [#201](https://github.com/cabol/nebulex/issues/201)
-- `Nebulex.Cache` callbacks mention "Shared Options" section that do not exist
-  [#199](https://github.com/cabol/nebulex/issues/199)
-- Errors when storing nil values
-  [#195](https://github.com/cabol/nebulex/issues/195)
-- Unregistering cache in registry happens after cache shuts down
-  [#194](https://github.com/cabol/nebulex/issues/194)
-- Is there a good way to evict multiple caches at once by some conditions?
-  [#192](https://github.com/cabol/nebulex/issues/192)
-- Unable to use module attributes when specifying a MFA cache within the decorator
-  [#191](https://github.com/cabol/nebulex/issues/191)
-- Nebulex crash when `gc_interval` is not set
-  [#182](https://github.com/cabol/nebulex/issues/182)
-- `ArgumentError` * 1st argument: the table identifier does not refer to an existing ETS table
-  [#181](https://github.com/cabol/nebulex/issues/181)
-- Feedback for `NebulexLocalDistributedAdapter`
-  [#180](https://github.com/cabol/nebulex/issues/180)
-- Multilevel invalidation
-  [#179](https://github.com/cabol/nebulex/issues/179)
-- External cache-key references on `cacheable` decorator
-  [#178](https://github.com/cabol/nebulex/issues/178)
-- [multiple clause functions] Cannot use ignored variables in decorator keys
-  [#173](https://github.com/cabol/nebulex/issues/173)
-- Ability for referencing a key in the `cacheable` decorator via `:references` option
-  [#169](https://github.com/cabol/nebulex/issues/169)
-- Multi level caching suggestion?
-  [#168](https://github.com/cabol/nebulex/issues/168)
-
-**Merged pull requests:**
-
-- Fix `Local.get_all` with false values
-  [#186](https://github.com/cabol/nebulex/pull/186)
-  ([renatoaguiar](https://github.com/renatoaguiar))
-- Add NebulexLocalMultilevelAdapter to the list
-  [#185](https://github.com/cabol/nebulex/pull/185)
-  ([martosaur](https://github.com/martosaur))
-- Fix the crash when `gc_interval` is not set
-  [#183](https://github.com/cabol/nebulex/pull/183)
-  ([dongfuye](https://github.com/dongfuye))
-- [#169] Reference a key in `cacheable` decorator via `:references` option
-  [#176](https://github.com/cabol/nebulex/pull/176)
-  ([cabol](https://github.com/cabol))
-- Creating New Adapter guide
-  [#175](https://github.com/cabol/nebulex/pull/175)
-  ([martosaur](https://github.com/martosaur))
-
-## [v2.4.2](https://github.com/cabol/nebulex/tree/v2.4.2) (2022-11-04)
-
-[Full Changelog](https://github.com/cabol/nebulex/compare/v2.4.1...v2.4.2)
-
-**Closed issues:**
-
-- Adapter configuration per-env?
-  [#171](https://github.com/cabol/nebulex/issues/171)
-- On-change handler for write-through decorators
-  [#165](https://github.com/cabol/nebulex/issues/165)
-- Document test env setup with decorators?
-  [#155](https://github.com/cabol/nebulex/issues/155)
-- Managing Failovers in the cluster
-  [#131](https://github.com/cabol/nebulex/issues/131)
-
-**Merged pull requests:**
-
-- Make Multilevel adapter apply deletes in reverse order
-  [#174](https://github.com/cabol/nebulex/pull/174)
-  ([martosaur](https://github.com/martosaur))
-- Use import Bitwise instead of use Bitwise
-  [#172](https://github.com/cabol/nebulex/pull/172)
-  ([ryvasquez](https://github.com/ryvasquez))
-- Fix result of getting value by non existent key
-  [#166](https://github.com/cabol/nebulex/pull/166)
-  ([fuelen](https://github.com/fuelen))
-
 ## [v2.4.1](https://github.com/cabol/nebulex/tree/v2.4.1) (2022-07-10)
 
 [Full Changelog](https://github.com/cabol/nebulex/compare/v2.4.0...v2.4.1)

diff --git a/README.md b/README.md
@@ -28,61 +28,57 @@ for more information.
 [cachex]: https://github.com/whitfin/cachex
 [redis]: https://redis.io/
 [memcached]: https://memcached.org/
-[nbx_caching]: http://hexdocs.pm/nebulex/Nebulex.Caching.html
+[nbx_caching]: http://hexdocs.pm/nebulex/Nebulex.Caching.Decorators.html
 [cache_patterns]: http://hexdocs.pm/nebulex/cache-usage-patterns.html
 [cache_topologies]: https://docs.oracle.com/middleware/1221/coherence/develop-applications/cache_intro.htm
 
 ## Usage
 
-You need to add `nebulex` as a dependency to your `mix.exs` file. However, in
-the case you want to use an external (a non built-in adapter) cache adapter,
-you also have to add the proper dependency to your `mix.exs` file.
-
-The supported caches and their adapters are:
+You need to add both Nebulex and the cache adapter as a dependency to your
+`mix.exs` file. The supported caches and their adapters are:
 
 Cache | Nebulex Adapter | Dependency
 :-----| :---------------| :---------
-Generational Local Cache | [Nebulex.Adapters.Local][la] | Built-In
-Partitioned | [Nebulex.Adapters.Partitioned][pa] | Built-In
-Replicated | [Nebulex.Adapters.Replicated][ra] | Built-In
-Multilevel | [Nebulex.Adapters.Multilevel][ma] | Built-In
 Nil (special adapter that disables the cache) | [Nebulex.Adapters.Nil][nil] | Built-In
-Cachex | Nebulex.Adapters.Cachex | [nebulex_adapters_cachex][nbx_cachex]
+Generational Local Cache | Nebulex.Adapters.Local | [nebulex_adapters_local][la]
+Partitioned | Nebulex.Adapters.Partitioned | [nebulex_adapters_partitioned][pa]
+Replicated | Nebulex.Adapters.Replicated | [nebulex_adapters_replicated][ra]
+Multilevel | Nebulex.Adapters.Multilevel | [nebulex_adapters_multilevel][ma]
 Redis | NebulexRedisAdapter | [nebulex_redis_adapter][nbx_redis]
+Cachex | Nebulex.Adapters.Cachex | [nebulex_adapters_cachex][nbx_cachex]
 Distributed with Horde | Nebulex.Adapters.Horde | [nebulex_adapters_horde][nbx_horde]
 Multilevel with cluster broadcasting | NebulexLocalMultilevelAdapter | [nebulex_local_multilevel_adapter][nbx_local_multilevel]
 
-[la]: http://hexdocs.pm/nebulex/Nebulex.Adapters.Local.html
-[pa]: http://hexdocs.pm/nebulex/Nebulex.Adapters.Partitioned.html
-[ra]: http://hexdocs.pm/nebulex/Nebulex.Adapters.Replicated.html
-[ma]: http://hexdocs.pm/nebulex/Nebulex.Adapters.Multilevel.html
 [nil]: http://hexdocs.pm/nebulex/Nebulex.Adapters.Nil.html
-[nbx_cachex]: https://github.com/cabol/nebulex_adapters_cachex
+[la]: https://github.com/elixir-nebulex/nebulex_adapters_local
+[pa]: https://github.com/elixir-nebulex/nebulex_adapters_partitioned
+[ra]: https://github.com/elixir-nebulex/nebulex_adapters_replicated
+[ma]: https://github.com/elixir-nebulex/nebulex_adapters_multilevel
 [nbx_redis]: https://github.com/cabol/nebulex_redis_adapter
+[nbx_cachex]: https://github.com/cabol/nebulex_adapters_cachex
 [nbx_horde]: https://github.com/eliasdarruda/nebulex_adapters_horde
 [nbx_local_multilevel]: https://github.com/slab/nebulex_local_multilevel_adapter
 
-
-For example, if you want to use a built-in cache, add to your `mix.exs` file:
+For example, if you want to use `Nebulex.Adapters.Local`, add to your `mix.exs`
+file:
 
 ```elixir
 def deps do
   [
-    {:nebulex, "~> 2.5"},
-    {:shards, "~> 1.1"},     #=> When using :shards as backend
-    {:decorator, "~> 1.4"},  #=> When using Caching Annotations
-    {:telemetry, "~> 1.0"}   #=> When using the Telemetry events (Nebulex stats)
+    {:nebulex, "~> 3.0"},
+    #=> When using the local cache adapter
+    {:nebulex_adapters_local, "~> 3.0"},
+    #=> When using Caching Annotations
+    {:decorator, "~> 1.4"},
+    #=> When using the Telemetry events
+    {:telemetry, "~> 1.0"}
   ]
 end
 ```
 
 In order to give more flexibility and fetch only needed dependencies, Nebulex
 makes all dependencies optional. For example:
 
-  * For intensive workloads, you may want to use `:shards` as the backend for
-    the local adapter and having partitioned tables. In such a case, you have
-    to add `:shards` to the dependency list.
-
   * For enabling the usage of
     [declarative annotation-based caching via decorators][nbx_caching],
     you have to add `:decorator` to the dependency list.
@@ -91,17 +87,14 @@ makes all dependencies optional. For example:
     you have to add `:telemetry` to the dependency list.
     See [telemetry guide][telemetry].
 
-  * If you want to use an external adapter (e.g: Cachex or Redis adapter), you
-    have to add the adapter dependency too.
-
 [telemetry]: http://hexdocs.pm/nebulex/telemetry.html
 
 Then run `mix deps.get` in your shell to fetch the dependencies. If you want to
 use another cache adapter, just choose the proper dependency from the table
 above.
 
 Finally, in the cache definition, you will need to specify the `adapter:`
-respective to the chosen dependency. For the local built-in cache it is:
+respective to the chosen dependency. For the local cache would be:
 
 ```elixir
 defmodule MyApp.Cache do
@@ -237,27 +230,12 @@ the directory [benchmarks](./benchmarks).
 To run a benchmark test you have to run:
 
 ```
-$ MIX_ENV=test mix run benchmarks/{BENCH_TEST_FILE}
+$ mix run benchmarks/benchmark.exs
 ```
 
-Where `BENCH_TEST_FILE` can be any of:
-
-  * `local_with_ets_bench.exs`: benchmark for the local adapter using
-    `:ets` backend.
-  * `local_with_shards_bench.exs`: benchmark for the local adapter using
-    `:shards` backend.
-  * `partitioned_bench.exs`:  benchmark for the partitioned adapter.
-
-For example, for running the benchmark for the local adapter using `:shards`
-backend:
-
-```
-$ MIX_ENV=test mix run benchmarks/local_with_shards_bench.exs
-```
-
-Additionally, you can also run performance tests using `:basho_bench`.
-See [nebulex_bench example](https://github.com/cabol/nebulex_examples/tree/master/nebulex_bench)
-for more information.
+> The benchmark uses the adapter `Nebulex.Adapters.Nil`; it is more focused on
+> measuring the Nebulex abstraction layer performance rather than a specific
+> adapter.
 
 ## Contributing