1application(3)             Erlang Module Definition             application(3)
2
3
4

NAME

6       application - Generic OTP application functions
7

DESCRIPTION

9       In  OTP,  application  denotes  a  component implementing some specific
10       functionality, that can be started and stopped as a unit, and that  can
11       be reused in other systems. This module interacts with application con‐
12       troller, a process started at every Erlang runtime system. This  module
13       contains  functions for controlling applications (for example, starting
14       and stopping applications), and functions to access  information  about
15       applications (for example, configuration parameters).
16
17       An application is defined by an application specification. The specifi‐
18       cation is normally located in an application resource file named Appli‐
19       cation.app,  where  Application  is  the  application name. For details
20       about the application specification, see app(4).
21
22       This module can also be viewed as a behaviour for an application imple‐
23       mented  according  to  the OTP design principles as a supervision tree.
24       The definition of how to start and stop the tree is to be located in an
25       application callback module, exporting a predefined set of functions.
26
27       For  details  about applications and behaviours, see OTP Design Princi‐
28       ples.
29

DATA TYPES

31       start_type() =
32           normal |
33           {takeover, Node :: node()} |
34           {failover, Node :: node()}
35
36       restart_type() = permanent | transient | temporary
37
38       tuple_of(T)
39
40              A tuple where the elements are of type T.
41

EXPORTS

