Elixir

v1.0.5

Elixir v1.0.5 Agent

Agents are a simple abstraction around state.

Often in Elixir there is a need to share or store state that must be accessed from different processes or by the same process at different points in time.

The Agent module provides a basic server implementation that allows state to be retrieved and updated via a simple API.

Examples

For example, in the Mix tool that ships with Elixir, we need to keep a set of all tasks executed by a given project. Since this set is shared, we can implement it with an Agent:

defmodule Mix.TasksServer do
  def start_link do
    Agent.start_link(fn -> HashSet.new end, name: __MODULE__)
  end

  @doc "Checks if the task has already executed"
  def executed?(task, project) do
    item = {task, project}
    Agent.get(__MODULE__, fn set ->
      item in set
    end)
  end

  @doc "Marks a task as executed"
  def put_task(task, project) do
    item = {task, project}
    Agent.update(__MODULE__, &Set.put(&1, item))
  end
end

Note that agents still provide a segregation between the client and server APIs, as seen in GenServers. In particular, all code inside the function passed to the agent is executed by the agent. This distinction is important because you may want to avoid expensive operations inside the agent, as it will effectively block the agent until the request is fulfilled.

Consider these two examples:

# Compute in the agent/server
def get_something(agent) do
  Agent.get(agent, fn state -> do_something_expensive(state) end)
end

# Compute in the agent/client
def get_something(agent) do
  Agent.get(agent, &(&1)) |> do_something_expensive()
end

The first one blocks the agent while the second one copies all the state to the client and executes the operation in the client. The trade-off here is exactly if the data is small enough to be sent to the client cheaply or large enough to require processing on the server (or at least some initial processing).

Name Registration

An Agent is bound to the same name registration rules as GenServers. Read more about it in the GenServer docs.

A word on distributed agents

It is important to consider the limitations of distributed agents. Agents provides two APIs, one that works with anonymous functions and another that expects explicit module, function and arguments.

In a distributed setup with multiple nodes, the API that accepts anonymous functions only works if the caller (client) and the agent have the same version of the caller module.

Keep in mind this issue also shows up when performing “rolling upgrades” with agents. By rolling upgrades we mean the following situation: you wish to deploy a new version of your software by shutting down some of your nodes and replacing them with nodes running a new version of the software. In this setup, part of your environment will have one version of a given module and the other part another version (the newer one) of the same module.

The best solution is to simply use the explicit module, function and arguments APIs when working with distributed agents.

Hot code swapping

An agent can have its code hot swapped live by simply passing a module, function and args tuple to the update instruction. For example, imagine you have an agent named :sample and you want to convert its inner state from some dict structure to a map. It can be done with the following instruction:

{:update, :sample, {:advanced, {Enum, :into, [%{}]}}}

The agent’s state will be added to the given list as the first argument.

Summary

Types

agent()

The agent reference

name()

The agent name

on_start()

Return values of start* functions

state()

The agent state

Functions

cast(agent, fun)

Performs a cast (fire and forget) operation on the agent state

cast(agent, module, fun, args)

Performs a cast (fire and forget) operation on the agent state

get(agent, fun, timeout \\ 5000)

Gets an agent value via the given function

get(agent, module, fun, args, timeout \\ 5000)

Gets an agent value via the given function

get_and_update(agent, fun, timeout \\ 5000)

Gets and updates the agent state in one operation

get_and_update(agent, module, fun, args, timeout \\ 5000)

Gets and updates the agent state in one operation

start(fun, options \\ [])

Starts an agent process without links (outside of a supervision tree)

start(module, fun, args, options \\ [])

Starts an agent with the given module function and arguments

start_link(fun, options \\ [])

Starts an agent linked to the current process with the given function

start_link(module, fun, args, options \\ [])

Starts an agent linked to the current process with the given module function and arguments

stop(agent, timeout \\ 5000)

Stops the agent

update(agent, fun, timeout \\ 5000)

Updates the agent state

update(agent, module, fun, args, timeout \\ 5000)

Updates the agent state

Types 

agent :: pid | {atom, node} | name

The agent reference

name ::
  atom |
  {:global, term} |
  {:via, module, term}

The agent name

on_start ::
  {:ok, pid} |
  {:error, {:already_started, pid} | term}

