<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.19.1">
<title>Agent – Elixir v1.7.2</title>
<link rel="stylesheet" href="dist/app-240d7fc7e5.css" />
<link rel="canonical" href="https://hexdocs.pm/elixir/v1.7/Agent.html" />
<script src="dist/sidebar_items-cdf4e58b19.js"></script>
</head>
<body data-type="modules">
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
<div class="main">
<button class="sidebar-button sidebar-toggle">
<span class="icon-menu" aria-hidden="true"></span>
<span class="sr-only">Toggle Sidebar</span>
</button>
<button class="sidebar-button night-mode-toggle">
<span class="icon-theme" aria-hidden="true"></span>
<span class="sr-only">Toggle Theme</span>
</button>
<section class="sidebar">
<a href="http://elixir-lang.org/docs.html" class="sidebar-projectLink">
<div class="sidebar-projectDetails">
<h1 class="sidebar-projectName">
Elixir </h1>
<h2 class="sidebar-projectVersion">
v1.7.2
</h2>
</div>
<img src="assets/logo.png" alt="Elixir" class="sidebar-projectImage">
</a>
<form class="sidebar-search" action="search.html">
<button type="submit" class="search-button">
<span class="icon-search" aria-hidden="true"></span>
</button>
<input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" />
</form>
<ul class="sidebar-listNav">
<li><a id="extras-list" href="#full-list">Pages</a></li>
<li><a id="modules-list" href="#full-list">Modules</a></li>
<li><a id="exceptions-list" href="#full-list">Exceptions</a></li>
</ul>
<div class="gradient"></div>
<ul id="full-list" class="sidebar-fullList"></ul>
</section>
<section class="content">
<div class="content-outer">
<div id="content" class="content-inner">
<h1>
<small class="visible-xs">Elixir v1.7.2</small>
Agent
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L1" title="View Source" class="view-source" rel="help">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</h1>
<section id="moduledoc">
<p>Agents are a simple abstraction around state.</p>
<p>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.</p>
<p>The <a href="Agent.html#content"><code class="inline">Agent</code></a> module provides a basic server implementation that
allows state to be retrieved and updated via a simple API.</p>
<h2 id="module-examples" class="section-heading">
<a href="#module-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<p>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:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">Mix.TasksServer</span><span class="w"> </span><span class="k" data-group-id="0709847524-1">do</span><span class="w">
</span><span class="kn">use</span><span class="w"> </span><span class="nc">Agent</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">start_link</span><span class="p" data-group-id="0709847524-2">(</span><span class="bp">_</span><span class="p" data-group-id="0709847524-2">)</span><span class="w"> </span><span class="k" data-group-id="0709847524-3">do</span><span class="w">
</span><span class="nc">Agent</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="0709847524-4">(</span><span class="k" data-group-id="0709847524-5">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="nc">MapSet</span><span class="o">.</span><span class="n">new</span><span class="w"> </span><span class="k" data-group-id="0709847524-5">end</span><span class="p">,</span><span class="w"> </span><span class="ss">name</span><span class="p">:</span><span class="w"> </span><span class="bp">__MODULE__</span><span class="p" data-group-id="0709847524-4">)</span><span class="w">
</span><span class="k" data-group-id="0709847524-3">end</span><span class="w">
</span><span class="na">@doc</span><span class="w"> </span><span class="s">"Checks if the task has already executed"</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">executed?</span><span class="p" data-group-id="0709847524-6">(</span><span class="n">task</span><span class="p">,</span><span class="w"> </span><span class="n">project</span><span class="p" data-group-id="0709847524-6">)</span><span class="w"> </span><span class="k" data-group-id="0709847524-7">do</span><span class="w">
</span><span class="n">item</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p" data-group-id="0709847524-8">{</span><span class="n">task</span><span class="p">,</span><span class="w"> </span><span class="n">project</span><span class="p" data-group-id="0709847524-8">}</span><span class="w">
</span><span class="nc">Agent</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="0709847524-9">(</span><span class="bp">__MODULE__</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="0709847524-10">fn</span><span class="w"> </span><span class="n">set</span><span class="w"> </span><span class="o">-></span><span class="w">
</span><span class="n">item</span><span class="w"> </span><span class="ow">in</span><span class="w"> </span><span class="n">set</span><span class="w">
</span><span class="k" data-group-id="0709847524-10">end</span><span class="p" data-group-id="0709847524-9">)</span><span class="w">
</span><span class="k" data-group-id="0709847524-7">end</span><span class="w">
</span><span class="na">@doc</span><span class="w"> </span><span class="s">"Marks a task as executed"</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">put_task</span><span class="p" data-group-id="0709847524-11">(</span><span class="n">task</span><span class="p">,</span><span class="w"> </span><span class="n">project</span><span class="p" data-group-id="0709847524-11">)</span><span class="w"> </span><span class="k" data-group-id="0709847524-12">do</span><span class="w">
</span><span class="n">item</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p" data-group-id="0709847524-13">{</span><span class="n">task</span><span class="p">,</span><span class="w"> </span><span class="n">project</span><span class="p" data-group-id="0709847524-13">}</span><span class="w">
</span><span class="nc">Agent</span><span class="o">.</span><span class="n">update</span><span class="p" data-group-id="0709847524-14">(</span><span class="bp">__MODULE__</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="nc">MapSet</span><span class="o">.</span><span class="n">put</span><span class="p" data-group-id="0709847524-15">(</span><span class="ni">&1</span><span class="p">,</span><span class="w"> </span><span class="n">item</span><span class="p" data-group-id="0709847524-15">)</span><span class="p" data-group-id="0709847524-14">)</span><span class="w">
</span><span class="k" data-group-id="0709847524-12">end</span><span class="w">
</span><span class="na">@doc</span><span class="w"> </span><span class="s">"Resets the executed tasks and returns the previous list of tasks"</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">take_all</span><span class="p" data-group-id="0709847524-16">(</span><span class="p" data-group-id="0709847524-16">)</span><span class="w"> </span><span class="k" data-group-id="0709847524-17">do</span><span class="w">
</span><span class="nc">Agent</span><span class="o">.</span><span class="n">get_and_update</span><span class="p" data-group-id="0709847524-18">(</span><span class="bp">__MODULE__</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="0709847524-19">fn</span><span class="w"> </span><span class="n">set</span><span class="w"> </span><span class="o">-></span><span class="w">
</span><span class="p" data-group-id="0709847524-20">{</span><span class="nc">Enum</span><span class="o">.</span><span class="n">into</span><span class="p" data-group-id="0709847524-21">(</span><span class="n">set</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="0709847524-22">[</span><span class="p" data-group-id="0709847524-22">]</span><span class="p" data-group-id="0709847524-21">)</span><span class="p">,</span><span class="w"> </span><span class="nc">MapSet</span><span class="o">.</span><span class="n">new</span><span class="p" data-group-id="0709847524-20">}</span><span class="w">
</span><span class="k" data-group-id="0709847524-19">end</span><span class="p" data-group-id="0709847524-18">)</span><span class="w">
</span><span class="k" data-group-id="0709847524-17">end</span><span class="w">
</span><span class="k" data-group-id="0709847524-1">end</span></code></pre>
<p>Agents provide a segregation between the client and server APIs (similar
to GenServers). In particular, the anonymous functions given to the <a href="Agent.html#content"><code class="inline">Agent</code></a>
are executed inside the agent (the server). This distinction is important
because you may want to avoid expensive operations inside the agent,
as they will effectively block the agent until the request is fulfilled.</p>
<p>Consider these two examples:</p>
<pre><code class="nohighlight makeup elixir"><span class="c1"># Compute in the agent/server</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">get_something</span><span class="p" data-group-id="6421340834-1">(</span><span class="n">agent</span><span class="p" data-group-id="6421340834-1">)</span><span class="w"> </span><span class="k" data-group-id="6421340834-2">do</span><span class="w">
</span><span class="nc">Agent</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="6421340834-3">(</span><span class="n">agent</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="6421340834-4">fn</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">do_something_expensive</span><span class="p" data-group-id="6421340834-5">(</span><span class="n">state</span><span class="p" data-group-id="6421340834-5">)</span><span class="w"> </span><span class="k" data-group-id="6421340834-4">end</span><span class="p" data-group-id="6421340834-3">)</span><span class="w">
</span><span class="k" data-group-id="6421340834-2">end</span><span class="w">
</span><span class="c1"># Compute in the agent/client</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">get_something</span><span class="p" data-group-id="6421340834-6">(</span><span class="n">agent</span><span class="p" data-group-id="6421340834-6">)</span><span class="w"> </span><span class="k" data-group-id="6421340834-7">do</span><span class="w">
</span><span class="nc">Agent</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="6421340834-8">(</span><span class="n">agent</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="p" data-group-id="6421340834-9">(</span><span class="ni">&1</span><span class="p" data-group-id="6421340834-9">)</span><span class="p" data-group-id="6421340834-8">)</span><span class="w"> </span><span class="o">|></span><span class="w"> </span><span class="n">do_something_expensive</span><span class="p" data-group-id="6421340834-10">(</span><span class="p" data-group-id="6421340834-10">)</span><span class="w">
</span><span class="k" data-group-id="6421340834-7">end</span></code></pre>
<p>The first function blocks the agent. The second function copies all the state
to the client and then executes the operation in the client. One aspect to
consider is whether the data is large enough to require processing in the server,
at least initially, or small enough to be sent to the client cheaply. Another
factor is whether the data needs to be processed atomically: getting the
state and calling <code class="inline">do_something_expensive(state)</code> outside of the agent means
that the agent’s state can be updated in the meantime. This is specially
important in case of updates as computing the new state in the client rather
than in the server can lead to race conditions if multiple clients are trying
to update the same state to different values.</p>
<p>Finally note <code class="inline">use Agent</code> defines a <a href="#child_spec/1"><code class="inline">child_spec/1</code></a> function, allowing the
defined module to be put under a supervision tree. The generated
<a href="#child_spec/1"><code class="inline">child_spec/1</code></a> can be customized with the following options:</p>
<ul>
<li><code class="inline">:id</code> - the child specification identifier, defaults to the current module
</li>
<li><code class="inline">:start</code> - how to start the child process (defaults to calling <code class="inline">__MODULE__.start_link/1</code>)
</li>
<li><code class="inline">:restart</code> - when the child should be restarted, defaults to <code class="inline">:permanent</code>
</li>
<li><code class="inline">:shutdown</code> - how to shut down the child
</li>
</ul>
<p>For example:</p>
<pre><code class="nohighlight makeup elixir"><span class="kn">use</span><span class="w"> </span><span class="nc">Agent</span><span class="p">,</span><span class="w"> </span><span class="ss">restart</span><span class="p">:</span><span class="w"> </span><span class="ss">:transient</span><span class="p">,</span><span class="w"> </span><span class="ss">shutdown</span><span class="p">:</span><span class="w"> </span><span class="mi">10_000</span></code></pre>
<p>See the <a href="Supervisor.html"><code class="inline">Supervisor</code></a> docs for more information.</p>
<h2 id="module-name-registration" class="section-heading">
<a href="#module-name-registration" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Name registration
</h2>
<p>An agent is bound to the same name registration rules as GenServers.
Read more about it in the <a href="GenServer.html"><code class="inline">GenServer</code></a> documentation.</p>
<h2 id="module-a-word-on-distributed-agents" class="section-heading">
<a href="#module-a-word-on-distributed-agents" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
A word on distributed agents
</h2>
<p>It is important to consider the limitations of distributed agents. Agents
provide two APIs, one that works with anonymous functions and another
that expects an explicit module, function, and arguments.</p>
<p>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.</p>
<p>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 <em>shutting down</em> 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.</p>
<p>The best solution is to simply use the explicit module, function, and arguments
APIs when working with distributed agents.</p>
<h2 id="module-hot-code-swapping" class="section-heading">
<a href="#module-hot-code-swapping" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Hot code swapping
</h2>
<p>An agent can have its code hot swapped live by simply passing a module,
function, and arguments tuple to the update instruction. For example, imagine
you have an agent named <code class="inline">:sample</code> and you want to convert its inner state
from a keyword list to a map. It can be done with the following
instruction:</p>
<pre><code class="nohighlight makeup elixir"><span class="p" data-group-id="8691157719-1">{</span><span class="ss">:update</span><span class="p">,</span><span class="w"> </span><span class="ss">:sample</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="8691157719-2">{</span><span class="ss">:advanced</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="8691157719-3">{</span><span class="nc">Enum</span><span class="p">,</span><span class="w"> </span><span class="ss">:into</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="8691157719-4">[</span><span class="p" data-group-id="8691157719-5">%{</span><span class="p" data-group-id="8691157719-5">}</span><span class="p" data-group-id="8691157719-4">]</span><span class="p" data-group-id="8691157719-3">}</span><span class="p" data-group-id="8691157719-2">}</span><span class="p" data-group-id="8691157719-1">}</span></code></pre>
<p>The agent’s state will be added to the given list of arguments (<code class="inline">[%{}]</code>) as
the first argument.</p>
</section>
<section id="summary" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#summary">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Summary
</h1>
<div class="summary-types summary">
<h2>
<a href="#types">Types</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:agent/0">agent()</a>
</div>
<div class="summary-synopsis"><p>The agent reference</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:name/0">name()</a>
</div>
<div class="summary-synopsis"><p>The agent name</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:on_start/0">on_start()</a>
</div>
<div class="summary-synopsis"><p>Return values of <code class="inline">start*</code> functions</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:state/0">state()</a>
</div>
<div class="summary-synopsis"><p>The agent state</p>
</div>
</div>
</div>
<div class="summary-functions summary">
<h2>
<a href="#functions">Functions</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#cast/2">cast(agent, fun)</a>
</div>
<div class="summary-synopsis"><p>Performs a cast (<em>fire and forget</em>) operation on the agent state</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#cast/4">cast(agent, module, fun, args)</a>
</div>
<div class="summary-synopsis"><p>Performs a cast (<em>fire and forget</em>) operation on the agent state</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#child_spec/1">child_spec(arg)</a>
</div>
<div class="summary-synopsis"><p>Returns a specification to start an agent under a supervisor</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#get/3">get(agent, fun, timeout \\ 5000)</a>
</div>
<div class="summary-synopsis"><p>Gets an agent value via the given anonymous function</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#get/5">get(agent, module, fun, args, timeout \\ 5000)</a>
</div>
<div class="summary-synopsis"><p>Gets an agent value via the given function</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#get_and_update/3">get_and_update(agent, fun, timeout \\ 5000)</a>
</div>
<div class="summary-synopsis"><p>Gets and updates the agent state in one operation via the given anonymous
function</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#get_and_update/5">get_and_update(agent, module, fun, args, timeout \\ 5000)</a>
</div>
<div class="summary-synopsis"><p>Gets and updates the agent state in one operation via the given function</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#start/2">start(fun, options \\ [])</a>
</div>
<div class="summary-synopsis"><p>Starts an agent process without links (outside of a supervision tree)</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#start/4">start(module, fun, args, options \\ [])</a>
</div>
<div class="summary-synopsis"><p>Starts an agent without links with the given module, function, and arguments</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#start_link/2">start_link(fun, options \\ [])</a>
</div>
<div class="summary-synopsis"><p>Starts an agent linked to the current process with the given function</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#start_link/4">start_link(module, fun, args, options \\ [])</a>
</div>
<div class="summary-synopsis"><p>Starts an agent linked to the current process</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#stop/3">stop(agent, reason \\ :normal, timeout \\ :infinity)</a>
</div>
<div class="summary-synopsis"><p>Synchronously stops the agent with the given <code class="inline">reason</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#update/3">update(agent, fun, timeout \\ 5000)</a>
</div>
<div class="summary-synopsis"><p>Updates the agent state via the given anonymous function</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#update/5">update(agent, module, fun, args, timeout \\ 5000)</a>
</div>
<div class="summary-synopsis"><p>Updates the agent state via the given function</p>
</div>
</div>
</div>
</section>
<section id="types" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#types">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Types
</h1>
<div class="types-list">
<div class="detail" id="t:agent/0">
<div class="detail-header">
<a href="#t:agent/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">agent()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L137" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>agent() :: <a href="typespecs.html#basic-types">pid</a>() | {<a href="typespecs.html#basic-types">atom</a>(), <a href="typespecs.html#built-in-types">node</a>()} | <a href="#t:name/0">name</a>()</pre>
</div>
</div>
<section class="docstring">
<p>The agent reference</p>
</section>
</div>
<div class="detail" id="t:name/0">
<div class="detail-header">
<a href="#t:name/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">name()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L134" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>name() :: <a href="typespecs.html#basic-types">atom</a>() | {:global, <a href="typespecs.html#built-in-types">term</a>()} | {:via, <a href="typespecs.html#built-in-types">module</a>(), <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>The agent name</p>
</section>
</div>
<div class="detail" id="t:on_start/0">
<div class="detail-header">
<a href="#t:on_start/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">on_start()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L131" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>on_start() :: {:ok, <a href="typespecs.html#basic-types">pid</a>()} | {:error, {:already_started, <a href="typespecs.html#basic-types">pid</a>()} | <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Return values of <code class="inline">start*</code> functions</p>
</section>
</div>
<div class="detail" id="t:state/0">
<div class="detail-header">
<a href="#t:state/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">state()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L140" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>state() :: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p>The agent state</p>
</section>
</div>
</div>
</section>
<section id="functions" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#functions">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Functions
</h1>
<div class="detail" id="cast/2">
<div class="detail-header">
<a href="#cast/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">cast(agent, fun)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L394" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>cast(<a href="#t:agent/0">agent</a>(), (<a href="#t:state/0">state</a>() -> <a href="#t:state/0">state</a>())) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Performs a cast (<em>fire and forget</em>) operation on the agent state.</p>
<p>The function <code class="inline">fun</code> is sent to the <code class="inline">agent</code> which invokes the function
passing the agent state. The return value of <code class="inline">fun</code> becomes the new
state of the agent.</p>
<p>Note that <code class="inline">cast</code> returns <code class="inline">:ok</code> immediately, regardless of whether <code class="inline">agent</code> (or
the node it should live on) exists.</p>
</section>
</div>
<div class="detail" id="cast/4">
<div class="detail-header">
<a href="#cast/4" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">cast(agent, module, fun, args)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L406" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>cast(<a href="#t:agent/0">agent</a>(), <a href="typespecs.html#built-in-types">module</a>(), <a href="typespecs.html#basic-types">atom</a>(), [<a href="typespecs.html#built-in-types">term</a>()]) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Performs a cast (<em>fire and forget</em>) operation on the agent state.</p>
<p>Same as <a href="#cast/2"><code class="inline">cast/2</code></a> but a module, function, and arguments are expected
instead of an anonymous function. The state is added as first
argument to the given list of arguments.</p>
</section>
</div>
<div class="detail" id="child_spec/1">
<div class="detail-header">
<a href="#child_spec/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">child_spec(arg)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L148" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(since 1.5.0)</span>
</div>
<section class="docstring">
<p>Returns a specification to start an agent under a supervisor.</p>
<p>See <a href="Supervisor.html"><code class="inline">Supervisor</code></a>.</p>
</section>
</div>
<div class="detail" id="get/3">
<span id="get/2"></span>
<div class="detail-header">
<a href="#get/3" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">get(agent, fun, timeout \\ 5000)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L285" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>get(<a href="#t:agent/0">agent</a>(), (<a href="#t:state/0">state</a>() -> a), <a href="typespecs.html#built-in-types">timeout</a>()) :: a when a: var</pre>
</div>
</div>
<section class="docstring">
<p>Gets an agent value via the given anonymous function.</p>
<p>The function <code class="inline">fun</code> is sent to the <code class="inline">agent</code> which invokes the function
passing the agent state. The result of the function invocation is
returned from this function.</p>
<p><code class="inline">timeout</code> is an integer greater than zero which specifies how many
milliseconds are allowed before the agent executes the function and returns
the result value, or the atom <code class="inline">:infinity</code> to wait indefinitely. If no result
is received within the specified time, the function call fails and the caller
exits.</p>
<h2 id="get/3-examples" class="section-heading">
<a href="#get/3-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="p" data-group-id="3030795111-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">pid</span><span class="p" data-group-id="3030795111-1">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="3030795111-2">(</span><span class="k" data-group-id="3030795111-3">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="mi">42</span><span class="w"> </span><span class="k" data-group-id="3030795111-3">end</span><span class="p" data-group-id="3030795111-2">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="3030795111-4">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="3030795111-5">fn</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="k" data-group-id="3030795111-5">end</span><span class="p" data-group-id="3030795111-4">)</span><span class="w">
</span><span class="mi">42</span></code></pre>
</section>
</div>
<div class="detail" id="get/5">
<span id="get/4"></span>
<div class="detail-header">
<a href="#get/5" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">get(agent, module, fun, args, timeout \\ 5000)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L297" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>get(<a href="#t:agent/0">agent</a>(), <a href="typespecs.html#built-in-types">module</a>(), <a href="typespecs.html#basic-types">atom</a>(), [<a href="typespecs.html#built-in-types">term</a>()], <a href="typespecs.html#built-in-types">timeout</a>()) :: <a href="typespecs.html#basic-types">any</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Gets an agent value via the given function.</p>
<p>Same as <a href="#get/3"><code class="inline">get/3</code></a> but a module, function, and arguments are expected
instead of an anonymous function. The state is added as first
argument to the given list of arguments.</p>
</section>
</div>
<div class="detail" id="get_and_update/3">
<span id="get_and_update/2"></span>
<div class="detail-header">
<a href="#get_and_update/3" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">get_and_update(agent, fun, timeout \\ 5000)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L326" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>get_and_update(<a href="#t:agent/0">agent</a>(), (<a href="#t:state/0">state</a>() -> {a, <a href="#t:state/0">state</a>()}), <a href="typespecs.html#built-in-types">timeout</a>()) :: a when a: var</pre>
</div>
</div>
<section class="docstring">
<p>Gets and updates the agent state in one operation via the given anonymous
function.</p>
<p>The function <code class="inline">fun</code> is sent to the <code class="inline">agent</code> which invokes the function
passing the agent state. The function must return a tuple with two
elements, the first being the value to return (that is, the “get” value)
and the second one being the new state of the agent.</p>
<p><code class="inline">timeout</code> is an integer greater than zero which specifies how many
milliseconds are allowed before the agent executes the function and returns
the result value, or the atom <code class="inline">:infinity</code> to wait indefinitely. If no result
is received within the specified time, the function call fails and the caller
exits.</p>
<h2 id="get_and_update/3-examples" class="section-heading">
<a href="#get_and_update/3-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="p" data-group-id="8257794969-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">pid</span><span class="p" data-group-id="8257794969-1">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="8257794969-2">(</span><span class="k" data-group-id="8257794969-3">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="mi">42</span><span class="w"> </span><span class="k" data-group-id="8257794969-3">end</span><span class="p" data-group-id="8257794969-2">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">get_and_update</span><span class="p" data-group-id="8257794969-4">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="8257794969-5">fn</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="p" data-group-id="8257794969-6">{</span><span class="n">state</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p" data-group-id="8257794969-6">}</span><span class="w"> </span><span class="k" data-group-id="8257794969-5">end</span><span class="p" data-group-id="8257794969-4">)</span><span class="w">
</span><span class="mi">42</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="8257794969-7">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="8257794969-8">fn</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="k" data-group-id="8257794969-8">end</span><span class="p" data-group-id="8257794969-7">)</span><span class="w">
</span><span class="mi">43</span></code></pre>
</section>
</div>
<div class="detail" id="get_and_update/5">
<span id="get_and_update/4"></span>
<div class="detail-header">
<a href="#get_and_update/5" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">get_and_update(agent, module, fun, args, timeout \\ 5000)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L338" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>get_and_update(<a href="#t:agent/0">agent</a>(), <a href="typespecs.html#built-in-types">module</a>(), <a href="typespecs.html#basic-types">atom</a>(), [<a href="typespecs.html#built-in-types">term</a>()], <a href="typespecs.html#built-in-types">timeout</a>()) :: <a href="typespecs.html#basic-types">any</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Gets and updates the agent state in one operation via the given function.</p>
<p>Same as <a href="#get_and_update/3"><code class="inline">get_and_update/3</code></a> but a module, function, and arguments are expected
instead of an anonymous function. The state is added as first
argument to the given list of arguments.</p>
</section>
</div>
<div class="detail" id="start/2">
<span id="start/1"></span>
<div class="detail-header">
<a href="#start/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">start(fun, options \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L250" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>start((() -> <a href="typespecs.html#built-in-types">term</a>()), <a href="GenServer.html#t:options/0">GenServer.options</a>()) :: <a href="#t:on_start/0">on_start</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Starts an agent process without links (outside of a supervision tree).</p>
<p>See <a href="#start_link/2"><code class="inline">start_link/2</code></a> for more information.</p>
<h2 id="start/2-examples" class="section-heading">
<a href="#start/2-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="p" data-group-id="6733496220-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">pid</span><span class="p" data-group-id="6733496220-1">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">start</span><span class="p" data-group-id="6733496220-2">(</span><span class="k" data-group-id="6733496220-3">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="mi">42</span><span class="w"> </span><span class="k" data-group-id="6733496220-3">end</span><span class="p" data-group-id="6733496220-2">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="6733496220-4">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="6733496220-5">fn</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="k" data-group-id="6733496220-5">end</span><span class="p" data-group-id="6733496220-4">)</span><span class="w">
</span><span class="mi">42</span></code></pre>
</section>
</div>
<div class="detail" id="start/4">
<span id="start/3"></span>
<div class="detail-header">
<a href="#start/4" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">start(module, fun, args, options \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L260" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>start(<a href="typespecs.html#built-in-types">module</a>(), <a href="typespecs.html#basic-types">atom</a>(), [<a href="typespecs.html#basic-types">any</a>()], <a href="GenServer.html#t:options/0">GenServer.options</a>()) :: <a href="#t:on_start/0">on_start</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Starts an agent without links with the given module, function, and arguments.</p>
<p>See <a href="#start_link/4"><code class="inline">start_link/4</code></a> for more information.</p>
</section>
</div>
<div class="detail" id="start_link/2">
<span id="start_link/1"></span>
<div class="detail-header">
<a href="#start_link/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">start_link(fun, options \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L221" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>start_link((() -> <a href="typespecs.html#built-in-types">term</a>()), <a href="GenServer.html#t:options/0">GenServer.options</a>()) :: <a href="#t:on_start/0">on_start</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Starts an agent linked to the current process with the given function.</p>
<p>This is often used to start the agent as part of a supervision tree.</p>
<p>Once the agent is spawned, the given function <code class="inline">fun</code> is invoked and its return
value is used as the agent state. Note that <a href="#start_link/2"><code class="inline">start_link/2</code></a> does not return
until the given function has returned.</p>
<h2 id="start_link/2-options" class="section-heading">
<a href="#start_link/2-options" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Options
</h2>
<p>The <code class="inline">:name</code> option is used for registration as described in the module
documentation.</p>
<p>If the <code class="inline">:timeout</code> 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 <code class="inline">{:error, :timeout}</code>.</p>
<p>If the <code class="inline">:debug</code> option is present, the corresponding function in the
<a href="http://www.erlang.org/doc/man/sys.html"><code class="inline">:sys</code> module</a> will be invoked.</p>
<p>If the <code class="inline">:spawn_opt</code> option is present, its value will be passed as options
to the underlying process as in <a href="Process.html#spawn/4"><code class="inline">Process.spawn/4</code></a>.</p>
<h2 id="start_link/2-return-values" class="section-heading">
<a href="#start_link/2-return-values" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Return values
</h2>
<p>If the server is successfully created and initialized, the function returns
<code class="inline">{:ok, pid}</code>, where <code class="inline">pid</code> is the PID of the server. If an agent with the
specified name already exists, the function returns
<code class="inline">{:error, {:already_started, pid}}</code> with the PID of that process.</p>
<p>If the given function callback fails, the function returns <code class="inline">{:error, reason}</code>.</p>
<h2 id="start_link/2-examples" class="section-heading">
<a href="#start_link/2-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="p" data-group-id="1177108323-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">pid</span><span class="p" data-group-id="1177108323-1">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="1177108323-2">(</span><span class="k" data-group-id="1177108323-3">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="mi">42</span><span class="w"> </span><span class="k" data-group-id="1177108323-3">end</span><span class="p" data-group-id="1177108323-2">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="1177108323-4">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="1177108323-5">fn</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="k" data-group-id="1177108323-5">end</span><span class="p" data-group-id="1177108323-4">)</span><span class="w">
</span><span class="mi">42</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="p" data-group-id="1177108323-6">{</span><span class="ss">:error</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1177108323-7">{</span><span class="n">exception</span><span class="p">,</span><span class="w"> </span><span class="c">_stacktrace</span><span class="p" data-group-id="1177108323-7">}</span><span class="p" data-group-id="1177108323-6">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">start</span><span class="p" data-group-id="1177108323-8">(</span><span class="k" data-group-id="1177108323-9">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="k">raise</span><span class="w"> </span><span class="s">"oops"</span><span class="w"> </span><span class="k" data-group-id="1177108323-9">end</span><span class="p" data-group-id="1177108323-8">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="n">exception</span><span class="w">
</span><span class="p" data-group-id="1177108323-10">%</span><span class="nc" data-group-id="1177108323-10">RuntimeError</span><span class="p" data-group-id="1177108323-10">{</span><span class="ss">message</span><span class="p">:</span><span class="w"> </span><span class="s">"oops"</span><span class="p" data-group-id="1177108323-10">}</span></code></pre>
</section>
</div>
<div class="detail" id="start_link/4">
<span id="start_link/3"></span>
<div class="detail-header">
<a href="#start_link/4" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">start_link(module, fun, args, options \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L233" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>start_link(<a href="typespecs.html#built-in-types">module</a>(), <a href="typespecs.html#basic-types">atom</a>(), [<a href="typespecs.html#basic-types">any</a>()], <a href="GenServer.html#t:options/0">GenServer.options</a>()) :: <a href="#t:on_start/0">on_start</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Starts an agent linked to the current process.</p>
<p>Same as <a href="#start_link/2"><code class="inline">start_link/2</code></a> but a module, function, and arguments are expected
instead of an anonymous function; <code class="inline">fun</code> in <code class="inline">module</code> will be called with the
given arguments <code class="inline">args</code> to initialize the state.</p>
</section>
</div>
<div class="detail" id="stop/3">
<span id="stop/1"></span>
<span id="stop/2"></span>
<div class="detail-header">
<a href="#stop/3" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">stop(agent, reason \\ :normal, timeout \\ :infinity)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L429" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>stop(<a href="#t:agent/0">agent</a>(), reason :: <a href="typespecs.html#built-in-types">term</a>(), <a href="typespecs.html#built-in-types">timeout</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Synchronously stops the agent with the given <code class="inline">reason</code>.</p>
<p>It returns <code class="inline">:ok</code> if the agent terminates with the given
reason. If the agent terminates with another reason, the call will
exit.</p>
<p>This function keeps OTP semantics regarding error reporting.
If the reason is any other than <code class="inline">:normal</code>, <code class="inline">:shutdown</code> or
<code class="inline">{:shutdown, _}</code>, an error report will be logged.</p>
<h2 id="stop/3-examples" class="section-heading">
<a href="#stop/3-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="p" data-group-id="8802177470-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">pid</span><span class="p" data-group-id="8802177470-1">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="8802177470-2">(</span><span class="k" data-group-id="8802177470-3">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="mi">42</span><span class="w"> </span><span class="k" data-group-id="8802177470-3">end</span><span class="p" data-group-id="8802177470-2">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">stop</span><span class="p" data-group-id="8802177470-4">(</span><span class="n">pid</span><span class="p" data-group-id="8802177470-4">)</span><span class="w">
</span><span class="ss">:ok</span></code></pre>
</section>
</div>
<div class="detail" id="update/3">
<span id="update/2"></span>
<div class="detail-header">
<a href="#update/3" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">update(agent, fun, timeout \\ 5000)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L367" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>update(<a href="#t:agent/0">agent</a>(), (<a href="#t:state/0">state</a>() -> <a href="#t:state/0">state</a>()), <a href="typespecs.html#built-in-types">timeout</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Updates the agent state via the given anonymous function.</p>
<p>The function <code class="inline">fun</code> is sent to the <code class="inline">agent</code> which invokes the function
passing the agent state. The return value of <code class="inline">fun</code> becomes the new
state of the agent.</p>
<p>This function always returns <code class="inline">:ok</code>.</p>
<p><code class="inline">timeout</code> is an integer greater than zero which specifies how many
milliseconds are allowed before the agent executes the function and returns
the result value, or the atom <code class="inline">:infinity</code> to wait indefinitely. If no result
is received within the specified time, the function call fails and the caller
exits.</p>
<h2 id="update/3-examples" class="section-heading">
<a href="#update/3-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="p" data-group-id="7182047018-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">pid</span><span class="p" data-group-id="7182047018-1">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="7182047018-2">(</span><span class="k" data-group-id="7182047018-3">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="mi">42</span><span class="w"> </span><span class="k" data-group-id="7182047018-3">end</span><span class="p" data-group-id="7182047018-2">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">update</span><span class="p" data-group-id="7182047018-4">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="7182047018-5">fn</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="k" data-group-id="7182047018-5">end</span><span class="p" data-group-id="7182047018-4">)</span><span class="w">
</span><span class="ss">:ok</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Agent</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="7182047018-6">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="7182047018-7">fn</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="k" data-group-id="7182047018-7">end</span><span class="p" data-group-id="7182047018-6">)</span><span class="w">
</span><span class="mi">43</span></code></pre>
</section>
</div>
<div class="detail" id="update/5">
<span id="update/4"></span>
<div class="detail-header">
<a href="#update/5" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">update(agent, module, fun, args, timeout \\ 5000)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/agent.ex#L379" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>update(<a href="#t:agent/0">agent</a>(), <a href="typespecs.html#built-in-types">module</a>(), <a href="typespecs.html#basic-types">atom</a>(), [<a href="typespecs.html#built-in-types">term</a>()], <a href="typespecs.html#built-in-types">timeout</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Updates the agent state via the given function.</p>
<p>Same as <a href="#update/3"><code class="inline">update/3</code></a> but a module, function, and arguments are expected
instead of an anonymous function. The state is added as first
argument to the given list of arguments.</p>
</section>
</div>
</section>
<footer class="footer">
<p>
<span class="line">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener">ExDoc</a> (v0.19.1),
</span>
<span class="line">
designed by
<a href="https://twitter.com/dignifiedquire" target="_blank" rel="noopener" title="@dignifiedquire">Friedel Ziegelmayer</a>.
</span>
</p>
</footer>
</div>
</div>
</section>
</div>
<script src="dist/app-a0c90688fa.js"></script>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
016232f1d9a3f7bee85855d35a2bca58
>
files
>
25
