agency v0.3.1 Agency behaviour View Source

Agency is an abstraction layer above Agent allowing to use any container supporting Access behind and simplifying the client API handling.

Agency itself implements Access behaviour, making it possible to embed instances in the middle of Access.keys chains.

In a nutshell, Agency backs up the Agent holding a container. All the standard CRUD-like calls are done through containers’ Access implementation, allowing transparent shared access.

The set of before_***/1 and after_***/1 functions are introduced, so that the main Agent feature distinguishing it from the standard GenServer holding state—namely, a separation of client and server APIs—is exposed transparently to the consumers.

Consider the following example.

defmodule MyAgent do
  use Agency, into: %{} # default

  def after_get(value) do
    value + 1
  end

  ...
end

The above code introduces an Agent backing up Map and exposes the standard CRUD-like functionality. After the value would be got from the server API, it’d be increased by 1 and returned to the consumer.

Options

use Agency accepts two options:

name: GenServer.name() the name, this process will be identified by. Optional, if not given the only instance of the Agent is allowed. If given, all the subsequent calls to CRUD functions must include this name as the first parameter. In that case, multiple instances are allowed
into: Access.t() the container to be used by Agent
data: map() | keyword() the static data to be held by the instances

One might also pass any struct, or whatever else implementing Access as into: option to be used as an Agent container.

Link to this section Summary

Types

key()

keys()

keyz()

value()

Functions

agent!(name, opts \\ [])

Creates an Agent module.

Callbacks

after_get(value)

The callback that is called from get/1 right after the Agent has returned the value, passing this value as a parameter.

after_get_and_update(value)

The callback that is called from get_and_update/2 right after the Agent has returned the value, passing this value as a parameter.

after_pop(value)

The callback that is called from pop/1 right after the Agent has returned the value, passing this value as a parameter.

after_put(value)

The callback that is called from put/2 right after the Agent has returned the value, passing this value as a parameter.

after_this(value)

The callback that is called from this/0 right after the Agent has returned the value, passing this value as a parameter.

after_update(value)

The callback that is called from update/2 right after the Agent has returned the value, passing this value as a parameter.

before_all(key)

The callback that is called from all the interface methods (but this/0) right before the Agent is to be called.

before_get(key)

The callback that is called from get/1 right before the Agent is to be called, passing key as an argument.

before_get_and_update(key)

The callback that is called from get_and_update/2 right before the Agent is to be called, passing key as an argument.

before_pop(key)

The callback that is called from pop/1 right before the Agent is to be called, passing key as an argument.

before_put(key)

The callback that is called from put/2 right before the Agent is to be called, passing key as an argument.

before_update(key)

The callback that is called from update/2 right before the Agent is to be called, passing key as an argument.

Link to this section Types

key()

Specs

key() :: any()

keys()

Specs

keys() :: [key()]

keyz()

Specs

keyz() :: key() | keys()

value()

Specs

value() :: any()

Link to this section Functions

agent!(name, opts \\ [])

Creates an Agent module.

If the module is already loaded, this is a no-op.

Link to this section Callbacks

after_get(value)

Specs

after_get(value) :: value when value: value()

The callback that is called from get/1 right after the Agent has returned the value, passing this value as a parameter.

after_get_and_update(value)

Specs

after_get_and_update(value) :: value when value: value()

The callback that is called from get_and_update/2 right after the Agent has returned the value, passing this value as a parameter.

after_pop(value)

Specs

after_pop(value) :: value when value: value()

The callback that is called from pop/1 right after the Agent has returned the value, passing this value as a parameter.

after_put(value)

Specs

after_put(value) :: value when value: value()

The callback that is called from put/2 right after the Agent has returned the value, passing this value as a parameter.

after_this(value)

Specs

after_this(value()) :: Access.t()

The callback that is called from this/0 right after the Agent has returned the value, passing this value as a parameter.

after_update(value)

Specs

after_update(value) :: value when value: value()

The callback that is called from update/2 right after the Agent has returned the value, passing this value as a parameter.

before_all(key)

Specs

before_all(key()) :: key()

The callback that is called from all the interface methods (but this/0) right before the Agent is to be called.

Specific handlers take precedence over this one.

before_get(key)

Specs

before_get(key) :: key when key: keys()

The callback that is called from get/1 right before the Agent is to be called, passing key as an argument.