This repository has been archived by the owner on Nov 23, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 8
/
elixir_v1.example.etf
81 lines (81 loc) · 10.8 KB
/
elixir_v1.example.etf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{elixir_docs_v1,[{docs,[{{cast,2},
274,def,
[{agent,[],nil},{'fun',[],nil}],
<<"Performs a cast (fire and forget) operation on the agent state.\n\nThe function `fun` is sent to the `agent` which invokes the function\npassing the agent state. The function must return the new state.\n\nNote that `cast` returns `:ok` immediately, regardless of whether the\ndestination node or agent exists.\n">>},
{{cast,4},
286,def,
[{agent,[],nil},
{module,[],nil},
{'fun',[],nil},
{args,[],nil}],
<<"Performs a cast (fire and forget) operation on the agent state.\n\nSame as `cast/2` but a module, function and args are expected\ninstead of an anonymous function. The state is added as first\nargument to the given list of args.\n">>},
{{get,3},
195,def,
[{agent,[],nil},
{'fun',[],nil},
{'\\\\',[],[{timeout,[],nil},5000]}],
<<"Gets an agent value via the given function.\n\nThe function `fun` is sent to the `agent` which invokes the function\npassing the agent state. The result of the function invocation is\nreturned.\n\nA timeout can also be specified (it has a default value of 5000).\n">>},
{{get,5},
207,def,
[{agent,[],nil},
{module,[],nil},
{'fun',[],nil},
{args,[],nil},
{'\\\\',[],[{timeout,[],nil},5000]}],
<<"Gets an agent value via the given function.\n\nSame as `get/3` but a module, function and args are expected\ninstead of an anonymous function. The state is added as first\nargument to the given list of args.\n">>},
{{get_and_update,3},
222,def,
[{agent,[],nil},
{'fun',[],nil},
{'\\\\',[],[{timeout,[],nil},5000]}],
<<"Gets and updates the agent state in one operation.\n\nThe function `fun` is sent to the `agent` which invokes the function\npassing the agent state. The function must return a tuple with two\nelements, the first being the value to return (i.e. the `get` value)\nand the second one is the new state.\n\nA timeout can also be specified (it has a default value of 5000).\n">>},
{{get_and_update,5},
234,def,
[{agent,[],nil},
{module,[],nil},
{'fun',[],nil},
{args,[],nil},
{'\\\\',[],[{timeout,[],nil},5000]}],
<<"Gets and updates the agent state in one operation.\n\nSame as `get_and_update/3` but a module, function and args are expected\ninstead of an anonymous function. The state is added as first\nargument to the given list of args.\n">>},
{{start,2},
170,def,
[{'fun',[],nil},{'\\\\',[],[{options,[],nil},[]]}],
<<"Starts an agent process without links (outside of a supervision tree).\n\nSee `start_link/2` for more information.\n">>},
{{start,4},
181,def,
[{module,[],nil},
{'fun',[],nil},
{args,[],nil},
{'\\\\',[],[{options,[],nil},[]]}],
<<"Starts an agent with the given module function and arguments.\n\nSimilar to `start/2` but a module, function and args are expected\ninstead of an anonymous function.\n">>},
{{start_link,2},
148,def,
[{'fun',[],nil},{'\\\\',[],[{options,[],nil},[]]}],
<<"Starts an agent linked to the current process with the given function.\n\nThis is often used to start the agent as part of a supervision tree.\n\nOnce the agent is spawned, the given function is invoked and its return\nvalue is used as the agent state. Note that `start_link` does not return\nuntil the given function has returned.\n\n## Options\n\nThe `:name` option is used for registration as described in the module\ndocumentation.\n\nIf the `:timeout` option is present, the agent is allowed to spend at most\nthe given number of milliseconds on initialization or it will be terminated\nand the start function will return `{:error, :timeout}`.\n\nIf the `:debug` option is present, the corresponding function in the\n[`:sys` module](http://www.erlang.org/doc/man/sys.html) will be invoked.\n\nIf the `:spawn_opt` option is present, its value will be passed as options\nto the underlying process as in `Process.spawn/4`.\n\n## Return values\n\nIf the server is successfully created and initialized, the function returns\n`{:ok, pid}`, where `pid` is the pid of the server. If there already exists\nan agent with the specified name, the function returns\n`{:error, {:already_started, pid}}` with the pid of that process.\n\nIf the given function callback fails with `reason`, the function returns\n`{:error, reason}`.\n">>},
{{start_link,4},
160,def,
[{module,[],nil},
{'fun',[],nil},
{args,[],nil},
{'\\\\',[],[{options,[],nil},[]]}],
<<"Starts an agent linked to the current process with the given module\nfunction and arguments.\n\nSame as `start_link/2` but a module, function and args are expected\ninstead of an anonymous function.\n">>},
{{stop,2},
296,def,
[{agent,[],nil},{'\\\\',[],[{timeout,[],nil},5000]}],
<<"Stops the agent.\n\nReturns `:ok` if the agent is stopped within the given `timeout`.\n">>},
{{update,3},
248,def,
[{agent,[],nil},
{'fun',[],nil},
{'\\\\',[],[{timeout,[],nil},5000]}],
<<"Updates the agent state.\n\nThe function `fun` is sent to the `agent` which invokes the function\npassing the agent state. The function must return the new state.\n\nA timeout can also be specified (it has a default value of 5000).\nThis function always returns `:ok`.\n">>},
{{update,5},
260,def,
[{agent,[],nil},
{module,[],nil},
{'fun',[],nil},
{args,[],nil},
{'\\\\',[],[{timeout,[],nil},5000]}],
<<"Updates the agent state.\n\nSame as `update/3` but a module, function and args are expected\ninstead of an anonymous function. The state is added as first\nargument to the given list of args.\n">>}]},
{moduledoc,{1,
<<"Agents are a simple abstraction around state.\n\nOften in Elixir there is a need to share or store state that\nmust be accessed from different processes or by the same process\nat different points in time.\n\nThe Agent module provides a basic server implementation that\nallows state to be retrieved and updated via a simple API.\n\n## Examples\n\nFor example, in the Mix tool that ships with Elixir, we need\nto keep a set of all tasks executed by a given project. Since\nthis set is shared, we can implement it with an Agent:\n\n defmodule Mix.TasksServer do\n def start_link do\n Agent.start_link(fn -> HashSet.new end, name: __MODULE__)\n end\n\n @doc \"Checks if the task has already executed\"\n def executed?(task, project) do\n item = {task, project}\n Agent.get(__MODULE__, fn set ->\n item in set\n end)\n end\n\n @doc \"Marks a task as executed\"\n def put_task(task, project) do\n item = {task, project}\n Agent.update(__MODULE__, &Set.put(&1, item))\n end\n end\n\nNote that agents still provide a segregation between the\nclient and server APIs, as seen in GenServers. In particular,\nall code inside the function passed to the agent is executed\nby the agent. This distinction is important because you may\nwant to avoid expensive operations inside the agent, as it will\neffectively block the agent until the request is fulfilled.\n\nConsider these two examples:\n\n # Compute in the agent/server\n def get_something(agent) do\n Agent.get(agent, fn state -> do_something_expensive(state) end)\n end\n\n # Compute in the agent/client\n def get_something(agent) do\n Agent.get(agent, &(&1)) |> do_something_expensive()\n end\n\nThe first one blocks the agent while the second one copies\nall the state to the client and executes the operation in the client.\nThe trade-off here is exactly if the data is small enough to be\nsent to the client cheaply or large enough to require processing on\nthe server (or at least some initial processing).\n\n## Name Registration\n\nAn Agent is bound to the same name registration rules as GenServers.\nRead more about it in the `GenServer` docs.\n\n## A word on distributed agents\n\nIt is important to consider the limitations of distributed agents. Agents\nprovides two APIs, one that works with anonymous functions and another\nthat expects explicit module, function and arguments.\n\nIn a distributed setup with multiple nodes, the API that accepts anonymous\nfunctions only works if the caller (client) and the agent have the same\nversion of the caller module.\n\nKeep in mind this issue also shows up when performing \"rolling upgrades\"\nwith agents. By rolling upgrades we mean the following situation: you wish\nto deploy a new version of your software by *shutting down* some of your\nnodes and replacing them with nodes running a new version of the software.\nIn this setup, part of your environment will have one version of a given\nmodule and the other part another version (the newer one) of the same module.\n\nThe best solution is to simply use the explicit module, function and arguments\nAPIs when working with distributed agents.\n\n## Hot code swapping\n\nAn agent can have its code hot swapped live by simply passing a module,\nfunction and args tuple to the update instruction. For example, imagine\nyou have an agent named `:sample` and you want to convert its inner state\nfrom some dict structure to a map. It can be done with the following\ninstruction:\n\n {:update, :sample, {:advanced, {Enum, :into, [%{}]}}}\n\nThe agent's state will be added to the given list as the first argument.\n">>}}]}.