File: gen_fsm.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (869 lines) | stat: -rw-r--r-- 35,750 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>gen_fsm</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>gen_fsm</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
gen_fsm
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Generic Finite State Machine Behaviour
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>A behaviour module for implementing a finite state machine.
A generic finite state machine process (gen_fsm) implemented
using this module will have a standard set of interface functions
and include functionality for tracing and error reporting. It will
also fit into an OTP supervision tree. Refer to <STRONG>OTP Design
        Principles</STRONG> for more information.
<P>A gen_fsm assumes all specific parts to be located in a callback
module exporting a pre-defined set of functions. The relationship
between the behaviour functions and the callback functions can be
illustrated as follows:
<PRE>
gen_fsm module                    Callback module
--------------                    ---------------
gen_fsm:start_link                -----&#62; Module:init/1

gen_fsm:send_event                -----&#62; Module:StateName/2

gen_fsm:send_all_state_event      -----&#62; Module:handle_event/3

gen_fsm:sync_send_event           -----&#62; Module:StateName/3

gen_fsm:sync_send_all_state_event -----&#62; Module:handle_sync_event/4

-                                 -----&#62; Module:handle_info/3

-                                 -----&#62; Module:terminate/3

-                                 -----&#62; Module:code_change/4
    
</PRE>

<P>If a callback function fails or returns a bad value, the gen_fsm
will terminate.
<P>The <CODE>sys</CODE> module can be used for debugging a gen_fsm.
<P>Note that a gen_fsm does not trap exit signals automatically,
this must be explicitly initiated in the callback module.
<P>Unless otherwise stated, all functions in this module fail if
the specified gen_fsm does not exist or if bad arguments are given.
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="start_link/3"><STRONG><CODE>start_link(Module, Args, Options) -&#62; Result</CODE></STRONG></A><BR>
<A NAME="start_link/4"><STRONG><CODE>start_link(FsmName, Module, Args, Options) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FsmName = {local,Name} | {global,GlobalName}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = {debug,Dbgs} | {timeout,Time} |
         {spawn_opt,SOpts}</CODE></STRONG><BR>
<STRONG><CODE>Dbgs = [Dbg]</CODE></STRONG><BR>
<STRONG><CODE>Dbg = trace | log | statistics</CODE></STRONG><BR>
<STRONG><CODE>| {log_to_file,FileName}
         | {install,{Func,FuncState}}</CODE></STRONG><BR>
<STRONG><CODE>SOpts = [SOpt]</CODE></STRONG><BR>
<STRONG><CODE>SOpt - see erlang:spawn_opt/2,3,4,5</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Pid} | ignore | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>Error = {already_started,Pid} | term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Creates a gen_fsm process as part of a supervision tree.
         The function should be called, directly or indirectly, by
         the supervisor. It will, among other things, ensure that
         the gen_fsm is linked to the supervisor.
<P>The gen_fsm process calls <CODE>Module:init/1</CODE> to
         initialize. To ensure a synchronized start-up procedure,
         <CODE>start_link/3,4</CODE> does not return until
         <CODE>Module:init/1</CODE> has returned.
<P>If <CODE>FsmName={local,Name}</CODE>, the gen_fsm is registered
         locally as <CODE>Name</CODE> using <CODE>register/2</CODE>.
         If <CODE>FsmName={global,GlobalName}</CODE>, the gen_fsm is registered
         globally as <CODE>GlobalName</CODE> using <CODE>global:register_name/2</CODE>.
         If no name is provided, the gen_fsm is not registered.
<P><CODE>Module</CODE> is the name of the callback module.
<P><CODE>Args</CODE> is an arbitrary term which is passed as
         the argument to <CODE>Module:init/1</CODE>.
<P>If the option <CODE>{timeout,Time}</CODE> is present, the gen_fsm
         is allowed to spend <CODE>Time</CODE> milliseconds initializing
         or it will be terminated and the start function will return
         <CODE>{error,timeout}</CODE>.
<P>If the option <CODE>{debug,Dbgs}</CODE> is present,
         the corresponding <CODE>sys</CODE> function will be called for each
         item in <CODE>Dbgs</CODE>. Refer to <CODE>sys(3)</CODE> for more
         information.
