agency v0.2.0 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

Callbacks

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

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

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

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

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

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

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

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

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

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

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

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

Link to this section Functions

Link to this function

agent!(name, opts \\ [])

View Source

Creates an Agent module.

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

Link to this section Callbacks

Link to this callback

after_get(value)

View Source
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.

Link to this callback

after_get_and_update(value)

View Source
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.

Link to this callback

after_pop(value)

View Source
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.

Link to this callback

after_put(value)

View Source
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.

Link to this callback

after_this(value)

View Source
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.

Link to this callback

after_update(value)

View Source
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.

Link to this callback

before_all(key)

View Source
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.

Link to this callback

before_get(key)

View Source
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.

It should return a modified key. Note that the key here is always represented a list, even if the single value was passed to the interface function.

Link to this callback

before_get_and_update(key)

View Source
before_get_and_update(key) :: key when key: keys()

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

It should return a modified key. Note that the key here is always represented a list, even if the single value was passed to the interface function.

Link to this callback

before_pop(key)

View Source
before_pop(key) :: key when key: keys()

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

It should return a modified key. Note that the key here is always represented a list, even if the single value was passed to the interface function.

Link to this callback

before_put(key)

View Source
before_put(key) :: key when key: keys()

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

It should return a modified key. Note that the key here is always represented a list, even if the single value was passed to the interface function.

Link to this callback

before_update(key)

View Source
before_update(key) :: key when key: keys()

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

It should return a modified key. Note that the key here is always represented a list, even if the single value was passed to the interface function.