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

CALLBACK MODULE

590       The following functions are to be exported from an application callback
591       module.
592

EXPORTS

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

SEE ALSO

714       OTP Design Principles, kernel(6), app(4)
715
716
717
718Ericsson AB                      kernel 8.3.2                   application(3)
Impressum