43       ensure_all_started(Application) -> {ok, Started} | {error, Reason}
44
45       ensure_all_started(Application, Type) ->
46                             {ok, Started} | {error, Reason}
47
48              Types:
49
50                 Application = atom()
51                 Type = restart_type()
52                 Started = [atom()]
53                 Reason = term()
54
55              Equivalent to calling start/1,2 repeatedly on  all  dependencies
56              that are not yet started for an application.
57
58              Returns  {ok, AppNames} for a successful start or for an already
59              started application (which is, however, omitted  from  the  App‐
60              Names list).
61
62              The function reports {error, {AppName,Reason}} for errors, where
63              Reason is any possible reason returned by start/1,2 when  start‐
64              ing a specific dependency.
65
66              If an error occurs, the applications started by the function are
67              stopped to bring the set of running  applications  back  to  its
68              initial state.
69
70       ensure_started(Application) -> ok | {error, Reason}
71
72       ensure_started(Application, Type) -> ok | {error, Reason}
73
74              Types:
75
76                 Application = atom()
77                 Type = restart_type()
78                 Reason = term()
79
80              Equivalent to start/1,2 except it returns ok for already started
81              applications.
82
83       get_all_env() -> Env
84
85       get_all_env(Application) -> Env
86
87              Types:
88
89                 Application = atom()
90                 Env = [{Par :: atom(), Val :: term()}]
91
92              Returns the configuration parameters and their values for Appli‐
93              cation.  If the argument is omitted, it defaults to the applica‐
94              tion of the calling process.
95
96              If the specified application is not loaded, or  if  the  process
97              executing the call does not belong to any application, the func‐
98              tion returns [].
99
100       get_all_key() -> [] | {ok, Keys}
101
102       get_all_key(Application) -> undefined | Keys
103
104              Types:
105
106                 Application = atom()
107                 Keys = {ok, [{Key :: atom(), Val :: term()}, ...]}
108
109              Returns the application specification keys and their values  for
110              Application.  If  the  argument  is  omitted, it defaults to the
111              application of the calling process.
112
113              If the specified application is not loaded, the function returns
114              undefined.  If the process executing the call does not belong to
115              any application, the function returns [].
116
117       get_application() -> undefined | {ok, Application}
118
119       get_application(PidOrModule) -> undefined | {ok, Application}
120
121              Types:
122
123                 PidOrModule = (Pid :: pid()) | (Module :: module())
124                 Application = atom()
125
126              Returns the name of the application to which the process Pid  or
127              the  module Module belongs. Providing no argument is the same as
128              calling get_application(self()).
129
130              If the specified process does not belong to any application,  or
131              if  the specified process or module does not exist, the function
132              returns undefined.
133
134       get_env(Par) -> undefined | {ok, Val}
135
136       get_env(Application, Par) -> undefined | {ok, Val}
137
138              Types:
139
140                 Application = Par = atom()
141                 Val = term()
142
143              Returns the value of configuration parameter  Par  for  Applica‐
144              tion. If the application argument is omitted, it defaults to the
145              application of the calling process.
146
147              Returns undefined if any of the following applies:
148
149                * The specified application is not loaded.
150
151                * The configuration parameter does not exist.
152
153                * The process executing the call does not belong to any appli‐
154                  cation.
155
156       get_env(Application, Par, Def) -> Val
157
158              Types:
159
160                 Application = Par = atom()
161                 Def = Val = term()
162
163              Works  like  get_env/2  but returns value Def when configuration
164              parameter Par does not exist.
165
166       get_key(Key) -> undefined | {ok, Val}
167
168       get_key(Application, Key) -> undefined | {ok, Val}
169
170              Types:
171
172                 Application = Key = atom()
173                 Val = term()
174
175              Returns the value of the application specification key  Key  for
176              Application. If the application argument is omitted, it defaults
177              to the application of the calling process.
178
179              Returns undefined if any of the following applies:
180
181                * The specified application is not loaded.
182
183                * The specification key does not exist.
184
185                * The process executing the call does not belong to any appli‐
186                  cation.
187
188       load(AppDescr) -> ok | {error, Reason}
189
190       load(AppDescr, Distributed) -> ok | {error, Reason}
191
192              Types:
193
194                 AppDescr = Application | (AppSpec :: application_spec())
195                 Application = atom()
196                 Distributed =
197                     {Application,  Nodes}  |  {Application,  Time,  Nodes}  |
198                 default
199                 Nodes = [node() | tuple_of(node())]
200                 Time = integer() >= 1
201                 Reason = term()
202                 application_spec() =
203                     {application,
204                      Application :: atom(),
205                      AppSpecKeys :: [application_opt()]}
206                 application_opt() =
207                     {description, Description :: string()} |
208                     {vsn, Vsn :: string()} |
209                     {id, Id :: string()} |
210                     {modules, [Module :: module()]} |
211                     {registered, Names :: [Name :: atom()]} |
212                     {applications, [Application :: atom()]} |
213                     {included_applications, [Application :: atom()]} |
214                     {env, [{Par :: atom(), Val :: term()}]} |
215                     {start_phases,
216                      [{Phase :: atom(), PhaseArgs :: term()}] | undefined} |
217                     {maxT, MaxT :: timeout()} |
218                     {maxP, MaxP :: integer() >= 1 | infinity} |
219                     {mod, Start :: {Module :: module(), StartArgs :: term()}}
220
221              Loads the application specification for an application into  the
222              application controller. It also loads the application specifica‐
223              tions for any included applications. Notice  that  the  function
224              does not load the Erlang object code.
225
226              The  application  can  be  specified by its name Application. In
227              this case, the application controller searches the code path for
228              the  application  resource  file  Application.app  and loads the
229              specification it contains.
230
231              The application specification can also be specified directly  as
232              a  tuple AppSpec, having the format and contents as described in
233              app(4).
234
235              If Distributed ==  {Application,[Time,]Nodes},  the  application
236              becomes  distributed.  The  argument overrides the value for the
237              application in the Kernel configuration  parameter  distributed.
238              Application  must  be the application name (same as in the first
239              argument). If a node crashes and Time is specified, the applica‐
240              tion controller waits for Time milliseconds before attempting to
241              restart the application on another node. If Time is  not  speci‐
242              fied,  it defaults to 0 and the application is restarted immedi‐
243              ately.
244
245              Nodes is a list of node names where the application can run,  in
246              priority  from  left  to  right. Node names can be grouped using
247              tuples to indicate that they have the same priority.
248
249              Example:
250
251              Nodes = [cp1@cave, {cp2@cave, cp3@cave}]
252
253              This means that the application is preferably to be  started  at
254              cp1@cave.  If cp1@cave is down, the application is to be started
255              at cp2@cave or cp3@cave.
256
257              If Distributed == default, the value for the application in  the
258              Kernel configuration parameter distributed is used.
259
260       loaded_applications() -> [{Application, Description, Vsn}]
261
262              Types:
263
264                 Application = atom()
265                 Description = Vsn = string()
266
267              Returns  a  list  with  information  about the applications, and
268              included applications, which are loaded using load/1,2. Applica‐
269              tion is the application name. Description and Vsn are the values
270              of their description and  vsn  application  specification  keys,
271              respectively.
272
273       set_env(Config) -> ok
274
275       set_env(Config, Opts) -> ok
276
277              Types:
278
279                 Config = [{Application, Env}]
280                 Application = atom()
281                 Env = [{Par :: atom(), Val :: term()}]
282                 Opts = [{timeout, timeout()} | {persistent, boolean()}]
283
284              Sets  the  configuration Config for multiple applications. It is
285              equivalent to calling set_env/4 on  each  application  individi‐
286              ally, except it is more efficient. The given Config is validated
287              before the configuration is set.
288
289              set_env/2 uses the standard gen_server time-out value (5000 ms).
290              Option  timeout  can  be  specified if another time-out value is
291              useful, for example, in situations where  the  application  con‐
292              troller is heavily loaded.
293
294              Option  persistent  can be set to true to guarantee that parame‐
295              ters set with set_env/2 are not overridden by those  defined  in
296              the  application  resource file on load. This means that persis‐
297              tent values will stick after the application is loaded and  also
298              on application reload.
299
300              If  an  application is given more than once or if an application
301              has the same key given more than once, the  behaviour  is  unde‐
302              fined  and a warning message will be logged. In future releases,
303              an error will be raised.
304
305              set_env/1 is equivalent to set_env(Config, []).
306
307          Warning:
308              Use this function only if you know what you are doing, that  is,
309              on  your  own applications. It is very application-dependent and
310              configuration parameter-dependent when and how often  the  value
311              is  read  by  the application. Careless use of this function can
312              put the application in a weird, inconsistent, and malfunctioning
313              state.
314
315
316       permit(Application, Permission) -> ok | {error, Reason}
317
318              Types:
319
320                 Application = atom()
321                 Permission = boolean()
322                 Reason = term()
323
324              Changes  the  permission  for  Application to run at the current
325              node. The application must be  loaded  using  load/1,2  for  the
326              function to have effect.
327
328              If  the  permission of a loaded, but not started, application is
329              set to false, start  returns  ok  but  the  application  is  not
330              started until the permission is set to true.
331
332              If  the permission of a running application is set to false, the
333              application is stopped. If the permission later is set to  true,
334              it is restarted.
335
336              If  the  application  is  distributed, setting the permission to
337              false means that the application will be started  at,  or  moved
338              to, another node according to how its distribution is configured
339              (see load/2).
340
341              The function does not return until the application  is  started,
342              stopped, or successfully moved to another node. However, in some
343              cases where permission is set to true, the function  returns  ok
344              even though the application is not started. This is true when an
345              application cannot start because of dependencies to other appli‐
346              cations  that are not yet started. When they are started, Appli‐
347              cation is started as well.
348
349              By default, all applications are loaded with permission true  on
350              all  nodes.  The  permission  can be configured using the Kernel
351              configuration parameter permissions.
352
353       set_env(Application, Par, Val) -> ok
354
355       set_env(Application, Par, Val, Opts) -> ok
356
357              Types:
358
359                 Application = Par = atom()
360                 Val = term()
361                 Opts = [{timeout, timeout()} | {persistent, boolean()}]
362
363              Sets the value of configuration parameter Par for Application.
364
365              set_env/4 uses the standard gen_server time-out value (5000 ms).
366              Option  timeout  can  be  specified if another time-out value is
367              useful, for example, in situations where  the  application  con‐
368              troller is heavily loaded.
369
370              If  set_env/4  is  called  before the application is loaded, the
371              application environment values specified in file Application.app
372              override the ones previously set. This is also true for applica‐
373              tion reloads.
374
375              Option persistent can be set to true to guarantee  that  parame‐
376              ters  set  with set_env/4 are not overridden by those defined in
377              the application resource file on load. This means  that  persis‐
378              tent  values will stick after the application is loaded and also
379              on application reload.
380
381          Warning:
382              Use this function only if you know what you are doing, that  is,
383              on  your  own applications. It is very application-dependent and
384              configuration parameter-dependent when and how often  the  value
385              is  read  by  the application. Careless use of this function can
386              put the application in a weird, inconsistent, and malfunctioning
387              state.
388
389
390       start(Application) -> ok | {error, Reason}
391
392       start(Application, Type) -> ok | {error, Reason}
393
394              Types:
395
396                 Application = atom()
397                 Type = restart_type()
398                 Reason = term()
399
400              Starts  Application.  If  it is not loaded, the application con‐
401              troller first  loads  it  using  load/1.  It  ensures  that  any
402              included  applications are loaded, but does not start them. That
403              is assumed to be taken care of in the code for Application.
404
405              The application controller checks the value of  the  application
406              specification  key applications, to ensure that all applications
407              needed to be started before this application are running. Other‐
408              wise,  {error,{not_started,App}}  is  returned, where App is the
409              name of the missing application.
410
411              The application controller then creates  an  application  master
412              for  the  application.  The application master becomes the group
413              leader of all the processes in the application. I/O is forwarded
414              to  the  previous  group  leader,  though, this is just a way to
415              identify processes that belong  to  the  application.  Used  for
416              example  to  find  itself from any process, or, reciprocally, to
417              kill them all when it terminates.
418
419              The application master starts the  application  by  calling  the
420              application  callback  function Module:start/2 as defined by the
421              application specification key mod.
422
423              Argument Type specifies the type of the application. If omitted,
424              it defaults to temporary.
425
426                * If  a  permanent  application terminates, all other applica‐
427                  tions and the entire Erlang node are also terminated.
428
429                *
430
431
432                  * If a transient application terminates with Reason ==  nor‐
433                    mal, this is reported but no other applications are termi‐
434                    nated.
435
436                  * If a  transient  application  terminates  abnormally,  all
437                    other  applications  and  the  entire Erlang node are also
438                    terminated.
439
440                * If a temporary application terminates, this is reported  but
441                  no other applications are terminated.
442
443              Notice  that  an application can always be stopped explicitly by
444              calling stop/1. Regardless of the type of  the  application,  no
445              other applications are affected.
446
447              Notice  also that the transient type is of little practical use,
448              because when a supervision tree terminates, the reason is set to
449              shutdown, not normal.
450
451       start_type() -> StartType | undefined | local
452
453              Types:
454
455                 StartType = start_type()
456
457              This function is intended to be called by a process belonging to
458              an application, when the application is  started,  to  determine
459              the start type, which is StartType or local.
460
461              For a description of StartType, see Module:start/2.
462
463              local is returned if only parts of the application are restarted
464              (by a supervisor), or  if  the  function  is  called  outside  a
465              startup.
466
467              If  the process executing the call does not belong to any appli‐
468              cation, the function returns undefined.
469
470       stop(Application) -> ok | {error, Reason}
471
472              Types:
473
474                 Application = atom()
475                 Reason = term()
476
477              Stops   Application.   The   application   master   calls   Mod‐
478              ule:prep_stop/1,  if  such a function is defined, and then tells
479              the top supervisor of the application to shut down (see supervi‐
480              sor(3)).  This means that the entire supervision tree, including
481              included applications, is terminated in  reversed  start  order.
482              After  the shutdown, the application master calls Module:stop/1.
483              Module is the callback module  as  defined  by  the  application
484              specification key mod.
485
486              Last,  the  application  master terminates. Notice that all pro‐
487              cesses with the application master as  group  leader,  that  is,
488              processes  spawned  from a process belonging to the application,
489              are also terminated.
490
491              When stopped, the application is still loaded.
492
493              To stop a distributed application, stop/1 must be called on  all
494              nodes  where  it can execute (that is, on all nodes where it has
495              been started). The call to stop/1 on the node where the applica‐
496              tion  currently executes stops its execution. The application is
497              not moved between nodes, as stop/1 is called on the  node  where
498              the  application  currently  executes before stop/1 is called on
499              the other nodes.
500
501       takeover(Application, Type) -> ok | {error, Reason}
502
503              Types:
504
505                 Application = atom()
506                 Type = restart_type()
507                 Reason = term()
508
509              Takes over the distributed application Application,  which  exe‐
510              cutes at another node Node. At the current node, the application
511              is restarted by calling Module:start({takeover,Node},StartArgs).
512              Module  and  StartArgs are retrieved from the loaded application
513              specification. The application at the other node is not  stopped
514              until the startup is completed, that is, when Module:start/2 and
515              any calls to Module:start_phase/3 have returned.
516
517              Thus, two instances of the application run simultaneously during
518              the  takeover,  so  that data can be transferred from the old to
519              the new instance. If this is not an acceptable  behavior,  parts
520              of  the  old  instance can be shut down when the new instance is
521              started. However, the application cannot be stopped entirely, at
522              least the top supervisor must remain alive.
523
524              For a description of Type, see start/1,2.
525
526       unload(Application) -> ok | {error, Reason}
527
528              Types:
529
530                 Application = atom()
531                 Reason = term()
532
533              Unloads  the  application specification for Application from the
534              application controller. It also unloads the application specifi‐
535              cations  for any included applications. Notice that the function
536              does not purge the Erlang object code.
537
538       unset_env(Application, Par) -> ok
539
540       unset_env(Application, Par, Opts) -> ok
541
542              Types:
543
544                 Application = Par = atom()
545                 Opts = [{timeout, timeout()} | {persistent, boolean()}]
546
547              Removes the configuration parameter Par and its value for Appli‐
548              cation.
549
550              unset_env/2  uses  the  standard gen_server time-out value (5000
551              ms). Option timeout can be specified if another  time-out  value
552              is useful, for example, in situations where the application con‐
553              troller is heavily loaded.
554
555              unset_env/3 also allows the persistent option to be passed  (see
556              set_env/4).
557
558          Warning:
559              Use  this function only if you know what you are doing, that is,
560              on your own applications. It is very  application-dependent  and
561              configuration  parameter-dependent  when and how often the value
562              is read by the application. Careless use of  this  function  can
563              put the application in a weird, inconsistent, and malfunctioning
564              state.
565
566
567       which_applications() -> [{Application, Description, Vsn}]
568
569       which_applications(Timeout) -> [{Application, Description, Vsn}]
570
571              Types:
572
573                 Timeout = timeout()
574                 Application = atom()
575                 Description = Vsn = string()
576
577              Returns a list with information about the applications that  are
578              currently running. Application is the application name. Descrip‐
579              tion and Vsn are the values of their description and vsn  appli‐
580              cation specification keys, respectively.
581
582              which_applications/0 uses the standard gen_server time-out value
583              (5000 ms). A Timeout argument can be specified if another  time-
584              out value is useful, for example, in situations where the appli‐
585              cation controller is heavily loaded.
586

