From 17405463ba134e71ff09e8d2921de9aa931805ee Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Mon, 9 May 2016 14:20:03 +0200 Subject: Fix all seealso and other minor changes --- lib/stdlib/doc/src/gen_statem.xml | 296 ++++++++++++-------------------------- 1 file changed, 88 insertions(+), 208 deletions(-) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index be90488a1f..b1d9799917 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -84,9 +84,7 @@ using this module has a standard set of interface functions and includes functionality for tracing and error reporting. It also fits into an OTP supervision tree. For more information, see - - OTP Design Principles - . + OTP Design Principles.

A gen_statem assumes all specific parts to be located in a @@ -136,28 +134,23 @@ erlang:'!' -----> Module:StateName/3 callback mode is state_functions, the state must be an atom and is used as the state function name; see - - Module:StateName/3 - . + Module:StateName/3. This gathers all code for a specific state in one function and hence dispatches on state first. Notice that in this mode the mandatory callback function - - Module:terminate/3 - makes the state name terminate unusable. + Module:terminate/3 + makes the state name terminate unusable.

When the callback mode is handle_event_function, the state can be any term and the state function name is - - Module:handle_event/4 - . + Module:handle_event/4. This makes it easy to dispatch on state or on event as you desire. Be careful about which events you handle in which - states so that you do not accidentally postpone one event + states so that you do not accidentally postpone an event forever creating an infinite busy loop.

@@ -178,15 +171,12 @@ erlang:'!' -----> Module:StateName/3

The state function can insert events using the - - action() next_event - + action() + next_event and such an event is inserted as the next to present to the state function. That is, as if it is the oldest incoming event. A dedicated - - event_type() - + event_type() internal can be used for such events making them impossible to mistake for external events.

@@ -206,21 +196,18 @@ erlang:'!' -----> Module:StateName/3

For the details of a state transition, see type - - transition_option() - . + transition_option().

A gen_statem handles system messages as described in sys. - The sysmodule can be used for debugging a gen_statem. + The sys module can be used for debugging a gen_statem.

