Nebulex.Adapter behaviour (Nebulex v3.0.0-rc.1)

View Source

Specifies the minimal API required from adapters.

Summary

Types

The metadata returned by the adapter init/1.

Nebulex wrappable error types

t()

Adapter

Callbacks

The callback invoked in case the adapter needs to inject code.

Initializes the adapter supervision tree by returning the children and adapter metadata.

Functions

Builds up a public wrapper function for invoking an adapter command.

Builds up a private wrapper function for invoking an adapter command.

Helper function for handling a Nebulex command response.

Returns the adapter metadata from its init/1 callback.

Convenience function for invoking the adapter running a command.

Types

adapter_meta()

@type adapter_meta() :: %{optional(atom()) => any()}

The metadata returned by the adapter init/1.

It must be a map and Nebulex itself will always inject the following keys into the meta:

  • :cache - The defined cache module.
  • :name - The name of the cache supervisor process.
  • :pid - The PID returned by the child spec returned in init/1.
  • :adapter - The defined cache adapter.
  • :telemetry - Whether Telemetry is enabled or not.
  • :telemetry_prefix – The Telemetry prefix.

nbx_error()

@type nbx_error() :: Nebulex.Error.t() | Nebulex.KeyError.t()

Nebulex wrappable error types

t()

@type t() :: module()

Adapter

Callbacks

__before_compile__(env)

(optional)
@macrocallback __before_compile__(env :: Macro.Env.t()) :: Macro.t()

The callback invoked in case the adapter needs to inject code.

init(config)

@callback init(config :: keyword()) :: {:ok, :supervisor.child_spec(), adapter_meta()}

Initializes the adapter supervision tree by returning the children and adapter metadata.

Functions

defcommand(fun, opts \\ [])

(macro)

Builds up a public wrapper function for invoking an adapter command.

NOTE: Internal purposes only.

defcommandp(fun, opts \\ [])

(macro)

Builds up a private wrapper function for invoking an adapter command.

NOTE: Internal purposes only.

handle_command_response(response)

@spec handle_command_response(ok | {:error, any()}) :: ok | {:error, nbx_error()}
when ok: :ok | {:ok, any()}

Helper function for handling a Nebulex command response.

Examples

iex> Nebulex.Adapter.handle_command_response({:ok, "ok"})
{:ok, "ok"}

iex> Nebulex.Adapter.handle_command_response(:ok)
:ok

iex> Nebulex.Adapter.handle_command_response(
...>   {:error, %Nebulex.Error{reason: :error}}
...> )
{:error, %Nebulex.Error{reason: :error}}

iex> Nebulex.Adapter.handle_command_response({:error, :error})
{:error, %Nebulex.Error{reason: :error}}

iex> Nebulex.Adapter.handle_command_response({:error, %RuntimeError{}})
{:error, %Nebulex.Error{reason: %RuntimeError{}}}

lookup_meta(name_or_pid)

@spec lookup_meta(atom() | pid()) :: adapter_meta()

Returns the adapter metadata from its init/1 callback.

It expects a process name of the cache. The name is either an atom or a PID. For a given cache, you often want to call this function based on the dynamic cache:

Nebulex.Adapter.lookup_meta(cache.get_dynamic_cache())

run_command(adapter_meta, command, args, opts)

@spec run_command(adapter_meta(), atom(), [any()], keyword()) :: any()

Convenience function for invoking the adapter running a command.

NOTE: Internal purposes only.