CALLBACK MODULE

588       The following functions are to be exported from an application callback
589       module.
590

EXPORTS

592       Module:start(StartType,  StartArgs)  ->  {ok, Pid} | {ok, Pid, State} |
593       {error, Reason}
594
595              Types:
596
597                 StartType = start_type()
598                 StartArgs = term()
599                 Pid = pid()
600                 State = term()
601
602              This function is called whenever an application is started using
603              start/1,2,  and is to start the processes of the application. If
604              the application is structured according to the OTP design  prin‐
605              ciples as a supervision tree, this means starting the top super‐
606              visor of the tree.
607
608              StartType defines the type of start:
609
610                * normal if it is a normal startup.
611
612                * normal also if the application is distributed and started at
613                  the  current  node  because of a failover from another node,
614                  and the application specification key start_phases ==  unde‐
615                  fined.
616
617                * {takeover,Node}   if  the  application  is  distributed  and
618                  started at the current node because of a takeover from Node,
619                  either  because  takeover/2  has  been called or because the
620                  current node has higher priority than Node.
621
622                * {failover,Node}  if  the  application  is  distributed   and
623                  started at the current node because of a failover from Node,
624                  and the application specification key start_phases /=  unde‐
625                  fined.
626
627              StartArgs  is  the StartArgs argument defined by the application
628              specification key mod.
629
630              The function is to return {ok,Pid} or {ok,Pid,State}, where  Pid
631              is the pid of the top supervisor and State is any term. If omit‐
632              ted, State defaults to []. If the application is stopped  later,
633              State is passed to Module:prep_stop/1.
634
635       Module:start_phase(Phase, StartType, PhaseArgs) -> ok | {error, Reason}
636
637              Types:
638
639                 Phase = atom()
640                 StartType = start_type()
641                 PhaseArgs = term()
642                 Pid = pid()
643                 State = state()
644
645              Starts  an application with included applications, when synchro‐
646              nization is needed between processes in the  different  applica‐
647              tions during startup.
648
649              The  start  phases  are defined by the application specification
650              key start_phases == [{Phase,PhaseArgs}]. For  included  applica‐
651              tions,  the  set of phases must be a subset of the set of phases
652              defined for the including application.
653
654              The function is called for each start phase (as defined for  the
655              primary   application)  for  the  primary  application  and  all
656              included applications, for which the start phase is defined.
657
658              For a description of StartType, see Module:start/2.
659
660       Module:prep_stop(State) -> NewState
661
662              Types:
663
664                 State = NewState = term()
665
666              This function is called when  an  application  is  about  to  be
667              stopped, before shutting down the processes of the application.
668
669              State  is  the  state  returned from Module:start/2, or [] if no
670              state was returned. NewState is any term and is passed  to  Mod‐
671              ule:stop/1.
672
673              The  function  is  optional. If it is not defined, the processes
674              are terminated and then Module:stop(State) is called.
675
676       Module:stop(State)
677
678              Types:
679
680                 State = term()
681
682              This function is called whenever an application has stopped.  It
683              is  intended  to  be the opposite of Module:start/2 and is to do
684              any necessary cleaning up. The return value is ignored.
685
686              State is the return value of Module:prep_stop/1, if such a func‐
687              tion  exists.  Otherwise State is taken from the return value of
688              Module:start/2.
689
690       Module:config_change(Changed, New, Removed) -> ok
691
692              Types:
693
694                 Changed = [{Par,Val}]
695                 New = [{Par,Val}]
696                 Removed = [Par]
697                  Par = atom()
698                  Val = term()
699
700              This function is called by an application after a code  replace‐
701              ment, if the configuration parameters have changed.
702
703              Changed  is  a list of parameter-value tuples including all con‐
704              figuration parameters with changed values.
705
706              New is a list of parameter-value tuples including all added con‐
707              figuration parameters.
708
709              Removed is a list of all removed parameters.
710

SEE ALSO

712       OTP Design Principles, kernel(6), app(4)
713
714
715
716Ericsson AB                      kernel 6.5.2                   application(3)
Impressum