Add Agent MFAs

Author: José Valim

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## v0.15.0-dev
 
 * Enhancements
+  * [Agent] Improve the Agent API to also accept functions that receive explicit module, function and arguments
   * [IEx] Support `--werl` call on Windows
   * [Logger] Add `Logger`
   * [Map] Add `Map.from_struct/1`

lib/elixir/lib/agent.ex

@@ -68,22 +68,22 @@ defmodule Agent do
   ## A word on distributed agents
 
   It is important to consider the limitations of distributed agents. Agents
-  work by sending anonymous functions between the caller and the agent.
-  In a distributed setup with multiple nodes, agents only work if the caller
-  (client) and the agent have the same version of a given module.
-
-  This setup may exhibit issues when doing "rolling upgrades". By rolling
-  upgrades we mean the following situation: you wish to deploy a new version of
-  your software by *shutting down* some of your nodes and replacing them with
-  nodes running a new version of the software. In this setup, part of your
-  environment will have one version of a given module and the other part
-  another version (the newer one) of the same module; this may cause agents to
-  crash. That said, if you plan to run in distributed environments, agents
-  should likely be avoided.
-
-  Note, however, that agents work fine if you want to perform hot code
-  swapping, as it keeps both the old and new versions of a given module.
-  We detail how to do hot code swapping with agents in the next section.
+  provides two APIs, one that works with anonymous functions and another
+  that expects explicit module, function and arguments.
+
+  In a distributed setup with multiple nodes, the API that accepts anonymous
+  functions only works if the caller (client) and the agent have the same
+  version of the caller module.
+
+  Keep in mind this issue also shows up when performing "rolling upgrades"
+  with agents. By rolling upgrades we mean the following situation: you wish
+  to deploy a new version of your software by *shutting down* some of your
+  nodes and replacing them with nodes running a new version of the software.
+  In this setup, part of your environment will have one version of a given
+  module and the other part another version (the newer one) of the same module.
+
+  The best solution is to simply use the explicit module, function and arguments
+  APIs when working with distributed agents.
 
   ## Hot code swapping
 
@@ -111,7 +111,7 @@ defmodule Agent do
   @type state :: term
 
   @doc """
-  Starts an agent linked to the current process.
+  Starts an agent linked to the current process with the given function.
 
   This is often used to start the agent as part of a supervision tree.
 
@@ -149,6 +149,18 @@ defmodule Agent do
     GenServer.start_link(Agent.Server, fun, options)
   end
 
+  @doc """
+  Starts an agent linked to the current process with the given module
+  function and arguments.
+
+  Same as `start_link/2` but a module, function and args are expected
+  instead of an anonymous function.
+  """
+  @spec start_link(module, atom, [any], GenServer.options) :: on_start
+  def start_link(module, fun, args, options \\ []) do
+    GenServer.start_link(Agent.Server, {module, fun, args}, options)
+  end
+
   @doc """
   Starts an agent process without links (outside of a supervision tree).
 
@@ -160,7 +172,18 @@ defmodule Agent do
   end
 
   @doc """
-  Gets the agent value and executes the given function.
+  Starts an agent with the given module function and arguments.
+
+  Similar to `start/2` but a module, function and args are expected
+  instead of an anonymous function.
+  """
+  @spec start(module, atom, [any], GenServer.options) :: on_start
+  def start(module, fun, args, options \\ []) do
+    GenServer.start(Agent.Server, {module, fun, args}, options)
+  end
+
+  @doc """
+  Gets an agent value via the given function.
 
   The function `fun` is sent to the `agent` which invokes the function
   passing the agent state. The result of the function invocation is
@@ -173,6 +196,18 @@ defmodule Agent do
     GenServer.call(agent, {:get, fun}, timeout)
   end
 
+  @doc """
+  Gets an agent value via the given function.
+
+  Same as `get/3` but a module, function and args are expected
+  instead of an anonymous function. The state is added as first
+  argument to the given list of args.
+  """
+  @spec get(agent, module, atom, [term], timeout) :: any
+  def get(agent, module, fun, args, timeout \\ 5000) do
+    GenServer.call(agent, {:get, {module, fun, args}}, timeout)
+  end
+
   @doc """
   Gets and updates the agent state in one operation.
 
