diff options
| -rw-r--r-- | lib/sasl/doc/src/appup.xml | 37 | ||||
| -rw-r--r-- | lib/sasl/doc/src/release_handler.xml | 16 | ||||
| -rw-r--r-- | lib/sasl/src/release_handler.erl | 6 | ||||
| -rw-r--r-- | system/doc/design_principles/appup_cookbook.xml | 43 | ||||
| -rw-r--r-- | system/doc/design_principles/release_handling.xml | 52 |
5 files changed, 123 insertions, 31 deletions
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 <pre> restart_new_emulator </pre> - <p>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.</p> + <p>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 <c>restart_new_emulator</c> + instruction is allowed in the relup, and it shall be placed + first. <seealso marker="systools#make_relup/3">systools:make_relup3,4</seealso> + 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.</p> + <p>An info report will be written when the upgrade is + completed. To programatically find out if the upgrade is + complete, + call <seealso marker="release_handler#which_release/0"> + release_handler:which_releases</seealso> and check if the + expected release has status <c>current</c>.</p> + <p>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.</p> + <pre> +restart_emulator + </pre> + <p>This instruction is similar to <c>restart_new_emulator</c>, + 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, <seealso marker="systools#make_relup/3">systools:make_relup/3,4</seealso> + ensures that there is only one <c>restart_emulator</c> + instruction and that it is the last instruction of the + relup.</p> </section> <section> 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 </func> <func> <name>install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name> - <name>install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {error, Reason}</name> + <name>install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}</name> <fsummary>Install a release in the system.</fsummary> <type> <v>Vsn = OtherVsn = string()</v> @@ -248,7 +248,8 @@ old reboot_old permanent <v> Timeout = default | infinity | int()>0</v> <v> Bool = boolean()</v> <v>Descr = term()</v> - <v>Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | term()</v> + <v>Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term()</v> + <v>App = atom()</v> </type> <desc> <p>Installs the specified version <c>Vsn</c> of the release. @@ -268,6 +269,15 @@ old reboot_old permanent <c>OtherVsn</c> and <c>Descr</c> are the version (<c>UpFromVsn</c> or <c>Vsn</c>) and description (<c>Descr1</c> or <c>Descr2</c>) as specified in the script.</p> + <p>If <c>{continue_after_restart,OtherVsn,Descr}</c> 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.</p> <p>If a recoverable error occurs, the function returns <c>{error,Reason}</c> 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 <c>release_handler</c> does.</p> <warning> - <p>These function is primarily intended for simplified testing of + <p>These functions are primarily intended for simplified testing of <c>.appup</c> files. They are not run within the context of the <c>release_handler</c> process. They must therefore <em>not</em> 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() %%----------------------------------------------------------------- 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 @@ <chapter> <header> <copyright> - <year>2003</year><year>2009</year> + <year>2003</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -603,25 +603,42 @@ code_change(_OldVsn, State, port) -> </section> <section> - <title>Emulator Restart</title> - <p>If the emulator can or should be restarted, the very simple - <c>.relup</c> file can be created manually:</p> + <title>Emulator Restart and Upgrade</title> + <p>There are two upgrade instructions that will restart the emulator:</p> + <taglist> + <tag><c>restart_new_emulator</c></tag> + <item>Intended for when erts, kernel, stdlib or sasl is + upgraded. It is automatically added when the relup file is + generated by <c>systools:make_relup/3,4</c>. It is executed + before all other upgrade instructions. See + <seealso marker="release_handling#restart_new_emulator_instr">Release + Handling</seealso> for more information about this + instruction.</item> + <tag><c>restart_emulator</c></tag> + <item>Used when a restart of the emulator is required after all + other upgrade instructions are executed. See + <seealso marker="release_handling#restart_emulator_instr">Release + Handling</seealso> for more information about this + instruction.</item> + </taglist> + + <p>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 <c>.relup</c> file can be created manually:</p> <code type="none"> {"B", [{"A", [], - [restart_new_emulator]}], + [restart_emulator]}], [{"A", [], - [restart_new_emulator]}] + [restart_emulator]}] }.</code> - <p>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 <c>.appup</c> files.</p> - <p>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 <c>.relup</c> - file as well.</p> + <p>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 <c>.appup</c> + files.</p> </section> </chapter> 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 @@ <chapter> <header> <copyright> - <year>2003</year><year>2009</year> + <year>2003</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -313,18 +313,35 @@ </section> <section> + <marker id="restart_new_emulator_instr"></marker> <title>restart_new_emulator (low-level)</title> <p>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 <c>restart_emulator</c> instruction should + be used instead.</p> + <p>Requires that the system is started with heart beat monitoring, see <c>erl(1)</c> and <c>heart(3)</c>.</p> - <p>When the release handler encounters the instruction, it shuts - down the current emulator by calling <c>init:reboot()</c>, see + <p>The <c>restart_new_emulator</c> instruction shall always be + the very first instruction in a relup. If the relup is + generated by <c>systools:make_relup/3,4</c> this is + automatically ensured.</p> + <p>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 <c>init:reboot()</c>, see <c>init(3)</c>. 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.</p> + 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.</p> + <p>An info report is written when the upgrade is completed. To + programatically find out if the upgrade is complete, + call <c>release_handler:which_releases/0</c> and check if the + expected release has status <c>current</c>.</p> + <p>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.</p> <p>On UNIX, the release handler tells the heart program which command to use to reboot the system. Note that the environment variable <c>HEART_COMMAND</c>, normally used by the heart @@ -333,6 +350,25 @@ by using the SASL configuration parameter <c>start_prg</c>, see <c>sasl(6)</c>.</p> </section> + + <section> + <marker id="restart_emulator_instr"></marker> + <title>restart_emulator (low-level)</title> + <p>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.</p> + <p>There can only be one <c>restart_emulator</c> instruction in + a relup script, and it shall always be placed at the end. If + the relup is generated by <c>systools:make_relup/3,4</c> this + is automatically ensured.</p> + <p>When the release handler encounters the instruction, it shuts down + the emulator by calling <c>init:reboot()</c>, see + <c>init(3)</c>. 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.</p> + </section> </section> <section> |