Gibreel

distributed cache implemented in Erlang

Installation

Using rebar:

{deps, [
    {gibreel, ".*", {hg, "https://bitbucket.org/jjmrocha/gibreel", "default"}}
]}.

Start Gibreel

Gibreel depends on columbo and cclock, you need to start both before gibreel.

#!erlang
ok = application:start(columbo),
ok = application:start(cclock),
ok = application:start(gibreel).

gibreel Module

The module gibreel allows you to create and destroy caches. The main functions are:

• create_cache/1 To create a basic cache (using defaults)
• create_cache/2 To create a cache with options
• delete_cache/1 Delete cache
• list_caches/0 List all caches

create_cache Function

#!erlang
gibreel:create_cache(CacheName :: atom()) -> 
    ok | {error, Reason :: any()}.

gibreel:create_cache(CacheName :: atom(), Options :: [Option, ...]) -> 
    ok | {error, Reason :: any()}.

The available options are:

• max_age - It's a pos_integer() and represents the expiration time of the items stored in the cache, time in seconds, defaults to 0 (items on the cache don't expire)
• get_value_function - It's a function fun((Key :: term()) -> term() | not_found | error) used by the cache to retrieve the value for the key, defaults to none
• max_size - It's a pos_integer() and represents the max number of items stored in the cache, when the max size is reached the oldest key-value is deleted to make space for the new one, defaults to none
• cluster_nodes - Must be one of the values local | all | [node(), ...], where (defaults to local):
  • local - The cache is local
  • all - The cache must synchronize with all cache instances running in the cluster
  • [node(), ...] The cache must synchronize with all cache instances running on the node list
• purge_interval - It's a pos_integer() and represents the running interval (time in seconds) for the purge process, which removes expired items from the cache, defaults to none (purge process don't run)
• sync_mode - Must be one of the values lazy | full, where (defaults to lazy):
  • lazy - Cache only synchronize the new key-values or when a item is removed
  • full - Cache must synchronize with all cache instances at start

delete_cache Function

#!erlang
gibreel:delete_cache(CacheName :: atom()) -> ok.

Deletes the cache.

list_caches Function

#!erlang
gibreel:list_caches() -> [atom(), ...].

Lists the names of all caches.

Examples

Using gibreel as a session storage

The webapp server Kill Bill uses Gibreel to store the session data.

#!erlang
Options = [
    {max_age, 1200},
    {purge_interval, 60},
    {cluster_nodes, all},
    {sync_mode, full}
],
gibreel:create_cache(my_webapp_session, Options).

Using gibreel as a DB cache

The site Gmailbox.org uses Gibreel as a DB cache for CouchDB.

#!erlang
LoadFunction = fun(Key) ->
    case chair:get_doc(gmailboxDB, Key) of
        {ok, Doc} -> Doc;
        {db_error, Error} ->
            case jsondoc:get_value(<<"error">>, Error) of
                <<"not_found">> -> not_found;
                _ -> error
            end;
        {error, _} -> error     
    end
end,
Options = [
    {get_value_function, LoadFunction},
    {max_age, 600},
    {max_size, 10000},
    {cluster_nodes, all}
],
gibreel:create_cache(account_cache, Options).

g_cache Module

The module cache allows you to store, remove and retrieve items from cache. The main functions are:

• store/3 Stores a key-value pair on the cache
• get/2 Retrieves the value for the key
• remove/2 Removes a key-value from the cache
• touch/2 Changes the item expiration date
• size/1 Return the number o key-value pairs in the cache
• foldl/3 Calls a function for all elements of the cache and returns an accumulator

store Function

#!erlang
g_cache:store(CacheName :: atom(), Key :: term(), Value :: term()) -> 
    no_cache | ok.

Stores a key-value pair on the cache.

get Function

#!erlang
g_cache:get(CacheName :: atom(), Key :: term()) -> 
    {ok, Value :: term()} | not_found | no_cache | error.

Retrieves the value for the key.

remove Function

#!erlang
g_cache:remove(CacheName :: atom(), Key :: term()) -> 
    no_cache | ok.

Removes a key-value from the cache.

touch Function

#!erlang
g_cache:touch(CacheName :: atom(), Key :: term()) -> ok.

Changes the item expiration date.

size Function

#!erlang
g_cache:size(CacheName :: atom()) -> no_cache | integer().

Return the number o key-value pairs in the cache.

foldl Function

#!erlang
g_cache:foldl(CacheName :: atom(), Fun, Acc :: term()) -> no_cache | term().

Calls function Fun on successive elements on the cache, starting with Acc. Fun/2 must return a new accumulator which is passed to the next call. The function returns the final value of the accumulator. Acc is returned if the list is empty.

For example:

#!erlang
g_cache:foldl(example, fun({_Key, Value}, Acc) ->
    [Value|Acc]
end, []).