kvx v0.1.0 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.Shards adapter that stores data into a shards distributed memory storage – shards.

For example, the bucket:

defmodule MyModule do
  use use KVX.Bucket
end

Could be configured with:

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

Most of the configuration that goes into the config is specific to the adapter, so check KVX.Bucket.Shards 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

Callbacks

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

Removes an item from the bucket, if it exists

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.Shards

Invalidate all existing cache items

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

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

Store this bulk data, possibly overwriting any existing data

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

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

Types

bucket :: atom
key :: term
ttl :: integer
value :: term

Callbacks

add(bucket, key, value, ttl)

Specs

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 an exception.

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

Example

MyBucket.add(:mybucket, "hello", "world")
delete(bucket, key)

Specs

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)

Specs

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.Shards.

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

Example

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

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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")