edeliver v1.2.6 Edeliver.Relup.Instructions.SuspendChannels

This upgrade instruction suspends the websocket processes

connected to phoenix channels to avoid that new channel events will be processed during the code upgrade / downgrade process. It will be appended to the instructions after the “point of no return” but before any application code is reloaded. It should be used in conjunction with and after the

Edeliver.Relup.Instructions.SuspendRanchAcceptors

instruction which avoids that new websockets processes for phoenix channels are started.

To make sure that the websocket connections can be found on the node, use this instruction after the

Edeliver.Relup.Instructions.CheckRanchConnections

instruction which will abort the upgrade if ranch (websocket) connections cannot be found in the supervision tree. Use the

Edeliver.Relup.Instructions.ResumeRanchAcceptors

instruction at the end of your instructions list to resume the websocket processes and reenable handling channel messages.

Suspending and resuming websocket processes for phoenix channels requires a recent phoenix version which handles sys events for websockets. It also requires that the builtin phoenix pubsub backend Phoenix.PubSub.PG2 is used for the phoenix channels.

Summary

Types

insert_fun()

instruction()

instructions()

Functions

arguments(instructions, config)

Returns name of the application. This name is taken as argument for the run/1 function and is required to access the acceptor processes through the supervision tree

bulk_suspend(processes, timeout \\ 1000)

Suspends a list of processes. Because suspending a process might take a while depending on the length of the message queue or duration of current operation processed by the pid, suspending is done asynchronously for each process by spawing a new process which calls :sys.suspend/2 and then waiting for all results before returning from this function. Be careful when using :infinity as timeout, because this function might hang for infinite time if one of the process does not handle sys events

call_this(arguments \\ [])

Calls the run/1 function of this module

debug(message)

Logs a debug message using the Logger on the running node which is upgraded

dependencies()

This module depends on the Edeliver.Relup.Instructions.CheckRanchAcceptors and the Edeliver.Relup.Instructions.CheckRanchConnections module which must be loaded before this instruction for upgrades and unload after this instruction for downgrades

ensure_dependencies_loaded_before_instruction_for_upgrade(instructions, call_this_instruction, dependencies \\ dependencies())

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the dependencies/0 callback are loaded before this instruction is executed during the upgrade

ensure_dependencies_unloaded_after_instruction_for_downgrade(instructions, call_this_instruction, dependencies \\ dependencies())

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the dependencies/0 callback are unloaded after this instruction is executed during the downgrade

error(message)

Logs an error using the Logger on the running node which is upgraded

format_in_upgrade_script(format, arguments)

Formats and prints the message on the node

info(message)

Logs an info message using the Logger on the running node which is upgraded

insert_where()

Appends this instruction to the instructions after the “point of no return” but before any instruction which loads or unloads new code, (re-)starts or stops any running processes, or (re-)starts or stops any application or the emulator

log_in_upgrade_script(type, message)

Logs the message of the given type on the node

modify_relup(instructions, config)

Callback implementation for Edeliver.Relup.Instruction.modify_relup/2

run(otp_application_name)

Suspends all websocket channels to avoid handling new channel events during the upgrade. This is possible only in recent phoenix versions since handling sys events is required for suspending. If an older version is used, a warning is printed that suspending is not supported

warn(message)

Logs a warning using the Logger on the running node which is upgraded

Macros

assume(assertion, error_message)

Assumes that the pattern matches or throws an error with the given error message

Types

insert_fun :: (%Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term} | instructions, new_instructions :: instruction | instructions -> updated_instructions :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term} | instructions)

instruction :: :relup.instruction

instructions :: [instruction]

Functions

arguments(instructions, config)

Specs

arguments(%Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}, %ReleaseManager.Config{dev: term, env: term, erl: term, name: term, package: term, relx_config: term, upgrade?: term, verbosity: term, version: term}) :: term

Returns name of the application. This name is taken as argument for the run/1 function and is required to access the acceptor processes through the supervision tree

bulk_suspend(processes, timeout \\ 1000)

Specs

bulk_suspend(processes :: [pid], timeout :: pos_integer | :infinity) ::
  :ok |
  {:errors, count :: pos_integer, [{pid :: pid, reason :: term}]} |
  :not_supported

call_this(arguments \\ [])

Specs

call_this(arguments :: [term]) ::
  instruction |
  instructions

Calls the run/1 function of this module

from the relup file during hot code upgrade

debug(message)

Specs

debug(message :: String.t) :: no_return

Logs a debug message using the Logger on the running node which is upgraded.

In addition the same debug message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

dependencies()

Specs

dependencies :: [instruction_module :: atom]

dependencies :: [Edeliver.Relup.Instructions.CheckRanchAcceptors]

ensure_dependencies_loaded_before_instruction_for_upgrade(instructions, call_this_instruction, dependencies \\ dependencies())

Specs

ensure_dependencies_loaded_before_instruction_for_upgrade(instructions :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}, runnable_instruction :: {:apply, {module :: atom, :run, arguments :: [term]}}, dependencies :: [instruction_module :: atom]) :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}

ensure_dependencies_unloaded_after_instruction_for_downgrade(instructions, call_this_instruction, dependencies \\ dependencies())

Specs

ensure_dependencies_unloaded_after_instruction_for_downgrade(instructions :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}, runnable_instruction :: {:apply, {module :: atom, :run, arguments :: [term]}}, dependencies :: [instruction_module :: atom]) :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}

error(message)

Specs

error(message :: String.t) :: no_return

Logs an error using the Logger on the running node which is upgraded.

In addition the same error message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

format_in_upgrade_script(format, arguments)

Specs

format_in_upgrade_script(format :: char_list, arguments :: [term]) :: no_return

Formats and prints the message on the node

running the upgrade script which was started by the $APP/bin/$APP upgrade $RELEASE command.

info(message)

Specs

info(message :: String.t) :: no_return

Logs an info message using the Logger on the running node which is upgraded.

In addition the same info message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

insert_where()

Specs

insert_where :: insert_fun

log_in_upgrade_script(type, message)

Specs

log_in_upgrade_script(type :: :error | :warning | :info | :debug, message :: String.t) :: no_return

Logs the message of the given type on the node

which executes the upgrade and displays it as output of the $APP/bin/$APP upgrade $RELEASE command. The message is prefixed with a string derived from the message type.

modify_relup(instructions, config)

Callback implementation for Edeliver.Relup.Instruction.modify_relup/2.

run(otp_application_name)

Specs

run(otp_application_name :: atom) :: :ok

warn(message)

Specs

warn(message :: String.t) :: no_return

Logs a warning using the Logger on the running node which is upgraded.

In addition the same warning message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

Macros

assume(assertion, error_message)

Assumes that the pattern matches or throws an error with the given error message.

The error message is logged as error to the logfile using the Logger and displayed as error output by the $APP/bin/$APP upgrade $RELEASE task using the $APP/ebin/install_upgrade.escript script. If the pattern matches the variables from the matching are assigned.