<P>If the option <CODE>{spawn_opt,SOpts}</CODE> is present,
         <CODE>SOpts</CODE> will be passed as option list to
         the <CODE>spawn_opt</CODE> BIF which is used to spawn the gen_fsm
         process. Refer to <CODE>erlang(3)</CODE> for information about
         the <CODE>spawn_opt</CODE> options.
<P>If the gen_fsm is successfully created and initialized
         the function returns <CODE>{ok,Pid}</CODE>, where <CODE>Pid</CODE> is
         the pid of the gen_fsm. If there already exists a process with
         the specified <CODE>FsmName</CODE>, the function returns
         <CODE>{error,{already_started,Pid}}</CODE> where <CODE>Pid</CODE> is
         the pid of that process.
<P>If <CODE>Module:init/1</CODE> fails with <CODE>Reason</CODE>,
         the function returns <CODE>{error,Reason}</CODE>. If
         <CODE>Module:init/1</CODE> returns <CODE>{stop,Reason}</CODE> or
         <CODE>ignore</CODE>, the process is terminated and the function
         returns <CODE>{error,Reason}</CODE> or <CODE>ignore</CODE>, respectively.
        
</DIV>

<P><A NAME="start/3"><STRONG><CODE>start(Module, Args, Options) -&#62; Result</CODE></STRONG></A><BR>
<A NAME="start/4"><STRONG><CODE>start(FsmName, Module, Args, Options) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FsmName = {local,Name} | {global,GlobalName}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = {debug,Dbgs} | {timeout,Time} |
         {spawn_opt,SOpts}</CODE></STRONG><BR>
<STRONG><CODE>Dbgs = [Dbg]</CODE></STRONG><BR>
<STRONG><CODE>Dbg = trace | log | statistics</CODE></STRONG><BR>
<STRONG><CODE>| {log_to_file,FileName}
         | {install,{Func,FuncState}}</CODE></STRONG><BR>
<STRONG><CODE>SOpts = [term()]</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Pid} | ignore | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>Error = {already_started,Pid} | term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Creates a stand-alone gen_fsm process, i.e. a gen_fsm which
         is not part of a supervision tree and thus has no supervisor.
        
<P>See <CODE>start_link/3,4</CODE> for a description of arguments and
         return values.
</DIV>

<P><A NAME="send_event/2"><STRONG><CODE>send_event(FsmRef, Event) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sends an event asynchronously to the gen_fsm <CODE>FsmRef</CODE>
         and returns <CODE>ok</CODE> immediately. The gen_fsm will call
         <CODE>Module:StateName/2</CODE> to handle the event, where
         <CODE>StateName</CODE> is the name of the current state of the gen_fsm.
        
<P><CODE>FsmRef</CODE> can be:
<P>
<UL>

<LI>
the pid,
</LI>


<LI>
<CODE>Name</CODE>, if the gen_fsm is locally registered,
</LI>


<LI>
<CODE>{Name,Node}</CODE>, if the gen_fsm is locally registered at
         another node, or
</LI>


<LI>
<CODE>{global,GlobalName}</CODE>, if the gen_fsm is globally registered.
         
</LI>


</UL>

<P><CODE>Event</CODE> is an arbitrary term which is passed as one of
         the arguments to <CODE>Module:StateName/2</CODE>.
</DIV>

<P><A NAME="send_all_state_event/2"><STRONG><CODE>send_all_state_event(FsmRef, Event) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sends an event asynchronously to the gen_fsm <CODE>FsmRef</CODE>
         and returns <CODE>ok</CODE> immediately. The gen_fsm will call
         <CODE>Module:handle_event/3</CODE> to handle the event.
<P>See <CODE>send_event/2</CODE> for a description of the arguments.
<P>The difference between <CODE>send_event</CODE> and
         <CODE>send_all_state_event</CODE> is which callback function is used to
         handle the event. This function is useful when sending events that
         are handled the same way in every state, as only one
         <CODE>handle_event</CODE> clause is needed to handle the event instead
         of one clause in each state name function.
</DIV>

<P><A NAME="sync_send_event/2"><STRONG><CODE>sync_send_event(FsmRef, Event) -&#62; Reply</CODE></STRONG></A><BR>
<A NAME="sync_send_event/3"><STRONG><CODE>sync_send_event(FsmRef, Event, Timeout) -&#62; Reply</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sends an event to the gen_fsm <CODE>FsmRef</CODE> and waits until a
         reply arrives or a timeout occurs. The gen_fsm will call
         <CODE>Module:StateName/3</CODE> to handle the event, where
         <CODE>StateName</CODE> is the name of the current state of the gen_fsm.
        
<P>See <CODE>send_event/2</CODE> for a description of <CODE>FsmRef</CODE> and
         <CODE>Event</CODE>.
<P><CODE>Timeout</CODE> is an integer greater than zero which specifies
         how many milliseconds to wait for a reply, or the atom
         <CODE>infinity</CODE> to wait indefinitely. Default value is 5000.
         If no reply is received within the specified time, the function
         call fails.
<P>The return value <CODE>Reply</CODE> is defined in the return value of
         <CODE>Module:StateName/3</CODE>.
<P>In the case where the gen_fsm terminates during the handling of
         the event and the caller is linked to the gen_fsm and trapping
         exits, the exit message is removed from the caller's receive
         queue before the function call fails.<BR>

         This behaviour is retained for backwards compatibility only and may
         change in the future. Note that if the gen_fsm crashes in between
         calls, a linked process must take care of the exit message anyway.
         <BR>

         Warning: Under certain circumstances
         (e.g. <CODE>FsmRef = {Name,Node}</CODE>, and <CODE>Node</CODE> goes down)
         the exit message cannot be removed.
</DIV>

<P><A NAME="sync_send_all_state_event/2"><STRONG><CODE>sync_send_all_state_event(FsmRef, Event) -&#62; Reply</CODE></STRONG></A><BR>
<A NAME="sync_send_all_state_event/3"><STRONG><CODE>sync_send_all_state_event(FsmRef, Event, Timeout) -&#62; Reply</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sends an event to the gen_fsm <CODE>FsmRef</CODE> and waits until a
         reply arrives or a timeout occurs. The gen_fsm will call
         <CODE>Module:handle_sync_event/4</CODE> to handle the event.
<P>See <CODE>send_event/2</CODE> for a description of <CODE>FsmRef</CODE> and
         <CODE>Event</CODE>. See <CODE>sync_send_event/3</CODE> for a description of
         <CODE>Timeout</CODE> and <CODE>Reply</CODE>.
<P>See <CODE>send_all_state_event/2</CODE> for a discussion about
         the difference between <CODE>sync_send_event</CODE> and
         <CODE>sync_send_all_state_event</CODE>.
</DIV>

<P><A NAME="reply/2"><STRONG><CODE>reply(Caller, Reply) -&#62; true</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Caller - see below</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function can be used by a gen_fsm to explicitly send a reply
         to a client process that called <CODE>sync_send_event</CODE> or
         <CODE>sync_send_all_state_event</CODE>, when the reply cannot be defined
         in the return value of <CODE>Module:State/3</CODE> or
         <CODE>Module:handle_sync_event/4</CODE>.
<P><CODE>Caller</CODE> must be the <CODE>From</CODE> argument provided to
         the callback function. <CODE>Reply</CODE> is an arbitrary term, which
         will be given back to the client as the return value of
         <CODE>sync_send_event</CODE> or <CODE>sync_send_all_state_event</CODE>.
</DIV>

<P><A NAME="send_event_after/2"><STRONG><CODE>send_event_after(Time, Event) -&#62; Ref</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Time = integer()</CODE></STRONG><BR>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>
<STRONG><CODE>Ref = reference()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sends a delayed event internally in the gen_fsm that calls
         this function after <CODE>Time</CODE> ms. Returns immediately a
         reference that can be used to cancel the delayed send using
         <CODE>cancel_timer/1</CODE>. 
        
<P>The gen_fsm will call <CODE>Module:StateName/2</CODE> to handle
         the event, where <CODE>StateName</CODE> is the name of the current
         state of the gen_fsm at the time the delayed event is
         delivered. 
        
<P><CODE>Event</CODE> is an arbitrary term which is passed as one of
         the arguments to <CODE>Module:StateName/2</CODE>.

</DIV>

<P><A NAME="start_timer/2"><STRONG><CODE>start_timer(Time, Msg) -&#62; Ref</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Time = integer()</CODE></STRONG><BR>
<STRONG><CODE>Msg = term()</CODE></STRONG><BR>
<STRONG><CODE>Ref = reference()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sends a timeout event internally in the gen_fsm that calls
         this function after <CODE>Time</CODE> ms. Returns immediately a
         reference that can be used to cancel the timer using
         <CODE>cancel_timer/1</CODE>.
        