@@ -188,6 +223,18 @@ defmodule Agent do
     GenServer.call(agent, {:get_and_update, fun}, timeout)
   end
 
+  @doc """
+  Gets and updates the agent state in one operation.
+
+  Same as `get_and_update/3` but a module, function and args are expected
+  instead of an anonymous function. The state is added as first
+  argument to the given list of args.
+  """
+  @spec get_and_update(agent, module, atom, [term], timeout) :: any
+  def get_and_update(agent, module, fun, args, timeout \\ 5000) do
+    GenServer.call(agent, {:get_and_update, {module, fun, args}}, timeout)
+  end
+
   @doc """
   Updates the agent state.
 
@@ -197,11 +244,23 @@ defmodule Agent do
   A timeout can also be specified (it has a default value of 5000).
   This function always returns `:ok`.
   """
-  @spec update(agent, (state -> state)) :: :ok
+  @spec update(agent, (state -> state), timeout) :: :ok
   def update(agent, fun, timeout \\ 5000) when is_function(fun, 1) do
     GenServer.call(agent, {:update, fun}, timeout)
   end
 
+  @doc """
+  Updates the agent state.
+
+  Same as `update/3` but a module, function and args are expected
+  instead of an anonymous function. The state is added as first
+  argument to the given list of args.
+  """
+  @spec update(agent, module, atom, [term], timeout) :: :ok
+  def update(agent, module, fun, args, timeout \\ 5000) do
+    GenServer.call(agent, {:update, {module, fun, args}}, timeout)
+  end
+
   @doc """
   Performs a cast (fire and forget) operation on the agent state.
 
@@ -213,7 +272,19 @@ defmodule Agent do
   """
   @spec cast(agent, (state -> state)) :: :ok
   def cast(agent, fun) when is_function(fun, 1) do
