Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
application(3)		   Erlang Module Definition		application(3)

NAME
       application - Generic OTP application functions

DESCRIPTION
       In  OTP,	 application  denotes  a  component implementing some specific
       functionality, that can be started and stopped as a unit, and that  can
       be reused in other systems. This	module interacts with application con-
       troller,	a process started at every Erlang runtime system. This	module
       contains	 functions for controlling applications	(for example, starting
       and stopping applications), and functions to access  information	 about
       applications (for example, configuration	parameters).

       An application is defined by an application specification. The specifi-
       cation is normally located in an	application resource file named	Appli-
       cation.app,  where  Application	is  the	 application name. For details
       about the application specification, see	app(4).

       This module can also be viewed as a behaviour for an application	imple-
       mented  according  to  the OTP design principles	as a supervision tree.
       The definition of how to	start and stop the tree	is to be located in an
       application callback module, exporting a	predefined set of functions.

       For  details  about applications	and behaviours,	see OTP	Design Princi-
       ples.

DATA TYPES
       start_type() =
	   normal |
	   {takeover, Node :: node()} |
	   {failover, Node :: node()}

       restart_type() =	permanent | transient |	temporary

       tuple_of(T)

	      A	tuple where the	elements are of	type T.

EXPORTS
       ensure_all_started(Application) -> {ok, Started}	| {error, Reason}

       ensure_all_started(Application, Type) ->
			     {ok, Started} | {error, Reason}

	      Types:

		 Application = atom()
		 Type =	restart_type()
		 Started = [atom()]
		 Reason	= term()

	      Equivalent to calling start/1,2 repeatedly on  all  dependencies
	      that are not yet started for an application.

	      Returns  {ok, AppNames} for a successful start or	for an already
	      started application (which is, however, omitted  from  the  App-
	      Names list).

	      The function reports {error, {AppName,Reason}} for errors, where
	      Reason is	any possible reason returned by	start/1,2 when	start-
	      ing a specific dependency.

	      If an error occurs, the applications started by the function are
	      stopped to bring the set of running  applications	 back  to  its
	      initial state.

       ensure_started(Application) -> ok | {error, Reason}

       ensure_started(Application, Type) -> ok | {error, Reason}

	      Types:

		 Application = atom()
		 Type =	restart_type()
		 Reason	= term()

	      Equivalent to start/1,2 except it	returns	ok for already started
	      applications.

       get_all_env() ->	Env

       get_all_env(Application)	-> Env

	      Types:

		 Application = atom()
		 Env = [{Par ::	atom(),	Val :: term()}]

	      Returns the configuration	parameters and their values for	Appli-
	      cation.  If the argument is omitted, it defaults to the applica-
	      tion of the calling process.

	      If the specified application is not loaded, or  if  the  process
	      executing	the call does not belong to any	application, the func-
	      tion returns [].

       get_all_key() ->	[] | {ok, Keys}

       get_all_key(Application)	-> undefined | Keys

	      Types:

		 Application = atom()
		 Keys =	{ok, [{Key :: atom(), Val :: term()}, ...]}

	      Returns the application specification keys and their values  for
	      Application.  If the argument is omitted,	it defaults to the ap-
	      plication	of the calling process.

	      If the specified application is not loaded, the function returns
	      undefined.  If the process executing the call does not belong to
	      any application, the function returns [].

       get_application() -> undefined |	{ok, Application}

       get_application(PidOrModule) -> undefined | {ok,	Application}

	      Types:

		 PidOrModule = (Pid :: pid()) |	(Module	:: module())
		 Application = atom()

	      Returns the name of the application to which the process Pid  or
	      the  module Module belongs. Providing no argument	is the same as
	      calling get_application(self()).

	      If the specified process does not	belong to any application,  or
	      if  the specified	process	or module does not exist, the function
	      returns undefined.

       get_env(Par) -> undefined | {ok,	Val}

       get_env(Application, Par) -> undefined |	{ok, Val}

	      Types:

		 Application = Par = atom()
		 Val = term()

	      Returns the value	of configuration parameter  Par	 for  Applica-
	      tion. If the application argument	is omitted, it defaults	to the
	      application of the calling process.

	      Returns undefined	if any of the following	applies:

		* The specified	application is not loaded.

		* The configuration parameter does not exist.

		* The process executing	the call does not belong to any	appli-
		  cation.

       get_env(Application, Par, Def) -> Val

	      Types:

		 Application = Par = atom()
		 Def = Val = term()

	      Works  like  get_env/2  but returns value	Def when configuration
	      parameter	Par does not exist.

       get_key(Key) -> undefined | {ok,	Val}

       get_key(Application, Key) -> undefined |	{ok, Val}

	      Types:

		 Application = Key = atom()
		 Val = term()

	      Returns the value	of the application specification key  Key  for
	      Application. If the application argument is omitted, it defaults
	      to the application of the	calling	process.

	      Returns undefined	if any of the following	applies:

		* The specified	application is not loaded.

		* The specification key	does not exist.

		* The process executing	the call does not belong to any	appli-
		  cation.

       load(AppDescr) -> ok | {error, Reason}

       load(AppDescr, Distributed) -> ok | {error, Reason}

	      Types:

		 AppDescr = Application	| (AppSpec :: application_spec())
		 Application = atom()
		 Distributed =
		     {Application,  Nodes}  | {Application, Time, Nodes} | de-
		 fault
		 Nodes = [node() | tuple_of(node())]
		 Time =	integer() >= 1
		 Reason	= term()
		 application_spec() =
		     {application,
		      Application :: atom(),
		      AppSpecKeys :: [application_opt()]}
		 application_opt() =
		     {description, Description :: string()} |
		     {vsn, Vsn :: string()} |
		     {id, Id ::	string()} |
		     {modules, [Module :: module()]} |
		     {registered, Names	:: [Name :: atom()]} |
		     {applications, [Application :: atom()]} |
		     {included_applications, [Application :: atom()]} |
		     {env, [{Par :: atom(), Val	:: term()}]} |
		     {start_phases,
		      [{Phase :: atom(), PhaseArgs :: term()}] | undefined} |
		     {maxT, MaxT :: timeout()} |
		     {maxP, MaxP :: integer() >= 1 | infinity} |
		     {mod, Start :: {Module :: module(), StartArgs :: term()}}

	      Loads the	application specification for an application into  the
	      application controller. It also loads the	application specifica-
	      tions for	any included applications. Notice  that	 the  function
	      does not load the	Erlang object code.

	      The  application	can  be	 specified by its name Application. In
	      this case, the application controller searches the code path for
	      the  application	resource  file	Application.app	 and loads the
	      specification it contains.

	      The application specification can	also be	specified directly  as
	      a	 tuple AppSpec,	having the format and contents as described in
	      app(4).

	      If Distributed ==	 {Application,[Time,]Nodes},  the  application
	      becomes  distributed.  The  argument overrides the value for the
	      application in the Kernel	configuration  parameter  distributed.
	      Application  must	 be the	application name (same as in the first
	      argument). If a node crashes and Time is specified, the applica-
	      tion controller waits for	Time milliseconds before attempting to
	      restart the application on another node. If Time is  not	speci-
	      fied,  it	defaults to 0 and the application is restarted immedi-
	      ately.

	      Nodes is a list of node names where the application can run,  in
	      priority from left to right. Node	names can be grouped using tu-
	      ples to indicate that they have the same priority.

	      Example:

	      Nodes = [cp1@cave, {cp2@cave, cp3@cave}]

	      This means that the application is preferably to be  started  at
	      cp1@cave.	 If cp1@cave is	down, the application is to be started
	      at cp2@cave or cp3@cave.

	      If Distributed ==	default, the value for the application in  the
	      Kernel configuration parameter distributed is used.

       loaded_applications() ->	[{Application, Description, Vsn}]

	      Types:

		 Application = atom()
		 Description = Vsn = string()

	      Returns  a list with information about the applications, and in-
	      cluded applications, which are loaded using  load/1,2.  Applica-
	      tion is the application name. Description	and Vsn	are the	values
	      of their description and vsn application specification keys, re-
	      spectively.

       set_env(Config) -> ok

       set_env(Config, Opts) ->	ok

	      Types:

		 Config	= [{Application, Env}]
		 Application = atom()
		 Env = [{Par ::	atom(),	Val :: term()}]
		 Opts =	[{timeout, timeout()} |	{persistent, boolean()}]

	      Sets  the	 configuration Config for multiple applications. It is
	      equivalent to calling set_env/4 on  each	application  individi-
	      ally, except it is more efficient. The given Config is validated
	      before the configuration is set.

	      set_env/2	uses the standard gen_server time-out value (5000 ms).
	      Option  timeout  can  be	specified if another time-out value is
	      useful, for example, in situations where	the  application  con-
	      troller is heavily loaded.

	      Option  persistent  can be set to	true to	guarantee that parame-
	      ters set with set_env/2 are not overridden by those  defined  in
	      the  application	resource file on load. This means that persis-
	      tent values will stick after the application is loaded and  also
	      on application reload.

	      If  an  application is given more	than once or if	an application
	      has the same key given more than once, the  behaviour  is	 unde-
	      fined  and a warning message will	be logged. In future releases,
	      an error will be raised.

	      set_env/1	is equivalent to set_env(Config, []).

	  Warning:
	      Use this function	only if	you know what you are doing, that  is,
	      on  your	own applications. It is	very application-dependent and
	      configuration parameter-dependent	when and how often  the	 value
	      is  read	by  the	application. Careless use of this function can
	      put the application in a weird, inconsistent, and	malfunctioning
	      state.

       permit(Application, Permission) -> ok | {error, Reason}

	      Types:

		 Application = atom()
		 Permission = boolean()
		 Reason	= term()

	      Changes  the  permission	for  Application to run	at the current
	      node. The	application must be  loaded  using  load/1,2  for  the
	      function to have effect.

	      If  the  permission of a loaded, but not started,	application is
	      set to false, start  returns  ok	but  the  application  is  not
	      started until the	permission is set to true.

	      If  the permission of a running application is set to false, the
	      application is stopped. If the permission	later is set to	 true,
	      it is restarted.

	      If  the  application  is	distributed, setting the permission to
	      false means that the application will be started	at,  or	 moved
	      to, another node according to how	its distribution is configured
	      (see load/2).

	      The function does	not return until the application  is  started,
	      stopped, or successfully moved to	another	node. However, in some
	      cases where permission is	set to true, the function  returns  ok
	      even though the application is not started. This is true when an
	      application cannot start because of dependencies to other	appli-
	      cations  that are	not yet	started. When they are started,	Appli-
	      cation is	started	as well.

	      By default, all applications are loaded with permission true  on
	      all  nodes.  The	permission  can	be configured using the	Kernel
	      configuration parameter permissions.

       set_env(Application, Par, Val) -> ok

       set_env(Application, Par, Val, Opts) -> ok

	      Types:

		 Application = Par = atom()
		 Val = term()
		 Opts =	[{timeout, timeout()} |	{persistent, boolean()}]

	      Sets the value of	configuration parameter	Par for	Application.

	      set_env/4	uses the standard gen_server time-out value (5000 ms).
	      Option  timeout  can  be	specified if another time-out value is
	      useful, for example, in situations where	the  application  con-
	      troller is heavily loaded.

	      If set_env/4 is called before the	application is loaded, the ap-
	      plication	environment values specified in	 file  Application.app
	      override the ones	previously set.	This is	also true for applica-
	      tion reloads.

	      Option persistent	can be set to true to guarantee	 that  parame-
	      ters  set	 with set_env/4	are not	overridden by those defined in
	      the application resource file on load. This means	 that  persis-
	      tent  values will	stick after the	application is loaded and also
	      on application reload.

	  Warning:
	      Use this function	only if	you know what you are doing, that  is,
	      on  your	own applications. It is	very application-dependent and
	      configuration parameter-dependent	when and how often  the	 value
	      is  read	by  the	application. Careless use of this function can
	      put the application in a weird, inconsistent, and	malfunctioning
	      state.

       start(Application) -> ok	| {error, Reason}

       start(Application, Type)	-> ok |	{error,	Reason}

	      Types:

		 Application = atom()
		 Type =	restart_type()
		 Reason	= term()

	      Starts  Application.  If	it is not loaded, the application con-
	      troller first loads it using load/1. It  ensures	that  any  in-
	      cluded applications are loaded, but does not start them. That is
	      assumed to be taken care of in the code for Application.

	      The application controller checks	the value of  the  application
	      specification  key applications, to ensure that all applications
	      needed to	be started before this application are running.	Other-
	      wise,  {error,{not_started,App}}	is  returned, where App	is the
	      name of the missing application.

	      The application controller then creates  an  application	master
	      for  the	application.  The application master becomes the group
	      leader of	all the	processes in the application. I/O is forwarded
	      to  the  previous	 group	leader,	 though, this is just a	way to
	      identify processes that belong to	the application. Used for  ex-
	      ample to find itself from	any process, or, reciprocally, to kill
	      them all when it terminates.

	      The application master starts the	application by calling the ap-
	      plication	callback function Module:start/2 as defined by the ap-
	      plication	specification key mod.

	      Argument Type specifies the type of the application. If omitted,
	      it defaults to temporary.

		* If  a	 permanent  application	terminates, all	other applica-
		  tions	and the	entire Erlang node are also terminated.

		*

		  * If a transient application terminates with Reason ==  nor-
		    mal, this is reported but no other applications are	termi-
		    nated.

		  * If a  transient  application  terminates  abnormally,  all
		    other  applications	 and  the  entire Erlang node are also
		    terminated.

		* If a temporary application terminates, this is reported  but
		  no other applications	are terminated.

	      Notice  that  an application can always be stopped explicitly by
	      calling stop/1. Regardless of the	type of	 the  application,  no
	      other applications are affected.

	      Notice  also that	the transient type is of little	practical use,
	      because when a supervision tree terminates, the reason is	set to
	      shutdown,	not normal.

       start_type() -> StartType | undefined | local

	      Types:

		 StartType = start_type()

	      This function is intended	to be called by	a process belonging to
	      an application, when the application is  started,	 to  determine
	      the start	type, which is StartType or local.

	      For a description	of StartType, see Module:start/2.

	      local is returned	if only	parts of the application are restarted
	      (by a supervisor), or  if	 the  function	is  called  outside  a
	      startup.

	      If  the process executing	the call does not belong to any	appli-
	      cation, the function returns undefined.

       stop(Application) -> ok | {error, Reason}

	      Types:

		 Application = atom()
		 Reason	= term()

	      Stops   Application.   The   application	 master	  calls	  Mod-
	      ule:prep_stop/1,	if  such a function is defined,	and then tells
	      the top supervisor of the	application to shut down (see supervi-
	      sor(3)).	This means that	the entire supervision tree, including
	      included applications, is	terminated in  reversed	 start	order.
	      After  the shutdown, the application master calls	Module:stop/1.
	      Module is	the callback module  as	 defined  by  the  application
	      specification key	mod.

	      Last,  the  application  master terminates. Notice that all pro-
	      cesses with the application master as  group  leader,  that  is,
	      processes	 spawned  from a process belonging to the application,
	      are also terminated.

	      When stopped, the	application is still loaded.

	      To stop a	distributed application, stop/1	must be	called on  all
	      nodes  where  it can execute (that is, on	all nodes where	it has
	      been started). The call to stop/1	on the node where the applica-
	      tion  currently executes stops its execution. The	application is
	      not moved	between	nodes, as stop/1 is called on the  node	 where
	      the  application	currently  executes before stop/1 is called on
	      the other	nodes.

       takeover(Application, Type) -> ok | {error, Reason}

	      Types:

		 Application = atom()
		 Type =	restart_type()
		 Reason	= term()

	      Takes over the distributed application Application,  which  exe-
	      cutes at another node Node. At the current node, the application
	      is restarted by calling Module:start({takeover,Node},StartArgs).
	      Module  and  StartArgs are retrieved from	the loaded application
	      specification. The application at	the other node is not  stopped
	      until the	startup	is completed, that is, when Module:start/2 and
	      any calls	to Module:start_phase/3	have returned.

	      Thus, two	instances of the application run simultaneously	during
	      the  takeover,  so  that data can	be transferred from the	old to
	      the new instance.	If this	is not an acceptable  behavior,	 parts
	      of  the  old  instance can be shut down when the new instance is
	      started. However,	the application	cannot be stopped entirely, at
	      least the	top supervisor must remain alive.

	      For a description	of Type, see start/1,2.

       unload(Application) -> ok | {error, Reason}

	      Types:

		 Application = atom()
		 Reason	= term()

	      Unloads  the  application	specification for Application from the
	      application controller. It also unloads the application specifi-
	      cations  for any included	applications. Notice that the function
	      does not purge the Erlang	object code.

       unset_env(Application, Par) -> ok

       unset_env(Application, Par, Opts) -> ok

	      Types:

		 Application = Par = atom()
		 Opts =	[{timeout, timeout()} |	{persistent, boolean()}]

	      Removes the configuration	parameter Par and its value for	Appli-
	      cation.

	      unset_env/2  uses	 the  standard gen_server time-out value (5000
	      ms). Option timeout can be specified if another  time-out	 value
	      is useful, for example, in situations where the application con-
	      troller is heavily loaded.

	      unset_env/3 also allows the persistent option to be passed  (see
	      set_env/4).

	  Warning:
	      Use  this	function only if you know what you are doing, that is,
	      on your own applications.	It is very  application-dependent  and
	      configuration  parameter-dependent  when and how often the value
	      is read by the application. Careless use of  this	 function  can
	      put the application in a weird, inconsistent, and	malfunctioning
	      state.

       which_applications() -> [{Application, Description, Vsn}]

       which_applications(Timeout) -> [{Application, Description, Vsn}]

	      Types:

		 Timeout = timeout()
		 Application = atom()
		 Description = Vsn = string()

	      Returns a	list with information about the	applications that  are
	      currently	running. Application is	the application	name. Descrip-
	      tion and Vsn are the values of their description and vsn	appli-
	      cation specification keys, respectively.

	      which_applications/0 uses	the standard gen_server	time-out value
	      (5000 ms). A Timeout argument can	be specified if	another	 time-
	      out value	is useful, for example,	in situations where the	appli-
	      cation controller	is heavily loaded.

