<!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>GenServer – Elixir v1.7.2</title>
<link rel="stylesheet" href="dist/app-240d7fc7e5.css" />
<link rel="canonical" href="https://hexdocs.pm/elixir/v1.7/GenServer.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>
GenServer <small>behaviour</small>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.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>A behaviour module for implementing the server of a client-server relation.</p>
<p>A GenServer is a process like any other Elixir process and it can be used
to keep state, execute code asynchronously and so on. The advantage of using
a generic server process (GenServer) implemented using this module is that it
will have a standard set of interface functions and include functionality for
tracing and error reporting. It will also fit into a supervision tree.</p>
<h2 id="module-example" class="section-heading">
<a href="#module-example" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Example
</h2>
<p>The GenServer behaviour abstracts the common client-server interaction.
Developers are only required to implement the callbacks and functionality
they are interested in.</p>
<p>Let’s start with a code example and then explore the available callbacks.
Imagine we want a GenServer that works like a stack, allowing us to push
and pop items:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">Stack</span><span class="w"> </span><span class="k" data-group-id="5888378571-1">do</span><span class="w">
</span><span class="kn">use</span><span class="w"> </span><span class="nc">GenServer</span><span class="w">
</span><span class="c1"># Callbacks</span><span class="w">
</span><span class="na">@impl</span><span class="w"> </span><span class="no">true</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">init</span><span class="p" data-group-id="5888378571-2">(</span><span class="n">stack</span><span class="p" data-group-id="5888378571-2">)</span><span class="w"> </span><span class="k" data-group-id="5888378571-3">do</span><span class="w">
</span><span class="p" data-group-id="5888378571-4">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">stack</span><span class="p" data-group-id="5888378571-4">}</span><span class="w">
</span><span class="k" data-group-id="5888378571-3">end</span><span class="w">
</span><span class="na">@impl</span><span class="w"> </span><span class="no">true</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">handle_call</span><span class="p" data-group-id="5888378571-5">(</span><span class="ss">:pop</span><span class="p">,</span><span class="w"> </span><span class="c">_from</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="5888378571-6">[</span><span class="n">head</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">tail</span><span class="p" data-group-id="5888378571-6">]</span><span class="p" data-group-id="5888378571-5">)</span><span class="w"> </span><span class="k" data-group-id="5888378571-7">do</span><span class="w">
</span><span class="p" data-group-id="5888378571-8">{</span><span class="ss">:reply</span><span class="p">,</span><span class="w"> </span><span class="n">head</span><span class="p">,</span><span class="w"> </span><span class="n">tail</span><span class="p" data-group-id="5888378571-8">}</span><span class="w">
</span><span class="k" data-group-id="5888378571-7">end</span><span class="w">
</span><span class="na">@impl</span><span class="w"> </span><span class="no">true</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">handle_cast</span><span class="p" data-group-id="5888378571-9">(</span><span class="p" data-group-id="5888378571-10">{</span><span class="ss">:push</span><span class="p">,</span><span class="w"> </span><span class="n">item</span><span class="p" data-group-id="5888378571-10">}</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="5888378571-9">)</span><span class="w"> </span><span class="k" data-group-id="5888378571-11">do</span><span class="w">
</span><span class="p" data-group-id="5888378571-12">{</span><span class="ss">:noreply</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="5888378571-13">[</span><span class="n">item</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="5888378571-13">]</span><span class="p" data-group-id="5888378571-12">}</span><span class="w">
</span><span class="k" data-group-id="5888378571-11">end</span><span class="w">
</span><span class="k" data-group-id="5888378571-1">end</span><span class="w">
</span><span class="c1"># Start the server</span><span class="w">
</span><span class="p" data-group-id="5888378571-14">{</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="5888378571-14">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">GenServer</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="5888378571-15">(</span><span class="nc">Stack</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="5888378571-16">[</span><span class="ss">:hello</span><span class="p" data-group-id="5888378571-16">]</span><span class="p" data-group-id="5888378571-15">)</span><span class="w">
</span><span class="c1"># This is the client</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">call</span><span class="p" data-group-id="5888378571-17">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="ss">:pop</span><span class="p" data-group-id="5888378571-17">)</span><span class="w">
</span><span class="c1">#=> :hello</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">cast</span><span class="p" data-group-id="5888378571-18">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="5888378571-19">{</span><span class="ss">:push</span><span class="p">,</span><span class="w"> </span><span class="ss">:world</span><span class="p" data-group-id="5888378571-19">}</span><span class="p" data-group-id="5888378571-18">)</span><span class="w">
</span><span class="c1">#=> :ok</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">call</span><span class="p" data-group-id="5888378571-20">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="ss">:pop</span><span class="p" data-group-id="5888378571-20">)</span><span class="w">
</span><span class="c1">#=> :world</span></code></pre>
<p>We start our <code class="inline">Stack</code> by calling <a href="#start_link/2"><code class="inline">start_link/2</code></a>, passing the module
with the server implementation and its initial argument (a list
representing the stack containing the item <code class="inline">:hello</code>). We can primarily
interact with the server by sending two types of messages. <strong>call</strong>
messages expect a reply from the server (and are therefore synchronous)
while <strong>cast</strong> messages do not.</p>
<p>Every time you do a <a href="GenServer.html#call/3"><code class="inline">GenServer.call/3</code></a>, the client will send a message
that must be handled by the <a href="#c:handle_call/3"><code class="inline">handle_call/3</code></a> callback in the GenServer.
A <a href="#cast/2"><code class="inline">cast/2</code></a> message must be handled by <a href="#c:handle_cast/2"><code class="inline">handle_cast/2</code></a>.</p>
<h2 id="module-client-server-apis" class="section-heading">
<a href="#module-client-server-apis" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Client / Server APIs
</h2>
<p>Although in the example above we have used <a href="GenServer.html#start_link/3"><code class="inline">GenServer.start_link/3</code></a> and
friends to directly start and communicate with the server, most of the
time we don’t call the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> functions directly. Instead, we wrap
the calls in new functions representing the public API of the server.</p>
<p>Here is a better implementation of our Stack module:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">Stack</span><span class="w"> </span><span class="k" data-group-id="6934429158-1">do</span><span class="w">
</span><span class="kn">use</span><span class="w"> </span><span class="nc">GenServer</span><span class="w">
</span><span class="c1"># Client</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="6934429158-2">(</span><span class="n">default</span><span class="p" data-group-id="6934429158-2">)</span><span class="w"> </span><span class="ow">when</span><span class="w"> </span><span class="n">is_list</span><span class="p" data-group-id="6934429158-3">(</span><span class="n">default</span><span class="p" data-group-id="6934429158-3">)</span><span class="w"> </span><span class="k" data-group-id="6934429158-4">do</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="6934429158-5">(</span><span class="bp">__MODULE__</span><span class="p">,</span><span class="w"> </span><span class="n">default</span><span class="p" data-group-id="6934429158-5">)</span><span class="w">
</span><span class="k" data-group-id="6934429158-4">end</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">push</span><span class="p" data-group-id="6934429158-6">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="n">item</span><span class="p" data-group-id="6934429158-6">)</span><span class="w"> </span><span class="k" data-group-id="6934429158-7">do</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">cast</span><span class="p" data-group-id="6934429158-8">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="6934429158-9">{</span><span class="ss">:push</span><span class="p">,</span><span class="w"> </span><span class="n">item</span><span class="p" data-group-id="6934429158-9">}</span><span class="p" data-group-id="6934429158-8">)</span><span class="w">
</span><span class="k" data-group-id="6934429158-7">end</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">pop</span><span class="p" data-group-id="6934429158-10">(</span><span class="n">pid</span><span class="p" data-group-id="6934429158-10">)</span><span class="w"> </span><span class="k" data-group-id="6934429158-11">do</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">call</span><span class="p" data-group-id="6934429158-12">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="ss">:pop</span><span class="p" data-group-id="6934429158-12">)</span><span class="w">
</span><span class="k" data-group-id="6934429158-11">end</span><span class="w">
</span><span class="c1"># Server (callbacks)</span><span class="w">
</span><span class="na">@impl</span><span class="w"> </span><span class="no">true</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">init</span><span class="p" data-group-id="6934429158-13">(</span><span class="n">stack</span><span class="p" data-group-id="6934429158-13">)</span><span class="w"> </span><span class="k" data-group-id="6934429158-14">do</span><span class="w">
</span><span class="p" data-group-id="6934429158-15">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">stack</span><span class="p" data-group-id="6934429158-15">}</span><span class="w">
</span><span class="k" data-group-id="6934429158-14">end</span><span class="w">
</span><span class="na">@impl</span><span class="w"> </span><span class="no">true</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">handle_call</span><span class="p" data-group-id="6934429158-16">(</span><span class="ss">:pop</span><span class="p">,</span><span class="w"> </span><span class="c">_from</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="6934429158-17">[</span><span class="n">head</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">tail</span><span class="p" data-group-id="6934429158-17">]</span><span class="p" data-group-id="6934429158-16">)</span><span class="w"> </span><span class="k" data-group-id="6934429158-18">do</span><span class="w">
</span><span class="p" data-group-id="6934429158-19">{</span><span class="ss">:reply</span><span class="p">,</span><span class="w"> </span><span class="n">head</span><span class="p">,</span><span class="w"> </span><span class="n">tail</span><span class="p" data-group-id="6934429158-19">}</span><span class="w">
</span><span class="k" data-group-id="6934429158-18">end</span><span class="w">
</span><span class="na">@impl</span><span class="w"> </span><span class="no">true</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">handle_cast</span><span class="p" data-group-id="6934429158-20">(</span><span class="p" data-group-id="6934429158-21">{</span><span class="ss">:push</span><span class="p">,</span><span class="w"> </span><span class="n">item</span><span class="p" data-group-id="6934429158-21">}</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="6934429158-20">)</span><span class="w"> </span><span class="k" data-group-id="6934429158-22">do</span><span class="w">
</span><span class="p" data-group-id="6934429158-23">{</span><span class="ss">:noreply</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="6934429158-24">[</span><span class="n">item</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="6934429158-24">]</span><span class="p" data-group-id="6934429158-23">}</span><span class="w">
</span><span class="k" data-group-id="6934429158-22">end</span><span class="w">
</span><span class="k" data-group-id="6934429158-1">end</span></code></pre>
<p>In practice, it is common to have both server and client functions in
the same module. If the server and/or client implementations are growing
complex, you may want to have them in different modules.</p>
<h2 id="module-use-genserver-and-callbacks" class="section-heading">
<a href="#module-use-genserver-and-callbacks" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
use GenServer and callbacks
</h2>
<p>There are 7 callbacks to be implemented when you use a <a href="GenServer.html#content"><code class="inline">GenServer</code></a>.
The only required callback is <code class="inline">init/1</code>.</p>
<p><code class="inline">use GenServer</code> also defines a <code class="inline">child_spec/1</code> function, allowing the
defined module to be put under a supervision tree. The generated
<code class="inline">child_spec/1</code> 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">GenServer</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>Both <a href="#start_link/3"><code class="inline">start_link/3</code></a> and <a href="#start/3"><code class="inline">start/3</code></a> support the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> to register
a name on start via the <code class="inline">:name</code> option. Registered names are also
automatically cleaned up on termination. The supported values are:</p>
<ul>
<li><p>an atom - the GenServer is registered locally with the given name
using <a href="Process.html#register/2"><code class="inline">Process.register/2</code></a>.</p>
</li>
<li><p><code class="inline">{:global, term}</code> - the GenServer is registered globally with the given
term using the functions in the <a href="http://www.erlang.org/doc/man/global.html"><code class="inline">:global</code> module</a>.</p>
</li>
<li><p><code class="inline">{:via, module, term}</code> - the GenServer is registered with the given
mechanism and name. The <code class="inline">:via</code> option expects a module that exports
<code class="inline">register_name/2</code>, <code class="inline">unregister_name/1</code>, <code class="inline">whereis_name/1</code> and <a href="Kernel.html#send/2"><code class="inline">send/2</code></a>.
One such example is the <a href="http://www.erlang.org/doc/man/global.html"><code class="inline">:global</code> module</a> which uses these functions
for keeping the list of names of processes and their associated PIDs
that are available globally for a network of Elixir nodes. Elixir also
ships with a local, decentralized and scalable registry called <a href="Registry.html"><code class="inline">Registry</code></a>
for locally storing names that are generated dynamically.</p>
</li>
</ul>
<p>For example, we could start and register our <code class="inline">Stack</code> server locally as follows:</p>
<pre><code class="nohighlight makeup elixir"><span class="c1"># Start the server and register it locally with name MyStack</span><span class="w">
</span><span class="p" data-group-id="8237717950-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="bp">_</span><span class="p" data-group-id="8237717950-1">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">GenServer</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="8237717950-2">(</span><span class="nc">Stack</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="8237717950-3">[</span><span class="ss">:hello</span><span class="p" data-group-id="8237717950-3">]</span><span class="p">,</span><span class="w"> </span><span class="ss">name</span><span class="p">:</span><span class="w"> </span><span class="nc">MyStack</span><span class="p" data-group-id="8237717950-2">)</span><span class="w">
</span><span class="c1"># Now messages can be sent directly to MyStack</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">call</span><span class="p" data-group-id="8237717950-4">(</span><span class="nc">MyStack</span><span class="p">,</span><span class="w"> </span><span class="ss">:pop</span><span class="p" data-group-id="8237717950-4">)</span><span class="w"> </span><span class="c1">#=> :hello</span></code></pre>
<p>Once the server is started, the remaining functions in this module (<a href="#call/3"><code class="inline">call/3</code></a>,
<a href="#cast/2"><code class="inline">cast/2</code></a>, and friends) will also accept an atom, or any <code class="inline">{:global, ...}</code> or
<code class="inline">{:via, ...}</code> tuples. In general, the following formats are supported:</p>
<ul>
<li>a PID
</li>
<li>an atom if the server is locally registered
</li>
<li><code class="inline">{atom, node}</code> if the server is locally registered at another node
</li>
<li><code class="inline">{:global, term}</code> if the server is globally registered
</li>
<li><code class="inline">{:via, module, name}</code> if the server is registered through an alternative
registry
</li>
</ul>
<p>If there is an interest to register dynamic names locally, do not use
atoms, as atoms are never garbage-collected and therefore dynamically
generated atoms won’t be garbage-collected. For such cases, you can
set up your own local registry by using the <a href="Registry.html"><code class="inline">Registry</code></a> module.</p>
<h2 id="module-receiving-regular-messages" class="section-heading">
<a href="#module-receiving-regular-messages" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Receiving “regular” messages
</h2>
<p>The goal of a <a href="GenServer.html#content"><code class="inline">GenServer</code></a> is to abstract the “receive” loop for developers,
automatically handling system messages, supporting code change, synchronous
calls and more. Therefore, you should never call your own “receive” inside
the GenServer callbacks as doing so will cause the GenServer to misbehave.</p>
<p>Besides the synchronous and asynchronous communication provided by <a href="#call/3"><code class="inline">call/3</code></a>
and <a href="#cast/2"><code class="inline">cast/2</code></a>, “regular” messages sent by functions such as <a href="Kernel.html#send/2"><code class="inline">Kernel.send/2</code></a>,
<a href="Process.html#send_after/4"><code class="inline">Process.send_after/4</code></a> and similar, can be handled inside the <a href="#c:handle_info/2"><code class="inline">handle_info/2</code></a>
callback.</p>
<p><a href="#c:handle_info/2"><code class="inline">handle_info/2</code></a> can be used in many situations, such as handling monitor
DOWN messages sent by <a href="Process.html#monitor/1"><code class="inline">Process.monitor/1</code></a>. Another use case for <a href="#c:handle_info/2"><code class="inline">handle_info/2</code></a>
is to perform periodic work, with the help of <a href="Process.html#send_after/4"><code class="inline">Process.send_after/4</code></a>:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">MyApp.Periodically</span><span class="w"> </span><span class="k" data-group-id="8438665029-1">do</span><span class="w">
</span><span class="kn">use</span><span class="w"> </span><span class="nc">GenServer</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">start_link</span><span class="w"> </span><span class="k" data-group-id="8438665029-2">do</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="8438665029-3">(</span><span class="bp">__MODULE__</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="8438665029-4">%{</span><span class="p" data-group-id="8438665029-4">}</span><span class="p" data-group-id="8438665029-3">)</span><span class="w">
</span><span class="k" data-group-id="8438665029-2">end</span><span class="w">
</span><span class="na">@impl</span><span class="w"> </span><span class="no">true</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">init</span><span class="p" data-group-id="8438665029-5">(</span><span class="n">state</span><span class="p" data-group-id="8438665029-5">)</span><span class="w"> </span><span class="k" data-group-id="8438665029-6">do</span><span class="w">
</span><span class="n">schedule_work</span><span class="p" data-group-id="8438665029-7">(</span><span class="p" data-group-id="8438665029-7">)</span><span class="w"> </span><span class="c1"># Schedule work to be performed on start</span><span class="w">
</span><span class="p" data-group-id="8438665029-8">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="8438665029-8">}</span><span class="w">
</span><span class="k" data-group-id="8438665029-6">end</span><span class="w">
</span><span class="na">@impl</span><span class="w"> </span><span class="no">true</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">handle_info</span><span class="p" data-group-id="8438665029-9">(</span><span class="ss">:work</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="8438665029-9">)</span><span class="w"> </span><span class="k" data-group-id="8438665029-10">do</span><span class="w">
</span><span class="c1"># Do the desired work here</span><span class="w">
</span><span class="n">schedule_work</span><span class="p" data-group-id="8438665029-11">(</span><span class="p" data-group-id="8438665029-11">)</span><span class="w"> </span><span class="c1"># Reschedule once more</span><span class="w">
</span><span class="p" data-group-id="8438665029-12">{</span><span class="ss">:noreply</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="8438665029-12">}</span><span class="w">
</span><span class="k" data-group-id="8438665029-10">end</span><span class="w">
</span><span class="kd">defp</span><span class="w"> </span><span class="nf">schedule_work</span><span class="p" data-group-id="8438665029-13">(</span><span class="p" data-group-id="8438665029-13">)</span><span class="w"> </span><span class="k" data-group-id="8438665029-14">do</span><span class="w">
</span><span class="nc">Process</span><span class="o">.</span><span class="n">send_after</span><span class="p" data-group-id="8438665029-15">(</span><span class="n">self</span><span class="p" data-group-id="8438665029-16">(</span><span class="p" data-group-id="8438665029-16">)</span><span class="p">,</span><span class="w"> </span><span class="ss">:work</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="mi">60</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="mi">60</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="mi">1000</span><span class="p" data-group-id="8438665029-15">)</span><span class="w"> </span><span class="c1"># In 2 hours</span><span class="w">
</span><span class="k" data-group-id="8438665029-14">end</span><span class="w">
</span><span class="k" data-group-id="8438665029-1">end</span></code></pre>
<h2 id="module-when-not-to-use-a-genserver" class="section-heading">
<a href="#module-when-not-to-use-a-genserver" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
When (not) to use a GenServer
</h2>
<p>So far, we have learned that a <a href="GenServer.html#content"><code class="inline">GenServer</code></a> can be used as a supervised process
that handles sync and async calls. It can also handle system messages, such as
periodic messages and monitoring events. GenServer processes may also be named.</p>
<p>A GenServer, or a process in general, must be used to model runtime characteristics
of your system. A GenServer must never be used for code organization purposes.</p>
<p>In Elixir, code organization is done by modules and functions, processes are not
necessary. For example, imagine you are implementing a calculator and you decide
to put all the calculator operations behind a GenServer:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">def</span><span class="w"> </span><span class="nf">add</span><span class="p" data-group-id="9946793839-1">(</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p" data-group-id="9946793839-1">)</span><span class="w"> </span><span class="k" data-group-id="9946793839-2">do</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">call</span><span class="p" data-group-id="9946793839-3">(</span><span class="bp">__MODULE__</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="9946793839-4">{</span><span class="ss">:add</span><span class="p">,</span><span class="w"> </span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p" data-group-id="9946793839-4">}</span><span class="p" data-group-id="9946793839-3">)</span><span class="w">
</span><span class="k" data-group-id="9946793839-2">end</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">handle_call</span><span class="p" data-group-id="9946793839-5">(</span><span class="p" data-group-id="9946793839-6">{</span><span class="ss">:add</span><span class="p">,</span><span class="w"> </span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p" data-group-id="9946793839-6">}</span><span class="p">,</span><span class="w"> </span><span class="c">_from</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="9946793839-5">)</span><span class="w"> </span><span class="k" data-group-id="9946793839-7">do</span><span class="w">
</span><span class="p" data-group-id="9946793839-8">{</span><span class="ss">:reply</span><span class="p">,</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">b</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="9946793839-8">}</span><span class="w">
</span><span class="k" data-group-id="9946793839-7">end</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">handle_call</span><span class="p" data-group-id="9946793839-9">(</span><span class="p" data-group-id="9946793839-10">{</span><span class="ss">:subtract</span><span class="p">,</span><span class="w"> </span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p" data-group-id="9946793839-10">}</span><span class="p">,</span><span class="w"> </span><span class="c">_from</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="9946793839-9">)</span><span class="w"> </span><span class="k" data-group-id="9946793839-11">do</span><span class="w">
</span><span class="p" data-group-id="9946793839-12">{</span><span class="ss">:reply</span><span class="p">,</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">b</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="9946793839-12">}</span><span class="w">
</span><span class="k" data-group-id="9946793839-11">end</span></code></pre>
<p>This is an anti-pattern not only because it convolutes the calculator logic but
also because you put the calculator logic behind a single process that will
potentially become a bottleneck in your system, especially as the number of
calls grow. Instead just define the functions directly:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">def</span><span class="w"> </span><span class="nf">add</span><span class="p" data-group-id="0202622135-1">(</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p" data-group-id="0202622135-1">)</span><span class="w"> </span><span class="k" data-group-id="0202622135-2">do</span><span class="w">
</span><span class="n">a</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">b</span><span class="w">
</span><span class="k" data-group-id="0202622135-2">end</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">subtract</span><span class="p" data-group-id="0202622135-3">(</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p" data-group-id="0202622135-3">)</span><span class="w"> </span><span class="k" data-group-id="0202622135-4">do</span><span class="w">
</span><span class="n">a</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">b</span><span class="w">
</span><span class="k" data-group-id="0202622135-4">end</span></code></pre>
<p>If you don’t need a process, then you don’t need a process. Use processes only to
model runtime properties, such as mutable state, concurrency and failures, never
for code organization.</p>
<h2 id="module-debugging-with-the-sys-module" class="section-heading">
<a href="#module-debugging-with-the-sys-module" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Debugging with the :sys module
</h2>
<p>GenServers, as <a href="http://erlang.org/doc/design_principles/spec_proc.html">special processes</a>,
can be debugged using the <a href="http://www.erlang.org/doc/man/sys.html"><code class="inline">:sys</code> module</a>.
Through various hooks, this module allows developers to introspect the state of
the process and trace system events that happen during its execution, such as
received messages, sent replies and state changes.</p>
<p>Let’s explore the basic functions from the
<a href="http://www.erlang.org/doc/man/sys.html"><code class="inline">:sys</code> module</a> used for debugging:</p>
<ul>
<li><a href="http://www.erlang.org/doc/man/sys.html#get_state-2"><code class="inline">:sys.get_state/2</code></a> - allows retrieval of the state of the process.
In the case of a GenServer process, it will be the callback module state,
as passed into the callback functions as last argument.
</li>
<li><a href="http://www.erlang.org/doc/man/sys.html#get_status-2"><code class="inline">:sys.get_status/2</code></a> - allows retrieval of the status of the process.
This status includes the process dictionary, if the process is running
or is suspended, the parent PID, the debugger state, and the state of
the behaviour module, which includes the callback module state
(as returned by <a href="http://www.erlang.org/doc/man/sys.html#get_state-2"><code class="inline">:sys.get_state/2</code></a>). It’s possible to change how this
status is represented by defining the optional <a href="GenServer.html#c:format_status/2"><code class="inline">GenServer.format_status/2</code></a>
callback.
</li>
<li><a href="http://www.erlang.org/doc/man/sys.html#trace-3"><code class="inline">:sys.trace/3</code></a> - prints all the system events to <code class="inline">:stdio</code>.
</li>
<li><a href="http://www.erlang.org/doc/man/sys.html#statistics-3"><code class="inline">:sys.statistics/3</code></a> - manages collection of process statistics.
</li>
<li><a href="http://www.erlang.org/doc/man/sys.html#no_debug-2"><code class="inline">:sys.no_debug/2</code></a> - turns off all debug handlers for the given process.
It is very important to switch off debugging once we’re done. Excessive
debug handlers or those that should be turned off, but weren’t, can
seriously damage the performance of the system.
</li>
<li><a href="http://www.erlang.org/doc/man/sys.html#suspend-2"><code class="inline">:sys.suspend/2</code></a> - allows to suspend a process so that it only
replies to system messages but no other messages. A suspended process
can be reactivated via <a href="http://www.erlang.org/doc/man/sys.html#resume-2"><code class="inline">:sys.resume/2</code></a>.
</li>
</ul>
<p>Let’s see how we could use those functions for debugging the stack server
we defined earlier.</p>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="p" data-group-id="1444747549-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="1444747549-1">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Stack</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="1444747549-2">(</span><span class="p" data-group-id="1444747549-3">[</span><span class="p" data-group-id="1444747549-3">]</span><span class="p" data-group-id="1444747549-2">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="ss">:sys</span><span class="o">.</span><span class="n">statistics</span><span class="p" data-group-id="1444747549-4">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="no">true</span><span class="p" data-group-id="1444747549-4">)</span><span class="w"> </span><span class="c1"># turn on collecting process statistics</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="ss">:sys</span><span class="o">.</span><span class="n">trace</span><span class="p" data-group-id="1444747549-5">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="no">true</span><span class="p" data-group-id="1444747549-5">)</span><span class="w"> </span><span class="c1"># turn on event printing</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Stack</span><span class="o">.</span><span class="n">push</span><span class="p" data-group-id="1444747549-6">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p" data-group-id="1444747549-6">)</span><span class="w">
</span><span class="o">*</span><span class="nc">DBG</span><span class="o">*</span><span class="w"> </span><span class="o"><</span><span class="mf">0.122</span><span class="o">.</span><span class="mi">0</span><span class="o">></span><span class="w"> </span><span class="n">got</span><span class="w"> </span><span class="n">cast</span><span class="w"> </span><span class="p" data-group-id="1444747549-7">{</span><span class="n">push</span><span class="p">,</span><span class="mi">1</span><span class="p" data-group-id="1444747549-7">}</span><span class="w">
</span><span class="o">*</span><span class="nc">DBG</span><span class="o">*</span><span class="w"> </span><span class="o"><</span><span class="mf">0.122</span><span class="o">.</span><span class="mi">0</span><span class="o">></span><span class="w"> </span><span class="n">new</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="p" data-group-id="1444747549-8">[</span><span class="mi">1</span><span class="p" data-group-id="1444747549-8">]</span><span class="w">
</span><span class="ss">:ok</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="ss">:sys</span><span class="o">.</span><span class="n">get_state</span><span class="p" data-group-id="1444747549-9">(</span><span class="n">pid</span><span class="p" data-group-id="1444747549-9">)</span><span class="w">
</span><span class="p" data-group-id="1444747549-10">[</span><span class="mi">1</span><span class="p" data-group-id="1444747549-10">]</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Stack</span><span class="o">.</span><span class="n">pop</span><span class="p" data-group-id="1444747549-11">(</span><span class="n">pid</span><span class="p" data-group-id="1444747549-11">)</span><span class="w">
</span><span class="o">*</span><span class="nc">DBG</span><span class="o">*</span><span class="w"> </span><span class="o"><</span><span class="mf">0.122</span><span class="o">.</span><span class="mi">0</span><span class="o">></span><span class="w"> </span><span class="n">got</span><span class="w"> </span><span class="n">call</span><span class="w"> </span><span class="n">pop</span><span class="w"> </span><span class="n">from</span><span class="w"> </span><span class="o"><</span><span class="mf">0.80</span><span class="o">.</span><span class="mi">0</span><span class="o">></span><span class="w">
</span><span class="o">*</span><span class="nc">DBG</span><span class="o">*</span><span class="w"> </span><span class="o"><</span><span class="mf">0.122</span><span class="o">.</span><span class="mi">0</span><span class="o">></span><span class="w"> </span><span class="n">sent</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="o"><</span><span class="mf">0.80</span><span class="o">.</span><span class="mi">0</span><span class="o">></span><span class="p">,</span><span class="w"> </span><span class="n">new</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="p" data-group-id="1444747549-12">[</span><span class="p" data-group-id="1444747549-12">]</span><span class="w">
</span><span class="mi">1</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="ss">:sys</span><span class="o">.</span><span class="n">statistics</span><span class="p" data-group-id="1444747549-13">(</span><span class="n">pid</span><span class="p">,</span><span class="w"> </span><span class="ss">:get</span><span class="p" data-group-id="1444747549-13">)</span><span class="w">
</span><span class="p" data-group-id="1444747549-14">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w">
</span><span class="p" data-group-id="1444747549-15">[</span><span class="ss">start_time</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="1444747549-16">{</span><span class="p" data-group-id="1444747549-17">{</span><span class="mi">2016</span><span class="p">,</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span><span class="w"> </span><span class="mi">16</span><span class="p" data-group-id="1444747549-17">}</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1444747549-18">{</span><span class="mi">12</span><span class="p">,</span><span class="w"> </span><span class="mi">29</span><span class="p">,</span><span class="w"> </span><span class="mi">41</span><span class="p" data-group-id="1444747549-18">}</span><span class="p" data-group-id="1444747549-16">}</span><span class="p">,</span><span class="w">
</span><span class="ss">current_time</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="1444747549-19">{</span><span class="p" data-group-id="1444747549-20">{</span><span class="mi">2016</span><span class="p">,</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span><span class="w"> </span><span class="mi">16</span><span class="p" data-group-id="1444747549-20">}</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1444747549-21">{</span><span class="mi">12</span><span class="p">,</span><span class="w"> </span><span class="mi">29</span><span class="p">,</span><span class="w"> </span><span class="mi">50</span><span class="p" data-group-id="1444747549-21">}</span><span class="p" data-group-id="1444747549-19">}</span><span class="p">,</span><span class="w">
</span><span class="ss">reductions</span><span class="p">:</span><span class="w"> </span><span class="mi">117</span><span class="p">,</span><span class="w"> </span><span class="ss">messages_in</span><span class="p">:</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="ss">messages_out</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p" data-group-id="1444747549-15">]</span><span class="p" data-group-id="1444747549-14">}</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="ss">:sys</span><span class="o">.</span><span class="n">no_debug</span><span class="p" data-group-id="1444747549-22">(</span><span class="n">pid</span><span class="p" data-group-id="1444747549-22">)</span><span class="w"> </span><span class="c1"># turn off all debug handlers</span><span class="w">
</span><span class="ss">:ok</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="ss">:sys</span><span class="o">.</span><span class="n">get_status</span><span class="p" data-group-id="1444747549-23">(</span><span class="n">pid</span><span class="p" data-group-id="1444747549-23">)</span><span class="w">
</span><span class="p" data-group-id="1444747549-24">{</span><span class="ss">:status</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1444747549-25">#</span><span class="nc" data-group-id="1444747549-25">PID</span><span class="p" data-group-id="1444747549-25"><</span><span class="mf">0.122</span><span class="o">.</span><span class="mi">0</span><span class="p" data-group-id="1444747549-25">></span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1444747549-26">{</span><span class="ss">:module</span><span class="p">,</span><span class="w"> </span><span class="ss">:gen_server</span><span class="p" data-group-id="1444747549-26">}</span><span class="p">,</span><span class="w">
</span><span class="p" data-group-id="1444747549-27">[</span><span class="p" data-group-id="1444747549-28">[</span><span class="ss">"$initial_call"</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="1444747549-29">{</span><span class="nc">Stack</span><span class="p">,</span><span class="w"> </span><span class="ss">:init</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p" data-group-id="1444747549-29">}</span><span class="p">,</span><span class="w"> </span><span class="c1"># pdict</span><span class="w">
</span><span class="ss">"$ancestors"</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="1444747549-30">[</span><span class="p" data-group-id="1444747549-31">#</span><span class="nc" data-group-id="1444747549-31">PID</span><span class="p" data-group-id="1444747549-31"><</span><span class="mf">0.80</span><span class="o">.</span><span class="mi">0</span><span class="p" data-group-id="1444747549-31">></span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1444747549-32">#</span><span class="nc" data-group-id="1444747549-32">PID</span><span class="p" data-group-id="1444747549-32"><</span><span class="mf">0.51</span><span class="o">.</span><span class="mi">0</span><span class="p" data-group-id="1444747549-32">></span><span class="p" data-group-id="1444747549-30">]</span><span class="p" data-group-id="1444747549-28">]</span><span class="p">,</span><span class="w">
</span><span class="ss">:running</span><span class="p">,</span><span class="w"> </span><span class="c1"># :running | :suspended</span><span class="w">
</span><span class="p" data-group-id="1444747549-33">#</span><span class="nc" data-group-id="1444747549-33">PID</span><span class="p" data-group-id="1444747549-33"><</span><span class="mf">0.80</span><span class="o">.</span><span class="mi">0</span><span class="p" data-group-id="1444747549-33">></span><span class="p">,</span><span class="w"> </span><span class="c1"># parent</span><span class="w">
</span><span class="p" data-group-id="1444747549-34">[</span><span class="p" data-group-id="1444747549-34">]</span><span class="p">,</span><span class="w"> </span><span class="c1"># debugger state</span><span class="w">
</span><span class="p" data-group-id="1444747549-35">[</span><span class="ss">header</span><span class="p">:</span><span class="w"> </span><span class="sc">'Status for generic server <0.122.0>'</span><span class="p">,</span><span class="w"> </span><span class="c1"># module status</span><span class="w">
</span><span class="ss">data</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="1444747549-36">[</span><span class="p" data-group-id="1444747549-37">{</span><span class="sc">'Status'</span><span class="p">,</span><span class="w"> </span><span class="ss">:running</span><span class="p" data-group-id="1444747549-37">}</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1444747549-38">{</span><span class="sc">'Parent'</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1444747549-39">#</span><span class="nc" data-group-id="1444747549-39">PID</span><span class="p" data-group-id="1444747549-39"><</span><span class="mf">0.80</span><span class="o">.</span><span class="mi">0</span><span class="p" data-group-id="1444747549-39">></span><span class="p" data-group-id="1444747549-38">}</span><span class="p">,</span><span class="w">
</span><span class="p" data-group-id="1444747549-40">{</span><span class="sc">'Logged events'</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1444747549-41">[</span><span class="p" data-group-id="1444747549-41">]</span><span class="p" data-group-id="1444747549-40">}</span><span class="p" data-group-id="1444747549-36">]</span><span class="p">,</span><span class="w"> </span><span class="ss">data</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="1444747549-42">[</span><span class="p" data-group-id="1444747549-43">{</span><span class="sc">'State'</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1444747549-44">[</span><span class="mi">1</span><span class="p" data-group-id="1444747549-44">]</span><span class="p" data-group-id="1444747549-43">}</span><span class="p" data-group-id="1444747549-42">]</span><span class="p" data-group-id="1444747549-35">]</span><span class="p" data-group-id="1444747549-27">]</span><span class="p" data-group-id="1444747549-24">}</span></code></pre>
<h2 id="module-learn-more" class="section-heading">
<a href="#module-learn-more" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Learn more
</h2>
<p>If you wish to find out more about GenServers, the Elixir Getting Started
guide provides a tutorial-like introduction. The documentation and links
in Erlang can also provide extra insight.</p>
<ul>
<li><a href="http://elixir-lang.org/getting-started/mix-otp/genserver.html">GenServer – Elixir’s Getting Started Guide</a>
</li>
<li><a href="http://www.erlang.org/doc/man/gen_server.html"><code class="inline">:gen_server</code> module documentation</a>
</li>
<li><a href="http://www.erlang.org/doc/design_principles/gen_server_concepts.html">gen_server Behaviour – OTP Design Principles</a>
</li>
<li><a href="http://learnyousomeerlang.com/clients-and-servers">Clients and Servers – Learn You Some Erlang for Great Good!</a>
</li>
</ul>
</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:debug/0">debug()</a>
</div>
<div class="summary-synopsis"><p>Debug options supported by the <code class="inline">start*</code> functions</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:from/0">from()</a>
</div>
<div class="summary-synopsis"><p>Tuple describing the client of a call request</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 GenServer 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:option/0">option()</a>
</div>
<div class="summary-synopsis"><p>Option values used by the <code class="inline">start*</code> functions</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:options/0">options()</a>
</div>
<div class="summary-synopsis"><p>Options used by the <code class="inline">start*</code> functions</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:server/0">server()</a>
</div>
<div class="summary-synopsis"><p>The server reference</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="#abcast/3">abcast(nodes \\ [node() | Node.list()], name, request)</a>
</div>
<div class="summary-synopsis"><p>Casts all servers locally registered as <code class="inline">name</code> at the specified nodes</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#call/3">call(server, request, timeout \\ 5000)</a>
</div>
<div class="summary-synopsis"><p>Makes a synchronous call to the <code class="inline">server</code> and waits for its reply</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#cast/2">cast(server, request)</a>
</div>
<div class="summary-synopsis"><p>Sends an asynchronous request to the <code class="inline">server</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#multi_call/4">multi_call(nodes \\ [node() | Node.list()], name, request, timeout \\ :infinity)</a>
</div>
<div class="summary-synopsis"><p>Calls all servers locally registered as <code class="inline">name</code> at the specified <code class="inline">nodes</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#reply/2">reply(client, reply)</a>
</div>
<div class="summary-synopsis"><p>Replies to a client</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#start/3">start(module, args, options \\ [])</a>
</div>
<div class="summary-synopsis"><p>Starts a <a href="GenServer.html#content"><code class="inline">GenServer</code></a> process without links (outside of a supervision tree)</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#start_link/3">start_link(module, args, options \\ [])</a>
</div>
<div class="summary-synopsis"><p>Starts a <a href="GenServer.html#content"><code class="inline">GenServer</code></a> process linked to the current process</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#stop/3">stop(server, reason \\ :normal, timeout \\ :infinity)</a>
</div>
<div class="summary-synopsis"><p>Synchronously stops the server with the given <code class="inline">reason</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#whereis/1">whereis(server)</a>
</div>
<div class="summary-synopsis"><p>Returns the <code class="inline">pid</code> or <code class="inline">{name, node}</code> of a GenServer process, or <code class="inline">nil</code> if
no process is associated with the given <code class="inline">server</code></p>
</div>
</div>
</div>
<div class="summary-callbacks summary">
<h2>
<a href="#callbacks">Callbacks</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:code_change/3">code_change(old_vsn, state, extra)</a>
</div>
<div class="summary-synopsis"><p>Invoked to change the state of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> when a different version of a
module is loaded (hot code swapping) and the state’s term structure should be
changed</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:format_status/2">format_status(reason, pdict_and_state)</a>
</div>
<div class="summary-synopsis"><p>Invoked in some cases to retrieve a formatted version of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> status</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:handle_call/3">handle_call(request, from, state)</a>
</div>
<div class="summary-synopsis"><p>Invoked to handle synchronous <a href="#call/3"><code class="inline">call/3</code></a> messages. <a href="#call/3"><code class="inline">call/3</code></a> will block until a
reply is received (unless the call times out or nodes are disconnected)</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:handle_cast/2">handle_cast(request, state)</a>
</div>
<div class="summary-synopsis"><p>Invoked to handle asynchronous <a href="#cast/2"><code class="inline">cast/2</code></a> messages</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:handle_continue/2">handle_continue(continue, state)</a>
</div>
<div class="summary-synopsis"><p>Invoked to handle <code class="inline">continue</code> instructions</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:handle_info/2">handle_info(msg, state)</a>
</div>
<div class="summary-synopsis"><p>Invoked to handle all other messages</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:init/1">init(args)</a>
</div>
<div class="summary-synopsis"><p>Invoked when the server is started. <a href="#start_link/3"><code class="inline">start_link/3</code></a> or <a href="#start/3"><code class="inline">start/3</code></a> will
block until it returns</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:terminate/2">terminate(reason, state)</a>
</div>
<div class="summary-synopsis"><p>Invoked when the server is about to exit. It should do any cleanup required</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:debug/0">
<div class="detail-header">
<a href="#t:debug/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">debug()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L645" 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>debug() :: [:trace | :log | :statistics | {:log_to_file, <a href="Path.html#t:t/0">Path.t</a>()}]</pre>
</div>
</div>
<section class="docstring">
<p>Debug options supported by the <code class="inline">start*</code> functions</p>
</section>
</div>
<div class="detail" id="t:from/0">
<div class="detail-header">
<a href="#t:from/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">from()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L656" 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>from() :: {<a href="typespecs.html#basic-types">pid</a>(), tag :: <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Tuple describing the client of a call request.</p>
<p><code class="inline">pid</code> is the PID of the caller and <code class="inline">tag</code> is a unique term used to identify the
call.</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/gen_server.ex#L632" 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 GenServer 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/gen_server.ex#L629" 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>()} | :ignore | {: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:option/0">
<div class="detail-header">
<a href="#t:option/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">option()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L638" 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>option() ::
{:debug, <a href="#t:debug/0">debug</a>()}
| {:name, <a href="#t:name/0">name</a>()}
| {:timeout, <a href="typespecs.html#built-in-types">timeout</a>()}
| {:spawn_opt, <a href="Process.html#t:spawn_opt/0">Process.spawn_opt</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Option values used by the <code class="inline">start*</code> functions</p>
</section>
</div>
<div class="detail" id="t:options/0">
<div class="detail-header">
<a href="#t:options/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">options()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L635" 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>options() :: [<a href="#t:option/0">option</a>()]</pre>
</div>
</div>
<section class="docstring">
<p>Options used by the <code class="inline">start*</code> functions</p>
</section>
</div>
<div class="detail" id="t:server/0">
<div class="detail-header">
<a href="#t:server/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">server()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L648" 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>server() :: <a href="typespecs.html#basic-types">pid</a>() | <a href="#t:name/0">name</a>() | {<a href="typespecs.html#basic-types">atom</a>(), <a href="typespecs.html#built-in-types">node</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>The server reference</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="abcast/3">
<span id="abcast/2"></span>
<div class="detail-header">
<a href="#abcast/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">abcast(nodes \\ [node() | Node.list()], name, request)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L982" 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>abcast([<a href="typespecs.html#built-in-types">node</a>()], name :: <a href="typespecs.html#basic-types">atom</a>(), <a href="typespecs.html#built-in-types">term</a>()) :: :abcast</pre>
</div>
</div>
<section class="docstring">
<p>Casts all servers locally registered as <code class="inline">name</code> at the specified nodes.</p>
<p>This function returns immediately and ignores nodes that do not exist, or where the
server name does not exist.</p>
<p>See <a href="#multi_call/4"><code class="inline">multi_call/4</code></a> for more information.</p>
</section>
</div>
<div class="detail" id="call/3">
<span id="call/2"></span>
<div class="detail-header">
<a href="#call/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">call(server, request, timeout \\ 5000)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L911" 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>call(<a href="#t:server/0">server</a>(), <a href="typespecs.html#built-in-types">term</a>(), <a href="typespecs.html#built-in-types">timeout</a>()) :: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Makes a synchronous call to the <code class="inline">server</code> and waits for its reply.</p>
<p>The client sends the given <code class="inline">request</code> to the server and waits until a reply
arrives or a timeout occurs. <a href="#c:handle_call/3"><code class="inline">handle_call/3</code></a> will be called on the server
to handle the request.</p>
<p><code class="inline">server</code> can be any of the values described in the “Name registration”
section of the documentation for this module.</p>
<h2 id="call/3-timeouts" class="section-heading">
<a href="#call/3-timeouts" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Timeouts
</h2>
<p><code class="inline">timeout</code> is an integer greater than zero which specifies how many
milliseconds to wait for a reply, or the atom <code class="inline">:infinity</code> to wait
indefinitely. The default value is <code class="inline">5000</code>. If no reply is received within
the specified time, the function call fails and the caller exits. If the
caller catches the failure and continues running, and the server is just late
with the reply, it may arrive at any time later into the caller’s message
queue. The caller must in this case be prepared for this and discard any such
garbage messages that are two-element tuples with a reference as the first
element.</p>
</section>
</div>
<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(server, request)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L971" 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:server/0">server</a>(), <a href="typespecs.html#built-in-types">term</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Sends an asynchronous request to the <code class="inline">server</code>.</p>
<p>This function always returns <code class="inline">:ok</code> regardless of whether
the destination <code class="inline">server</code> (or node) exists. Therefore it
is unknown whether the destination <code class="inline">server</code> successfully
handled the message.</p>
<p><a href="#c:handle_cast/2"><code class="inline">handle_cast/2</code></a> will be called on the server to handle
the request. In case the <code class="inline">server</code> is on a node which is
not yet connected to the caller one, the call is going to
block until a connection happens. This is different than
the behaviour in OTP’s <code class="inline">:gen_server</code> where the message
is sent by another process in this case, which could cause
messages to other nodes to arrive out of order.</p>
</section>
</div>
<div class="detail" id="multi_call/4">
<span id="multi_call/2"></span>
<span id="multi_call/3"></span>
<div class="detail-header">
<a href="#multi_call/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">multi_call(nodes \\ [node() | Node.list()], name, request, timeout \\ :infinity)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L1033" 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>multi_call([<a href="typespecs.html#built-in-types">node</a>()], name :: <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>()) ::
{replies :: [{<a href="typespecs.html#built-in-types">node</a>(), <a href="typespecs.html#built-in-types">term</a>()}], bad_nodes :: [<a href="typespecs.html#built-in-types">node</a>()]}</pre>
</div>
</div>
<section class="docstring">
<p>Calls all servers locally registered as <code class="inline">name</code> at the specified <code class="inline">nodes</code>.</p>
<p>First, the <code class="inline">request</code> is sent to every node in <code class="inline">nodes</code>; then, the caller waits
for the replies. This function returns a two-element tuple <code class="inline">{replies,
bad_nodes}</code> where:</p>
<ul>
<li><code class="inline">replies</code> - is a list of <code class="inline">{node, reply}</code> tuples where <code class="inline">node</code> is the node
that replied and <code class="inline">reply</code> is its reply
</li>
<li><code class="inline">bad_nodes</code> - is a list of nodes that either did not exist or where a
server with the given <code class="inline">name</code> did not exist or did not reply
</li>
</ul>
<p><code class="inline">nodes</code> is a list of node names to which the request is sent. The default
value is the list of all known nodes (including this node).</p>
<p>To avoid that late answers (after the timeout) pollute the caller’s message
queue, a middleman process is used to do the actual calls. Late answers will
then be discarded when they arrive to a terminated process.</p>
<h2 id="multi_call/4-examples" class="section-heading">
<a href="#multi_call/4-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<p>Assuming the <code class="inline">Stack</code> GenServer mentioned in the docs for the <a href="GenServer.html#content"><code class="inline">GenServer</code></a>
module is registered as <code class="inline">Stack</code> in the <code class="inline">:"foo@my-machine"</code> and
<code class="inline">:"bar@my-machine"</code> nodes:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">GenServer</span><span class="o">.</span><span class="n">multi_call</span><span class="p" data-group-id="7897546498-1">(</span><span class="nc">Stack</span><span class="p">,</span><span class="w"> </span><span class="ss">:pop</span><span class="p" data-group-id="7897546498-1">)</span><span class="w">
</span><span class="c1">#=> {[{:"foo@my-machine", :hello}, {:"bar@my-machine", :world}], []}</span></code></pre>
</section>
</div>
<div class="detail" id="reply/2">
<div class="detail-header">
<a href="#reply/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">reply(client, reply)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L1070" 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>reply(<a href="#t:from/0">from</a>(), <a href="typespecs.html#built-in-types">term</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Replies to a client.</p>
<p>This function can be used to explicitly send a reply to a client that called
<a href="#call/3"><code class="inline">call/3</code></a> or <a href="#multi_call/4"><code class="inline">multi_call/4</code></a> when the reply cannot be specified in the return
value of <a href="#c:handle_call/3"><code class="inline">handle_call/3</code></a>.</p>
<p><code class="inline">client</code> must be the <code class="inline">from</code> argument (the second argument) accepted by
<a href="#c:handle_call/3"><code class="inline">handle_call/3</code></a> callbacks. <code class="inline">reply</code> is an arbitrary term which will be given
back to the client as the return value of the call.</p>
<p>Note that <a href="#reply/2"><code class="inline">reply/2</code></a> can be called from any process, not just the GenServer
that originally received the call (as long as that GenServer communicated the
<code class="inline">from</code> argument somehow).</p>
<p>This function always returns <code class="inline">:ok</code>.</p>
<h2 id="reply/2-examples" class="section-heading">
<a href="#reply/2-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="kd">def</span><span class="w"> </span><span class="nf">handle_call</span><span class="p" data-group-id="2871474639-1">(</span><span class="ss">:reply_in_one_second</span><span class="p">,</span><span class="w"> </span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="2871474639-1">)</span><span class="w"> </span><span class="k" data-group-id="2871474639-2">do</span><span class="w">
</span><span class="nc">Process</span><span class="o">.</span><span class="n">send_after</span><span class="p" data-group-id="2871474639-3">(</span><span class="n">self</span><span class="p" data-group-id="2871474639-4">(</span><span class="p" data-group-id="2871474639-4">)</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="2871474639-5">{</span><span class="ss">:reply</span><span class="p">,</span><span class="w"> </span><span class="n">from</span><span class="p" data-group-id="2871474639-5">}</span><span class="p">,</span><span class="w"> </span><span class="mi">1_000</span><span class="p" data-group-id="2871474639-3">)</span><span class="w">
</span><span class="p" data-group-id="2871474639-6">{</span><span class="ss">:noreply</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="2871474639-6">}</span><span class="w">
</span><span class="k" data-group-id="2871474639-2">end</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">handle_info</span><span class="p" data-group-id="2871474639-7">(</span><span class="p" data-group-id="2871474639-8">{</span><span class="ss">:reply</span><span class="p">,</span><span class="w"> </span><span class="n">from</span><span class="p" data-group-id="2871474639-8">}</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="2871474639-7">)</span><span class="w"> </span><span class="k" data-group-id="2871474639-9">do</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">reply</span><span class="p" data-group-id="2871474639-10">(</span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="ss">:one_second_has_passed</span><span class="p" data-group-id="2871474639-10">)</span><span class="w">
</span><span class="p" data-group-id="2871474639-11">{</span><span class="ss">:noreply</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="2871474639-11">}</span><span class="w">
</span><span class="k" data-group-id="2871474639-9">end</span></code></pre>
</section>
</div>
<div class="detail" id="start/3">
<span id="start/2"></span>
<div class="detail-header">
<a href="#start/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">start(module, args, options \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L826" 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">any</a>(), <a href="#t:options/0">options</a>()) :: <a href="#t:on_start/0">on_start</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Starts a <a href="GenServer.html#content"><code class="inline">GenServer</code></a> process without links (outside of a supervision tree).</p>
<p>See <a href="#start_link/3"><code class="inline">start_link/3</code></a> for more information.</p>
</section>
</div>
<div class="detail" id="start_link/3">
<span id="start_link/2"></span>
<div class="detail-header">
<a href="#start_link/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">start_link(module, args, options \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L816" 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">any</a>(), <a href="#t:options/0">options</a>()) :: <a href="#t:on_start/0">on_start</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Starts a <a href="GenServer.html#content"><code class="inline">GenServer</code></a> process linked to the current process.</p>
<p>This is often used to start the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> as part of a supervision tree.</p>
<p>Once the server is started, the <a href="#c:init/1"><code class="inline">init/1</code></a> function of the given <code class="inline">module</code> is
called with <code class="inline">args</code> as its arguments to initialize the server. To ensure a
synchronized start-up procedure, this function does not return until <a href="#c:init/1"><code class="inline">init/1</code></a>
has returned.</p>
<p>Note that a <a href="GenServer.html#content"><code class="inline">GenServer</code></a> started with <a href="#start_link/3"><code class="inline">start_link/3</code></a> is linked to the
parent process and will exit in case of crashes from the parent. The GenServer
will also exit due to the <code class="inline">:normal</code> reasons in case it is configured to trap
exits in the <a href="#c:init/1"><code class="inline">init/1</code></a> callback.</p>
<h2 id="start_link/3-options" class="section-heading">
<a href="#start_link/3-options" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Options
</h2>
<ul>
<li><p><code class="inline">:name</code> - used for name registration as described in the “Name
registration” section in the documentation for <a href="GenServer.html#content"><code class="inline">GenServer</code></a></p>
</li>
<li><p><code class="inline">:timeout</code> - if present, the server is allowed to spend the given number of
milliseconds initializing or it will be terminated and the start function
will return <code class="inline">{:error, :timeout}</code></p>
</li>
<li><p><code class="inline">:debug</code> - if present, the corresponding function in the <a href="http://www.erlang.org/doc/man/sys.html"><code class="inline">:sys</code> module</a> is invoked</p>
</li>
<li><p><code class="inline">:spawn_opt</code> - if present, its value is passed as options to the
underlying process as in <a href="Process.html#spawn/4"><code class="inline">Process.spawn/4</code></a></p>
</li>
</ul>
<h2 id="start_link/3-return-values" class="section-heading">
<a href="#start_link/3-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, this function returns
<code class="inline">{:ok, pid}</code>, where <code class="inline">pid</code> is the PID of the server. If a process with the
specified server name already exists, this function returns
<code class="inline">{:error, {:already_started, pid}}</code> with the PID of that process.</p>
<p>If the <a href="#c:init/1"><code class="inline">init/1</code></a> callback fails with <code class="inline">reason</code>, this function returns
<code class="inline">{:error, reason}</code>. Otherwise, if it returns <code class="inline">{:stop, reason}</code>
or <code class="inline">:ignore</code>, the process is terminated and this function returns
<code class="inline">{:error, reason}</code> or <code class="inline">:ignore</code>, respectively.</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(server, reason \\ :normal, timeout \\ :infinity)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L870" 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:server/0">server</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 server with the given <code class="inline">reason</code>.</p>
<p>The <a href="#c:terminate/2"><code class="inline">terminate/2</code></a> callback of the given <code class="inline">server</code> will be invoked before
exiting. This function returns <code class="inline">:ok</code> if the server terminates with the
given reason; if it terminates with another reason, the call exits.</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 is logged.</p>
</section>
</div>
<div class="detail" id="whereis/1">
<div class="detail-header">
<a href="#whereis/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">whereis(server)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L1119" 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>whereis(<a href="#t:server/0">server</a>()) :: <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>()} | nil</pre>
</div>
</div>
<section class="docstring">
<p>Returns the <code class="inline">pid</code> or <code class="inline">{name, node}</code> of a GenServer process, or <code class="inline">nil</code> if
no process is associated with the given <code class="inline">server</code>.</p>
<h2 id="whereis/1-examples" class="section-heading">
<a href="#whereis/1-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<p>For example, to lookup a server process, monitor it and send a cast to it:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">process</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">GenServer</span><span class="o">.</span><span class="n">whereis</span><span class="p" data-group-id="5453883772-1">(</span><span class="n">server</span><span class="p" data-group-id="5453883772-1">)</span><span class="w">
</span><span class="n">monitor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Process</span><span class="o">.</span><span class="n">monitor</span><span class="p" data-group-id="5453883772-2">(</span><span class="n">process</span><span class="p" data-group-id="5453883772-2">)</span><span class="w">
</span><span class="nc">GenServer</span><span class="o">.</span><span class="n">cast</span><span class="p" data-group-id="5453883772-3">(</span><span class="n">process</span><span class="p">,</span><span class="w"> </span><span class="ss">:hello</span><span class="p" data-group-id="5453883772-3">)</span></code></pre>
</section>
</div>
</section>
<section id="callbacks" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#callbacks">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Callbacks
</h1>
<div class="detail" id="c:code_change/3">
<div class="detail-header">
<a href="#c:code_change/3" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">code_change(old_vsn, state, extra)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L594" 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">(optional)</span>
<div class="specs">
<pre>code_change(old_vsn, state :: <a href="typespecs.html#built-in-types">term</a>(), extra :: <a href="typespecs.html#built-in-types">term</a>()) ::
{:ok, new_state :: <a href="typespecs.html#built-in-types">term</a>()} | {:error, reason :: <a href="typespecs.html#built-in-types">term</a>()} | {:down, <a href="typespecs.html#built-in-types">term</a>()}
when old_vsn: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Invoked to change the state of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> when a different version of a
module is loaded (hot code swapping) and the state’s term structure should be
changed.</p>
<p><code class="inline">old_vsn</code> is the previous version of the module (defined by the <code class="inline">@vsn</code>
attribute) when upgrading. When downgrading the previous version is wrapped in
a 2-tuple with first element <code class="inline">:down</code>. <code class="inline">state</code> is the current state of the
<a href="GenServer.html#content"><code class="inline">GenServer</code></a> and <code class="inline">extra</code> is any extra data required to change the state.</p>
<p>Returning <code class="inline">{:ok, new_state}</code> changes the state to <code class="inline">new_state</code> and the code
change is successful.</p>
<p>Returning <code class="inline">{:error, reason}</code> fails the code change with reason <code class="inline">reason</code> and
the state remains as the previous state.</p>
<p>If <a href="#c:code_change/3"><code class="inline">code_change/3</code></a> raises the code change fails and the loop will continue
with its previous state. Therefore this callback does not usually contain side effects.</p>
<p>This callback is optional.</p>
</section>
</div>
<div class="detail" id="c:format_status/2">
<div class="detail-header">
<a href="#c:format_status/2" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">format_status(reason, pdict_and_state)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L617" 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">(optional)</span>
<div class="specs">
<pre>format_status(reason, pdict_and_state :: <a href="typespecs.html#built-in-types">list</a>()) :: <a href="typespecs.html#built-in-types">term</a>()
when reason: :normal | :terminate</pre>
</div>
</div>
<section class="docstring">
<p>Invoked in some cases to retrieve a formatted version of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> status.</p>
<p>This callback can be useful to control the <em>appearance</em> of the status of the
<a href="GenServer.html#content"><code class="inline">GenServer</code></a>. For example, it can be used to return a compact representation of
the <a href="GenServer.html#content"><code class="inline">GenServer</code></a>’s state to avoid having large state terms printed.</p>
<ul>
<li><p>one of <a href="http://www.erlang.org/doc/man/sys.html#get_status-1"><code class="inline">:sys.get_status/1</code></a> or <a href="http://www.erlang.org/doc/man/sys.html#get_status-2"><code class="inline">:sys.get_status/2</code></a> is invoked to get the
status of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a>; in such cases, <code class="inline">reason</code> is <code class="inline">:normal</code></p>
</li>
<li><p>the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> terminates abnormally and logs an error; in such cases,
<code class="inline">reason</code> is <code class="inline">:terminate</code></p>
</li>
</ul>
<p><code class="inline">pdict_and_state</code> is a two-elements list <code class="inline">[pdict, state]</code> where <code class="inline">pdict</code> is a
list of <code class="inline">{key, value}</code> tuples representing the current process dictionary of
the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> and <code class="inline">state</code> is the current state of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a>.</p>
</section>
</div>
<div class="detail" id="c:handle_call/3">
<div class="detail-header">
<a href="#c:handle_call/3" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">handle_call(request, from, state)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L449" 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">(optional)</span>
<div class="specs">
<pre>handle_call(request :: <a href="typespecs.html#built-in-types">term</a>(), <a href="#t:from/0">from</a>(), state :: <a href="typespecs.html#built-in-types">term</a>()) ::
{:reply, reply, new_state}
| {:reply, reply, new_state, <a href="typespecs.html#built-in-types">timeout</a>() | :hibernate | {:continue, <a href="typespecs.html#built-in-types">term</a>()}}
| {:noreply, new_state}
| {:noreply, new_state, <a href="typespecs.html#built-in-types">timeout</a>() | :hibernate, {:continue, <a href="typespecs.html#built-in-types">term</a>()}}
| {:stop, reason, reply, new_state}
| {:stop, reason, new_state}
when reply: <a href="typespecs.html#built-in-types">term</a>(), new_state: <a href="typespecs.html#built-in-types">term</a>(), reason: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Invoked to handle synchronous <a href="#call/3"><code class="inline">call/3</code></a> messages. <a href="#call/3"><code class="inline">call/3</code></a> will block until a
reply is received (unless the call times out or nodes are disconnected).</p>
<p><code class="inline">request</code> is the request message sent by a <a href="#call/3"><code class="inline">call/3</code></a>, <code class="inline">from</code> is a 2-tuple
containing the caller’s PID and a term that uniquely identifies the call, and
<code class="inline">state</code> is the current state of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a>.</p>
<p>Returning <code class="inline">{:reply, reply, new_state}</code> sends the response <code class="inline">reply</code> to the
caller and continues the loop with new state <code class="inline">new_state</code>.</p>
<p>Returning <code class="inline">{:reply, reply, new_state, timeout}</code> is similar to
<code class="inline">{:reply, reply, new_state}</code> except <code class="inline">handle_info(:timeout, new_state)</code> will be
called after <code class="inline">timeout</code> milliseconds if no messages are received.</p>
<p>Returning <code class="inline">{:reply, reply, new_state, :hibernate}</code> is similar to
<code class="inline">{:reply, reply, new_state}</code> except the process is hibernated and will
continue the loop once a message is in its message queue. If a message is
already in the message queue this will be immediately. Hibernating a
<a href="GenServer.html#content"><code class="inline">GenServer</code></a> causes garbage collection and leaves a continuous heap that
minimises the memory used by the process.</p>
<p>Returning <code class="inline">{:reply, reply, new_state, {:continue, continue}}</code> is similar to
<code class="inline">{:reply, reply, new_state}</code> except <a href="#c:handle_continue/2"><code class="inline">handle_continue/2</code></a> will be invoked
immediately after with the value <code class="inline">continue</code> as first argument.</p>
<p>Hibernating should not be used aggressively as too much time could be spent
garbage collecting. Normally it should only be used when a message is not
expected soon and minimising the memory of the process is shown to be
beneficial.</p>
<p>Returning <code class="inline">{:noreply, new_state}</code> does not send a response to the caller and
continues the loop with new state <code class="inline">new_state</code>. The response must be sent with
<a href="#reply/2"><code class="inline">reply/2</code></a>.</p>
<p>There are three main use cases for not replying using the return value:</p>
<ul>
<li>To reply before returning from the callback because the response is known
before calling a slow function.
</li>
<li>To reply after returning from the callback because the response is not yet
available.
</li>
<li>To reply from another process, such as a task.
</li>
</ul>
<p>When replying from another process the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> should exit if the other
process exits without replying as the caller will be blocking awaiting a
reply.</p>
<p>Returning <code class="inline">{:noreply, new_state, timeout | :hibernate | {:continue, continue}}</code>
is similar to <code class="inline">{:noreply, new_state}</code> except a timeout, hibernation or continue
occurs as with a <code class="inline">:reply</code> tuple.</p>
<p>Returning <code class="inline">{:stop, reason, reply, new_state}</code> stops the loop and <a href="#c:terminate/2"><code class="inline">terminate/2</code></a>
is called with reason <code class="inline">reason</code> and state <code class="inline">new_state</code>. Then the <code class="inline">reply</code> is sent
as the response to call and the process exits with reason <code class="inline">reason</code>.</p>
<p>Returning <code class="inline">{:stop, reason, new_state}</code> is similar to
<code class="inline">{:stop, reason, reply, new_state}</code> except a reply is not sent.</p>
<p>This callback is optional. If one is not implemented, the server will fail
if a call is performed against it.</p>
</section>
</div>
<div class="detail" id="c:handle_cast/2">
<div class="detail-header">
<a href="#c:handle_cast/2" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">handle_cast(request, state)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L485" 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">(optional)</span>
<div class="specs">
<pre>handle_cast(request :: <a href="typespecs.html#built-in-types">term</a>(), state :: <a href="typespecs.html#built-in-types">term</a>()) ::
{:noreply, new_state}
| {:noreply, new_state, <a href="typespecs.html#built-in-types">timeout</a>() | :hibernate | {:continue, <a href="typespecs.html#built-in-types">term</a>()}}
| {:stop, reason :: <a href="typespecs.html#built-in-types">term</a>(), new_state}
when new_state: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Invoked to handle asynchronous <a href="#cast/2"><code class="inline">cast/2</code></a> messages.</p>
<p><code class="inline">request</code> is the request message sent by a <a href="#cast/2"><code class="inline">cast/2</code></a> and <code class="inline">state</code> is the current
state of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a>.</p>
<p>Returning <code class="inline">{:noreply, new_state}</code> continues the loop with new state <code class="inline">new_state</code>.</p>
<p>Returning <code class="inline">{:noreply, new_state, timeout}</code> is similar to
<code class="inline">{:noreply, new_state}</code> except <code class="inline">handle_info(:timeout, new_state)</code> will be
called after <code class="inline">timeout</code> milliseconds if no messages are received.</p>
<p>Returning <code class="inline">{:noreply, new_state, :hibernate}</code> is similar to
<code class="inline">{:noreply, new_state}</code> except the process is hibernated before continuing the
loop. See <a href="#c:handle_call/3"><code class="inline">handle_call/3</code></a> for more information.</p>
<p>Returning <code class="inline">{:noreply, new_state, {:continue, continue}}</code> is similar to
<code class="inline">{:noreply, new_state}</code> except <a href="#c:handle_continue/2"><code class="inline">handle_continue/2</code></a> will be invoked
immediately after with the value <code class="inline">continue</code> as first argument.</p>
<p>Returning <code class="inline">{:stop, reason, new_state}</code> stops the loop and <a href="#c:terminate/2"><code class="inline">terminate/2</code></a> is
called with the reason <code class="inline">reason</code> and state <code class="inline">new_state</code>. The process exits with
reason <code class="inline">reason</code>.</p>
<p>This callback is optional. If one is not implemented, the server will fail
if a cast is performed against it.</p>
</section>
</div>
<div class="detail" id="c:handle_continue/2">
<div class="detail-header">
<a href="#c:handle_continue/2" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">handle_continue(continue, state)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L521" 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">(optional)</span>
<div class="specs">
<pre>handle_continue(continue :: <a href="typespecs.html#built-in-types">term</a>(), state :: <a href="typespecs.html#built-in-types">term</a>()) ::
{:noreply, new_state}
| {:noreply, new_state, <a href="typespecs.html#built-in-types">timeout</a>() | :hibernate | {:continue, <a href="typespecs.html#built-in-types">term</a>()}}
| {:stop, reason :: <a href="typespecs.html#built-in-types">term</a>(), new_state}
when new_state: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Invoked to handle <code class="inline">continue</code> instructions.</p>
<p>It is useful for performing work after initialization or for splitting the work
in a callback in multiple steps, updating the process state along the way.</p>
<p>Return values are the same as <a href="#c:handle_cast/2"><code class="inline">handle_cast/2</code></a>.</p>
<p>This callback is optional. If one is not implemented, the server will fail
if a continue instruction is used.</p>
<p>This callback is only supported on Erlang/OTP 21+.</p>
</section>
</div>
<div class="detail" id="c:handle_info/2">
<div class="detail-header">
<a href="#c:handle_info/2" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">handle_info(msg, state)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L502" 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">(optional)</span>
<div class="specs">
<pre>handle_info(msg :: :timeout | <a href="typespecs.html#built-in-types">term</a>(), state :: <a href="typespecs.html#built-in-types">term</a>()) ::
{:noreply, new_state}
| {:noreply, new_state, <a href="typespecs.html#built-in-types">timeout</a>() | :hibernate | {:continue, <a href="typespecs.html#built-in-types">term</a>()}}
| {:stop, reason :: <a href="typespecs.html#built-in-types">term</a>(), new_state}
when new_state: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Invoked to handle all other messages.</p>
<p><code class="inline">msg</code> is the message and <code class="inline">state</code> is the current state of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a>. When
a timeout occurs the message is <code class="inline">:timeout</code>.</p>
<p>Return values are the same as <a href="#c:handle_cast/2"><code class="inline">handle_cast/2</code></a>.</p>
<p>This callback is optional. If one is not implemented, the received message
will be logged.</p>
</section>
</div>
<div class="detail" id="c:init/1">
<div class="detail-header">
<a href="#c:init/1" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">init(args)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L381" 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>init(args :: <a href="typespecs.html#built-in-types">term</a>()) ::
{:ok, state}
| {:ok, state, <a href="typespecs.html#built-in-types">timeout</a>() | :hibernate | {:continue, <a href="typespecs.html#built-in-types">term</a>()}}
| :ignore
| {:stop, reason :: <a href="typespecs.html#basic-types">any</a>()}
when state: <a href="typespecs.html#basic-types">any</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Invoked when the server is started. <a href="#start_link/3"><code class="inline">start_link/3</code></a> or <a href="#start/3"><code class="inline">start/3</code></a> will
block until it returns.</p>
<p><code class="inline">args</code> is the argument term (second argument) passed to <a href="#start_link/3"><code class="inline">start_link/3</code></a>.</p>
<p>Returning <code class="inline">{:ok, state}</code> will cause <a href="#start_link/3"><code class="inline">start_link/3</code></a> to return
<code class="inline">{:ok, pid}</code> and the process to enter its loop.</p>
<p>Returning <code class="inline">{:ok, state, timeout}</code> is similar to <code class="inline">{:ok, state}</code>
except <code class="inline">handle_info(:timeout, state)</code> will be called after <code class="inline">timeout</code>
milliseconds if no messages are received within the timeout.</p>
<p>Returning <code class="inline">{:ok, state, :hibernate}</code> is similar to <code class="inline">{:ok, state}</code>
except the process is hibernated before entering the loop. See
<a href="#c:handle_call/3"><code class="inline">handle_call/3</code></a> for more information on hibernation.</p>
<p>Returning <code class="inline">{:ok, state, {:continue, continue}}</code> is similar to
<code class="inline">{:ok, state}</code> except that immediately after entering the loop
the <a href="#c:handle_continue/2"><code class="inline">handle_continue/2</code></a> callback will be invoked with the value
<code class="inline">continue</code> as first argument.</p>
<p>Returning <code class="inline">:ignore</code> will cause <a href="#start_link/3"><code class="inline">start_link/3</code></a> to return <code class="inline">:ignore</code> and
the process will exit normally without entering the loop or calling
<a href="#c:terminate/2"><code class="inline">terminate/2</code></a>. If used when part of a supervision tree the parent
supervisor will not fail to start nor immediately try to restart the
<a href="GenServer.html#content"><code class="inline">GenServer</code></a>. The remainder of the supervision tree will be started
and so the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> should not be required by other processes.
It can be started later with <a href="Supervisor.html#restart_child/2"><code class="inline">Supervisor.restart_child/2</code></a> as the child
specification is saved in the parent supervisor. The main use cases for
this are:</p>
<ul>
<li>The <a href="GenServer.html#content"><code class="inline">GenServer</code></a> is disabled by configuration but might be enabled later.
</li>
<li>An error occurred and it will be handled by a different mechanism than the
<a href="Supervisor.html"><code class="inline">Supervisor</code></a>. Likely this approach involves calling <a href="Supervisor.html#restart_child/2"><code class="inline">Supervisor.restart_child/2</code></a>
after a delay to attempt a restart.
</li>
</ul>
<p>Returning <code class="inline">{:stop, reason}</code> will cause <a href="#start_link/3"><code class="inline">start_link/3</code></a> to return
<code class="inline">{:error, reason}</code> and the process to exit with reason <code class="inline">reason</code> without
entering the loop or calling <a href="#c:terminate/2"><code class="inline">terminate/2</code></a>.</p>
</section>
</div>
<div class="detail" id="c:terminate/2">
<div class="detail-header">
<a href="#c:terminate/2" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">terminate(reason, state)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/gen_server.ex#L570" 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">(optional)</span>
<div class="specs">
<pre>terminate(reason, state :: <a href="typespecs.html#built-in-types">term</a>()) :: <a href="typespecs.html#built-in-types">term</a>()
when reason: :normal | :shutdown | {:shutdown, <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Invoked when the server is about to exit. It should do any cleanup required.</p>
<p><code class="inline">reason</code> is exit reason and <code class="inline">state</code> is the current state of the <a href="GenServer.html#content"><code class="inline">GenServer</code></a>.
The return value is ignored.</p>
<p><a href="#c:terminate/2"><code class="inline">terminate/2</code></a> is called if a callback (except <a href="#c:init/1"><code class="inline">init/1</code></a>) does one of the
following:</p>
<ul>
<li>returns a <code class="inline">:stop</code> tuple
</li>
<li>raises
</li>
<li>calls <a href="Kernel.html#exit/1"><code class="inline">Kernel.exit/1</code></a>
</li>
<li>returns an invalid value
</li>
<li>the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> traps exits (using <a href="Process.html#flag/2"><code class="inline">Process.flag/2</code></a>) <em>and</em> the parent
process sends an exit signal
</li>
</ul>
<p>If part of a supervision tree, a <a href="GenServer.html#content"><code class="inline">GenServer</code></a>’s <a href="Supervisor.html"><code class="inline">Supervisor</code></a> will send an exit
signal when shutting it down. The exit signal is based on the shutdown
strategy in the child’s specification. If it is <code class="inline">:brutal_kill</code> the <a href="GenServer.html#content"><code class="inline">GenServer</code></a>
is killed and so <a href="#c:terminate/2"><code class="inline">terminate/2</code></a> is not called. However if it is a timeout the
<a href="Supervisor.html"><code class="inline">Supervisor</code></a> will send the exit signal <code class="inline">:shutdown</code> and the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> will
have the duration of the timeout to call <a href="#c:terminate/2"><code class="inline">terminate/2</code></a> - if the process is
still alive after the timeout it is killed.</p>
<p>If the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> receives an exit signal (that is not <code class="inline">:normal</code>) from any
process when it is not trapping exits it will exit abruptly with the same
reason and so not call <a href="#c:terminate/2"><code class="inline">terminate/2</code></a>. Note that a process does <em>NOT</em> trap
exits by default and an exit signal is sent when a linked process exits or its
node is disconnected.</p>
<p>Therefore it is not guaranteed that <a href="#c:terminate/2"><code class="inline">terminate/2</code></a> is called when a <a href="GenServer.html#content"><code class="inline">GenServer</code></a>
exits. For such reasons, we usually recommend important clean-up rules to
happen in separated processes either by use of monitoring or by links
themselves. There is no cleanup needed when the <a href="GenServer.html#content"><code class="inline">GenServer</code></a> controls a <code class="inline">port</code> (e.g.
<code class="inline">:gen_tcp.socket</code>) or <a href="File.html#t:io_device/0"><code class="inline">File.io_device/0</code></a>, because these will be closed on
receiving a <a href="GenServer.html#content"><code class="inline">GenServer</code></a>’s exit signal and do not need to be closed manually
in <a href="#c:terminate/2"><code class="inline">terminate/2</code></a>.</p>
<p>If <code class="inline">reason</code> is not <code class="inline">:normal</code>, <code class="inline">:shutdown</code>, nor <code class="inline">{:shutdown, term}</code> an error is
logged.</p>
<p>This callback is optional.</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
>
67
