1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
<TITLE>appup</TITLE>
<SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
<STYLE TYPE="text/css">
<!--
.REFBODY { margin-left: 13mm }
.REFTYPES { margin-left: 8mm }
-->
</STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
<IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>appup</H1>
</CENTER>
<H3>FILE</H3>
<DIV CLASS=REFBODY>
appup
</DIV>
<H3>FILE SUMMARY</H3>
<DIV CLASS=REFBODY>
Application upgrade file.
</DIV>
<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>
<P>The <STRONG>application upgrade file</STRONG> defines how an application
is upgraded or downgraded in a running system.
<P>This file is used by the functions in <CODE>systools</CODE> when
generating a release upgrade file <CODE>relup</CODE>.
</DIV>
<H3>FILE SYNTAX</H3>
<DIV CLASS=REFBODY>
<P>The application upgrade file should be called
<CODE>Application.appup</CODE> where <CODE>Application</CODE> is the name of
the application. The file should be located in the <CODE>ebin</CODE>
directory for the application.
<P>The <CODE>.appup</CODE> file contains one single Erlang term, which
defines the instructions used to upgrade or downgrade
the application. The file has the following syntax:
<PRE>
{Vsn,
[{UpFromVsn, Instructions}, ...],
[{DownToVsn, Instructions}, ...]}.
</PRE>
<P>
<UL>
<LI>
<CODE>Vsn = string()</CODE> is the current version of
the application.<BR>
</LI>
<LI>
<CODE>UpFromVsn = string()</CODE> is an earlier version of
the application to upgrade from.<BR>
</LI>
<LI>
<CODE>DownToVsn = string()</CODE> is an earlier version of
the application to downgrade to.<BR>
</LI>
<LI>
<CODE>Instructions</CODE> is a list of <STRONG>release upgrade
instructions</STRONG>, see below. It is recommended to use
high-level instructions only. These are automatically
translated to low-level instructions by <CODE>systools</CODE> when
creating the <CODE>relup</CODE> file.<BR>
</LI>
</UL>
</DIV>
<H3>RELEASE UPGRADE INSTRUCTIONS</H3>
<DIV CLASS=REFBODY>
<P>Release upgrade instructions are interpreted by the release
handler when an upgrade or downgrade is made. For more
information about release handling, refer to <STRONG>OTP Design
Principes</STRONG>.
<P>A process is said to <STRONG>use</STRONG> a module <CODE>Mod</CODE>, if
<CODE>Mod</CODE> is listed in the <CODE>Modules</CODE> part of the child
specification used to start the process, see <CODE>supervisor(3)</CODE>.
In the case of gen_event, an event manager process is said to use
<CODE>Mod</CODE> if <CODE>Mod</CODE> is an installed event handler.
<P><STRONG>High-level instructions</STRONG>
<PRE>
{update, Mod}
{update, Mod, supervisor}
{update, Mod, Change}
{update, Mod, DepMods}
{update, Mod, Change, DepMods}
{update, Mod, Change, PrePurge, PostPurge, DepMods}
{update, Mod, Timeout, Change, PrePurge, PostPurge, DepMods}
{update, Mod, ModType, Timeout, Change, PrePurge, PostPurge, DepMods}
Mod = atom()
ModType = static | dynamic
Timeout = int()>0 | default | infinity
Change = soft | {advanced,Extra}
Extra = term()
PrePurge = PostPurge = soft_purge | brutal_purge
DepMods = [Mod]
</PRE>
<P>Synchronized code replacement of processes using the module
<CODE>Mod</CODE>. All those processes are suspended using
<CODE>sys:suspend</CODE>, the new version of the module is loaded and
then the processes are resumed using <CODE>sys:resume</CODE>.
<P><CODE>Change</CODE> defaults to <CODE>soft</CODE> and defines the type of
code change. If it is set to <CODE>{advanced,Extra}</CODE>, processes
implemented using gen_server, gen_fsm or gen_event will transform
their internal state by calling the callback function
<CODE>code_change</CODE>. Special processes will call the callback
function <CODE>system_code_change/4</CODE>. In both cases, the term
<CODE>Extra</CODE> is passed as an argument to the callback function.
<P><CODE>PrePurge</CODE> defaults to <CODE>brutal_purge</CODE> and controls
what action to take with processes that are executing old code
before loading the new version of the module. If the value
is <CODE>brutal_purge</CODE>, the processes are killed. If the value is
<CODE>soft_purge</CODE>, <CODE>release_handler:install_release/1</CODE>
returns <CODE>{error,{old_processes,Mod}}</CODE>.
<P><CODE>PostPurge</CODE> defaults to <CODE>brutal_purge</CODE> and controls
what action to take with processes that are executing old code
when the new version of the module has been loaded. If the value
is <CODE>brutal_purge</CODE>, the code is purged when the release is
made permanent and the processes are killed. If the value is
<CODE>soft_purge</CODE>, the release handler will purge the old code
when no remaining processes execute the code.
<P><CODE>DepMods</CODE> defaults to [] and defines which other modules
<CODE>Mod</CODE> is dependent on. In <CODE>relup</CODE>, instructions for
suspending processes using <CODE>Mod</CODE> will come before
instructions for suspending processes using modules in
<CODE>DepMods</CODE> when upgrading, and vice versa when downgrading.
In case of circular dependencies, the order of the instructions in
the <CODE>appup</CODE> script is kept.
<P><CODE>Timeout</CODE> defines the timeout when suspending processes.
If no value or <CODE>default</CODE> is given, the default value for
<CODE>sys:suspend</CODE> is used.
<P><CODE>ModType</CODE> defaults to <CODE>dynamic</CODE> and specifies if
the code is "dynamic", that is if a process using the module does
spontaneously switch to new code, or if it is "static".
When doing an advanced update and upgrading, the new version of a
dynamic module is loaded before the process is asked to change
code. When downgrading, the process is asked to change code before
loading the new version. For static modules, the new version is
loaded before the process is asked to change code, both in
the case of upgrading and downgrading. Callback modules are
dynamic.
<P><CODE>update</CODE> with argument <CODE>supervisor</CODE> is used when
changing the start specification of a supervisor.
<PRE>
{load_module, Mod}
{load_module, Mod, DepMods}
{load_module, Mod, PrePurge, PostPurge, DepMods}
Mod = atom()
PrePurge = PostPurge = soft_purge | brutal_purge
DepMods = [Mod]
</PRE>
<P>Simple code replacement of the module <CODE>Mod</CODE>.
<P>See <CODE>update</CODE> above for a description of <CODE>PrePurge</CODE> and
<CODE>PostPurge</CODE>.
<P><CODE>DepMods</CODE> defaults to [] and defines which other modules
<CODE>Mod</CODE> is dependent on. In <CODE>relup</CODE>, instructions for
loading these modules will come before the instruction for loading
<CODE>Mod</CODE> when upgrading, and vice versa when downgrading.
<PRE>
{add_module, Mod}
Mod = atom()
</PRE>
<P>Loads a new module <CODE>Mod</CODE>.
<PRE>
{delete_module, Mod}
Mod = atom()
</PRE>
<P>Deletes a module <CODE>Mod</CODE> using the low-level instructions
<CODE>remove</CODE> and <CODE>purge</CODE>.
<PRE>
{add_application, Application}
Application = atom()
</PRE>
<P>Adding an application means that the modules defined by
the <CODE>modules</CODE> key in the <CODE>.app</CODE> file are loaded using
<CODE>add_module</CODE>, then the application is started.
<PRE>
{remove_application, Application}
Application = atom()
</PRE>
<P>Removing an application means that the application is stopped,
the modules are unloaded using <CODE>delete_module</CODE> and then
the application specification is unloaded from the application
controller.
<PRE>
{restart_application, Application}
Application = atom()
</PRE>
<P>Restarting an application means that the application is
stopped and then started again similar to using the instructions
<CODE>remove_application</CODE> and <CODE>add_application</CODE> in sequence.
<P><STRONG>Low-level instructions</STRONG>
<PRE>
{load_object_code, {App, Vsn, [Mod]}}
App = Mod = atom()
Vsn = string()
</PRE>
<P>Reads each <CODE>Mod</CODE> from the directory <CODE>App-Vsn/ebin</CODE> as
a binary. It does not load the modules. The instruction should be
placed first in the script in order to read all new code from file
to make the suspend-load-resume cycle less time consuming. After
this instruction has been executed, the code server with the new
version of <CODE>App</CODE>.
<PRE>
point_of_no_return
</PRE>
<P>If a crash occurs after this instruction, the system cannot
recover and is restarted from the old version of the release.
The instruction must only occur once in a script. It should be
placed after all <CODE>load_object_code</CODE> instructions.
<PRE>
{load, {Mod, PrePurge, PostPurge}}
Mod = atom()
PrePurge = PostPurge = soft_purge | brutal_purge
</PRE>
<P>Before this instruction occurs, <CODE>Mod</CODE> must have been loaded
using <CODE>load_object_code</CODE>. This instruction loads the module.
<CODE>PrePurge</CODE> is ignored. See the high-level instruction
<CODE>update</CODE> for a description of <CODE>PostPurge</CODE>.
<PRE>
{remove, {Mod, PrePurge, PostPurge}}
Mod = atom()
PrePurge = PostPurge = soft_purge | brutal_purge
</PRE>
<P>Makes the current version of <CODE>Mod</CODE> old.
<CODE>PrePurge</CODE> is ignored. See the high-level instruction
<CODE>update</CODE> for a description of <CODE>PostPurge</CODE>.
<PRE>
{purge, [Mod]}
Mod = atom()
</PRE>
<P>Purges each module <CODE>Mod</CODE>, that is removes the old code.
Note that any process executing purged code is killed.
<PRE>
{suspend, [Mod | {Mod, Timeout}]}
Mod = atom()
Timeout = int()>0 | default | infinity
</PRE>
<P>Tries to suspend all processes using a module <CODE>Mod</CODE>. If a
process does not respond, it is ignored. This may cause
the process to die, either because it crashes when it
spontaneously switches to new code, or as a result of a purge
operation. If no <CODE>Timeout</CODE> is specified or <CODE>default</CODE> is
given, the default value for <CODE>sys:suspend</CODE> is used.
<PRE>
{resume, [Mod]}
Mod = atom()
</PRE>
<P>Resumes all suspended processes using a module <CODE>Mod</CODE>.
<PRE>
{code_change, [{Mod, Extra}]}
{code_change, Mode, [{Mod, Extra}]}
Mod = atom()
Mode = up | down
Extra = term()
</PRE>
<P><CODE>Mode</CODE> defaults to <CODE>up</CODE> and specifies if it is an
upgrade or downgrade.
<P>This instruction sends a <CODE>code_change</CODE> system message to
all processes using a module <CODE>Mod</CODE> by calling the function
<CODE>sys:change_code</CODE>, passing the term <CODE>Extra</CODE> as argument.
<PRE>
{stop, [Mod]}
Mod = atom()
</PRE>
<P>Stops all processes using a module <CODE>Mod</CODE> by calling
<CODE>supervisor:terminate_child/2</CODE>. The instruction is useful
when the simplest way to change code is to stop and restart the
processes which run the code.
<PRE>
{start, [Mod]}
Mod = atom()
</PRE>
<P>Starts all stopped processes using a module <CODE>Mod</CODE> by calling
<CODE>supervisor:restart_child/2</CODE>.
<PRE>
{sync_nodes, Id, [Node]}
{sync_nodes, Id, {M, F, A}}
Id = term()
Node = node()
M = F = atom()
A = [term()]
</PRE>
<P><CODE>apply(M, F, A)</CODE> must return a list of nodes.
<P>The instruction synchronizes the release installation with other
nodes. Each <CODE>Node</CODE> must evaluate this command, with the same
<CODE>Id</CODE>. The local node waits for all other nodes to evaluate
the instruction before execution continues. In case a node goes
down, it is considered to be an unrecoverable error, and
the local node is restarted from the old release. There is no
timeout for this instruction, which means that it may hang
forever.
<PRE>
{apply, {M, F, A}}
M = F = atom()
A = [term()]
</PRE>
<P>Evaluates <CODE>apply(M, F, A)</CODE>. If the instruction appears
before the <CODE>point_of_no_return</CODE> instruction, a failure is
caught. <CODE>release_handler:install_release/1</CODE> then returns
<CODE>{error,{'EXIT',Reason}}</CODE>, unless <CODE>{error,Error}</CODE> is
thrown or returned. Then it returns <CODE>{error,Error}</CODE>.
<P>If the instruction appears after the <CODE>point_of_no_return</CODE>
instruction, and the function call fails, the system is
restarted.
<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.
</DIV>
<H3>SEE ALSO</H3>
<DIV CLASS=REFBODY>
<P><A HREF="relup.html">relup(4)</A>,
<A HREF="release_handler.html">release_handler(3)</A>,
supervisor(3),
<A HREF="systools.html">systools(3)</A>
</DIV>
<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Gunilla Arendt - support@erlang.ericsson.se<BR>
</DIV>
<CENTER>
<HR>
<SMALL>sasl 2.0<BR>
Copyright © 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>
|