<P>The gen_fsm will call <CODE>Module:StateName/2</CODE> to handle
         the event, where <CODE>StateName</CODE> is the name of the current
         state of the gen_fsm at the time the timeout message is
         delivered. 
        
<P><CODE>Msg</CODE> is an arbitrary term which is passed in the
         timeout message, <CODE>{timeout, Ref, Msg}</CODE>, as one of
         the arguments to <CODE>Module:StateName/2</CODE>.

</DIV>

<P><A NAME="cancel_timer/1"><STRONG><CODE>cancel_timer(Ref) -&#62; RemainingTime | false</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Ref = reference()</CODE></STRONG><BR>
<STRONG><CODE>RemainingTime = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Cancels an internal timer referred by <CODE>Ref</CODE> in the
         gen_fsm that calls this function.
        
<P><CODE>Ref</CODE> is a reference returned from
         <CODE>send_event_after/2</CODE> or <CODE>start_timer/2</CODE>.
        
<P>If the timer has already timed out, but the event not yet
         been delivered, it is cancelled as if it had <STRONG>not</STRONG>
         timed out, so there will be no false timer event after
         returning from this function.
        
<P>Returns the remaining time in ms until the timer would
         have expired if <CODE>Ref</CODE> referred to an active timer,
         <CODE>false</CODE> otherwise. 

</DIV>

<P><A NAME="enter_loop/4"><STRONG><CODE>enter_loop(Module, Options, StateName, StateData)</CODE></STRONG></A><BR>
<A NAME="enter_loop/5"><STRONG><CODE>enter_loop(Module, Options, StateName, StateData,
        FsmName)</CODE></STRONG></A><BR>
<A NAME="enter_loop/5"><STRONG><CODE>enter_loop(Module, Options, StateName, StateData,
        Timeout)</CODE></STRONG></A><BR>
<A NAME="enter_loop/6"><STRONG><CODE>enter_loop(Module, Options, StateName, StateData,
        FsmName, Timeout)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = {debug,Dbgs}</CODE></STRONG><BR>
<STRONG><CODE>Dbgs = [Dbg]</CODE></STRONG><BR>
<STRONG><CODE>Dbg = trace | log | statistics</CODE></STRONG><BR>
<STRONG><CODE>| {log_to_file,FileName}
         | {install,{Func,FuncState}}</CODE></STRONG><BR>
<STRONG><CODE>StateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>StateData = term()</CODE></STRONG><BR>
<STRONG><CODE>FsmName = {local,Name} | {global,GlobalName}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int() | infinity</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Makes an existing process into a gen_fsm. Does not return,
         instead the calling process will enter the gen_fsm receive
         loop and become a gen_fsm process. The process <STRONG>must</STRONG>
         have been started using one of the start functions in
         <CODE>proc_lib</CODE>, see
         <A HREF="proc_lib.html">proc_lib(3)</A>. The user is
         responsible for any initialization of the process, including
         registering a name for it.
<P>This function is useful when a more complex initialization
         procedure is needed than the gen_fsm behaviour provides.
<P><CODE>Module</CODE>, <CODE>Options</CODE> and <CODE>FsmName</CODE> have
         the same meanings as when calling
         <A HREF="#start_link/3">start[_link]/3,4</A>.
         However, if <CODE>FsmName</CODE> is specified, the process must have
         been registered accordingly <STRONG>before</STRONG> this function is
         called.
<P><CODE>StateName</CODE>, <CODE>StateData</CODE> and <CODE>Timeout</CODE> have
         the same meanings as in the return value of
         <A HREF="#Moduleinit">Module:init/1</A>.
         Also, the callback module <CODE>Module</CODE> does not need to
         export an <CODE>init/1</CODE> function.
<P>Failure: If the calling process was not started by a
         <CODE>proc_lib</CODE> start function, or if it is not registered
         according to <CODE>FsmName</CODE>.
</DIV>

<H3>CALLBACK FUNCTIONS</H3>
<DIV CLASS=REFBODY>

<P>The following functions should be exported from a <CODE>gen_fsm</CODE>
callback module.
<P>In the description, the expression <STRONG>state name</STRONG> is used to
denote a state of the state machine. <STRONG>state data</STRONG> is used to
denote the internal state of the Erlang process which implements
the state machine.
<P> 
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="Module:init/1"><STRONG><CODE>Module:init(Args) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Return = {ok,StateName,StateData}
         | {ok,StateName,StateData,Timeout}</CODE></STRONG><BR>
<STRONG><CODE>| {stop,Reason} | ignore</CODE></STRONG><BR>
<STRONG><CODE>StateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>StateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>
<A NAME="Moduleinit"><!-- Empty --></A>
<P>Whenever a gen_fsm is started using <CODE>gen_fsm:start/3,4</CODE> or
         <CODE>gen_fsm:start_link/3,4</CODE>, this function is called by the new
         process to initialize.
<P><CODE>Args</CODE> is the <CODE>Args</CODE> argument provided to the start
         function.
<P>If initialization is successful, the function should return
         <CODE>{ok,StateName,StateData}</CODE> or
         <CODE>{ok,StateName,StateData,Timout}</CODE>, where <CODE>StateName</CODE>
         is the initial state name and <CODE>StateData</CODE> the initial
         state data of the gen_fsm.
<P>If an integer timout value is provided, a timout will occur
         unless an event or a message is received within <CODE>Timeout</CODE>
         milliseconds. A timout is represented by the atom <CODE>timeout</CODE>
         and should be handled by the <CODE>Module:StateName/2</CODE> callback
         functions. The atom <CODE>inifinity</CODE> can be used to wait
         indefinitely, this is the default value.
<P>If something goes wrong during the initialization the function
         should return <CODE>{stop,Reason}</CODE>, where <CODE>Reason</CODE> is any
         term, or <CODE>ignore</CODE>.
</DIV>

<P><A NAME="Module:StateName/2"><STRONG><CODE>Module:StateName(Event, StateData) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Event = timeout | term()</CODE></STRONG><BR>
<STRONG><CODE>StateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {next_state,NextStateName,NewStateData} |
         {next_state,NextStateName,NewStateData,Timeout}</CODE></STRONG><BR>
<STRONG><CODE> | {stop,Reason,NewStateData}</CODE></STRONG><BR>
<STRONG><CODE>NextStateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>NewStateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>There should be one instance of this function for each possible
         state name. Whenever a gen_fsm receives an event sent using
         <CODE>gen_fsm:send_event/2</CODE>, the instance of this function with
         the same name as the current state name <CODE>StateName</CODE> is called
         to handle the event. It is also called if a timeout occurs.
<P><CODE>Event</CODE> is either the atom <CODE>timeout</CODE>, if a timeout has
         occured, or the <CODE>Event</CODE> argument provided to
         <CODE>send_event</CODE>.
<P><CODE>StateData</CODE> is the state data of the gen_fsm.
<P>If the function returns
         <CODE>{next_state,NextStateName,NewStateData}</CODE> or
         <CODE>{next_state,NextStateName,NewStateData,Timeout}</CODE>,
         the gen_fsm will continue executing with the current state name
         set to <CODE>NextStateName</CODE> and with the possibly updated state
         data <CODE>NewStateData</CODE>.
         See <CODE>Module:init/1</CODE> for a description of <CODE>Timeout</CODE>.
<P>If the function returns <CODE>{stop,Reason,NewStateData}</CODE>,
         the gen_fsm will call <CODE>Module:terminate(Reason,NewStateData)</CODE>
         and terminate.
</DIV>

<P><A NAME="Module:handle_event/3"><STRONG><CODE>Module:handle_event(Event, StateName, StateData) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>
<STRONG><CODE>StateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>StateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {next_state,NextStateName,NewStateData} |
         {next_state,NextStateName,NewStateData,Timeout}</CODE></STRONG><BR>
<STRONG><CODE> | {stop,Reason,NewStateData}</CODE></STRONG><BR>
<STRONG><CODE>NextStateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>NewStateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Whenever a gen_fsm receives an event sent using
         <CODE>gen_fsm:send_all_state_event/2</CODE>, this function is called
         to handle the event.
<P><CODE>StateName</CODE> is the current state name of the gen_fsm.
<P>See <CODE>Module:StateName/2</CODE> for a description of the other
         arguments and possible return values.
</DIV>

<P><A NAME="Module:StateName/3"><STRONG><CODE>Module:StateName(Event, From, StateData) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>
<STRONG><CODE>From = {pid(),Tag}</CODE></STRONG><BR>
<STRONG><CODE>StateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {reply,Reply,NextStateName,NewStateData} |
         {reply,Reply,NextStateName,NewStateData,Timeout}</CODE></STRONG><BR>
<STRONG><CODE> | {next_state,NextStateName,NewStateData} |
         {next_state,NextStateName,NewStateData,Timeout}</CODE></STRONG><BR>
<STRONG><CODE> | {stop,Reason,Reply,NewStateData} |
         {stop,Reason,NewStateData}</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>
<STRONG><CODE>NextStateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>NewStateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = normal | term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>There should be one instance of this function for each possible
         state name. Whenever a gen_fsm receives an event sent using
         <CODE>gen_fsm:sync_send_event/2,3</CODE>, the instance of this function
         with the same name as the current state name <CODE>StateName</CODE> is
         called to handle the event.
<P><CODE>Event</CODE> is the <CODE>Event</CODE> argument provided to
         <CODE>sync_send_event</CODE>.
<P><CODE>From</CODE> is a tuple <CODE>{Pid,Tag}</CODE> where <CODE>Pid</CODE> is
         the pid of the process which called <CODE>sync_send_event</CODE> and
         <CODE>Tag</CODE> is a unique tag.
<P><CODE>StateData</CODE> is the state data of the gen_fsm.
<P>If the function returns
         <CODE>{reply,Reply,NextStateName,NewStateData}</CODE> or
         <CODE>{reply,Reply,NextStateName,NewStateData,Timeout}</CODE>,
         <CODE>Reply</CODE> will be given back to <CODE>From</CODE> as the return value
         of <CODE>sync_send_event</CODE>. The gen_fsm then continues executing
         with the current state name set to <CODE>NextStateName</CODE> and with
         the possibly updated state data <CODE>NewStateData</CODE>.
         See <CODE>Module:init/1</CODE> for a description of <CODE>Timeout</CODE>.
<P>If the function returns
         <CODE>{next_state,NextStateName,NewStateData}</CODE> or
         <CODE>{next_state,NextStateName,NewStateData,Timeout}</CODE>,
         the gen_fsm will continue executing in <CODE>NextStateName</CODE> with
         <CODE>NewStateData</CODE>. Any reply to <CODE>From</CODE> must be given
         explicitly using <CODE>gen_fsm:reply/2</CODE>.
<P>If the function returns <CODE>{stop,Reason,Reply,NewStateData}</CODE>,
         <CODE>Reply</CODE> will be given back to <CODE>From</CODE>. If the function
         returns <CODE>{stop,Reason,NewStateData}</CODE>, any reply to <CODE>From</CODE>
         must be given explicitly using <CODE>gen_fsm:reply/2</CODE>. The gen_fsm
         will then call <CODE>Module:terminate(Reason,NewStateData)</CODE> and
         terminate.
</DIV>

<P><A NAME="Module:handle_sync_event/4"><STRONG><CODE>Module:handle_sync_event(Event, From, StateName, StateData)
        -&#62; Result
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>
<STRONG><CODE>From = {pid(),Tag}</CODE></STRONG><BR>
<STRONG><CODE>StateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>StateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {reply,Reply,NextStateName,NewStateData} |
         {reply,Reply,NextStateName,NewStateData,Timeout}</CODE></STRONG><BR>
<STRONG><CODE> | {next_state,NextStateName,NewStateData} |
         {next_state,NextStateName,NewStateData,Timeout}</CODE></STRONG><BR>
<STRONG><CODE> | {stop,Reason,Reply,NewStateData} |
         {stop,Reason,NewStateData}</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>
<STRONG><CODE>NextStateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>NewStateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Whenever a gen_fsm receives an event sent using
         <CODE>gen_fsm:sync_send_all_state_event/2,3</CODE>, this function is
         called to handle the event.
<P><CODE>StateName</CODE> is the current state name of the gen_fsm.
<P>See <CODE>Module:StateName/3</CODE> for a description of the other
         arguments and possible return values.
</DIV>

<P><A NAME="Module:handle_info/3"><STRONG><CODE>Module:handle_info(Info, StateName, StateData) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Info = term()</CODE></STRONG><BR>
<STRONG><CODE>StateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>StateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {next_state,NextStateName,NewStateData} |
         {next_state,NextStateName,NewStateData,Timeout}</CODE></STRONG><BR>
<STRONG><CODE> | {stop,Reason,NewStateData}</CODE></STRONG><BR>
<STRONG><CODE>NextStateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>NewStateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = normal | term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function is called by a gen_fsm when it receives any other
         message than a synchronous or asynchronous event (or a system
         message).
<P><CODE>Info</CODE> is the received message.
<P>See <CODE>Module:StateName/2</CODE> for a description of the other
         arguments and possible return values.
</DIV>

<P><A NAME="Module:terminate/3"><STRONG><CODE>Module:terminate(Reason, StateName, StateData)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Reason = normal | shutdown | term()</CODE></STRONG><BR>
<STRONG><CODE>StateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>StateData = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function is called by a gen_fsm when it is about to
         terminate. It should be the opposite of <CODE>Module:init/1</CODE> and
         do any necessary cleaning up. When it returns, the gen_fsm
         terminates with <CODE>Reason</CODE>. The return value is ignored.
<P><CODE>Reason</CODE> is a term denoting the stop reason, <CODE>StateName</CODE>
         is the current state name, and <CODE>StateData</CODE> is the state data
         of the gen_fsm.
<P><CODE>Reason</CODE> depends on why the gen_fsm is terminating. If it is
         because another callback function has returned a stop tuple
         <CODE>{stop,..}</CODE>, <CODE>Reason</CODE> will have the value specified in
         that tuple. If it is due to a failure, <CODE>Reason</CODE> is the error
         reason.
<P>If the gen_fsm is part of a supervision tree and is ordered
         by its superviser to terminate, this function will be called with
         <CODE>Reason=shutdown</CODE> if the following conditions apply:
<P>
<UL>

<LI>
the gen_fsm has been set to trap exit signals, and
</LI>


<LI>
the shutdown strategy as defined in the supervisor's child
         specification is an integer timeout value, not
         <CODE>brutal_kill</CODE>.
         
</LI>


</UL>

<P>Otherwise, the gen_fsm will be immediately terminated.
<P>Note that for any other reason than <CODE>normal</CODE> or
         <CODE>shutdown</CODE>, the gen_fsm is assumed to terminate due to an
         error and an error report is issued using
         <CODE>error_logger:format/2</CODE>.
</DIV>

<P><A NAME="Module:code_change/4"><STRONG><CODE>Module:code_change(OldVsn, StateName, StateData, Extra) -&#62;
        {ok, NextStateName, NewStateData}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>OldVsn = Vsn | {down, Vsn}</CODE></STRONG><BR>
<STRONG><CODE>Vsn = term()</CODE></STRONG><BR>
<STRONG><CODE>StateName = NextStateName = atom()</CODE></STRONG><BR>
<STRONG><CODE>StateData = NewStateData = term()</CODE></STRONG><BR>
<STRONG><CODE>Extra = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function is called by a gen_fsm when it should update
         its internal state data during a release upgrade/downgrade,
         i.e. when the instruction <CODE>{update,Module,Change,...}</CODE>
         where <CODE>Change={advanced,Extra}</CODE> is given in
         the <CODE>appup</CODE> file. See <STRONG>OTP Design Principles</STRONG> for
         more information.
<P>In the case of an upgrade, <CODE>OldVsn</CODE> is <CODE>Vsn</CODE>, and
         in the case of a downgrade, <CODE>OldVsn</CODE> is
         <CODE>{down,Vsn}</CODE>. <CODE>Vsn</CODE> is defined by the <CODE>vsn</CODE>
         attribute(s) of the old version of the callback module
         <CODE>Module</CODE>. If no such attribute is defined, the version is
         the checksum of the BEAM file.
<P><CODE>StateName</CODE> is the current state name and
         <CODE>StateData</CODE> the internal state data of the gen_fsm.
<P><CODE>Extra</CODE> is passed as-is from the <CODE>{advanced,Extra}</CODE>
         part of the update instruction.
<P>The function should return the new current state name and
         updated internal data.
</DIV>

<H3>SEE ALSO</H3>
<DIV CLASS=REFBODY>

<P><A HREF="supervisor.html">supervisor(3)</A>, 
<A HREF="sys.html">sys(3)</A>
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Gunilla Arendt - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.14.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>