CALLBACK MODULE
       The following functions are to be exported from an application callback
       module.

EXPORTS
       Module:start(StartType,	StartArgs)  ->	{ok, Pid} | {ok, Pid, State} |
       {error, Reason}

	      Types:

		 StartType = start_type()
		 StartArgs = term()
		 Pid = pid()
		 State = term()

	      This function is called whenever an application is started using
	      start/1,2,  and is to start the processes	of the application. If
	      the application is structured according to the OTP design	 prin-
	      ciples as	a supervision tree, this means starting	the top	super-
	      visor of the tree.

	      StartType	defines	the type of start:

		* normal if it is a normal startup.

		* normal also if the application is distributed	and started at
		  the  current	node  because of a failover from another node,
		  and the application specification key	start_phases ==	 unde-
		  fined.

		* {takeover,Node}   if	the  application  is  distributed  and
		  started at the current node because of a takeover from Node,
		  either  because  takeover/2  has  been called	or because the
		  current node has higher priority than	Node.

		* {failover,Node}  if  the  application	 is  distributed   and
		  started at the current node because of a failover from Node,
		  and the application specification key	start_phases /=	 unde-
		  fined.

	      StartArgs	 is  the StartArgs argument defined by the application
	      specification key	mod.

	      The function is to return	{ok,Pid} or {ok,Pid,State}, where  Pid
	      is the pid of the	top supervisor and State is any	term. If omit-
	      ted, State defaults to []. If the	application is stopped	later,
	      State is passed to Module:prep_stop/1.

       Module:start_phase(Phase, StartType, PhaseArgs) -> ok | {error, Reason}

	      Types:

		 Phase = atom()
		 StartType = start_type()
		 PhaseArgs = term()
		 Pid = pid()
		 State = state()

	      Starts  an application with included applications, when synchro-
	      nization is needed between processes in the  different  applica-
	      tions during startup.

	      The  start  phases  are defined by the application specification
	      key start_phases == [{Phase,PhaseArgs}]. For  included  applica-
	      tions,  the  set of phases must be a subset of the set of	phases
	      defined for the including	application.

	      The function is called for each start phase (as defined for  the
	      primary  application)  for  the  primary application and all in-
	      cluded applications, for which the start phase is	defined.

	      For a description	of StartType, see Module:start/2.

       Module:prep_stop(State) -> NewState

	      Types:

		 State = NewState = term()

	      This function is called when  an	application  is	 about	to  be
	      stopped, before shutting down the	processes of the application.

	      State  is	 the  state  returned from Module:start/2, or [] if no
	      state was	returned. NewState is any term and is passed  to  Mod-
	      ule:stop/1.

	      The  function  is	 optional. If it is not	defined, the processes
	      are terminated and then Module:stop(State) is called.

       Module:stop(State)

	      Types:

		 State = term()

	      This function is called whenever an application has stopped.  It
	      is  intended  to	be the opposite	of Module:start/2 and is to do
	      any necessary cleaning up. The return value is ignored.

	      State is the return value	of Module:prep_stop/1, if such a func-
	      tion  exists.  Otherwise State is	taken from the return value of
	      Module:start/2.

       Module:config_change(Changed, New, Removed) -> ok

	      Types:

		 Changed = [{Par,Val}]
		 New = [{Par,Val}]
		 Removed = [Par]
		  Par =	atom()
		  Val =	term()

	      This function is called by an application	after a	code  replace-
	      ment, if the configuration parameters have changed.

	      Changed  is  a list of parameter-value tuples including all con-
	      figuration parameters with changed values.

	      New is a list of parameter-value tuples including	all added con-
	      figuration parameters.

	      Removed is a list	of all removed parameters.

SEE ALSO
       OTP Design Principles, kernel(6), app(4)

Ericsson AB			  kernel 6.3			application(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | CALLBACK MODULE | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=application&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help