From 281fb9929e2cdcfdaf95e0b90b3b690b78535ddb Mon Sep 17 00:00:00 2001
From: Siri Hansen
Date: Mon, 24 Oct 2011 14:25:15 +0200
Subject: Document upgrade instructions restart_new_emulator and
restart_emulator
---
system/doc/design_principles/appup_cookbook.xml | 43 +++++++++++++------
system/doc/design_principles/release_handling.xml | 52 +++++++++++++++++++----
2 files changed, 74 insertions(+), 21 deletions(-)
(limited to 'system/doc/design_principles')
diff --git a/system/doc/design_principles/appup_cookbook.xml b/system/doc/design_principles/appup_cookbook.xml
index bc61578953..eebe6ba7b4 100644
--- a/system/doc/design_principles/appup_cookbook.xml
+++ b/system/doc/design_principles/appup_cookbook.xml
@@ -4,7 +4,7 @@
- 20032009
+ 20032011
Ericsson AB. All Rights Reserved.
@@ -603,25 +603,42 @@ code_change(_OldVsn, State, port) ->
- Emulator Restart
- If the emulator can or should be restarted, the very simple
- .relup file can be created manually:
+ Emulator Restart and Upgrade
+ There are two upgrade instructions that will restart the emulator:
+
+ restart_new_emulator
+ - Intended for when erts, kernel, stdlib or sasl is
+ upgraded. It is automatically added when the relup file is
+ generated by systools:make_relup/3,4. It is executed
+ before all other upgrade instructions. See
+ Release
+ Handling for more information about this
+ instruction.
+ restart_emulator
+ - Used when a restart of the emulator is required after all
+ other upgrade instructions are executed. See
+ Release
+ Handling for more information about this
+ instruction.
+
+
+ If an emulator restart is necessary and no upgrade instructions
+ are needed, i.e. if the restart itself is enough for the
+ upgraded applications to start running the new versions, a very
+ simple .relup file can be created manually:
{"B",
[{"A",
[],
- [restart_new_emulator]}],
+ [restart_emulator]}],
[{"A",
[],
- [restart_new_emulator]}]
+ [restart_emulator]}]
}.
- This way, the release handler framework with automatic packing
- and unpacking of release packages, automatic path updates etc. can
- be used without having to specify .appup files.
- If some transformation of persistent data, for example database
- contents, needs to be done before installing the new release
- version, instructions for this can be added to the .relup
- file as well.
+ In this case, the release handler framework with automatic
+ packing and unpacking of release packages, automatic path
+ updates etc. can be used without having to specify .appup
+ files.
diff --git a/system/doc/design_principles/release_handling.xml b/system/doc/design_principles/release_handling.xml
index 1d62c242c0..8ed36f3c56 100644
--- a/system/doc/design_principles/release_handling.xml
+++ b/system/doc/design_principles/release_handling.xml
@@ -4,7 +4,7 @@
- 20032009
+ 20032011
Ericsson AB. All Rights Reserved.
@@ -313,18 +313,35 @@
+
restart_new_emulator (low-level)
This instruction is used when changing to a new emulator
- version, or if a system reboot is needed for some other reason.
- Requires that the system is started with heart beat
+ version, or when any of the core applications kernel, stdlib
+ or sasl is upgraded. If a system reboot is needed for some
+ other reason, the restart_emulator instruction should
+ be used instead.
+ Requires that the system is started with heart beat
monitoring, see erl(1) and heart(3).
- When the release handler encounters the instruction, it shuts
- down the current emulator by calling init:reboot(), see
+
The restart_new_emulator instruction shall always be
+ the very first instruction in a relup. If the relup is
+ generated by systools:make_relup/3,4 this is
+ automatically ensured.
+ When the release handler encounters the instruction, it first
+ generates a temporary boot file, which starts the new versions
+ of the emulator and the core applications. Then it shuts down
+ the current emulator by calling init:reboot(), see
init(3). All processes are terminated gracefully and
the system can then be rebooted by the heart program, using
- the new release version. This new version must still be made
- permanent when the new emulator is up and running. Otherwise,
- the old version is used in case of a new system reboot.
+ the temporary boot file. After the reboot, the rest of the
+ relup instructions are executed. This is done as a part of the
+ boot script.
+ An info report is written when the upgrade is completed. To
+ programatically find out if the upgrade is complete,
+ call release_handler:which_releases/0 and check if the
+ expected release has status current.
+ The new version must be made permanent when the new emulator
+ is up and running. Otherwise, the old version will be used in
+ case of a new system reboot.
On UNIX, the release handler tells the heart program which
command to use to reboot the system. Note that the environment
variable HEART_COMMAND, normally used by the heart
@@ -333,6 +350,25 @@
by using the SASL configuration parameter start_prg, see
sasl(6).
+
+
+
+ restart_emulator (low-level)
+ This instruction is not related to upgrades of erts or any of
+ the core applications. It can be used by any application to
+ force a restart of the emulator after all upgrade instructions
+ are executed.
+ There can only be one restart_emulator instruction in
+ a relup script, and it shall always be placed at the end. If
+ the relup is generated by systools:make_relup/3,4 this
+ is automatically ensured.
+ When the release handler encounters the instruction, it shuts down
+ the emulator by calling init:reboot(), see
+ init(3). All processes are terminated gracefully and
+ the system can then be rebooted by the heart program using the
+ new release version. No more upgrade instruction will be
+ executed after the restart.
+