Specifies the adapter Composite KV API.

Composite operations combine a read and a write on the same key in one call and receive a function as an argument. This behaviour covers get_and_update/6, update/7, fetch_or_store/6, and get_or_store/6.

By default, Nebulex builds these operations on top of the Nebulex.Adapter.KV primitives (fetch, put, and delete), and the given function runs in the calling process, on the local node. This holds even when the adapter performs the underlying read and write commands on remote nodes.

Because the read and the write are separate commands, the default implementation is not atomic:

• For get_and_update/6 and update/7, concurrent calls on the same key can overwrite each other's changes.

• For fetch_or_store/6 and get_or_store/6, concurrent cache misses on the same key can evaluate the function more than once, and the last write wins.

If atomicity is required and the adapter supports transactions, wrap the call in Nebulex.Cache.transaction/2 locking the key with the :keys option. The lock coordinates only writers that use transactions on the same keys; plain writes are not affected.

This behaviour is required: Nebulex.Cache validates at compile time that the adapter implements it, alongside Nebulex.Adapter and Nebulex.Adapter.KV. Most adapters get it with use Nebulex.Adapter.CompositeKV, which provides the default implementation in this module. An adapter implements the callbacks itself to change where the function runs (e.g., on the node owning the key) or to provide different atomicity guarantees.

Default implementation

use Nebulex.Adapter.CompositeKV declares the behaviour and provides the default implementation for every callback. The callbacks are overridable, so an adapter can override only some of them:

defmodule MyAdapter do
  @behaviour Nebulex.Adapter
  @behaviour Nebulex.Adapter.KV

  use Nebulex.Adapter.CompositeKV

  # Override `get_and_update/6` and `update/7`; the other callbacks
  # fall back to the default implementation.
  @impl true
  def get_and_update(adapter_meta, key, fun, ttl, keep_ttl?, opts) do
    # Adapter-specific implementation ...
  end

  @impl true
  def update(adapter_meta, key, initial, fun, ttl, keep_ttl?, opts) do
    # Adapter-specific implementation ...
  end

  ...
end

Telemetry

Each composite operation is a cache command itself: a Telemetry span with command: :get_and_update, command: :update, command: :fetch_or_store, or command: :get_or_store is emitted. The default implementation runs the primitive commands through Nebulex.Adapter.run_command/4, so each of them emits its own command span as well, and the cache entry events and stats built on those spans are still produced. The shared :telemetry, :telemetry_event, and :telemetry_metadata options apply to the composite command span and are forwarded to the primitive commands.