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 --- lib/sasl/doc/src/appup.xml | 37 ++++++++++++++++++++++++++++++------ lib/sasl/doc/src/release_handler.xml | 16 +++++++++++++--- lib/sasl/src/release_handler.erl | 6 +++++- 3 files changed, 49 insertions(+), 10 deletions(-) (limited to 'lib') diff --git a/lib/sasl/doc/src/appup.xml b/lib/sasl/doc/src/appup.xml index 89bcf23b5e..195f9fe1d3 100644 --- a/lib/sasl/doc/src/appup.xml +++ b/lib/sasl/doc/src/appup.xml @@ -319,12 +319,37 @@ point_of_no_return 
 restart_new_emulator
-

Shuts down the current emulator and starts a ne one. All - processes are terminated gracefully. The new release must still - be made permanent when the new emulator is up and running. - Otherwise, the old emulator is started in case of a emulator - restart. This instruction should be used when a new emulator is - introduced, or if a complete reboot of the system should be done.

+

This instruction is used when erts, kernel, stdlib or sasl is + upgraded. It shuts down the current emulator and starts a new + one. All processes are terminated gracefully, and the new + version of erts, kernel, stdlib and sasl are used when the + emulator restarts. Only one restart_new_emulator + instruction is allowed in the relup, and it shall be placed + first. systools:make_relup3,4 + will ensure this when the relup is generated. The rest of the + relup script is executed after the restart as a part of the boot + script.

+

An info report will be written when the upgrade is + completed. To programatically find out if the upgrade is + complete, + call + release_handler:which_releases and check if the + expected release has status current.

+

The new release must still be made permanent after the upgrade + is completed. Otherwise, the old emulator is started in case of + an emulator restart.

+ 
+restart_emulator
+
+

This instruction is similar to restart_new_emulator, + except it shall be placed at the end of the relup script. It is + not related to an upgrade of the emulator or the core + applications, but can be used by any application when a complete + reboot of the system is reqiured. When generating the + relup, systools:make_relup/3,4 + ensures that there is only one restart_emulator + instruction and that it is the last instruction of the + relup.

diff --git a/lib/sasl/doc/src/release_handler.xml b/lib/sasl/doc/src/release_handler.xml index 5ac0dc1acc..c625b40c9d 100644 --- a/lib/sasl/doc/src/release_handler.xml +++ b/lib/sasl/doc/src/release_handler.xml @@ -238,7 +238,7 @@ old reboot_old permanent install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason} - install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {error, Reason} + install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason} Install a release in the system. Vsn = OtherVsn = string() @@ -248,7 +248,8 @@ old reboot_old permanent  Timeout = default | infinity | int()>0  Bool = boolean() Descr = term() - Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | term() + Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term() + App = atom()

Installs the specified version Vsn of the release. @@ -268,6 +269,15 @@ old reboot_old permanent OtherVsn and Descr are the version (UpFromVsn or Vsn) and description (Descr1 or Descr2) as specified in the script.

+

If {continue_after_restart,OtherVsn,Descr} is + returned, it means that the emulator will be restarted + before the upgrade instructions are executed. This will + happen if the emulator or any of the applications kernel, + stdlib or sasl are updated. The new version of the emulator + and these core applications will execute after the restart, + but for all other applications the old versions will be + started and the upgrade will be performed as normal by + executing the upgrade instructions.

If a recoverable error occurs, the function returns {error,Reason} and the original application specifications are restored. If a non-recoverable error @@ -442,7 +452,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). and evaluated exactly in the same way as release_handler does.

-

These function is primarily intended for simplified testing of +

These functions are primarily intended for simplified testing of .appup files. They are not run within the context of the release_handler process. They must therefore not be used together with calls to diff --git a/lib/sasl/src/release_handler.erl b/lib/sasl/src/release_handler.erl index abe6d6bee6..87660db3e3 100644 --- a/lib/sasl/src/release_handler.erl +++ b/lib/sasl/src/release_handler.erl @@ -193,11 +193,15 @@ check_check_install_options([],Purge) -> %%----------------------------------------------------------------- %% Purpose: Executes the relup script for the specified version. %% The release must be unpacked. -%% Returns: {ok, FromVsn, Descr} | {error, Reason} +%% Returns: {ok, FromVsn, Descr} | +%% {continue_after_restart, FromVsn, Descr} | +%% {error, Reason} %% Reason = {already_installed, Vsn} | %% {bad_relup_file, RelFile} | %% {no_such_release, Vsn} | %% {no_such_from_vsn, Vsn} | +%% {could_not_create_hybrid_boot,Why} | +%% {missing_base_app,Vsn,App} | %% {illegal_option, Opt}} | %% exit_reason() %%----------------------------------------------------------------- -- cgit v1.2.3