         Agent.get(agent, &(&1)) |> do_something_expensive()
       end
 
-  The first function blocks the agent. The second function copies
-  all the state to the client and then executes the operation in the
-  client. The difference is whether the data is large enough to require
-  processing in the server, at least initially, or small enough to be
-  sent to the client cheaply.
-
-  ## Name Registration
-
-  An Agent is bound to the same name registration rules as GenServers.
-  Read more about it in the `GenServer` docs.
+  The first function blocks the agent. The second function copies all the state
+  to the client and then executes the operation in the client. One difference is
+  whether the data is large enough to require processing in the server, at least
+  initially, or small enough to be sent to the client cheaply. Another
+  difference is whether the data needs to be processed atomically: getting the
+  state and calling `do_something_expensive(state)` outside of the agent means
+  that the agent's state can be updated in the meantime, so putting the state
+  back in the agent afterwards may override the updated that happened while
+  processing.
+
+  ## Name registration
+
+  An agent is bound to the same name registration rules as GenServers.
+  Read more about it in the `GenServer` documentation.
 
   ## A word on distributed agents
 

  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


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

  Consider these two examples:
