1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE fileref SYSTEM "fileref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
33
<filesummary>Application upgrade file.</filesummary>
35
<p>The <em>application upgrade file</em> defines how an application
36
is upgraded or downgraded in a running system.</p>
37
<p>This file is used by the functions in <c>systools</c> when
38
generating a release upgrade file <c>relup</c>.</p>
42
<title>FILE SYNTAX</title>
43
<p>The application upgrade file should be called
44
<c>Application.appup</c> where <c>Application</c> is the name of
45
the application. The file should be located in the <c>ebin</c>
46
directory for the application.</p>
47
<p>The <c>.appup</c> file contains one single Erlang term, which
48
defines the instructions used to upgrade or downgrade
49
the application. The file has the following syntax:</p>
52
[{UpFromVsn, Instructions}, ...],
53
[{DownToVsn, Instructions}, ...]}.
55
<list type="bulleted">
57
<p><c>Vsn = string()</c> is the current version of
61
<p><c>UpFromVsn = string()</c> is an earlier version of
62
the application to upgrade from.</p>
65
<p><c>DownToVsn = string()</c> is an earlier version of
66
the application to downgrade to.</p>
69
<p><c>Instructions</c> is a list of <em>release upgrade instructions</em>, see below. It is recommended to use
70
high-level instructions only. These are automatically
71
translated to low-level instructions by <c>systools</c> when
72
creating the <c>relup</c> file.</p>
78
<title>RELEASE UPGRADE INSTRUCTIONS</title>
79
<p>Release upgrade instructions are interpreted by the release
80
handler when an upgrade or downgrade is made. For more
81
information about release handling, refer to <em>OTP Design Principes</em>.</p>
82
<p>A process is said to <em>use</em> a module <c>Mod</c>, if
83
<c>Mod</c> is listed in the <c>Modules</c> part of the child
84
specification used to start the process, see <c>supervisor(3)</c>.
85
In the case of gen_event, an event manager process is said to use
86
<c>Mod</c> if <c>Mod</c> is an installed event handler.</p>
87
<p><em>High-level instructions</em></p>
90
{update, Mod, supervisor}
92
{update, Mod, DepMods}
93
{update, Mod, Change, DepMods}
94
{update, Mod, Change, PrePurge, PostPurge, DepMods}
95
{update, Mod, Timeout, Change, PrePurge, PostPurge, DepMods}
96
{update, Mod, ModType, Timeout, Change, PrePurge, PostPurge, DepMods}
98
ModType = static | dynamic
99
Timeout = int()>0 | default | infinity
100
Change = soft | {advanced,Extra}
102
PrePurge = PostPurge = soft_purge | brutal_purge
105
<p>Synchronized code replacement of processes using the module
106
<c>Mod</c>. All those processes are suspended using
107
<c>sys:suspend</c>, the new version of the module is loaded and
108
then the processes are resumed using <c>sys:resume</c>.</p>
109
<p><c>Change</c> defaults to <c>soft</c> and defines the type of
110
code change. If it is set to <c>{advanced,Extra}</c>, processes
111
implemented using gen_server, gen_fsm or gen_event will transform
112
their internal state by calling the callback function
113
<c>code_change</c>. Special processes will call the callback
114
function <c>system_code_change/4</c>. In both cases, the term
115
<c>Extra</c> is passed as an argument to the callback function.</p>
116
<p><c>PrePurge</c> defaults to <c>brutal_purge</c> and controls
117
what action to take with processes that are executing old code
118
before loading the new version of the module. If the value
119
is <c>brutal_purge</c>, the processes are killed. If the value is
120
<c>soft_purge</c>, <c>release_handler:install_release/1</c>
121
returns <c>{error,{old_processes,Mod}}</c>.</p>
122
<p><c>PostPurge</c> defaults to <c>brutal_purge</c> and controls
123
what action to take with processes that are executing old code
124
when the new version of the module has been loaded. If the value
125
is <c>brutal_purge</c>, the code is purged when the release is
126
made permanent and the processes are killed. If the value is
127
<c>soft_purge</c>, the release handler will purge the old code
128
when no remaining processes execute the code.</p>
129
<p><c>DepMods</c> defaults to [] and defines which other modules
130
<c>Mod</c> is dependent on. In <c>relup</c>, instructions for
131
suspending processes using <c>Mod</c> will come before
132
instructions for suspending processes using modules in
133
<c>DepMods</c> when upgrading, and vice versa when downgrading.
134
In case of circular dependencies, the order of the instructions in
135
the <c>appup</c> script is kept.</p>
136
<p><c>Timeout</c> defines the timeout when suspending processes.
137
If no value or <c>default</c> is given, the default value for
138
<c>sys:suspend</c> is used.</p>
139
<p><c>ModType</c> defaults to <c>dynamic</c> and specifies if
140
the code is "dynamic", that is if a process using the module does
141
spontaneously switch to new code, or if it is "static".
142
When doing an advanced update and upgrading, the new version of a
143
dynamic module is loaded before the process is asked to change
144
code. When downgrading, the process is asked to change code before
145
loading the new version. For static modules, the new version is
146
loaded before the process is asked to change code, both in
147
the case of upgrading and downgrading. Callback modules are
149
<p><c>update</c> with argument <c>supervisor</c> is used when
150
changing the start specification of a supervisor.</p>
153
{load_module, Mod, DepMods}
154
{load_module, Mod, PrePurge, PostPurge, DepMods}
156
PrePurge = PostPurge = soft_purge | brutal_purge
159
<p>Simple code replacement of the module <c>Mod</c>.</p>
160
<p>See <c>update</c> above for a description of <c>PrePurge</c> and
161
<c>PostPurge</c>.</p>
162
<p><c>DepMods</c> defaults to [] and defines which other modules
163
<c>Mod</c> is dependent on. In <c>relup</c>, instructions for
164
loading these modules will come before the instruction for loading
165
<c>Mod</c> when upgrading, and vice versa when downgrading.</p>
170
<p>Loads a new module <c>Mod</c>.</p>
175
<p>Deletes a module <c>Mod</c> using the low-level instructions
176
<c>remove</c> and <c>purge</c>.</p>
178
{add_application, Application}
181
<p>Adding an application means that the modules defined by
182
the <c>modules</c> key in the <c>.app</c> file are loaded using
183
<c>add_module</c>, then the application is started.</p>
185
{remove_application, Application}
188
<p>Removing an application means that the application is stopped,
189
the modules are unloaded using <c>delete_module</c> and then
190
the application specification is unloaded from the application
193
{restart_application, Application}
196
<p>Restarting an application means that the application is
197
stopped and then started again similar to using the instructions
198
<c>remove_application</c> and <c>add_application</c> in sequence.</p>
199
<p><em>Low-level instructions</em></p>
201
{load_object_code, {App, Vsn, [Mod]}}
205
<p>Reads each <c>Mod</c> from the directory <c>App-Vsn/ebin</c> as
206
a binary. It does not load the modules. The instruction should be
207
placed first in the script in order to read all new code from file
208
to make the suspend-load-resume cycle less time consuming. After
209
this instruction has been executed, the code server with the new
210
version of <c>App</c>.</p>
214
<p>If a crash occurs after this instruction, the system cannot
215
recover and is restarted from the old version of the release.
216
The instruction must only occur once in a script. It should be
217
placed after all <c>load_object_code</c> instructions.</p>
219
{load, {Mod, PrePurge, PostPurge}}
221
PrePurge = PostPurge = soft_purge | brutal_purge
223
<p>Before this instruction occurs, <c>Mod</c> must have been loaded
224
using <c>load_object_code</c>. This instruction loads the module.
225
<c>PrePurge</c> is ignored. See the high-level instruction
226
<c>update</c> for a description of <c>PostPurge</c>.</p>
228
{remove, {Mod, PrePurge, PostPurge}}
230
PrePurge = PostPurge = soft_purge | brutal_purge
232
<p>Makes the current version of <c>Mod</c> old.
233
<c>PrePurge</c> is ignored. See the high-level instruction
234
<c>update</c> for a description of <c>PostPurge</c>.</p>
239
<p>Purges each module <c>Mod</c>, that is removes the old code.
240
Note that any process executing purged code is killed.</p>
242
{suspend, [Mod | {Mod, Timeout}]}
244
Timeout = int()>0 | default | infinity
246
<p>Tries to suspend all processes using a module <c>Mod</c>. If a
247
process does not respond, it is ignored. This may cause
248
the process to die, either because it crashes when it
249
spontaneously switches to new code, or as a result of a purge
250
operation. If no <c>Timeout</c> is specified or <c>default</c> is
251
given, the default value for <c>sys:suspend</c> is used.</p>
256
<p>Resumes all suspended processes using a module <c>Mod</c>.</p>
258
{code_change, [{Mod, Extra}]}
259
{code_change, Mode, [{Mod, Extra}]}
264
<p><c>Mode</c> defaults to <c>up</c> and specifies if it is an
265
upgrade or downgrade.</p>
266
<p>This instruction sends a <c>code_change</c> system message to
267
all processes using a module <c>Mod</c> by calling the function
268
<c>sys:change_code</c>, passing the term <c>Extra</c> as argument.</p>
273
<p>Stops all processes using a module <c>Mod</c> by calling
274
<c>supervisor:terminate_child/2</c>. The instruction is useful
275
when the simplest way to change code is to stop and restart the
276
processes which run the code.</p>
281
<p>Starts all stopped processes using a module <c>Mod</c> by calling
282
<c>supervisor:restart_child/2</c>.</p>
284
{sync_nodes, Id, [Node]}
285
{sync_nodes, Id, {M, F, A}}
291
<p><c>apply(M, F, A)</c> must return a list of nodes.</p>
292
<p>The instruction synchronizes the release installation with other
293
nodes. Each <c>Node</c> must evaluate this command, with the same
294
<c>Id</c>. The local node waits for all other nodes to evaluate
295
the instruction before execution continues. In case a node goes
296
down, it is considered to be an unrecoverable error, and
297
the local node is restarted from the old release. There is no
298
timeout for this instruction, which means that it may hang
305
<p>Evaluates <c>apply(M, F, A)</c>. If the instruction appears
306
before the <c>point_of_no_return</c> instruction, a failure is
307
caught. <c>release_handler:install_release/1</c> then returns
308
<c>{error,{'EXIT',Reason}}</c>, unless <c>{error,Error}</c> is
309
thrown or returned. Then it returns <c>{error,Error}</c>.</p>
310
<p>If the instruction appears after the <c>point_of_no_return</c>
311
instruction, and the function call fails, the system is
316
<p>Shuts down the current emulator and starts a ne one. All
317
processes are terminated gracefully. The new release must still
318
be made permanent when the new emulator is up and running.
319
Otherwise, the old emulator is started in case of a emulator
320
restart. This instruction should be used when a new emulator is
321
introduced, or if a complete reboot of the system should be done.</p>
325
<title>SEE ALSO</title>
326
<p><seealso marker="relup">relup(4)</seealso>,
327
<seealso marker="release_handler">release_handler(3)</seealso>,
329
<seealso marker="systools">systools(3)</seealso></p>
added
removed
lib/sasl/doc/src/appup.xml
