diff options
Diffstat (limited to 'system')
| -rw-r--r-- | system/doc/Makefile | 1 | ||||
| -rw-r--r-- | system/doc/design_principles/applications.xml | 2 | ||||
| -rw-r--r-- | system/doc/design_principles/statem.xml | 451 | ||||
| -rw-r--r-- | system/doc/efficiency_guide/binaryhandling.xml | 8 | ||||
| -rw-r--r-- | system/doc/embedded/starting.xml | 2 | ||||
| -rw-r--r-- | system/doc/general_info/Makefile | 99 | ||||
| -rw-r--r-- | system/doc/general_info/book.xml | 44 | ||||
| -rw-r--r-- | system/doc/general_info/deprecations.xml | 98 | ||||
| -rw-r--r-- | system/doc/general_info/part.xml | 34 | ||||
| -rw-r--r-- | system/doc/general_info/scheduled_for_removal.xml | 61 | ||||
| -rw-r--r-- | system/doc/general_info/xmlfiles.mk | 22 | ||||
| -rw-r--r-- | system/doc/html/general_info/.gitignore | 0 | ||||
| -rw-r--r-- | system/doc/oam/oam_intro.xml | 55 | ||||
| -rw-r--r-- | system/doc/reference_manual/expressions.xml | 1 | ||||
| -rw-r--r-- | system/doc/system_principles/misc.xml | 8 | ||||
| -rw-r--r-- | system/doc/top/Makefile | 5 | ||||
| -rw-r--r-- | system/doc/top/book.xml | 1 | ||||
| -rw-r--r-- | system/doc/top/templates/index.html.src | 2 | ||||
| -rw-r--r-- | system/doc/xml/general_info/.gitignore | 0 |
19 files changed, 700 insertions, 194 deletions
diff --git a/system/doc/Makefile b/system/doc/Makefile index 0c4adf6554..8f2faeee04 100644 --- a/system/doc/Makefile +++ b/system/doc/Makefile @@ -24,6 +24,7 @@ include $(ERL_TOP)/make/$(TARGET)/otp.mk # SUB_DIRECTORIES = design_principles \ + general_info \ getting_started \ system_architecture_intro \ embedded \ diff --git a/system/doc/design_principles/applications.xml b/system/doc/design_principles/applications.xml index 3b7b8fdaee..8f1969ff29 100644 --- a/system/doc/design_principles/applications.xml +++ b/system/doc/design_principles/applications.xml @@ -185,7 +185,7 @@ ch_app:stop([])</code> the directory with the highest version number, if more than one version of an application is present.</p> <section> - <title>Directory Structure guidelines for a Development Environment</title> + <title>Directory Structure Guidelines for a Development Environment</title> <p>Any directory structure for development will suffice as long as the released directory structure adhere to the <seealso marker="#app_dir_released">description below</seealso>, but it is encouraged that the same directory structure diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index 16a901b3a5..45ea972ff2 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2016</year><year>2018</year> + <year>2016</year><year>2019</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -44,28 +44,40 @@ <title>Event-Driven State Machines</title> <p> Established Automata Theory does not deal much with - how a state transition is triggered, + how a <em>state transition</em> is triggered, but assumes that the output is a function of the input (and the state) and that they are some kind of values. </p> <p> For an Event-Driven State Machine, the input is an event - that triggers a state transition and the output - is actions executed during the state transition. + that triggers a <em>state transition</em> and the output + is actions executed during the <em>state transition</em>. It can analogously to the mathematical model of a - Finite-State Machine be described as + Finite State Machine be described as a set of relations of the following form: </p> <pre> State(S) x Event(E) -> Actions(A), State(S')</pre> - <p>These relations are interpreted as follows: + <p> + These relations are interpreted as follows: if we are in state <c>S</c> and event <c>E</c> occurs, we are to perform actions <c>A</c> and make a transition to state <c>S'</c>. Notice that <c>S'</c> can be equal to <c>S</c> and that <c>A</c> can be empty. </p> <p> + In <c>gen_statem</c> we define + a <em>state change</em> as a <em>state transition</em> + in which the new state <c>S'</c> is different from + the current state <c>S</c>, where "different" means + Erlang's strict inequality: <c>=/=</c> + also know as "does not match". + During a <em>state changes</em>, + <c>gen_statem</c> does more things + than during other <em>state transitions</em>. + </p> + <p> As <c>A</c> and <c>S'</c> depend only on <c>S</c> and <c>E</c>, the kind of state machine described here is a Mealy machine @@ -95,8 +107,8 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <list type="bulleted"> <item> Co-located callback code for each state, - regardless of - <seealso marker="#Event Types">Event Type</seealso> + for all + <seealso marker="#Event Types"><em>Event Types</em></seealso> (such as <em>call</em>, <em>cast</em> and <em>info</em>) </item> <item> @@ -114,13 +126,13 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </item> <item> <seealso marker="#State Enter Calls"> - State Enter Calls + <em>State Enter Calls</em> </seealso> (callback on state entry co-located with the rest of each state's callback code) </item> <item> - Easy-to-use timeouts + Easy-to-use time-outs (<seealso marker="#State Time-Outs">State Time-Outs</seealso>, <seealso marker="#Event Time-Outs">Event Time-Outs</seealso> and @@ -152,11 +164,11 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <marker id="Callback Module" /> <title>Callback Module</title> <p> - The callback module contains functions that implement + The <em>callback module</em> contains functions that implement the state machine. When an event occurs, the <c>gen_statem</c> behaviour engine - calls a function in the callback module with the event, + calls a function in the <em>callback module</em> with the event, current state and server data. This function performs the actions for this event, and returns the new state and server data @@ -166,7 +178,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> The behaviour engine holds the state machine state, server data, timer references, a queue of posponed messages and other metadata. It receives all process messages, - handles the system messages, and calls the callback module + handles the system messages, and calls the <em>callback module</em> with machine specific events. </p> </section> @@ -177,7 +189,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <marker id="Callback Modes" /> <title>Callback Modes</title> <p> - The <c>gen_statem</c> behavior supports two callback modes: + The <c>gen_statem</c> behavior supports two <em>callback modes</em>: </p> <taglist> <tag> @@ -202,31 +214,33 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </item> </taglist> <p> - The callback mode is selected at server start + The <em>callback mode</em> is selected at server start and may be changed with a code upgrade/downgrade. </p> <p> See the section - <seealso marker="#Event Handler">Event Handler</seealso> + <seealso marker="#State Callback"><em>State Callback</em></seealso> that describes the event handling callback function(s). </p> <p> - The callback mode is selected by implementing + The <em>callback mode</em> is selected by implementing a mandatory callback function <seealso marker="stdlib:gen_statem#Module:callback_mode/0"> <c>Module:callback_mode()</c> </seealso> - that returns one of the callback modes. + that returns one of the <em>callback modes</em>. </p> <p> The <seealso marker="stdlib:gen_statem#Module:callback_mode/0"> <c>Module:callback_mode()</c> </seealso> - function may also return a list containing the callback mode + function may also return a list containing the <em>callback mode</em> and the atom <c>state_enter</c> in which case - <seealso marker="#State Enter Calls">State Enter Calls</seealso> - are activated for the callback mode. + <seealso marker="#State Enter Calls"> + <em>state enter calls</em> + </seealso> + are activated for the <em>callback mode</em>. </p> <section> @@ -237,11 +251,11 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> it is the one most like <c>gen_fsm</c>. But if you do not want the restriction that the state must be an atom, or if you do not want to write - one event handler function per state; please read on... + one <em>state callback</em> function per state; please read on... </p> <p> The two - <seealso marker="#Callback Modes">Callback Modes</seealso> + <seealso marker="#Callback Modes"><em>callback modes</em></seealso> give different possibilities and restrictions, with one common goal: to handle all possible combinations of events and states. @@ -257,7 +271,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> With <c>state_functions</c>, you are restricted to use atom-only states, and the <c>gen_statem</c> engine branches depending on state name for you. - This encourages the callback module to co-locate + This encourages the <em>callback module</em> to co-locate the implementation of all event actions particular to one state in the same place in the code, hence to focus on one state at the time. @@ -302,11 +316,12 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <!-- =================================================================== --> <section> - <marker id="Event Handler" /> - <title>Event Handler</title> + <marker id="State Callback" /> + <title>State Callback</title> <p> - Which callback function that handles an event - depends on the callback mode: + The <em>state callback</em> is the callback function + that handles an event in the current state, + and which function that is depends on the <em>callback mode</em>: </p> <taglist> <tag><c>state_functions</c></tag> @@ -329,7 +344,9 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </seealso> <p> See section - <seealso marker="#One Event Handler">One Event Handler</seealso> + <seealso marker="#One State Callback"> + <em>One State Callback</em> + </seealso> for an example. </p> </item> @@ -338,15 +355,17 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> The state is either the name of the function itself or an argument to it. The other arguments are the <c>EventType</c> described in section <seealso marker="#Event Types">Event Types</seealso>, - the event dependent <c>EventContent</c>, and the current server <c>Data</c>. + the event dependent <c>EventContent</c>, + and the current server <c>Data</c>. </p> <p> - State enter calls are also handled by the event handler and have - slightly different arguments. See the section + <em>State enter calls</em> are also handled by the event handler + and have slightly different arguments. See section <seealso marker="#State Enter Calls">State Enter Calls</seealso>. </p> <p> - The event handler return values are defined in the description of + The <em>state callback</em> return values + are defined in the description of <seealso marker="stdlib:gen_statem#Module:StateName/3"> <c>Module:StateName/3</c> </seealso> @@ -361,24 +380,29 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <item> <p> Set next state and update the server data. - If the <c>Actions</c> field is used, execute state transition actions. - An empty <c>Actions</c> list is equivalent to not returning the field. + If the <c>Actions</c> field is used, + execute <em>transition actions</em>. + An empty <c>Actions</c> list is equivalent to + not returning the field. </p> <p> See section - <seealso marker="#State Transition Actions"> - State Transition Actions + <seealso marker="#Transition Actions"> + <em>Transition Actions</em> </seealso> for a list of possible - state transition actions. + <em>transition actions</em>. </p> <p> - If <c>NextState =/= State</c> the state machine changes - to a new state. A + If <c>NextState =/= State</c> this is a <em>state change</em> + so the extra things <c>gen_statem</c> does are: the event queue + is restarted from the oldest + <seealso marker="#Postponing Events">postponed event</seealso>, + any current + <seealso marker="#State Time-Outs">state time-out</seealso> + is cancelled, and a <seealso marker="#State Enter Calls">state enter call</seealso> - is performed if enabled and all - <seealso marker="#Postponing Events">postponed events</seealso> - are retried. + is performed, if enabled. </p> </item> <tag> @@ -388,7 +412,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <item> <p> Same as the <c>next_state</c> values with - <c>NextState =:= State</c>, that is, no state change. + <c>NextState =:= State</c>, that is, no <em>state change</em>. </p> </item> <tag> @@ -414,9 +438,16 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <seealso marker="#State Enter Calls"> State Enter Calls </seealso> - are enabled, repeat the state enter call + are enabled, repeat the <em>state enter call</em> as if this state was entered again. </p> + <p> + If these return values are used from a + <em>state enter call</em> the <c>OldState</c> does not change, + but if used from an event handling <em>state callback</em> + the new <em>state enter call's</em> <c>OldState</c> + will be the current state. + </p> </item> <tag> <c>{stop, Reason, NewData}</c><br /> @@ -435,7 +466,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <item> <p> Same as the <c>stop</c> values, but first execute the given - state transition actions that may only be reply actions. + <seealso marker="#Transition Actions"> + <em>transition actions</em> + </seealso> + that may only be reply actions. </p> </item> </taglist> @@ -449,8 +483,8 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <c>Module:init(Args)</c> </seealso> callback function is called before any - <seealso marker="#Event Handler">Event Handler</seealso> - is called. This function behaves like an event handler + <seealso marker="#State Callback"><em>state callback</em></seealso> + is called. This function behaves like an <em>state callback</em> function, but gets its only argument <c>Args</c> from the <c>gen_statem</c> <seealso marker="stdlib:gen_statem#start/3"> @@ -474,8 +508,8 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <!-- =================================================================== --> <section> - <marker id="State Transition Actions" /> - <title>State Transition Actions</title> + <marker id="Transition Actions" /> + <title>Transition Actions</title> <p> In the first section <seealso marker="#Event-Driven State Machines"> @@ -483,13 +517,13 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </seealso> actions were mentioned as a part of the general state machine model. These general actions - are implemented with the code that callback module + are implemented with the code that <em>callback module</em> <c>gen_statem</c> executes in an event-handling callback function before returning to the <c>gen_statem</c> engine. </p> <p> - There are more specific state-transition actions + There are more specific <em>transition actions</em> that a callback function can command the <c>gen_statem</c> engine to do after the callback function return. These are commanded by returning a list of @@ -500,7 +534,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </seealso> from the <seealso marker="stdlib:gen_statem#Module:StateName/3">callback function</seealso>. - These are the possible state transition actions: + These are the possible <em>transition actions</em>: </p> <taglist> <tag> @@ -512,7 +546,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> If set postpone the current event, see section - <seealso marker="#Postponing Events">Postponing Events</seealso> + <seealso marker="#Postponing Events">Postponing Events</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-hibernate"> @@ -523,41 +557,44 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> If set hibernate the <c>gen_statem</c>, treated in section - <seealso marker="#Hibernation">Hibernation</seealso> + <seealso marker="#Hibernation">Hibernation</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-state_timeout"> - <c>{state_timeout, Time}</c> + <c>{state_timeout, EventContent, Time}</c> </seealso> <br /> - <c>{state_timeout, Time, Opts}</c> + <c>{state_timeout, EventContent, Time, Opts}</c> </tag> <item> - Start a state time-out, read more in section - <seealso marker="#State Time-Outs">State Time-Outs</seealso> + Start a state time-out, read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#State Time-Outs">State Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-generic_timeout"> - <c>{{timeout, Name}, Time}</c> + <c>{{timeout, Name}, EventContent, Time}</c> </seealso> <br /> - <c>{{timeout, Name}, Time, Opts}</c> + <c>{{timeout, Name}, EventContent, Time, Opts}</c> </tag> <item> - Start a generic time-out, read more in section - <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso> + Start a generic time-out, read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-event_timeout"> - <c>{timeout, Time}</c> + <c>{timeout, EventContent, Time}</c> </seealso> <br /> - <c>{timeout, Time, Opts}</c><br /> + <c>{timeout, EventContent, Time, Opts}</c><br /> <c>Time</c> </tag> <item> - Start an event time-out, see more in section - <seealso marker="#Event Time-Outs">Event Time-Outs</seealso> + Start an event time-out, see more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#Event Time-Outs">Event Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-reply_action"> @@ -566,7 +603,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> Reply to a caller, mentioned at the end of section - <seealso marker="#All State Events">All State Events</seealso> + <seealso marker="#All State Events">All State Events</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-action"> @@ -575,7 +612,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </tag> <item> Generate the next event to handle, see section - <seealso marker="#Inserted Events">Inserted Events</seealso> + <seealso marker="#Inserted Events">Inserted Events</seealso>. </item> </taglist> <p> @@ -596,13 +633,13 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <title>Event Types</title> <p> Events are categorized in different - <seealso marker="stdlib:gen_statem#type-event_type">event types</seealso>. + <seealso marker="stdlib:gen_statem#type-event_type"><em>event types</em></seealso>. Events of all types are for a given state handled in the same callback function, and that function gets <c>EventType</c> and <c>EventContent</c> as arguments. </p> <p> - The following is a complete list of event types and where + The following is a complete list of <em>event types</em> and where they come from: </p> <taglist> @@ -624,7 +661,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> Generated by <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call</c></seealso>, where <c>From</c> is the reply address to use - when replying either through the state transition action + when replying either through the <em>transition action</em> <c>{reply,From,Msg}</c> or by calling <seealso marker="stdlib:gen_statem#reply/1"><c>gen_statem:reply</c></seealso>. </item> @@ -643,11 +680,13 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </seealso> </tag> <item> - Generated by state transition action - <seealso marker="stdlib:gen_statem#type-state_timeout"> + Generated by <em>transition action</em> + <seealso marker="stdlib:gen_statem#type-timeout_action"> <c>{state_timeout,Time,EventContent}</c> </seealso> - state timer timing out. + state timer timing out. Read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#State Time-Outs">State Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-timeout_event_type"> @@ -655,11 +694,13 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </seealso> </tag> <item> - Generated by state transition action - <seealso marker="stdlib:gen_statem#type-generic_timeout"> + Generated by <em>transition action</em> + <seealso marker="stdlib:gen_statem#type-timeout_action"> <c>{{timeout,Name},Time,EventContent}</c> </seealso> - generic timer timing out. + generic timer timing out. Read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-timeout_event_type"> @@ -667,12 +708,14 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </seealso> </tag> <item> - Generated by state transition action - <seealso marker="stdlib:gen_statem#type-event_timeout"> + Generated by <em>transition action</em> + <seealso marker="stdlib:gen_statem#type-timeout_action"> <c>{timeout,Time,EventContent}</c> </seealso> (or its short form <c>Time</c>) - event timer timing out. + event timer timing out. Read more in sections + <seealso marker="#Time-Outs">Time-Outs</seealso> and + <seealso marker="#Event Time-Outs">Event Time-Outs</seealso>. </item> <tag> <seealso marker="stdlib:gen_statem#type-event_type"> @@ -680,10 +723,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </seealso> </tag> <item> - Generated by state transition - <seealso marker="stdlib:gen_statem#type-action">action</seealso> - <c>{next_event,internal,EventContent}</c>. - All event types above can also be generated using + Generated by <em>transition action</em> + <seealso marker="stdlib:gen_statem#type-enter_action"><c>{next_event,internal,EventContent}</c></seealso>. + All <em>event types</em> above can also be generated using + the <c>next_event</c> action: <c>{next_event,EventType,EventContent}</c>. </item> </taglist> @@ -696,14 +739,14 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <title>State Enter Calls</title> <p> The <c>gen_statem</c> behavior can if this is enabled, - regardless of callback mode, + regardless of <em>callback mode</em>, automatically <seealso marker="stdlib:gen_statem#type-state_enter"> call the state callback </seealso> with special arguments whenever the state changes so you can write state enter actions - near the rest of the state transition rules. + near the rest of the <em>state transition</em> rules. It typically looks like this: </p> <pre> @@ -714,36 +757,140 @@ StateName(EventType, EventContent, Data) -> ... code for actions here ... {next_state, NewStateName, NewData}.</pre> <p> - Since the state enter call is not an event there are restrictions + Since the <em>state enter call</em> is not an event there are restrictions on the allowed return value and <seealso marker="#State Transition Actions">State Transition Actions</seealso>. You may not change the state, <seealso marker="#Postponing Events">postpone</seealso> this non-event, or - <seealso marker="#Inserted Events">insert events</seealso>. + <seealso marker="#Inserted Events">insert any events</seealso>. </p> <p> - The first state that is entered will get a state enter call + The first state that is entered + will get a <em>state enter call</em> with <c>OldState</c> equal to the current state. </p> <p> - You may repeat the state enter call using the <c>{repeat_state,...}</c> + You may repeat the <em>state enter call</em> + using the <c>{repeat_state,...}</c> return value from the - <seealso marker="#Event Handler">Event Handler</seealso>. + <seealso marker="#State Callback">state callback</seealso>. In this case <c>OldState</c> will also be equal to the current state. </p> <p> Depending on how your state machine is specified, - this can be a very useful feature, - but it forces you to handle the state enter calls in all states. + this can be a very useful feature, but it forces you to handle + the <em>state enter calls</em> in all states. See also the <seealso marker="#State Enter Actions"> State Enter Actions </seealso> - chapter. + section. + </p> + </section> + +<!-- =================================================================== --> + + <section> + <marker id="Time-Outs" /> + <title>Time-outs</title> + <p> + Time-outs in <c>gen_statem</c> are started from a + <seealso marker="#Transition Actions"> + <em>transition action</em> + </seealso> + during a state transition that is when exiting from the + <seealso marker="#State Callback"><em>state callback</em></seealso>. + </p> + <p> + There are 3 types of time-outs in <c>gen_statem</c>: + </p> + <taglist> + <tag> + <seealso marker="stdlib:gen_statem#type-state_timeout"> + <c>state_timeout</c> + </seealso> + </tag> + <item> + There is one + <seealso marker="#State Time-Outs">State Time-Out</seealso> + that is automatically cancelled by a <em>state change</em>. + </item> + <tag> + <seealso marker="stdlib:gen_statem#type-generic_timeout"> + <c>{timeout, Name}</c> + </seealso> + </tag> + <item> + There are any number of + <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso> + differing by their <c>Name</c>. + They have no automatic cancelling. + </item> + <tag> + <seealso marker="stdlib:gen_statem#type-event_timeout"> + <c>timeout</c> + </seealso> + </tag> + <item> + There is one + <seealso marker="#Event Time-Outs">Event Time-Out</seealso> + that is automatically cancelled by any event. + Note that + <seealso marker="#Postponing Events">postponed </seealso> + and + <seealso marker="#Inserted Events">inserted</seealso> + events cancel this timeout just as external events. + </item> + </taglist> + <p> + When a time-out is started any running time-out with the same tag, + <c>state_timeout</c>, <c>{timeout, Name}</c> or <c>timeout</c>, + is cancelled, that is the time-out is restarted with the new time. + </p> + <p> + All time-outs has got an <c>EventContent</c> that is part of the + <seealso marker="#Transition Actions"> + <em>transition action</em> + </seealso> + that starts the time-out. + Different <c>EventContent</c>s does not create different time-outs. + The <c>EventContent</c> is delivered to the + <seealso marker="#State Callback"><em>state callback</em></seealso> + when the time-out expires. </p> + <section> + <marker id="Cancelling a Time-Out" /> + <title>Cancelling a Time-Out</title> + <p> + If a time-out is started with the time <c>infinity</c> it will + never time out, in fact it will not even be started, and any + running time-out with the same tag will be cancelled. + The <c>EventContent</c> will in this case be ignored, + so why not set it to <c>undefined</c>. + </p> + </section> + <section> + <marker id="Time-Out Zero" /> + <title>Time-Out Zero</title> + <p> + If a time-out is started with the time <c>0</c> it will + actually not be started. Instead the time-out event will + immediately be inserted to be processed after any events + already enqueued, and before any not yet received external events. + Note that some time-outs are automatically cancelled + so if you for example combine + <seealso marker="#Postponing Events">postponing</seealso> + an event in a <em>state change</em> with starting an + <seealso marker="#Event Time-Outs">event time-out</seealso> + with time <c>0</c> there will be no timeout event inserted + since the event time-out is cancelled by the postponed + event that is delivered due to the state change. + </p> + </section> </section> + <!-- =================================================================== --> <section> @@ -765,7 +912,7 @@ StateName(EventType, EventContent, Data) -> </image> <p> This code lock state machine can be implemented using - <c>gen_statem</c> with the following callback module: + <c>gen_statem</c> with the following <em>callback module</em>: </p> <code type="erl"><![CDATA[ -module(code_lock). @@ -868,7 +1015,8 @@ start_link(Code) -> <item> <p> The second argument, <c>?MODULE</c>, is the name of - the callback module, that is, the module where the callback + the <em>callback module</em>, that is, + the module where the callback functions are located, which is this module. </p> <p> @@ -935,7 +1083,7 @@ init(Code) -> <seealso marker="stdlib:gen_statem#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> selects the <seealso marker="#Callback Modes"><c>CallbackMode</c></seealso> - for the callback module, in this case + for the <em>callback module</em>, in this case <seealso marker="stdlib:gen_statem#type-callback_mode"><c>state_functions</c></seealso>. That is, each state has got its own handler function: </p> @@ -1051,11 +1199,11 @@ open(state_timeout, lock, Data) -> ]]></code> <p> The timer for a state time-out is automatically cancelled - when the state machine changes states. You can restart - a state time-out by setting it to a new time, which cancels - the running timer and starts a new. This implies that - you can cancel a state time-out by restarting it with - time <c>infinity</c>. + when the state machine does a <em>state change</em>. + You can restart a state time-out by setting it to a new time, + which cancels the running timer and starts a new. + This implies that you can cancel a state time-out + by restarting it with time <c>infinity</c>. </p> </section> @@ -1137,7 +1285,7 @@ open(...) -> ... ; care about what it is. </p> <p> - If the common event handler needs to know the current state + If the common <em>state callback</em> needs to know the current state a function <c>handle_common/4</c> can be used instead: </p> <code type="erl"><![CDATA[ @@ -1149,12 +1297,12 @@ open(...) -> ... ; <!-- =================================================================== --> <section> - <marker id="One Event Handler" /> - <title>One Event Handler</title> + <marker id="One State Callback" /> + <title>One State Callback</title> <p> If <seealso marker="#Callback Modes"> - Callback Mode + <em>callback mode</em> </seealso> <c>handle_event_function</c> is used, all events are handled in @@ -1289,7 +1437,10 @@ stop() -> You get either an event or a time-out, but not both. </p> <p> - It is ordered by the state transition action + It is ordered by the + <seealso marker="#Transition Actions"> + <em>transition action</em> + </seealso> <c>{timeout,Time,EventContent}</c>, or just an integer <c>Time</c>, even without the enclosing actions list (the latter is a form inherited from <c>gen_fsm</c>. @@ -1315,7 +1466,7 @@ locked( ]]></code> <p> Whenever we receive a button event we start an event time-out - of 30 seconds, and if we get an event type <c>timeout</c> + of 30 seconds, and if we get an <em>event type</em> of <c>timeout</c> we reset the remaining code sequence. </p> <p> @@ -1327,7 +1478,7 @@ locked( </p> <p> Note that an event time-out does not work well with - when you have for example a status call as in + when you have for example a status call as in section <seealso marker="#All State Events">All State Events</seealso>, or handle unknown events, since all kinds of events will cancel the event time-out. @@ -1383,14 +1534,14 @@ open(cast, {button,_}, Data) -> ]]></code> <p> Specific generic time-outs can just as - <seealso marker="#State Time-Outs">State Time-Outs</seealso> + <seealso marker="#State Time-Outs">state time-outs</seealso> be restarted or cancelled by setting it to a new time or <c>infinity</c>. </p> <p> - In this particular case we do not need to cancel the timeout - since the timeout event is the only possible reason to - change the state from <c>open</c> to <c>locked</c>. + In this particular case we do not need to cancel the time-out + since the time-out event is the only possible reason to + do a <em>state change</em> from <c>open</c> to <c>locked</c>. </p> <p> Instead of bothering with when to cancel a time-out, @@ -1410,7 +1561,7 @@ open(cast, {button,_}, Data) -> <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/3,4</c></seealso>. Most time-out tasks can be performed with the time-out features in <c>gen_statem</c>, - but an example of one that can not is if you should need + but an example of one that cannot is if you should need the return value from <seealso marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seealso>, that is; the remaining time of the timer. </p> @@ -1442,7 +1593,7 @@ open(cast, {button,_}, Data) -> ]]></code> <p> Removing the <c>timer</c> key from the map when we - change to state <c>locked</c> is not strictly + do a <em>state change</em> to <c>locked</c> is not strictly necessary since we can only get into state <c>open</c> with an updated <c>timer</c> map value. But it can be nice to not have outdated values in the state <c>Data</c>! @@ -1474,13 +1625,13 @@ open(cast, {button,_}, Data) -> <p> If you want to ignore a particular event in the current state and handle it in a future state, you can postpone the event. - A postponed event is retried after the state has - changed, that is, <c>OldState =/= NewState</c>. + A postponed event is retried after a <em>state change</em>, + that is, <c>OldState =/= NewState</c>. </p> <p> - Postponing is ordered by the state transition - <seealso marker="#State Transition Actions"> - State Transition Action + Postponing is ordered by the + <seealso marker="#Transition Actions"> + <em>transition action</em> </seealso> <c>postpone</c>. </p> @@ -1496,7 +1647,8 @@ open(cast, {button,_}, Data) -> ... ]]></code> <p> - Since a postponed event is only retried after a state change, + Since a postponed event is only retried + after a <em>state change</em>, you have to think about where to keep a state data item. You can keep it in the server <c>Data</c> or in the <c>State</c> itself, @@ -1505,7 +1657,7 @@ open(cast, {button,_}, Data) -> (see section <seealso marker="#Complex State">Complex State</seealso>) with - <seealso marker="#Callback Modes">Callback Mode</seealso> + <seealso marker="#Callback Modes"><em>callback mode</em></seealso> <seealso marker="stdlib:gen_statem#type-callback_mode"><c>handle_event_function</c></seealso>. If a change in the value changes the set of events that is handled, then the value should be kept in the State. @@ -1606,17 +1758,17 @@ do_unlock() -> <seealso marker="stdlib:sys"><c>sys</c></seealso> compatible behaviors must respond to system messages and therefore do that in their engine receive loop, - passing non-system messages to the callback module. + passing non-system messages to the <em>callback module</em>. </p> <p> The - <seealso marker="#State Transition Actions"> - State Transition Action + <seealso marker="#Transition Actions"> + <em>transition action</em> </seealso> <c>postpone</c> is designed to model selective receives. A selective receive implicitly postpones any not received events, but the <c>postpone</c> - state transition action explicitly postpones one received event. + <em>transition action</em> explicitly postpones one received event. </p> <p> Both mechanisms have the same theoretical @@ -1638,14 +1790,17 @@ do_unlock() -> (described in the next section), especially if just one or a few states has got state enter actions, this is a perfect use case for the built in - <seealso marker="#State Enter Calls">State Enter Calls</seealso>. + <seealso marker="#State Enter Calls"><em>state enter calls</em></seealso>. </p> <p> You return a list containing <c>state_enter</c> from your - <seealso marker="stdlib:gen_statem#Module:callback_mode/0"><c>callback_mode/0</c></seealso> + <seealso marker="stdlib:gen_statem#Module:callback_mode/0"> + <c>callback_mode/0</c> + </seealso> function and the <c>gen_statem</c> engine will call your - state callback once with the arguments - <c>(enter, OldState, ...)</c> whenever the state changes. + <em>state callback</em> once with an event + <c>(enter, OldState, ...)</c> + whenever it does a <em>state change</em>. Then you just need to handle these event-like calls in all states. </p> <code type="erl"><![CDATA[ @@ -1700,8 +1855,8 @@ open(state_timeout, lock, Data) -> It can sometimes be beneficial to be able to generate events to your own state machine. This can be done with the - <seealso marker="#State Transition Actions"> - State Transition Action + <seealso marker="#Transition Actions"> + <em>transition action</em> </seealso> <c>{next_event,EventType,EventContent}</c>. </p> @@ -1731,11 +1886,9 @@ open(state_timeout, lock, Data) -> </p> <p> A variant of this is to use a - <seealso marker="#Complex State"> - Complex State - </seealso> + <seealso marker="#Complex State">complex state</seealso> with - <seealso marker="#One Event Handler">One Event Handler</seealso>. + <seealso marker="#One State Callback"><em>one state callback</em></seealso>. The state is then modeled with for example a tuple <c>{MainFSMState,SubFSMState}</c>. </p> @@ -1795,7 +1948,7 @@ open(internal, {button,_}, Data) -> <title>Example Revisited</title> <p> This section includes the example after most of the mentioned - modifications and some more using state enter calls, + modifications and some more using <em>state enter calls</em>, which deserves a new state diagram: </p> <!-- The image is edited with dia in a .dia file, @@ -1920,7 +2073,8 @@ terminate(_Reason, State, _Data) -> This section describes what to change in the example to use one <c>handle_event/4</c> function. The previously used approach to first branch depending on event - does not work that well here because of the state enter calls, + does not work that well here + because of the <em>state enter calls</em>, so this example first branches depending on state: </p> <code type="erl"><![CDATA[ @@ -2059,7 +2213,7 @@ format_status(Opt, [_PDict,State,Data]) -> <marker id="Complex State" /> <title>Complex State</title> <p> - The callback mode + The <em>callback mode</em> <seealso marker="stdlib:gen_statem#type-callback_mode"><c>handle_event_function</c></seealso> enables using a non-atom state as described in section <seealso marker="#Callback Modes">Callback Modes</seealso>, @@ -2068,7 +2222,7 @@ format_status(Opt, [_PDict,State,Data]) -> <p> One reason to use this is when you have a state item that when changed should cancel the - <seealso marker="#State Time-Outs">State Time-Out</seealso>, + <seealso marker="#State Time-Outs">state time-out</seealso>, or one that affects the event handling in combination with postponing events. We will go for the latter and complicate the previous example @@ -2104,7 +2258,7 @@ x so it is not to be recognized as the lock button. Or we can make the lock button part of the state so when we then change the lock button in the locked state, - the change becomes a state change + the change becomes a <em>state change</em> and all postponed events are retried, therefore the lock is immediately locked! </p> @@ -2258,20 +2412,21 @@ handle_event(enter, _OldState, {open,_}, _Data) -> </p> <p> Another not uncommon scenario is to use the - <seealso marker="#Event Time-Outs">Event Time-Out</seealso> + <seealso marker="#Event Time-Outs">event time-out</seealso> to trigger hibernation after a certain time of inactivity. There is also a server start option - <seealso marker="stdlib:gen_statem#type-hibernate_after_opt"> + <seealso marker="stdlib:gen_statem#type-enter_loop_opt"> <c>{hibernate_after, Timeout}</c> </seealso> for - <seealso marker="stdlib:gen_statem#start/3"> - <c>start/3,4</c> - </seealso> - or + <seealso marker="stdlib:gen_statem#start/3"><c>start/3,4</c></seealso>, <seealso marker="stdlib:gen_statem#start_link/3"> <c>start_link/3,4</c> </seealso> + or + <seealso marker="stdlib:gen_statem#enter_loop/4"> + <c>enter_loop/4,5,6</c> + </seealso> that may be used to automatically hibernate the server. </p> <p> diff --git a/system/doc/efficiency_guide/binaryhandling.xml b/system/doc/efficiency_guide/binaryhandling.xml index b500329ef9..d92da17390 100644 --- a/system/doc/efficiency_guide/binaryhandling.xml +++ b/system/doc/efficiency_guide/binaryhandling.xml @@ -384,8 +384,8 @@ export ERL_COMPILER_OPTIONS=bin_opt_info]]></code> <p>The warnings look as follows:</p> <code type="erl"><![CDATA[ -./efficiency_guide.erl:60: Warning: NOT OPTIMIZED: sub binary is used or returned -./efficiency_guide.erl:62: Warning: OPTIMIZED: creation of sub binary delayed]]></code> +./efficiency_guide.erl:60: Warning: NOT OPTIMIZED: binary is returned from the function +./efficiency_guide.erl:62: Warning: OPTIMIZED: match context reused]]></code> <p>To make it clearer exactly what code the warnings refer to, the warnings in the following examples are inserted as comments @@ -393,10 +393,10 @@ export ERL_COMPILER_OPTIONS=bin_opt_info]]></code> <code type="erl"><![CDATA[ after_zero(<<0,T/binary>>) -> - %% NOT OPTIMIZED: sub binary is used or returned + %% BINARY CREATED: binary is returned from the function T; after_zero(<<_,T/binary>>) -> - %% OPTIMIZED: creation of sub binary delayed + %% OPTIMIZED: match context reused after_zero(T); after_zero(<<>>) -> <<>>.]]></code> diff --git a/system/doc/embedded/starting.xml b/system/doc/embedded/starting.xml index 11bf9b412a..6888f9c959 100644 --- a/system/doc/embedded/starting.xml +++ b/system/doc/embedded/starting.xml @@ -231,7 +231,7 @@ exec $BINDIR/erlexec -boot $RELDIR/$VSN/start -config $RELDIR/$VSN/sys $* < <p>If a diskless and/or read-only client node with the SASL configuration parameter <c>static_emulator</c> set to <c>true</c> is about to start the <c>-boot</c> and <c>-config</c> flags must be - changed. As such a client can not read a new <c>start_erl.data</c> + changed. As such a client cannot read a new <c>start_erl.data</c> file (the file is not possible to change dynamically) the boot and config files is always fetched from the same place (but with a new contents if a new release has been installed). The diff --git a/system/doc/general_info/Makefile b/system/doc/general_info/Makefile new file mode 100644 index 0000000000..539075280e --- /dev/null +++ b/system/doc/general_info/Makefile @@ -0,0 +1,99 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1996-2018. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# %CopyrightEnd% +# +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include $(ERL_TOP)/erts/vsn.mk +#VSN=$(SYSTEM_VSN) + +APPLICATION=otp-system-documentation +XMLDIR := $(XMLDIR)/general_info +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = "$(RELEASE_PATH)/doc/general_info" + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_PART_FILES = part.xml + +include xmlfiles.mk + +XML_CHAPTER_FILES=$(GENERAL_INFO_CHAPTER_FILES) + +TOPDOCDIR=.. + +BOOK_FILES = book.xml + +GIF_FILES = + +XML_FILES = \ + $(BOOK_FILES) $(XML_CHAPTER_FILES) \ + $(XML_PART_FILES) + +# ---------------------------------------------------- + +HTMLDIR = ../html/general_info + +HTML_UG_FILE = $(HTMLDIR)/users_guide.html + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- + +docs: html + +local_docs: PDFDIR=../../pdf + +html: $(GIF_FILES) $(HTML_UG_FILE) + +debug opt: + +clean clean_docs: + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs +# $(INSTALL_DIR) "$(RELEASE_PATH)/pdf" +# $(INSTALL_DATA) $(TOP_PDF_FILE) "$(RELEASE_PATH)/pdf" + $(INSTALL_DIR) $(RELSYSDIR) + $(INSTALL_DATA) $(GIF_FILES) $(HTMLDIR)/*.html \ + $(RELSYSDIR) + +release_spec: + diff --git a/system/doc/general_info/book.xml b/system/doc/general_info/book.xml new file mode 100644 index 0000000000..ca9b5fae39 --- /dev/null +++ b/system/doc/general_info/book.xml @@ -0,0 +1,44 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + <header titlestyle="normal"> + <copyright> + <year>2019</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>General Information</title> + <prepared>OTP Team</prepared> + <docno></docno> + <date>2019-02-23</date> + <rev></rev> + <file>book.xml</file> + </header> + <insidecover> + </insidecover> + <pagetext>General Information</pagetext> + <preamble> + <contents level="2"></contents> + </preamble> + <parts lift="no"> + <xi:include href="part.xml"/> + </parts> + <listofterms></listofterms> + <index></index> +</book> + diff --git a/system/doc/general_info/deprecations.xml b/system/doc/general_info/deprecations.xml new file mode 100644 index 0000000000..c748e60059 --- /dev/null +++ b/system/doc/general_info/deprecations.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2019</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>Deprecations</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>deprecations.xml</file> + </header> + <section> + <title>Introduction</title> + <p>This document aim to list all deprecated functionality in Erlang/OTP. It + was introduced as of OTP 22, and have not yet been updated with all old + deprecations. Deprecations made in other parts of the documentation are of + course still valid. For more information regarding the strategy regarding + deprecations see the documentation of + <seealso marker="../system_principles/misc#deprecation">Support, Compatibility, + Deprecations, and Removal</seealso>.</p> + </section> + <section> + <marker id="OTP-22"/> + <title>OTP 22</title> + <section> + <title>VxWorks Support</title> + <p>Some parts of OTP has had limited VxWorks support, such as for + example <seealso marker="erl_interface:index"><c>erl_interface</c></seealso>. + This support is now deprecated and has also been + <seealso marker="scheduled_for_removal#OTP-23">scheduled for removal</seealso>.</p> + </section> + <section> + <title>Legacy parts of erl_interface</title> + <p>The old legacy <seealso marker="erl_interface:index"><c>erl_interface</c></seealso> + library (functions with prefix <c>erl_</c>) is deprecated as of OTP 22. These + parts of <c>erl_interface</c> has been informally deprecated + for a very long time. You typically want to replace the usage of + the <c>erl_interface</c> library with the use of the <c>ei</c> library + which also is part of the <c>erl_interface</c> application. The old legacy + <seealso marker="erl_interface:index"><c>erl_interface</c></seealso> + library has also been <seealso marker="scheduled_for_removal#OTP-23">scheduled + for removal</seealso>.</p> + </section> + <section> + <title>System Events</title> + <p> + The format of "System Events" as defined in the man page for + <seealso marker="stdlib:sys">sys</seealso> + has been clarified and cleaned up. + Due to this, code that relied on the internal badly + documented previous (before this change) format + of OTP's "System Events", needs to be changed. + </p> + <p> + In the wake of this the function + <seealso marker="stdlib:sys#get_debug/3">sys:get_debug/3</seealso> + that returns data with undocumented and internal format + (and therefore is practically useless) has been deprecated, + and a new function + <seealso marker="stdlib:sys#get_log/1">sys:get_log/1</seealso> + has been added, + that hopefully does what the deprecated function was intended for. + </p> + </section> + </section> + <section> + <marker id="OTP-18"/> + <title>OTP 18</title> + <section> + <title>erlang:now()</title> + <p>New time functionality and a new time API was introduced. For more information + see the <seealso marker="erts:time_correction">Time and Time Correction</seealso> + chapter in the ERTS User's guide and specifically the + <seealso marker="erts:time_correction#Dos_and_Donts">Dos and Donts</seealso> + section on how to replace usage of <c>erlang:now()</c>.</p> + </section> + </section> +</chapter> diff --git a/system/doc/general_info/part.xml b/system/doc/general_info/part.xml new file mode 100644 index 0000000000..fead7d58e7 --- /dev/null +++ b/system/doc/general_info/part.xml @@ -0,0 +1,34 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2019</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>General Information</title> + <prepared>OTP Team</prepared> + <docno></docno> + <date>2019-02-23</date> + <rev></rev> + <file>part.xml</file> + </header> + <xi:include href="deprecations.xml"/> + <xi:include href="scheduled_for_removal.xml"/> +</part> diff --git a/system/doc/general_info/scheduled_for_removal.xml b/system/doc/general_info/scheduled_for_removal.xml new file mode 100644 index 0000000000..a9421df385 --- /dev/null +++ b/system/doc/general_info/scheduled_for_removal.xml @@ -0,0 +1,61 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2019</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>Scheduled for Removal</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>scheduled_for_removal.xml</file> + </header> + <section> + <title>Introduction</title> + <p>This document list all functionality in Erlang/OTP that currently are + scheduled for removal. For more information regarding the strategy regarding + removal of functionality see the documentation of + <seealso marker="../system_principles/misc#removal">Support, Compatibility, + Deprecations, and Removal</seealso>.</p> + </section> + <section> + <marker id="OTP-23"/> + <title>OTP 23</title> + <section> + <title>VxWorks Support</title> + <p>Some parts of OTP has had limited VxWorks support, such as for + example <seealso marker="erl_interface:index"><c>erl_interface</c></seealso>. + This support will be removed as of OTP 23. This limited support + was formally deprecated as of OTP 22</p> + </section> + <section> + <title>Legacy parts of erl_interface</title> + <p>The old legacy <seealso marker="erl_interface:index"><c>erl_interface</c></seealso> + library (functions with prefix <c>erl_</c>) will be removed as of + OTP 23. These parts of <c>erl_interface</c> has been informally deprecated + for a very long time, and was formally deprecated in OTP 22. You typically + want to replace the usage of the <c>erl_interface</c> library with the use + of the <c>ei</c> library which also is part of the <c>erl_interface</c> + application.</p> + </section> + </section> +</chapter> diff --git a/system/doc/general_info/xmlfiles.mk b/system/doc/general_info/xmlfiles.mk new file mode 100644 index 0000000000..eab1632a4f --- /dev/null +++ b/system/doc/general_info/xmlfiles.mk @@ -0,0 +1,22 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2009-2018. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# %CopyrightEnd% +# +GENERAL_INFO_CHAPTER_FILES = \ + deprecations.xml \ + scheduled_for_removal.xml diff --git a/system/doc/html/general_info/.gitignore b/system/doc/html/general_info/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/general_info/.gitignore diff --git a/system/doc/oam/oam_intro.xml b/system/doc/oam/oam_intro.xml index ead8c026b9..3d08a5f3b1 100644 --- a/system/doc/oam/oam_intro.xml +++ b/system/doc/oam/oam_intro.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1997</year><year>2017</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -178,7 +178,7 @@ <section> <title>MIB Structure</title> <p>The top-level OTP MIB is called <c>OTP-REG</c> and it is - included in the SASL application. All other OTP MIBs + included in the SNMP application. All other OTP MIBs import some objects from this MIB.</p> <p>Each MIB is contained in one application. The MIB text @@ -186,67 +186,44 @@ the application directory. The generated <c>.hrl</c> files with constant declarations are stored under <c><![CDATA[include/<MIB>.hrl]]></c>, and the compiled MIBs - are stored under <c><![CDATA[priv/mibs/<MIB>.bin]]></c>. - For example, the <c>OTP-MIB</c> is included in the - SASL application:</p> + are stored under <c><![CDATA[priv/mibs/<MIB>.bin]]></c>. </p> - <code type="none"> -sasl-1.3/mibs/OTP-MIB.mib -include/OTP-MIB.hrl -priv/mibs/OTP-MIB.bin</code> - - <p>An application that needs to import this MIB into another + <p>An application that needs to import an MIB into another MIB is to use the <c>il</c> option to the SNMP MIB compiler:</p> <code type="none"> -snmp:c("MY-MIB", [{il, ["sasl/priv/mibs"]}]).</code> +snmp:c("MY-MIB", [{il, ["snmp/priv/mibs"]}]).</code> - <p>If the application needs to include the generated + <p>If the application needs to include a generated <c>.hrl</c> file, it is to use the <c>-include_lib</c> directive to the Erlang compiler:</p> <code type="none"> -module(my_mib). --include_lib("sasl/include/OTP-MIB.hrl").</code> +-include_lib("snmp/include/OTP-REG.hrl").</code> - <p>The following MIBs are defined in the OTP system:</p> + <p>Here is a list of some of the MIBs defined in the OTP system:</p> <list type="bulleted"> - <item><p><c>OTP-REG</c> (in SASL) contains the top-level + <item><p><c>OTP-REG</c> (in SNMP) contains the top-level OTP registration objects, used by all other MIBs.</p></item> - <item><p><c>OTP-TC</c> (in SASL) contains the general + <item><p><c>OTP-TC</c> (in SNMP) contains the general Textual Conventions, which can be used by any other MIB.</p></item> - <item><p><c>OTP-MIB</c> (in SASL) contains objects for - instrumentation of the Erlang nodes, the Erlang machines, - and the applications in the system.</p></item> - <item><p><c>OTP-OS-MON-MIB</c> (in <c>oc_mon</c>) contains - objects for instrumentation of disk, memory, and CPU use - of the nodes in the system.</p></item> <item><p><c>OTP-SNMPEA-MIB</c> (in <c>snmp</c>) contains objects for instrumentation and control of the extensible SNMP agent itself. The agent also implements the standard SNMPv2-MIB (or v1 part of MIB-II, if SNMPv1 is used).</p></item> - <item><p><c>OTP-EVA-MIB</c> (in <c>eva</c>) contains objects - for instrumentation and control of the events and alarms in - the system.</p></item> - <item><p><c>OTP-LOG-MIB</c> (in <c>eva</c>) contains objects - for instrumentation and control of the logs and FTP transfer of - logs.</p></item> - <item><p><c>OTP-EVA-LOG-MIB</c> (in <c>eva</c>) contains objects - for instrumentation and control of the events and alarm logs - in the system.</p></item> - <item><p><c>OTP-SNMPEA-LOG-MIB</c> (in <c>eva</c>) contains - objects for instrumentation and control of the SNMP audit - trail log in the system.</p></item> </list> <p>The different applications use different strategies for loading the MIBs into the agent. Some MIB implementations are code-only, while others need a server. One way, used by the code-only MIB implementations, is for the user to call a - function such as <c>otp_mib:load(Agent)</c> to load the MIB, - and <c>otp_mib:unload(Agent)</c> to unload the MIB. See the - manual page for each application for a description of how - to load each MIB.</p> + function such as + <c>snmpa:unload_mibs(Agent, [Mib])</c> + to load the MIB, and + <c>snmpa:unload_mibs(Agent, [Mib])</c> + to unload the MIB. See the manual page for each application for + a description of how to load each MIB.</p> </section> </section> </chapter> diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index 76b3e92937..8c47070890 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -578,6 +578,7 @@ number < atom < reference < fun < port < pid < tuple < map ascending term order and then by values in key order. In maps key order integers types are considered less than floats types. </p> + <p>Atoms are compared using their string value, codepoint by codepoint.</p> <p>When comparing an integer to a float, the term with the lesser precision is converted into the type of the other term, unless the operator is one of <c>=:=</c> or <c>=/=</c>. A float is more precise than diff --git a/system/doc/system_principles/misc.xml b/system/doc/system_principles/misc.xml index dd6c2a1336..ed3675d180 100644 --- a/system/doc/system_principles/misc.xml +++ b/system/doc/system_principles/misc.xml @@ -34,6 +34,14 @@ </header> <section> + <title>Introduction</title> + <p>This document describes strategy regarding supported Releases, + compatibility, deprecations and removal of functionality. This + document was introduced in OTP 21. Actions taken regarding these + issues before OTP 21 did not adhere this document.</p> + </section> + + <section> <marker id="supported_releases"/> <title>Supported Releases</title> <p> diff --git a/system/doc/top/Makefile b/system/doc/top/Makefile index 3267bf96df..e3f9c4710a 100644 --- a/system/doc/top/Makefile +++ b/system/doc/top/Makefile @@ -39,6 +39,7 @@ INFO_FILES = ../../../README.md ../../COPYRIGHT PR.template TOPDOCDIR=. +include ../general_info/xmlfiles.mk include ../installation_guide/xmlfiles.mk include ../system_principles/xmlfiles.mk include ../embedded/xmlfiles.mk @@ -56,6 +57,7 @@ XML_FILES = \ $(BOOK_FILES) XML_GUIDE_FILES = \ + $(GENERAL_INFO_CHAPTER_FILES:%=general_info/%) \ $(INST_GUIDE_CHAPTER_FILES:%=installation_guide/%) \ $(INST_GUIDE_CHAPTER_GEN_FILES:%=installation_guide/%) \ $(SYSTEM_PRINCIPLES_CHAPTER_FILES:%=system_principles/%) \ @@ -79,6 +81,7 @@ XML_GUIDE_FILES = \ XML_GEN_FILES = \ $(XML_GUIDE_FILES:%=$(XMLDIR)/%) \ + $(XMLDIR)/general_info/part.xml \ $(XMLDIR)/installation_guide/part.xml \ $(XMLDIR)/system_principles/part.xml \ $(XMLDIR)/embedded/part.xml \ @@ -91,7 +94,7 @@ XML_GEN_FILES = \ $(XMLDIR)/oam/part.xml -XMLLINT_SRCDIRS= $(XMLDIR)/installation_guide:$(XMLDIR)/system_principles:$(XMLDIR)/embedded:$(XMLDIR)/getting_started:$(XMLDIR)/reference_manual:$(XMLDIR)/programming_examples:$(XMLDIR)/efficiency_guide:$(XMLDIR)/tutorial:$(XMLDIR)/design_principles:$(XMLDIR)/oam +XMLLINT_SRCDIRS= $(XMLDIR)/general_info:$(XMLDIR)/installation_guide:$(XMLDIR)/system_principles:$(XMLDIR)/embedded:$(XMLDIR)/getting_started:$(XMLDIR)/reference_manual:$(XMLDIR)/programming_examples:$(XMLDIR)/efficiency_guide:$(XMLDIR)/tutorial:$(XMLDIR)/design_principles:$(XMLDIR)/oam HTMLDIR= ../html PDFREFDIR= pdf diff --git a/system/doc/top/book.xml b/system/doc/top/book.xml index 61e75591ef..64c1e4caf6 100644 --- a/system/doc/top/book.xml +++ b/system/doc/top/book.xml @@ -36,6 +36,7 @@ <contents level="2"></contents> </preamble> <parts lift="no"> + <xi:include href="../xml/general_info/part.xml"/> <xi:include href="../xml/installation_guide/part.xml"/> <xi:include href="../xml/system_principles/part.xml"/> <xi:include href="../xml/embedded/part.xml"/> diff --git a/system/doc/top/templates/index.html.src b/system/doc/top/templates/index.html.src index 747d19cf7e..3b61052b99 100644 --- a/system/doc/top/templates/index.html.src +++ b/system/doc/top/templates/index.html.src @@ -41,6 +41,8 @@ limitations under the License. <ul class="section-links"> <li><a href="applications.html">Applications</a></li> <li><a href="man_index.html" class="modules">Modules</a></li> + <li><a href="general_info/deprecations.html" class="modules">Deprecations</a></li> + <li><a href="general_info/scheduled_for_removal.html" class="modules">Scheduled for Removal</a></li> </ul> <ul class="expand-collapse-items"> diff --git a/system/doc/xml/general_info/.gitignore b/system/doc/xml/general_info/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/general_info/.gitignore |