Notice that a gen_statem does not trap exit signals automatically, this must be explicitly initiated in the callback module (by calling - - process_flag(trap_exit, true). + process_flag(trap_exit, true).

Unless otherwise stated, all functions in this module fail if @@ -229,9 +216,7 @@ erlang:'!' -----> Module:StateName/3

The gen_statem process can go into hibernation; see - - proc_lib:hibernate/3 - . + proc_lib:hibernate/3. It is done when a state function or Module:init/1 @@ -242,9 +227,7 @@ erlang:'!' -----> Module:StateName/3 However, use this feature with care, as hibernation can be too costly to use after every event; see - - erlang:hibernate/3 - . + erlang:hibernate/3.

@@ -257,7 +240,7 @@ erlang:'!' -----> Module:StateName/3 state_functions. You can push the button and it replies if it went on or off, and you can ask for a count of how many times it has been - pushed to on. + pushed to switch on.

The following is the complete callback module file pushbutton.erl:

@@ -381,13 +364,10 @@ handle_event(_, _, State, Data) ->

Name specification to use when starting a gen_statem server. See - - start_link/3 - + start_link/3 and - - server_ref() - below. + server_ref() + below.

@@ -398,14 +378,12 @@ handle_event(_, _, State, Data) -> Server specification to use when addressing a gen_statem server. See call/2 and - - server_name() - + server_name() above.

It can be:

- pid() | LocalName + pid() | LocalName

The gen_statem is locally registered. @@ -421,21 +399,21 @@ handle_event(_, _, State, Data) -> {global,GlobalName}

- The gen_statem is globally registered - in kernel:global. + The gen_statem is globally registered in + kernel:global.

{via,RegMod,ViaName}

- The gen_statem is registered through + The gen_statem is registered in an alternative process registry. The registry callback module RegMod is to export functions register_name/2, unregister_name/1, whereis_name/1, and send/2, - which are to behave like the corresponding functions - in kernel:global. + which are to behave like the corresponding functions in + kernel:global. Thus, {via,global,GlobalName} is the same as {global,GlobalName}.

@@ -482,9 +460,7 @@ handle_event(_, _, State, Data) ->

Destination to use when replying through, for example, the - - action() - + action() {reply,From,Reply} to a process that has called the gen_statem server using call/2. @@ -554,9 +530,7 @@ handle_event(_, _, State, Data) -> or when calling enter_loop/5,6,7, and with the return value from - - Module:code_change/4 - . + Module:code_change/4.

state_functions @@ -565,9 +539,7 @@ handle_event(_, _, State, Data) -> The state must be of type state_name() and one callback function per state, that is, - - Module:StateName/3 - , + Module:StateName/3, is used.

@@ -575,9 +547,7 @@ handle_event(_, _, State, Data) ->

The state can be any term and the callback function - - Module:handle_event/4 - + Module:handle_event/4 is used for all states.

@@ -604,9 +574,7 @@ handle_event(_, _, State, Data) ->

If - - postpone() - + postpone() is true, the current event is postponed.

@@ -620,9 +588,7 @@ handle_event(_, _, State, Data) ->

All events stored with - - action() - + action() next_event are inserted in the queue to be processed before all other events. @@ -631,13 +597,9 @@ handle_event(_, _, State, Data) ->

If an - - event_timeout() - + event_timeout() is set through - - action() - + action() timeout, an event timer can be started or a time-out zero event can be enqueued. @@ -651,9 +613,7 @@ handle_event(_, _, State, Data) -> otherwise the gen_statem goes into receive or hibernation (if - - hibernate() - + hibernate() is true) to wait for the next message. In hibernation the next non-system event awakens the gen_statem, or rather @@ -681,16 +641,13 @@ handle_event(_, _, State, Data) ->

If true, hibernates the gen_statem by calling - - proc_lib:hibernate/3 - + proc_lib:hibernate/3 before going into receive to wait for a new external event. If there are enqueued events, to prevent receiving any new event, an - - erlang:garbage_collect/0 - is done instead to simulate + erlang:garbage_collect/0 + is done instead to simulate that the gen_statem entered hibernation and immediately got awakened by the oldest enqueued event.

@@ -731,8 +688,8 @@ handle_event(_, _, State, Data) ->

These state transition actions can be invoked by returning them from the - state function, - from Module:init/1 + state function, from + Module:init/1 or by giving them to enter_loop/6,7.

@@ -741,15 +698,11 @@ handle_event(_, _, State, Data) ->

Actions that set - - transition options - + transition options override any previous of the same type, so the last in the containing list wins. For example, the last - - event_timeout() - + event_timeout() overrides any other event_timeout() in the list.

@@ -757,12 +710,8 @@ handle_event(_, _, State, Data) ->

Sets the - - transition_option() - - - postpone() - + transition_option() + postpone() for this state transition. This action is ignored when returned from Module:init/1 @@ -775,12 +724,8 @@ handle_event(_, _, State, Data) ->

Sets the - - transition_option() - - - hibernate() - + transition_option() + hibernate() for this state transition.

@@ -792,22 +737,16 @@ handle_event(_, _, State, Data) -> This form exists to make the state function return value {next_state,NextState,NewData,Timeout} - allowed like for - - gen_fsm:Module:StateName/2 - . + allowed like for gen_fsm's + Module:StateName/2.

timeout

Sets the - - transition_option() - - - event_timeout() - + transition_option() + event_timeout() to Time with EventContent.

@@ -832,9 +771,7 @@ handle_event(_, _, State, Data) ->

An event of type - - internal - + internal is to be used when you want to reliably distinguish an event inserted this way from any external event.

@@ -849,9 +786,7 @@ handle_event(_, _, State, Data) -> Replies to a caller waiting for a reply in call/2. From must be the term from argument - - {call,From} - + {call,From} to the state function.

@@ -907,9 +842,7 @@ handle_event(_, _, State, Data) ->

Terminates the gen_statem by calling - - Module:terminate/3 - + Module:terminate/3 with Reason and NewData, if specified.

@@ -919,9 +852,7 @@ handle_event(_, _, State, Data) ->

Sends all Replies, then terminates the gen_statem by calling - - Module:terminate/3 - + Module:terminate/3 with Reason and NewData, if specified.

@@ -965,9 +896,7 @@ handle_event(_, _, State, Data) ->

Makes a synchronous call to the gen_statem - - ServerRef - + ServerRef by sending a request and waiting until its reply arrives. The gen_statem calls the @@ -1015,9 +944,7 @@ handle_event(_, _, State, Data) ->

Sends an asynchronous event to the gen_statem - - ServerRef - + ServerRef and returns ok immediately, ignoring if the destination node or gen_statem does not exist. @@ -1038,9 +965,7 @@ handle_event(_, _, State, Data) -> The same as enter_loop/7 except that no - - server_name() - + server_name() must have been registered.

@@ -1055,9 +980,7 @@ handle_event(_, _, State, Data) -> the same as enter_loop/7 except that no - - server_name() - + server_name() must have been registered and Actions = Server_or_Actions.

@@ -1095,13 +1018,9 @@ handle_event(_, _, State, Data) -> Module, Opts, and Server have the same meanings as when calling - - start[_link]/3,4 - . + start[_link]/3,4. However, the - - server_name() - + server_name() name must have been registered accordingly before this function is called.

@@ -1137,16 +1056,12 @@ handle_event(_, _, State, Data) ->

From must be the term from argument - - {call,From} - + {call,From} to the state function. From and Reply can also be specified using a - - reply_action() - + reply_action() and multiple replies with a list of them.

@@ -1204,9 +1119,7 @@ handle_event(_, _, State, Data) ->

ServerName specifies the - - server_name() - + server_name() to register for the gen_statem. If the gen_statem is started with start_link/3, no ServerName is provided and @@ -1225,8 +1138,7 @@ handle_event(_, _, State, Data) -> Opts, the gen_statem is allowed to spend Time milliseconds initializing or it terminates and the start function returns - - {error,timeout}. + {error,timeout}.

@@ -1241,8 +1153,8 @@ handle_event(_, _, State, Data) ->

If option {spawn_opt,SpawnOpts} is present in Opts, SpawnOpts is passed - as option list to - erlang:spawn_opt/2, + as option list to + erlang:spawn_opt/2, which is used to spawn the gen_statem process.

@@ -1250,22 +1162,19 @@ handle_event(_, _, State, Data) ->

Using spawn option monitor is not - allowed, it cause this function to fail with reason + allowed, it causes this function to fail with reason badarg.

If the gen_statem is successfully created and initialized, this function returns - - {ok,Pid} - , + {ok,Pid}, where Pid is the pid() of the gen_statem. If a process with the specified ServerName exists already, this function returns - - {error,{already_started,Pid}}, + {error,{already_started,Pid}}, where Pid is the pid() of that process.

@@ -1273,16 +1182,12 @@ handle_event(_, _, State, Data) -> this function returns {error,Reason}. If Module:init/1 returns - - {stop,Reason} - + {stop,Reason} or ignore, the process is terminated and this function returns - - {error,Reason} - + {error,Reason} or ignore, respectively. @@ -1296,9 +1201,7 @@ handle_event(_, _, State, Data) ->

The same as - - stop(ServerRef, normal, infinity). - + stop(ServerRef, normal, infinity).

@@ -1309,15 +1212,11 @@ handle_event(_, _, State, Data) ->

Orders the gen_statem - - ServerRef - + ServerRef to exit with the specified Reason and waits for it to terminate. The gen_statem calls - - Module:terminate/3 - + Module:terminate/3 before exiting.

@@ -1325,9 +1224,7 @@ handle_event(_, _, State, Data) -> with the expected reason. Any other reason than normal, shutdown, or {shutdown,Term} causes an error report to be issued through - - error_logger:format/2 - . + error_logger:format/2. The default Reason is normal.

@@ -1388,9 +1285,7 @@ handle_event(_, _, State, Data) -> where Change={advanced,Extra}, is specified in the appup file. For more information, see - - OTP Design Principles - . + OTP Design Principles.

For an upgrade, OldVsn is Vsn, and @@ -1403,9 +1298,7 @@ handle_event(_, _, State, Data) ->

If you would dare to change - - callback mode - + callback mode during release upgrade/downgrade, the upgrade is no problem, as the new code surely knows what callback mode it needs. However, for a downgrade this function must @@ -1483,8 +1376,7 @@ handle_event(_, _, State, Data) -> return {CallbackMode,State,Data} or {CallbackMode,State,Data,Actions}. CallbackMode selects the - - callback mode + callback mode of the gen_statem. State is the initial state() @@ -1549,9 +1441,7 @@ handle_event(_, _, State, Data) -> One of - - sys:get_status/1,2 - + sys:get_status/1,2 is invoked to get the gen_statem status. Opt is set to the atom normal for this case. @@ -1564,9 +1454,7 @@ handle_event(_, _, State, Data) -> This function is useful for changing the form and appearance of the gen_statem status for these cases. A callback module wishing to change the - - sys:get_status/1,2 - + sys:get_status/1,2 return value and how its status appears in termination error logs exports an instance of format_status/2, which returns a term @@ -1589,9 +1477,7 @@ handle_event(_, _, State, Data) -> changes the details of the current state and status of the gen_statem. There are no restrictions on the form Status can take, but for the - - sys:get_status/1,2 - + sys:get_status/1,2 case (when Opt is normal), the recommended form for the Status value is [{data, [{"State", @@ -1599,9 +1485,7 @@ handle_event(_, _, State, Data) -> the gen_statem state. Following this recommendation is not required, but it makes the callback module status consistent with the rest of the - - sys:get_status/1,2 - + sys:get_status/1,2 return value.

@@ -1642,15 +1526,11 @@ handle_event(_, _, State, Data) -> StateFunctionResult = - - state_function_result() - + state_function_result() HandleEventResult = - - handle_event_result() - + handle_event_result() @@ -1766,9 +1646,7 @@ handle_event(_, _, State, Data) -> shutdown, or {shutdown,Term}, the gen_statem is assumed to terminate because of an error and an error report is issued using - - error_logger:format/2. - + error_logger:format/2.

This function can use @@ -1781,11 +1659,13 @@ handle_event(_, _, State, Data) ->

See Also -

gen_event(3), +

+ gen_event(3), gen_fsm(3), gen_server(3), proc_lib(3), supervisor(3), - sys(3)

+ sys(3). +

-- cgit v1.2.3