Skip to content

Commit

Permalink
Document upgrade instructions restart_new_emulator and restart_emulator
Browse files Browse the repository at this point in the history
  • Loading branch information
@sirihansen
sirihansen committed Nov 17, 2011
1 parent 1e344f3 commit 281fb99
Show file tree
Hide file tree
Showing 5 changed files with 123 additions and 31 deletions.
37 changes: 31 additions & 6 deletions lib/sasl/doc/src/appup.xml
View file
Expand Up @@ -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>
Expand Down
16 changes: 13 additions & 3 deletions lib/sasl/doc/src/release_handler.xml
View file
Expand Up @@ -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>
Expand All @@ -248,7 +248,8 @@ old reboot_old permanent
<v>&nbsp;Timeout = default | infinity | int()>0</v>
<v>&nbsp;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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion lib/sasl/src/release_handler.erl
View file
Expand Up @@ -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()
%%-----------------------------------------------------------------
Expand Down
43 changes: 30 additions & 13 deletions system/doc/design_principles/appup_cookbook.xml
View file
Expand Up @@ -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>
Expand Down Expand Up @@ -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>

52 changes: 44 additions & 8 deletions system/doc/design_principles/release_handling.xml
View file
Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand All @@ -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>
Expand Down

0 comments on commit 281fb99

Please sign in to comment.