View Source ProcessHub.Strategy.Migration.HotSwap (ProcessHub v0.2.0-alpha)

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.

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, :handover_start, startup_resp, from}.

Example migration with handover using GenServer:

def handle_info({:process_hub, :handover_start, startup_resp, child_id, from}, state) do
  case startup_resp do
    {:ok, pid} ->
      # Send the state to the remote process.
      Process.send(pid, {:process_hub, :handover, state}, [])

      # Signal the handler process that the state handover has been handled.
      Process.send(from, {:process_hub, :retention_handled, child_id}, [])

    _ ->
      nil
  end

  {:noreply, state}
end

def handle_info({:process_hub, :handover, 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

Summary

Types

t()

Hot-swap migration strategy configuration. Available options

Types

Link to this type

t()

View Source 
@type t() :: %ProcessHub.Strategy.Migration.HotSwap{
  handover: boolean(),
  retention: pos_integer()
}

Hot-swap migration strategy configuration. Available options:

  • :retention - An integer value in milliseconds is used to specify how long the peer process should be kept alive after a new child process has been started on the remote node. This option is used to ensure that the peer process has had enough time to perform any cleanup or state synchronization before the local process is terminated. Keep in mind that process will be terminated before the retention time has passed if the peer process has notified the handler process that the state transfer has been handled. The default value is 5000.

  • :handover - A boolean value. If set to true, the processes involved in the migration must handle the following message: {:process_hub, :handover_start, startup_resp, from}. This message will be sent to the peer process that will be terminated after the migration. The variable startup_resp will contain the response from the ProcessHub.DistributedSupervisor.start_child/2 function, and if successful, it will be {:ok, pid}. The PID can be used to send the state of the process to the remote process. If the retention option is used, then the peer process has to signal the handler process that the state has been handled; otherwise, the handler will wait until the default retention time has passed. The handler PID is passed in the from variable. The default value is false.