-    GenServer.cast(agent, fun)
+    GenServer.cast(agent, {:cast, fun})
+  end
+
+  @doc """
+  Performs a cast (fire and forget) operation on the agent state.
+
+  Same as `cast/2` but a module, function and args are expected
+  instead of an anonymous function. The state is added as first
+  argument to the given list of args.
+  """
+  @spec cast(agent, module, atom, [term]) :: :ok
+  def cast(agent, module, fun, args) do
+    GenServer.cast(agent, {:cast, {module, fun, args}})
   end
 
   @doc """

lib/elixir/lib/agent/server.ex

@@ -4,20 +4,20 @@ defmodule Agent.Server do
   use GenServer
 
   def init(fun) do
-    {:ok, fun.()}
+    {:ok, run(fun, [])}
   end
 
   def handle_call({:get, fun}, _from, state) do
-    {:reply, fun.(state), state}
+    {:reply, run(fun, [state]), state}
   end
 
   def handle_call({:get_and_update, fun}, _from, state) do
-    {reply, state} = fun.(state)
+    {reply, state} = run(fun, [state])
     {:reply, reply, state}
   end
 
   def handle_call({:update, fun}, _from, state) do
-    {:reply, :ok, fun.(state)}
+    {:reply, :ok, run(fun, [state])}
   end
 
   def handle_call(:stop, _from, state) do
@@ -28,16 +28,16 @@ defmodule Agent.Server do
     super(msg, from, state)
   end
 
-  def handle_cast(fun, state) when is_function(fun, 1) do
-    {:noreply, fun.(state)}
+  def handle_cast({:cast, fun}, state) do
+    {:noreply, run(fun, [state])}
   end
 
   def handle_cast(msg, state) do
     super(msg, state)
   end
 
-  def code_change(_old, state, { m, f, a }) do
-    {:ok, apply(m, f, [state|a])}
+  def code_change(_old, state, fun) do
+    {:ok, run(fun, [state])}
   end
 
   def terminate(_reason, _state) do
@@ -50,4 +50,7 @@ defmodule Agent.Server do
     end
     :ok
   end
+
+  defp run({m, f, a}, extra), do: apply(m, f, extra ++ a)
+  defp run(fun, extra), do: apply(fun, extra)
 end

lib/elixir/lib/task.ex

@@ -58,7 +58,7 @@ defmodule Task do
   that dynamically supervise tasks:
 
       {:ok, pid} = Task.Supervisor.start_link()
-      Task.Supervisor.async(pid, fn -> do_work() end)
+      Task.Supervisor.async(pid, MyMod, :my_fun, [arg1, arg2, arg3])
 
   `Task.Supervisor` also makes it possible to spawn tasks in remote nodes as
   long as the supervisor is registered locally or globally:
@@ -67,7 +67,7 @@ defmodule Task do
       Task.Supervisor.start_link(name: :tasks_sup)
 
       # In the client
-      Task.Supervisor.async({:tasks_sup, :remote@local}, fn -> do_work() end)
+      Task.Supervisor.async({:tasks_sup, :remote@local}, MyMod, :my_fun, [arg1, arg2, arg3])
 
   `Task.Supervisor` is more often started in your supervision tree as:
 
@@ -77,7 +77,15 @@ defmodule Task do
         supervisor(Task.Supervisor, [[name: :tasks_sup]])
       ]
 
-  Check `Task.Supervisor` for other operations supported by the Task supervisor.
+  Note that, when working with distributed tasks, one should use the `async/4` API,
+  that expects explicit module, function and arguments, instead of `async/2` that
+  works with anonymous functions. That's because the anonymous function API expects
+  the same module version to exist on all involved nodes. Check the `Agent` module
+  documentation for more information on distributed processes, as the limitations
+  described in the agents documentation apply to the whole ecosystem.
+
+  Finally, check `Task.Supervisor` for other operations supported by the Task
+  supervisor.
   """
 
   @doc """

lib/elixir/test/elixir/agent_test.exs

@@ -3,7 +3,11 @@ Code.require_file "test_helper.exs", __DIR__
 defmodule AgentTest do
   use ExUnit.Case, async: true
 
-  test "start_link/2 workflow with unregistered name" do
+  def identity(state) do
+    state
+  end
+
+  test "start_link/2 workflow with unregistered name and anonymous functions" do
     {:ok, pid} = Agent.start_link(fn -> %{} end)
 
     {:links, links} = Process.info(self, :links)
@@ -17,21 +21,21 @@ defmodule AgentTest do
     wait_until_dead(pid)
   end
 
-  test "start/2 workflow with registered name" do
-    {:ok, pid} = Agent.start(fn -> %{} end, name: :agent)
+  test "start/2 workflow with registered name and module functions" do
+    {:ok, pid} = Agent.start(Map, :new, [], name: :agent)
     assert Process.info(pid, :registered_name) == {:registered_name, :agent}
-    assert Agent.cast(:agent, &Map.put(&1, :hello, :world)) == :ok
-    assert Agent.get(:agent, &Map.get(&1, :hello)) == :world
-    assert Agent.get_and_update(:agent, &Map.pop(&1, :hello)) == :world
-    assert Agent.get(:agent, &(&1)) == %{}
+    assert Agent.cast(:agent, Map, :put, [:hello, :world]) == :ok
+    assert Agent.get(:agent, Map, :get, [:hello]) == :world
+    assert Agent.get_and_update(:agent, Map, :pop, [:hello]) == :world
+    assert Agent.get(:agent, AgentTest, :identity, []) == %{}
     assert Agent.stop(:agent) == :ok
     assert Process.info(pid, :registered_name) == nil
   end
 
   test ":sys.change_code/4 with mfa" do
     { :ok, pid } = Agent.start_link(fn -> %{} end)
     :ok = :sys.suspend(pid)
-    mfa = { Map, :put, [:hello, :world] }
+    mfa = {Map, :put, [:hello, :world]}
     assert :sys.change_code(pid, __MODULE__, "vsn", mfa) == :ok
     :ok = :sys.resume(pid)
     assert Agent.get(pid, &Map.get(&1, :hello)) == :world