mirror of
https://github.com/valitydev/cache.git
synced 2024-11-06 01:45:19 +00:00
update README.md
This commit is contained in:
Dmitry Kolesnikov
parent
3a1969f6c0
commit
9ad89e30e6
158
README.md
158
README.md
@ -1,40 +1,121 @@
|
||||
# Segmented in-memory cache
|
||||
|
||||
[](http://travis-ci.org/fogfish/cache)
|
||||
[](https://hex.pm/packages/cache)
|
||||
[](https://github.com/fogfish/cache)
|
||||
|
||||
|
||||
## Inspiration
|
||||
|
||||
Cache uses N disposable ETS tables instead of single one. The cache applies eviction and quota
|
||||
policies at segment level. The oldest ETS table is destroyed and new one is created when
|
||||
quota or TTL criteria are exceeded.
|
||||
quota or TTL criteria are exceeded. This approach outperforms the traditional timestamp indexing techniques.
|
||||
|
||||
The write operation always uses youngest segment. The read operation lookup key from youngest to oldest table until it is found same time key is moved to youngest segment to prolong TTL. If none of ETS table contains key then cache-miss occurs.
|
||||
|
||||
The downside is inability to assign precise TTL per single cache entry. TTL is always approximated to nearest segment. (e.g. cache with 60 sec TTL and 10 segments has 6 sec accuracy on TTL)
|
||||
|
||||
## Change log
|
||||
|
||||
[](http://travis-ci.org/fogfish/cache)
|
||||
[](https://github.com/fogfish/cache)
|
||||
## Getting started
|
||||
|
||||
* 2.0.0 - various changes on asynchronous api, not compatible with version 1.x
|
||||
* 1.0.1 - production release
|
||||
The latest version of the library is available at its `master` branch. All development, including new features and bug fixes, take place on the `master` branch using forking and pull requests as described in contribution guidelines.
|
||||
|
||||
## Usage
|
||||
### Installation
|
||||
|
||||
If you are using `rebar3` you can include the library in your project with
|
||||
|
||||
```erlang
|
||||
{deps, [
|
||||
cache
|
||||
]}.
|
||||
```
|
||||
|
||||
|
||||
### Usage
|
||||
|
||||
The library exposes public interface through exports of [`cache.erl`](src/cache.erl) module.
|
||||
|
||||
Build library and run the development console to evaluate Key features
|
||||
|
||||
```
|
||||
make && make run
|
||||
```
|
||||
|
||||
|
||||
## Key features
|
||||
|
||||
|
||||
### key/value interface
|
||||
|
||||
The library implements traditional key/value interface through `put`, `get` and `remove` notation.
|
||||
|
||||
```erlang
|
||||
application:start(cache).
|
||||
{ok, _} = cache:start_link(my_cache, [{n, 10}, {ttl, 60}]).
|
||||
|
||||
%% synchronous i/o
|
||||
ok = cache:put(my_cache, <<"my key">>, <<"my value">>).
|
||||
Val = cache:get(my_cache, <<"my key">>).
|
||||
```
|
||||
|
||||
|
||||
### asynchronous i/o
|
||||
|
||||
The library implements synchronous and asynchronous implementation of same functions. The asynchronous variant of function is annotated with `_` suffix. E.g. `get(...)` is a synchronous cache lookup operation (the process is blocked until cache returns); `get_(...)` is an asynchronous variant that delivers result of execution to mailbox of the process.
|
||||
|
||||
```erlang
|
||||
application:start(cache).
|
||||
{ok, _} = cache:start_link(my_cache, [{n, 10}, {ttl, 60}]).
|
||||
|
||||
%% asynchronous i/o
|
||||
Ref = cache:get_(my_cache, <<"my key">>).
|
||||
receive {Ref, Val} -> Val end.
|
||||
```
|
||||
|
||||
### transform element
|
||||
|
||||
The library allows to apply an function over the cache element.
|
||||
|
||||
```erlang
|
||||
application:start(cache).
|
||||
{ok, _} = cache:start_link(my_cache, [{n, 10}, {ttl, 60}]).
|
||||
|
||||
cache:put(my_cache, <<"my key">>, <<"x">>).
|
||||
cache:apply(my_cache, <<"my key">>, fun(X) -> <<"x", X/binary>> end).
|
||||
cache:get(my_cache, <<"my key">>).
|
||||
```
|
||||
|
||||
The library implement to helper functions to transform elements with `append` or `prepend`
|
||||
|
||||
```erlang
|
||||
application:start(cache).
|
||||
{ok, _} = cache:start_link(my_cache, [{n, 10}, {ttl, 60}]).
|
||||
|
||||
cache:put(my_cache, <<"my key">>, <<"b">>).
|
||||
cache:append(my_cache, <<"my key">>, <<"c">>).
|
||||
cache:prepend(my_cache, <<"my key">>, <<"a">>).
|
||||
cache:get(my_cache, <<"my key">>).
|
||||
```
|
||||
|
||||
### accumulator
|
||||
|
||||
```erlang
|
||||
application:start(cache).
|
||||
{ok, _} = cache:start_link(my_cache, [{n, 10}, {ttl, 60}]).
|
||||
|
||||
cache:acc(my_cache, <<"my key">>, 1).
|
||||
cache:acc(my_cache, <<"my key">>, 1).
|
||||
cache:acc(my_cache, <<"my key">>, 1).
|
||||
```
|
||||
|
||||
### check-and-store
|
||||
|
||||
The library implements the check-and-store semantic for put operations:
|
||||
* `add` store key/val only if cache does not already hold data for this key
|
||||
* `replace` store key/val only if cache does hold data for this key
|
||||
|
||||
|
||||
### configuration via Erlang `sys.config`
|
||||
|
||||
The cache instances are configurable via `sys.config`. Theses cache instances are supervised by application
|
||||
supervisor.
|
||||
The cache instances are configurable via `sys.config`. Theses cache instances are supervised by application supervisor.
|
||||
|
||||
```erlang
|
||||
{cache, [
|
||||
@ -73,19 +154,56 @@ The local cache instance is accessible for any Erlang nodes in the cluster.
|
||||
```
|
||||
|
||||
|
||||
## Performance
|
||||
## How to Contribute
|
||||
|
||||
MacBook Pro, Intel Core i5, 2.5GHz, 8GB 1600 MHz DDR3, 256 SSD
|
||||
The library is Apache 2.0 licensed and accepts contributions via GitHub pull requests.
|
||||
|
||||
LRU Cache, 10 segments, 20 sec ttl (~2 sec per segment)
|
||||
### getting started
|
||||
|
||||
Local cache (application and cache within same VM)
|
||||
|
||||
* Fork the repository on GitHub
|
||||
* Read the README.md for build instructions
|
||||
* Make pull request
|
||||
|
||||
Distributed cache (application and cache runs in different VMs)
|
||||
|
||||
### commit message
|
||||
|
||||
The commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter [Contributing to a Project](http://git-scm.com/book/ch5-2.html) of Git book.
|
||||
|
||||
>
|
||||
> Short (50 chars or less) summary of changes
|
||||
>
|
||||
> More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.
|
||||
>
|
||||
> Further paragraphs come after blank lines.
|
||||
>
|
||||
> Bullet points are okay, too
|
||||
>
|
||||
> Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here
|
||||
>
|
||||
|
||||
## Bugs
|
||||
|
||||
If you detect a bug, please bring it to our attention via GitHub issues. Please make your report detailed and accurate so that we can identify and replicate the issues you experience:
|
||||
- specify the configuration of your environment, including which operating system you're using and the versions of your runtime environments
|
||||
- attach logs, screen shots and/or exceptions if possible
|
||||
- briefly summarize the steps you took to resolve or reproduce the problem
|
||||
|
||||
|
||||
## Change log
|
||||
|
||||
* 2.0.0 - various changes on asynchronous api, not compatible with version 1.x
|
||||
* 1.0.1 - production release
|
||||
|
||||
## Contributors
|
||||
* Jose Luis Navarro https://github.com/artefactop
|
||||
* Valentin Micic
|
||||
|
||||
* Jose Luis Navarro https://github.com/artefactop
|
||||
* Valentin Micic
|
||||
|
||||
|
||||
## License
|
||||
|
||||
Copyright 2014 Dmitry Kolesnikov
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
|
||||
|
||||
|
||||
BIN
distributed.png
BIN
distributed.png
Binary file not shown.
|
Before Width: | Height: | Size: 100 KiB |
Loading…
Reference in New Issue
Block a user