Return values of start* functions

state :: term

The agent state

Functions

cast(agent, fun)

Specs

cast(agent, (state -> state)) :: :ok

Performs a cast (fire and forget) operation on the agent state.

The function fun is sent to the agent which invokes the function passing the agent state. The function must return the new state.

Note that cast returns :ok immediately, regardless of whether the destination node or agent exists.

cast(agent, module, fun, args)

Specs

cast(agent, module, atom, [term]) :: :ok

Performs a cast (fire and forget) operation on the agent state.

Same as cast/2 but a module, function and args are expected instead of an anonymous function. The state is added as first argument to the given list of args.

get(agent, fun, timeout \\ 5000)

Specs

get(agent, (state -> a), timeout) :: a when a: var

Gets an agent value via the given function.

The function fun is sent to the agent which invokes the function passing the agent state. The result of the function invocation is returned.

A timeout can also be specified (it has a default value of 5000).

get(agent, module, fun, args, timeout \\ 5000)

Specs

get(agent, module, atom, [term], timeout) :: any

Gets an agent value via the given function.

Same as get/3 but a module, function and args are expected instead of an anonymous function. The state is added as first argument to the given list of args.

get_and_update(agent, fun, timeout \\ 5000)

Specs

get_and_update(agent, (state -> {a, state}), timeout) :: a when a: var

Gets and updates the agent state in one operation.

The function fun is sent to the agent which invokes the function passing the agent state. The function must return a tuple with two elements, the first being the value to return (i.e. the get value) and the second one is the new state.

A timeout can also be specified (it has a default value of 5000).

get_and_update(agent, module, fun, args, timeout \\ 5000)

Specs

get_and_update(agent, module, atom, [term], timeout) :: any

Gets and updates the agent state in one operation.

Same as get_and_update/3 but a module, function and args are expected instead of an anonymous function. The state is added as first argument to the given list of args.

start(fun, options \\ [])

Specs

start((() -> term), GenServer.options) :: on_start

Starts an agent process without links (outside of a supervision tree).

See start_link/2 for more information.

start(module, fun, args, options \\ [])

Specs

start(module, atom, [any], GenServer.options) :: on_start

Starts an agent with the given module function and arguments.

Similar to start/2 but a module, function and args are expected instead of an anonymous function.

start_link(fun, options \\ [])

Specs

start_link((() -> term), GenServer.options) :: on_start

Starts an agent linked to the current process with the given function.

This is often used to start the agent as part of a supervision tree.

Once the agent is spawned, the given function is invoked and its return value is used as the agent state. Note that start_link does not return until the given function has returned.

Options

The :name option is used for registration as described in the module documentation.

If the :timeout option is present, the agent is allowed to spend at most the given number of milliseconds on initialization or it will be terminated and the start function will return {:error, :timeout}.

If the :debug option is present, the corresponding function in the :sys module will be invoked.

If the :spawn_opt option is present, its value will be passed as options to the underlying process as in Process.spawn/4.

Return values

If the server is successfully created and initialized, the function returns {:ok, pid}, where pid is the pid of the server. If there already exists an agent with the specified name, the function returns {:error, {:already_started, pid}} with the pid of that process.

If the given function callback fails with reason, the function returns {:error, reason}.

start_link(module, fun, args, options \\ [])

Specs

start_link(module, atom, [any], GenServer.options) :: on_start

Starts an agent linked to the current process with the given module function and arguments.

Same as start_link/2 but a module, function and args are expected instead of an anonymous function.

stop(agent, timeout \\ 5000)

Specs

stop(agent, timeout) :: :ok

Stops the agent.

Returns :ok if the agent is stopped within the given timeout.

update(agent, fun, timeout \\ 5000)

Specs

update(agent, (state -> state), timeout) :: :ok

Updates the agent state.

The function fun is sent to the agent which invokes the function passing the agent state. The function must return the new state.

A timeout can also be specified (it has a default value of 5000). This function always returns :ok.

update(agent, module, fun, args, timeout \\ 5000)

Specs

update(agent, module, atom, [term], timeout) :: :ok

Updates the agent state.

Same as update/3 but a module, function and args are expected instead of an anonymous function. The state is added as first argument to the given list of args.