Skip to content

Commit 85bd0ce

Browse files
cabolcabol
committed
Improve docs
1 parent 348aa51 commit 85bd0ce

3 files changed

Lines changed: 273 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 136 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# Nebulex.Adapters.Cachex
22
> ### Nebulex adapter for [Cachex][Cachex]
3+
> Cachex via Nebulex out-of-box.
34
45
[Cachex]: https://github.com/whitfin/cachex
56

@@ -11,8 +12,6 @@
1112
See the [docs](https://hexdocs.pm/nebulex_adapters_cachex/)
1213
for more information.
1314

14-
*Still WIP*
15-
1615
## Installation
1716

1817
Add `:nebulex_adapters_cachex` to your list of dependencies in `mix.exs`:
@@ -24,3 +23,138 @@ def deps do
2423
]
2524
end
2625
```
26+
27+
## Usage
28+
29+
You can define a cache using Cachex as follows:
30+
31+
```elixir
32+
defmodule MyApp.Cache do
33+
use Nebulex.Cache,
34+
otp_app: :my_app,
35+
adapter: Nebulex.Adapters.Cachex
36+
end
37+
```
38+
39+
Where the configuration for the cache must be in your application
40+
environment, usually defined in your `config/config.exs`:
41+
42+
```elixir
43+
config :my_app, MyApp.Cache,
44+
limit: 1_000_000,
45+
stats: true,
46+
...
47+
```
48+
49+
If your application was generated with a supervisor (by passing `--sup`
50+
to `mix new`) you will have a `lib/my_app/application.ex` file containing
51+
the application start callback that defines and starts your supervisor.
52+
You just need to edit the `start/2` function to start the cache as a
53+
supervisor on your application's supervisor:
54+
55+
```elixir
56+
def start(_type, _args) do
57+
children = [
58+
{MyApp.Cache, []},
59+
]
60+
61+
...
62+
end
63+
```
64+
65+
Since Cachex uses macros for some configuration options, you could also
66+
pass the options in runtime when the cache is started, either by calling
67+
`MyApp.Cache.start_link/1` directly, or in your app supervision tree:
68+
69+
```elixir
70+
def start(_type, _args) do
71+
children = [
72+
{MyApp.Cache, cachex_opts()},
73+
]
74+
75+
...
76+
end
77+
78+
defp cachex_opts do
79+
import Cachex.Spec
80+
81+
[
82+
expiration: expiration(
83+
# default record expiration
84+
default: :timer.seconds(60),
85+
86+
# how often cleanup should occur
87+
interval: :timer.seconds(30),
88+
89+
# whether to enable lazy checking
90+
lazy: true
91+
),
92+
93+
# complex limit
94+
limit: limit(
95+
size: 500,
96+
policy: Cachex.Policy.LRW,
97+
reclaim: 0.5,
98+
options: []
99+
),
100+
101+
...
102+
]
103+
end
104+
```
105+
106+
> See [Cachex.start_link/1][cachex_start_link] for more information.
107+
108+
[cachex_start_link]: https://hexdocs.pm/cachex/Cachex.html#start_link/1
109+
110+
## Distributed caching topologies
111+
112+
In the same way we use the distributed adapters and the multilevel one to
113+
create distributed topologies, we can also do the same but instead of using
114+
the built-in local adapter using Cachex.
115+
116+
For example, let's define a multi-level cache (near cache topology), where
117+
the L1 is a local cache using Cachex and the L2 is a partitioned cache.
118+
119+
```elixir
120+
defmodule MyApp.NearCache do
121+
use Nebulex.Cache,
122+
otp_app: :nebulex,
123+
adapter: Nebulex.Adapters.Multilevel
124+
125+
defmodule L1 do
126+
use Nebulex.Cache,
127+
otp_app: :nebulex,
128+
adapter: Nebulex.Adapters.Cachex
129+
end
130+
131+
defmodule L2 do
132+
use Nebulex.Cache,
133+
otp_app: :nebulex,
134+
adapter: Nebulex.Adapters.Partitioned,
135+
primary_storage_adapter: Nebulex.Adapters.Cachex
136+
end
137+
end
138+
```
139+
140+
And the configuration may look like:
141+
142+
```elixir
143+
config :my_app, MyApp.NearCache,
144+
model: :inclusive,
145+
levels: [
146+
{MyApp.NearCache.L1, [limit: 100_000]},
147+
{MyApp.NearCache.L2, primary: [limit: 1_000_000]}
148+
]
149+
```
150+
151+
> **NOTE:** You could also use [NebulexRedisAdapter][nbx_redis_adapter] for L2,
152+
it would be matter of changing the adapter for the L2 and the configuration
153+
for set up Redis adapter.
154+
155+
See [Nebulex examples](https://github.com/cabol/nebulex_examples). You will
156+
find examples for all different topologies, even using other adapters like
157+
Redis; for all examples you can just replace `Nebulex.Adapters.Local` by
158+
`Nebulex.Adapters.Cachex`.
159+
160+
[nbx_redis_adapter]: https://github.com/cabol/nebulex_redis_adapter

‎lib/nebulex/adapters/cachex.ex‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,143 @@
11
defmodule Nebulex.Adapters.Cachex do
22
@moduledoc """
33
Nebulex adapter for Cachex.
4+
5+
Cachex is one of the most used cache (maybe the most used one) in Elixir.
6+
For that reason, Nebulex provides this adapter to use Cachex via Nebulex
7+
taking advantage of all their benefits and/or features.
8+
9+
Cachex is now a very good alternative for local caching aside from the
10+
built-in local adapter provided by Nebulex. Besides, you can setup distributed
11+
topologies by using the distributed adapters Nebulex brings with it and set up
12+
Cachex as local cache.
13+
14+
## Options
15+
16+
Since Nebulex is just a wrapper on top of Cachex, the options are the same as
17+
[Cachex.start_link/1][cachex_start_link].
18+
19+
[cachex_start_link]: https://hexdocs.pm/cachex/Cachex.html#start_link/1
20+
21+
## Example
22+
23+
You can define a cache using Cachex as follows:
24+
25+
defmodule MyApp.Cache do
26+
use Nebulex.Cache,
27+
otp_app: :my_app,
28+
adapter: Nebulex.Adapters.Cachex
29+
end
30+
31+
Where the configuration for the cache must be in your application
32+
environment, usually defined in your `config/config.exs`:
33+
34+
config :my_app, MyApp.Cache,
35+
limit: 1_000_000,
36+
stats: true,
37+
...
38+
39+
If your application was generated with a supervisor (by passing `--sup`
40+
to `mix new`) you will have a `lib/my_app/application.ex` file containing
41+
the application start callback that defines and starts your supervisor.
42+
You just need to edit the `start/2` function to start the cache as a
43+
supervisor on your application's supervisor:
44+
45+
def start(_type, _args) do
46+
children = [
47+
{MyApp.Cache, []},
48+
]
49+
50+
...
51+
end
52+
53+
Since Cachex uses macros for some configuration options, you could also
54+
pass the options in runtime when the cache is started, either by calling
55+
`MyApp.Cache.start_link/1` directly, or in your app supervision tree:
56+
57+
def start(_type, _args) do
58+
children = [
59+
{MyApp.Cache, cachex_opts()},
60+
]
61+
62+
...
63+
end
64+
65+
defp cachex_opts do
66+
import Cachex.Spec
67+
68+
[
69+
expiration: expiration(
70+
# default record expiration
71+
default: :timer.seconds(60),
72+
73+
# how often cleanup should occur
74+
interval: :timer.seconds(30),
75+
76+
# whether to enable lazy checking
77+
lazy: true
78+
),
79+
80+
# complex limit
81+
limit: limit(
82+
size: 500,
83+
policy: Cachex.Policy.LRW,
84+
reclaim: 0.5,
85+
options: []
86+
),
87+
88+
...
89+
]
90+
end
91+
92+
> See [Cachex.start_link/1][cachex_start_link] for more information.
93+
94+
## Distributed caching topologies
95+
96+
In the same way we use the distributed adapters and the multilevel one to
97+
create distributed topologies, we can also do the same but instead of using
98+
the built-in local adapter using Cachex.
99+
100+
For example, let's define a multi-level cache (near cache topology), where
101+
the L1 is a local cache using Cachex and the L2 is a partitioned cache.
102+
103+
defmodule MyApp.NearCache do
104+
use Nebulex.Cache,
105+
otp_app: :nebulex,
106+
adapter: Nebulex.Adapters.Multilevel
107+
108+
defmodule L1 do
109+
use Nebulex.Cache,
110+
otp_app: :nebulex,
111+
adapter: Nebulex.Adapters.Cachex
112+
end
113+
114+
defmodule L2 do
115+
use Nebulex.Cache,
116+
otp_app: :nebulex,
117+
adapter: Nebulex.Adapters.Partitioned,
118+
primary_storage_adapter: Nebulex.Adapters.Cachex
119+
end
120+
end
121+
122+
And the configuration may look like:
123+
124+
config :my_app, MyApp.NearCache,
125+
model: :inclusive,
126+
levels: [
127+
{MyApp.NearCache.L1, [limit: 100_000]},
128+
{MyApp.NearCache.L2, primary: [limit: 1_000_000]}
129+
]
130+
131+
> **NOTE:** You could also use [NebulexRedisAdapter][nbx_redis_adapter] for
132+
L2, it would be matter of changing the adapter for the L2 and the
133+
configuration for set up Redis adapter.
134+
135+
[nbx_redis_adapter]: https://github.com/cabol/nebulex_redis_adapter
136+
137+
See [Nebulex examples](https://github.com/cabol/nebulex_examples). You will
138+
find examples for all different topologies, even using other adapters like
139+
Redis; for all examples you can just replace `Nebulex.Adapters.Local` by
140+
`Nebulex.Adapters.Cachex`.
4141
"""
5142

6143
# Provide Cache Implementation

‎test_cache‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)