The hot swap migration strategy implements the ProcessHub.Strategy.Migration.Base protocol. It provides a migration strategy where the local process is terminated after the new one is started on the remote node.

In the following text, we will refer to the process that is being terminated after the migration as the peer process.

Hotswap migration can also handle process state migration when nodes are leaving the cluster. The process states are stored in the local storage and are sent to the remote node before the local process is terminated. This will only work if the node is being shut down gracefully.

The hot swap strategy is useful when we want to ensure that there is no downtime when migrating the child process to the remote node. It also provides a way to ensure that the state of the process is synchronized before terminating the peer process.

To pass the process state to the newly started process on the remote node, the :handover option must be set to true in the migration strategy configuration, and necessary messages must be handled in the processes.

Using the handover option

When the :handover option is set to true, the peer process must handle the following message: {:process_hub, :send_handover_state, receiver, child_id, opts}.

Example migration with handover using GenServer:

def handle_info({:process_hub, :send_handover_state, receiver, child_id, opts}, state) do
  if is_pid(receiver) do
    Process.send(receiver, {:process_hub, :handover, child_id, state}, [])
  end

  if is_pid(opts[:retention_receiver]) do
    Process.send(opts[:retention_receiver], {:process_hub, :retention_handled, child_id}, [])
  end

  {:noreply, state}
end

def handle_info({:process_hub, :handover, _child_id, handover_state}, _state) do
  {:noreply, handover_state}
end

Use HotSwap macro to provide the handover callbacks automatically.

It's convenient to use the HotSwap macro to provide the handover callbacks automatically.

use ProcessHub.Strategy.Migration.HotSwap