kvx v0.1.3 KVX.Bucket behaviour

Defines a Bucket.

A bucket maps to an underlying data store, controlled by the adapter. For example, KVX ships with a KVX.Bucket.ExShards adapter that stores data into ExShards distributed memory storage – ExShards.

For example, the bucket:

defmodule MyModule do
  use use KVX.Bucket
end

Could be configured with:

config :kvx,
  adapter: KVX.Bucket.ExShards,
  ttl: 10

Most of the configuration that goes into the config is specific to the adapter, so check KVX.Bucket.ExShards documentation for more information. However, some configuration is shared across all adapters, they are:

:ttl - The time in seconds to wait until the key expires. Value :infinity will wait indefinitely (default: 3600)

Check adapters documentation for more information.

Summary

Types

bucket()

key()

ttl()

value()

Callbacks

add(bucket, key, value, ttl)

Store this data, only if it does not already exist. If an item already exists and an add fails with a KVX.ConflictError exception

delete(bucket)

Deletes an entire bucket, if it exists

delete(bucket, key)

Removes an item from the bucket, if it exists

find_all(bucket, query)

Returns all objects/tuples {key, value} that matches with the specified query. The query type/spec depends on each adapter implementation – :ets.match_spec in case of KVX.Bucket.ExShards

flush(bucket)

Invalidate all existing cache items

get(bucket, key)

Get the value of key. If the key does not exist the special value nil is returned

mget(bucket, list)

Returns the values of all specified keys. For every key that does not hold a string value or does not exist, the special value nil is returned. Because of this, the operation never fails

mset(bucket, list, ttl)

Store this bulk data, possibly overwriting any existing data

new(bucket, list)

Creates a new bucket if it doesn’t exist. If the bucket already exist, nothing happens – it works as an idempotent operation

set(bucket, key, value, ttl)

Most common command. Store this data, possibly overwriting any existing data

Types

bucket()

bucket() :: atom

key()

key() :: term

ttl()

ttl() :: integer | :infinity

value()

value() :: term

Callbacks

add(bucket, key, value, ttl)

add(bucket, key, value, ttl) :: bucket | KVX.ConflictError

Store this data, only if it does not already exist. If an item already exists and an add fails with a KVX.ConflictError exception.

If bucket doesn’t exist, it will raise an argument error.

Example

MyBucket.add(:mybucket, "hello", "world")

delete(bucket)

delete(bucket) :: bucket

Deletes an entire bucket, if it exists.

If bucket doesn’t exist, it will raise an argument error.

Example

MyBucket.delete(:mybucket)

delete(bucket, key)

delete(bucket, key) :: bucket

Removes an item from the bucket, if it exists.

If bucket doesn’t exist, it will raise an argument error.

Example

MyBucket.delete(:mybucket, "hello")

find_all(bucket, query)

find_all(bucket, query :: term) :: [{key, value}]

Returns all objects/tuples {key, value} that matches with the specified query. The query type/spec depends on each adapter implementation – :ets.match_spec in case of KVX.Bucket.ExShards.

If bucket doesn’t exist, it will raise an argument error.

Example

MyBucket.find_all(bucket, Ex2ms.fun do object -> object end)

flush(bucket)

flush(bucket) :: bucket

Invalidate all existing cache items.

If bucket doesn’t exist, it will raise an argument error.

Example

MyBucket.flush(:mybucket)

get(bucket, key)

get(bucket, key) :: value | nil

Get the value of key. If the key does not exist the special value nil is returned.

If bucket doesn’t exist, it will raise an argument error.

Example

MyBucket.get(:mybucket, "hello")

mget(bucket, list)

mget(bucket, [key]) :: [value | nil]

Returns the values of all specified keys. For every key that does not hold a string value or does not exist, the special value nil is returned. Because of this, the operation never fails.

If bucket doesn’t exist, it will raise an argument error.

Example

MyBucket.mget(:mybucket, ["hello", "world"])

mset(bucket, list, ttl)

mset(bucket, [{key, value}], ttl) :: bucket

Store this bulk data, possibly overwriting any existing data.

If bucket doesn’t exist, it will raise an argument error.

Example

MyBucket.mset(:mybucket, [{"a": 1}, {"b", "2"}])

new(bucket, list)

new(bucket, [term]) :: bucket

Creates a new bucket if it doesn’t exist. If the bucket already exist, nothing happens – it works as an idempotent operation.

Example

MyBucket.new(:mybucket)

set(bucket, key, value, ttl)

set(bucket, key, value, ttl) :: bucket

Most common command. Store this data, possibly overwriting any existing data.

If bucket doesn’t exist, it will raise an argument error.

Example

MyBucket.set(:mybucket, "hello", "world")