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.

+
-- cgit v1.2.3