diff options
Diffstat (limited to 'system/doc')
65 files changed, 940 insertions, 399 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/Makefile b/system/doc/design_principles/Makefile index 41d2d1208f..2fbd7d087f 100644 --- a/system/doc/design_principles/Makefile +++ b/system/doc/design_principles/Makefile @@ -88,7 +88,6 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) $(HTMLDIR)/%.gif: %.gif $(INSTALL_DATA) $< $@ @@ -107,7 +106,8 @@ images: $(IMAGE_FILES:%=$(HTMLDIR)/%) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ 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/des_princ.xml b/system/doc/design_principles/des_princ.xml index e21f2a7f4e..2bfb8eb3c7 100644 --- a/system/doc/design_principles/des_princ.xml +++ b/system/doc/design_principles/des_princ.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> @@ -64,7 +64,7 @@ the supervisors are similar in structure. The only difference between them is which child processes they supervise. Many of the workers are servers in a server-client relation, - finite-state machines, or event handlers such as error loggers.</p> + finite-state machines, or event handlers.</p> <p><em>Behaviours</em> are formalizations of these common patterns. The idea is to divide the code for a process in a generic part (a behaviour module) and a specific part (a diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index 80ee9c992f..23e9054547 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,39 +757,143 @@ 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>. + <seealso marker="#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> <marker id="Example" /> <title>Example</title> <p> @@ -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> @@ -956,14 +1104,14 @@ callback_mode() -> <seealso marker="stdlib:gen_statem#cast/2"><c>gen_statem:cast/2</c></seealso>: </p> <code type="erl"><![CDATA[ -button(Digit) -> - gen_statem:cast(?NAME, {button,Digit}). +button(Button) -> + gen_statem:cast(?NAME, {button,Button}). ]]></code> <p> The first argument is the name of the <c>gen_statem</c> and must agree with the name used to start it. So, we use the same macro <c>?NAME</c> as when starting. - <c>{button,Digit}</c> is the event content. + <c>{button,Button}</c> is the event content. </p> <p> The event is sent to the <c>gen_statem</c>. @@ -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 @@ -1171,7 +1319,7 @@ open(...) -> ... ; callback_mode() -> handle_event_function. -handle_event(cast, {button,Digit}, State, #{code := Code} = Data) -> +handle_event(cast, {button,Button}, State, #{code := Code} = Data) -> case State of locked -> #{length := Length, buttons := Buttons} = Data, @@ -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>. @@ -1305,7 +1456,7 @@ stop() -> locked(timeout, _, Data) -> {next_state, locked, Data#{buttons := []}}; locked( - cast, {button,Digit}, + cast, {button,Button}, #{code := Code, length := Length, buttons := Buttons} = Data) -> ... true -> % Incomplete | Incorrect @@ -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. @@ -1364,7 +1515,7 @@ locked( <code type="erl"><![CDATA[ ... locked( - cast, {button,Digit}, + cast, {button,Button}, #{code := Code, length := Length, buttons := Buttons} = Data) -> ... if @@ -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> @@ -1421,7 +1572,7 @@ open(cast, {button,_}, Data) -> <code type="erl"><![CDATA[ ... locked( - cast, {button,Digit}, + cast, {button,Button}, #{code := Code, length := Length, buttons := Buttons} = Data) -> ... if @@ -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[ @@ -1662,7 +1817,7 @@ locked(enter, _OldState, Data) -> do_lock(), {keep_state,Data#{buttons => []}}; locked( - cast, {button,Digit}, + cast, {button,Button}, #{code := Code, length := Length, buttons := Buttons} = Data) -> ... if @@ -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> @@ -1747,7 +1900,7 @@ open(state_timeout, lock, Data) -> </p> <code type="erl"><![CDATA[ ... --export(down/1, up/1). +-export([down/1, up/1]). ... down(Button) -> gen_statem:cast(?NAME, {down,Button}). @@ -1759,15 +1912,15 @@ up(Button) -> locked(enter, _OldState, Data) -> do_lock(), - {keep_state,Data#{remaining => Code, buf => []}}; + {keep_state,Data#{buttons => []}}; locked( - internal, {button,Digit}, + internal, {button,Button}, #{code := Code, length := Length, buttons := Buttons} = Data) -> ... ]]></code> <code type="erl"><![CDATA[ handle_common(cast, {down,Button}, Data) -> - {keep_state, Data#{button := Button}}; + {keep_state, Data#{button => Button}}; handle_common(cast, {up,Button}, Data) -> case Data of #{button := Button} -> @@ -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, @@ -1833,10 +1986,10 @@ start_link(Code) -> stop() -> gen_statem:stop(?NAME). -down(Digit) -> - gen_statem:cast(?NAME, {down,Digit}). -up(Digit) -> - gen_statem:cast(?NAME, {up,Digit}). +down(Button) -> + gen_statem:cast(?NAME, {down,Button}). +up(Button) -> + gen_statem:cast(?NAME, {up,Button}). code_length() -> gen_statem:call(?NAME, code_length). ]]></code> @@ -1873,7 +2026,7 @@ locked(enter, _OldState, Data) -> locked(state_timeout, button, Data) -> {keep_state, Data#{buttons := []}}; locked( - internal, {button,Digit}, + internal, {button,Button}, #{code := Code, length := Length, buttons := Buttons} = Data) -> NewButtons = if @@ -1884,7 +2037,6 @@ locked( end ++ [Button], if NewButtons =:= Code -> % Correct - do_unlock(), {next_state, open, Data}; true -> % Incomplete | Incorrect {keep_state, Data#{buttons := NewButtons}, @@ -1921,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[ @@ -1940,7 +2093,7 @@ handle_event(enter, _OldState, locked, Data) -> handle_event(state_timeout, button, locked, Data) -> {keep_state, Data#{buttons := []}}; handle_event( - internal, {button,Digit}, locked, + internal, {button,Button}, locked, #{code := Code, length := Length, buttons := Buttons} = Data) -> NewButtons = if @@ -1951,7 +2104,6 @@ handle_event( end ++ [Button], if NewButtons =:= Code -> % Correct - do_unlock(), {next_state, open, Data}; true -> % Incomplete | Incorrect {keep_state, Data#{buttons := NewButtons}, @@ -2061,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>, @@ -2070,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 @@ -2106,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> @@ -2152,7 +2304,7 @@ handle_event(enter, _OldState, {locked,_}, Data) -> handle_event(state_timeout, button, {locked,_}, Data) -> {keep_state, Data#{buttons := []}}; handle_event( - cast, {button,Digit}, {locked,LockButton}, + cast, {button,Button}, {locked,LockButton}, #{code := Code, length := Length, buttons := Buttons} = Data) -> NewButtons = if @@ -2163,7 +2315,6 @@ handle_event( end ++ [Button], if NewButtons =:= Code -> % Correct - do_unlock(), {next_state, {open,LockButton}, Data}; true -> % Incomplete | Incorrect {keep_state, Data#{buttons := NewButtons}, @@ -2177,11 +2328,11 @@ handle_event(enter, _OldState, {open,_}, _Data) -> do_unlock(), {keep_state_and_data, [{state_timeout,10000,lock}]}; % Time in milliseconds -handle_event(state_timeout, lock, {open,_}, Data) -> - {next_state, locked, Data}; +handle_event(state_timeout, lock, {open,LockButton}, Data) -> + {next_state, {locked,LockButton}, Data}; handle_event(cast, {button,LockButton}, {open,LockButton}, Data) -> {next_state, {locked,LockButton}, Data}; -handle_event(cast, {button,_}, {open,_}, Data) -> +handle_event(cast, {button,_}, {open,_}, _Data) -> {keep_state_and_data,[postpone]}; ]]></code> <code type="erl"><![CDATA[ @@ -2261,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/design_principles/sup_princ.xml b/system/doc/design_principles/sup_princ.xml index 06ca44a9f6..321fa41e8d 100644 --- a/system/doc/design_principles/sup_princ.xml +++ b/system/doc/design_principles/sup_princ.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> @@ -312,12 +312,17 @@ child_spec() = #{id => child_id(), % mandatory signal back. If no exit signal is received within the specified time, the child process is unconditionally terminated using <c>exit(Child, kill)</c>.</item> - <item>If the child process is another supervisor, it is to be + <item>If the child process is another supervisor, it must be set to <c>infinity</c> to give the subtree enough time to shut down. It is also allowed to set it to <c>infinity</c>, - if the child process is a worker. See the warning below:</item> + if the child process is a worker. See the warning below:</item> </list> <warning> + <p>Setting the shutdown time to anything other + than <c>infinity</c> for a child of type <c>supervisor</c> + can cause a race condition where the child in question + unlinks its own children, but fails to terminate them + before it is killed.</p> <p>Be careful when setting the shutdown time to <c>infinity</c> when the child process is a worker. Because, in this situation, the termination of the supervision tree depends on the diff --git a/system/doc/efficiency_guide/Makefile b/system/doc/efficiency_guide/Makefile index f6ad638853..a2742a1354 100644 --- a/system/doc/efficiency_guide/Makefile +++ b/system/doc/efficiency_guide/Makefile @@ -87,7 +87,6 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) docs: html @@ -98,7 +97,8 @@ html: $(GIF_FILES) $(HTML_UG_FILE) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ 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/efficiency_guide/commoncaveats.xml b/system/doc/efficiency_guide/commoncaveats.xml index b41ffc3902..7b2128d888 100644 --- a/system/doc/efficiency_guide/commoncaveats.xml +++ b/system/doc/efficiency_guide/commoncaveats.xml @@ -36,10 +36,9 @@ <title>Timer Module</title> <p>Creating timers using <seealso - marker="erts:erlang#erlang:send_after/3">erlang:send_after/3</seealso> + marker="erts:erlang#send_after/3">erlang:send_after/3</seealso> and - <seealso marker="erts:erlang#erlang:start_timer/3">erlang:start_timer/3</seealso> -, + <seealso marker="erts:erlang#start_timer/3">erlang:start_timer/3</seealso>, is much more efficient than using the timers provided by the <seealso marker="stdlib:timer">timer</seealso> module in STDLIB. The <c>timer</c> module uses a separate process to manage the timers. @@ -169,53 +168,5 @@ multiple_setelement(T0) -> {Bin1,Bin2} = split_binary(Bin, Num)</code> </section> - <section> - <title>Operator "--"</title> - <p>The "<c>--</c>" operator has a complexity - proportional to the product of the length of its operands. - This means that the operator is very slow if both of its operands - are long lists:</p> - - <p><em>DO NOT</em></p> - <code type="none"><![CDATA[ - HugeList1 -- HugeList2]]></code> - - <p>Instead use the <seealso marker="stdlib:ordsets">ordsets</seealso> - module in STDLIB:</p> - - <p><em>DO</em></p> - <code type="none"> - HugeSet1 = ordsets:from_list(HugeList1), - HugeSet2 = ordsets:from_list(HugeList2), - ordsets:subtract(HugeSet1, HugeSet2)</code> - - <p>Obviously, that code does not work if the original order - of the list is important. If the order of the list must be - preserved, do as follows:</p> - - <p><em>DO</em></p> - <code type="none"><![CDATA[ - Set = gb_sets:from_list(HugeList2), - [E || E <- HugeList1, not gb_sets:is_element(E, Set)]]]></code> - - <note><p>This code behaves differently from "<c>--</c>" - if the lists contain duplicate elements (one occurrence - of an element in HugeList2 removes <em>all</em> - occurrences in HugeList1.)</p> - <p>Also, this code compares lists elements using the - "<c>==</c>" operator, while "<c>--</c>" uses the "<c>=:=</c>" operator. - If that difference is important, <c>sets</c> can be used instead of - <c>gb_sets</c>, but <c>sets:from_list/1</c> is much - slower than <c>gb_sets:from_list/1</c> for long lists.</p></note> - - <p>Using the "<c>--</c>" operator to delete an element - from a list is not a performance problem:</p> - - <p><em>OK</em></p> - <code type="none"> - HugeList1 -- [Element]</code> - - </section> - </chapter> diff --git a/system/doc/efficiency_guide/profiling.xml b/system/doc/efficiency_guide/profiling.xml index cdc80289cf..5ec1f1be6e 100644 --- a/system/doc/efficiency_guide/profiling.xml +++ b/system/doc/efficiency_guide/profiling.xml @@ -94,7 +94,7 @@ <p>The above slogan is one of the more common reasons for Erlang to terminate. For unknown reasons the Erlang Run-Time System failed to allocate memory to use. When this happens a crash dump is generated that contains information - about the state of the system as it ran out of mmeory. Use the + about the state of the system as it ran out of memory. Use the <seealso marker="observer:cdv"><c>crashdump_viewer</c></seealso> to get a view of the memory is being used. Look for processes with large heaps or many messages, large ets tables, etc.</p> diff --git a/system/doc/efficiency_guide/retired_myths.xml b/system/doc/efficiency_guide/retired_myths.xml index 9b914a3b6e..144c942c2b 100644 --- a/system/doc/efficiency_guide/retired_myths.xml +++ b/system/doc/efficiency_guide/retired_myths.xml @@ -60,4 +60,18 @@ That leads us to the myth that tail-recursive functions are faster than body-recursive functions.</p> </section> + + <section> + <title>Myth: List subtraction ("--" operator) is slow</title> + + <p>List subtraction used to have a run-time complexity proportional to the + product of the length of its operands, so it was extremely slow when both + lists were long.</p> + + <p>As of OTP 22 the run-time complexity is "n log n" and the operation will + complete quickly even when both lists are very long. In fact, it is + faster and uses less memory than the commonly used workaround to convert + both lists to ordered sets before subtracting them with + <c>ordsets:subtract/2</c>.</p> + </section> </chapter> diff --git a/system/doc/embedded/Makefile b/system/doc/embedded/Makefile index 2b09c5b852..1604075312 100644 --- a/system/doc/embedded/Makefile +++ b/system/doc/embedded/Makefile @@ -75,7 +75,6 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) docs: html @@ -86,7 +85,8 @@ html: $(GIF_FILES) $(HTML_UG_FILE) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ 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/getting_started/Makefile b/system/doc/getting_started/Makefile index 7b90fe1337..1c917895d5 100644 --- a/system/doc/getting_started/Makefile +++ b/system/doc/getting_started/Makefile @@ -74,7 +74,6 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) docs: html @@ -85,7 +84,8 @@ html: $(GIF_FILES) $(HTML_UG_FILE) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ diff --git a/system/doc/html/design_principles/.gitignore b/system/doc/html/design_principles/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/design_principles/.gitignore diff --git a/system/doc/html/efficiency_guide/.gitignore b/system/doc/html/efficiency_guide/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/efficiency_guide/.gitignore diff --git a/system/doc/html/embedded/.gitignore b/system/doc/html/embedded/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/embedded/.gitignore 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/html/getting_started/.gitignore b/system/doc/html/getting_started/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/getting_started/.gitignore diff --git a/system/doc/html/installation_guide/.gitignore b/system/doc/html/installation_guide/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/installation_guide/.gitignore diff --git a/system/doc/html/installation_guide/source/.gitignore b/system/doc/html/installation_guide/source/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/installation_guide/source/.gitignore diff --git a/system/doc/html/js/.gitignore b/system/doc/html/js/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/js/.gitignore diff --git a/system/doc/html/oam/.gitignore b/system/doc/html/oam/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/oam/.gitignore diff --git a/system/doc/html/programming_examples/.gitignore b/system/doc/html/programming_examples/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/programming_examples/.gitignore diff --git a/system/doc/html/reference_manual/.gitignore b/system/doc/html/reference_manual/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/reference_manual/.gitignore diff --git a/system/doc/html/system_architecture_intro/.gitignore b/system/doc/html/system_architecture_intro/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/system_architecture_intro/.gitignore diff --git a/system/doc/html/system_principles/.gitignore b/system/doc/html/system_principles/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/system_principles/.gitignore diff --git a/system/doc/html/tutorial/.gitignore b/system/doc/html/tutorial/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/html/tutorial/.gitignore diff --git a/system/doc/installation_guide/Makefile b/system/doc/installation_guide/Makefile index 91e7cb2772..c5234c1c9a 100644 --- a/system/doc/installation_guide/Makefile +++ b/system/doc/installation_guide/Makefile @@ -91,7 +91,6 @@ $(XMLDIR)/%.xml: $(ERL_TOP)/HOWTO/%.md $(ERL_TOP)/make/emd2exml $(ERL_TOP)/make/emd2exml $< $@ $(REDIRECT_HTML_DIR)/%.html: Makefile - test -d $(REDIRECT_HTML_DIR) || $(INSTALL_DIR) $(REDIRECT_HTML_DIR) echo "<html><head><meta HTTP-EQUIV=\"REFRESH\"" > $@ echo " content=\"5; url=../"$(notdir $@)"\">" >> $@ echo "<title>This page has moved</title></head><body>" >> $@ @@ -112,6 +111,9 @@ debug opt: clean clean_docs: rm -f $(GENERATED_XML_FILES) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html + rm -f $(XML_GEN_FILES) rm -rf $(HTMLDIR) rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ diff --git a/system/doc/oam/Makefile b/system/doc/oam/Makefile index b09ae1aed2..2eb429e04d 100644 --- a/system/doc/oam/Makefile +++ b/system/doc/oam/Makefile @@ -71,10 +71,9 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) $(HTMLDIR)/%.gif: %.gif - $(INSTALL_DATA) $< $@ + $(CP) $< $@ docs: html @@ -87,7 +86,8 @@ gifs: $(GIF_FILES:%=$(HTMLDIR)/%) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ 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/programming_examples/Makefile b/system/doc/programming_examples/Makefile index 2d04e8b5e2..9c67c24b64 100644 --- a/system/doc/programming_examples/Makefile +++ b/system/doc/programming_examples/Makefile @@ -74,7 +74,6 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) docs: html local_docs: PDFDIR=../../pdf @@ -84,7 +83,8 @@ html: $(GIF_FILES) $(HTML_UG_FILE) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ diff --git a/system/doc/reference_manual/Makefile b/system/doc/reference_manual/Makefile index 02a7f002ed..809eb2c979 100644 --- a/system/doc/reference_manual/Makefile +++ b/system/doc/reference_manual/Makefile @@ -84,7 +84,6 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) docs: html @@ -95,7 +94,8 @@ html: $(GIF_FILES) $(HTML_UG_FILE) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index 94e40dd077..ea3b2159fc 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2017</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -567,6 +567,10 @@ Expr1 <input>op</input> Expr2</pre> order is defined:</p> <pre> number < atom < reference < fun < port < pid < tuple < map < nil < list < bit string</pre> + <p><c>nil</c> in the previous expression represents the empty list + (<c>[]</c>), which is regarded as a separate type from + <c>list/0</c>. That is why <c>nil < list</c>. + </p> <p>Lists are compared element by element. Tuples are ordered by size, two tuples with the same size are compared element by element.</p> @@ -574,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 @@ -1216,10 +1221,10 @@ Ei = Value | <<1,17,0,42>> 10> <input>H.</input> <<17,0,42>> -11> <input><<G,H/bitstring>> = <<1,17,42:12>>.</input> -<<1,17,1,10:4>> -12> <input>H.</input> -<<17,1,10:4>> +11> <input><<G,J/bitstring>> = <<1,17,42:12>>.</input> +<<1,17,2,10:4>> +12> <input>J.</input> +<<17,2,10:4>> 13> <input><<1024/utf8>>.</input> <<208,128>> </pre> diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml index f6a19397c3..27cd0ba83d 100644 --- a/system/doc/reference_manual/typespec.xml +++ b/system/doc/reference_manual/typespec.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2017</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -113,8 +113,8 @@ | Erlang_Atom %% 'foo', 'bar', ... Bitstring :: <<>> - | <<_:M>> %% M is a positive integer - | <<_:_*N>> %% N is a positive integer + | <<_:M>> %% M is an Integer_Value that evaluates to a positive integer + | <<_:_*N>> %% N is an Integer_Value that evaluates to a positive integer | <<_:M, _:_*N>> Fun :: fun() %% any function @@ -123,8 +123,17 @@ | fun((TList) -> Type) Integer :: integer() - | Erlang_Integer %% ..., -1, 0, 1, ... 42 ... - | Erlang_Integer..Erlang_Integer %% specifies an integer range + | Integer_Value + | Integer_Value..Integer_Value %% specifies an integer range + + Integer_Value :: Erlang_Integer %% ..., -1, 0, 1, ... 42 ... + | Erlang_Character %% $a, $b ... + | Integer_Value BinaryOp Integer_Value + | UnaryOp Integer_Value + + BinaryOp :: '*' | 'div' | 'rem' | 'band' | '+' | '-' | 'bor' | 'bxor' | 'bsl' | 'bsr' + + UnaryOp :: '+' | '-' | 'bnot' List :: list(Type) %% Proper list ([]-terminated) | maybe_improper_list(Type1, Type2) %% Type1=contents, Type2=termination @@ -151,8 +160,13 @@ Union :: Type1 | Type2 ]]></pre> <p> + Integer values are either integer or character literals or expressions + consisting of possibily nested unary or binary operations that evaluate to + an integer. Such expressions can also be used in bit strings and ranges. + </p> + <p> The general form of bit strings is <c><<_:M, _:_*N>></c>, - where <c>M</c> and <c>N</c> are positive integers. It denotes a + where <c>M</c> and <c>N</c> must evaluate to positive integers. It denotes a bit string that is <c>M + (k*N)</c> bits long (that is, a bit string that starts with <c>M</c> bits and continues with <c>k</c> segments of <c>N</c> bits each, where <c>k</c> is also a positive integer). diff --git a/system/doc/system_architecture_intro/Makefile b/system/doc/system_architecture_intro/Makefile index ebfcc3a1c8..ea9ee85105 100644 --- a/system/doc/system_architecture_intro/Makefile +++ b/system/doc/system_architecture_intro/Makefile @@ -69,7 +69,6 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) docs: html @@ -80,7 +79,8 @@ html: $(GIF_FILES) $(HTML_UG_FILE) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ diff --git a/system/doc/system_principles/Makefile b/system/doc/system_principles/Makefile index bb74125f3a..5110b73373 100644 --- a/system/doc/system_principles/Makefile +++ b/system/doc/system_principles/Makefile @@ -70,7 +70,6 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) docs: html @@ -81,7 +80,8 @@ html: $(GIF_FILES) $(HTML_UG_FILE) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ diff --git a/system/doc/system_principles/create_target.xmlsrc b/system/doc/system_principles/create_target.xmlsrc index 47b84e5760..ea0d938936 100644 --- a/system/doc/system_principles/create_target.xmlsrc +++ b/system/doc/system_principles/create_target.xmlsrc @@ -352,7 +352,7 @@ fi START_ERL_DATA=${1:-$RELDIR/start_erl.data} $ROOTDIR/bin/run_erl -daemon /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl $ROOTDIR\ -$RELDIR $START_ERL_DATA -heart</code> +$RELDIR $START_ERL_DATA -heart"</code> <p>We use the simplest possible <c>sys.config</c>, which we store in <c>releases/FIRST</c>:</p> <code type="none"> 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/system_principles/versions.xml b/system/doc/system_principles/versions.xml index 11dc9d5637..fbdcc6b2b0 100644 --- a/system/doc/system_principles/versions.xml +++ b/system/doc/system_principles/versions.xml @@ -181,7 +181,7 @@ goes for application versions.</p> <p>In general, versions can have more than three parts. The versions are then only partially ordered. Such - versions are only used in exceptional cases. When an extra + versions are only used when branching off from another branch. When an extra part (out of the normal three parts) is added to a version number, a new branch of versions is made. The new branch has a linear order against the base version. However, versions on different @@ -240,6 +240,33 @@ </section> <section> + <marker id="otp_versions_tree"/> + <title>OTP Versions Tree</title> + <p> + All released OTP versions can be found in the + <url href="http://www.erlang.org/download/otp_versions_tree.html">OTP + Versions Tree</url> which is automatically updated whenever + we release a new OTP version. Note that every version number as + such explicitly define its position in the version tree. Nothing + more than the version numbers are needed in order to construct + the tree. The root of the tree is OTP version 17.0 which is when + we introduced the new + <seealso marker="#version_scheme">version scheme</seealso>. The + green versions are normal versions released on the main track. + Old <seealso marker="#releases_and_patches">OTP releases</seealso> + will be maintained for a while on <c>maint</c> branches that have + branched off from the main track. Old <c>maint</c> branches always + branch off from the main track when the next OTP release is + introduced into the main track. Versions on these old <c>maint</c> + branches are marked blue. Besides the green and blue versions, + there are also gray versions. These are versions on branches + introduced in order to fix a specific problem for a specific + customer on a specific base version. Branches with gray versions + will typically become dead ends very quickly if not immediately. + </p> + </section> + + <section> <marker id="otp_17_0_app_versions"/> <title>OTP 17.0 Application Versions</title> <p>The following list details the application versions that diff --git a/system/doc/top/Makefile b/system/doc/top/Makefile index 0703b821f1..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,13 +94,32 @@ 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 TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf TOPDOC=true +ifdef RELEASE_PATH +INST_TYPE=rel +INST_TYPE_SRC_DIR=$(RELEASE_PATH) +# We build to the 'temporary' dir in order to be able to install +# results using INSTALL_DATA (in order to get correct access +# rights on installed files) +INST_TYPE_DEST_DIR=$(RELSYSDIR)/temporary +INST_TYPE_DEST_DIR_DEP=$(INST_TYPE_DEST_DIR) +INST_TYPE_JS_DEST_DIR=$(INST_TYPE_DEST_DIR) +INST_TYPE_VSN_FILE=$(INST_TYPE_DEST_DIR)/OTP_VERSION +else +INST_TYPE=src +INST_TYPE_SRC_DIR=$(ERL_TOP) +INST_TYPE_DEST_DIR=$(HTMLDIR) +INST_TYPE_DEST_DIR_DEP= +INST_TYPE_JS_DEST_DIR=$(INST_TYPE_DEST_DIR)/js +INST_TYPE_VSN_FILE=$(ERL_TOP)/OTP_VERSION +endif + #-------------------------------------------------------------------------- # We generate the index page from the installed system. This make # it important that this is done last. The file index.html.src @@ -107,17 +129,18 @@ EBIN = ebin INDEX_SCRIPT = $(EBIN)/erl_html_tools.$(EMULATOR) INDEX_SRC = src/erl_html_tools.erl -INDEX_FILES = \ - $(HTMLDIR)/index.html \ - $(HTMLDIR)/applications.html -JAVASCRIPT = $(HTMLDIR)/js/erlresolvelinks.js +INDEX_HTML=$(INST_TYPE_DEST_DIR)/index.html +APPLICATIONS_HTML=$(INST_TYPE_DEST_DIR)/applications.html +INDEX_FILES = $(INDEX_HTML) $(APPLICATIONS_HTML) + +JAVASCRIPT = $(INST_TYPE_JS_DEST_DIR)/erlresolvelinks.js JAVASCRIPT_BUILD_SCRIPT = $(EBIN)/erlresolvelinks.$(EMULATOR) JAVASCRIPT_BUILD_SCRIPT_SRC = src/erlresolvelinks.erl MAN_INDEX_SCRIPT = $(EBIN)/otp_man_index.$(EMULATOR) MAN_INDEX_SRC = src/otp_man_index.erl -MAN_INDEX = $(HTMLDIR)/man_index.html +MAN_INDEX = $(INST_TYPE_DEST_DIR)/man_index.html GLOSSARY = $(HTMLDIR)/glossary.html GLOSSARY_SRC = $(ERL_TOP)/system/internal_tools/doctools/src/glossary.erl @@ -132,45 +155,38 @@ TEMPLATES = \ $(INDEX_SCRIPT): $(INDEX_SRC) $(ERLC) -o$(EBIN) +warn_unused_vars $< -# We don't list toc_*.html as targets because we don't know -$(HTMLDIR)/index.html + $(HTMLDIR)/applications.html: $(INDEX_SCRIPT) $(TEMPLATES) - echo "Generating index $@" -# Check if we are building the index from source or an installed release - if test "$$RELEASE_ROOT" = "" ; then \ - $(ERL) -noshell -pa $(EBIN) -s erl_html_tools top_index src $(ERL_TOP) \ - $(HTMLDIR) `cat "$(ERL_TOP)/OTP_VERSION"` -s erlang halt ;\ +$(INST_TYPE_DEST_DIR)/OTP_VERSION: $(INST_TYPE_DEST_DIR_DEP) + if test -f "$(RELEASE_PATH)/releases/$(SYSTEM_VSN)/OTP_VERSION"; then \ + $(CP) "$(RELEASE_PATH)/releases/$(SYSTEM_VSN)/OTP_VERSION" $@; \ else \ - $(ERL) -noshell -pa $(EBIN) -s erl_html_tools top_index rel $(RELEASE_ROOT) \ - $(HTMLDIR) `cat "$(RELEASE_ROOT)/releases/$(SYSTEM_VSN)/OTP_VERSION"` \ - -s erlang halt ;\ + $(CP) $(ERL_TOP)/OTP_VERSION $@; \ fi +# We don't list toc_*.html as targets because we don't know +$(INDEX_HTML) + $(APPLICATIONS_HTML): $(INST_TYPE_DEST_DIR_DEP) $(INDEX_SCRIPT) $(TEMPLATES) $(INST_TYPE_VSN_FILE) + echo "Generating index $@" + $(ERL) -noshell -pa $(EBIN) -s erl_html_tools top_index $(INST_TYPE) \ + $(INST_TYPE_SRC_DIR) $(INST_TYPE_DEST_DIR) \ + `cat "$(INST_TYPE_VSN_FILE)"` -s erlang halt + #-------------------------------------------------------------------------- $(JAVASCRIPT_BUILD_SCRIPT): $(JAVASCRIPT_BUILD_SCRIPT_SRC) $(ERLC) -o$(EBIN) +warn_unused_vars $< -$(JAVASCRIPT): $(JAVASCRIPT_BUILD_SCRIPT) - erl -noshell -pa $(EBIN) -s erlresolvelinks make -s erlang halt - $(INSTALL_DIR) $(HTMLDIR)/js - $(INSTALL_DATA) erlresolvelinks.js $(JAVASCRIPT) +$(JAVASCRIPT): $(INST_TYPE_DEST_DIR_DEP) $(JAVASCRIPT_BUILD_SCRIPT) + erl -noshell -pa $(EBIN) -run erlresolvelinks make $(ERL_TOP) \ + $(INST_TYPE_SRC_DIR) $(INST_TYPE_JS_DEST_DIR) -s erlang halt #-------------------------------------------------------------------------- $(MAN_INDEX_SCRIPT): $(MAN_INDEX_SRC) $(ERLC) -o$(EBIN) +warn_unused_vars $< -$(MAN_INDEX): $(MAN_INDEX_SCRIPT) -# Check if we are building the index from source or an installed release - if test "$$RELEASE_ROOT" = "" ; then \ - $(ERL) -noshell -pa $(EBIN) -s otp_man_index gen src $(ERL_TOP) $@ \ - -s erlang halt ;\ - else \ - $(ERL) -noshell -pa $(EBIN) -s otp_man_index gen rel $(RELEASE_ROOT) $@ \ - -s erlang halt ;\ - fi - +$(MAN_INDEX): $(INST_TYPE_DEST_DIR_DEP) $(MAN_INDEX_SCRIPT) + $(ERL) -noshell -pa $(EBIN) -s otp_man_index gen $(INST_TYPE) \ + $(INST_TYPE_SRC_DIR) $@ -s erlang halt #-------------------------------------------------------------------------- @@ -248,18 +264,22 @@ html: $(INDEX_FILES) \ debug opt: clean: - rm -rf ../html/js - rm -f PR.template - rm -f $(INDEX_FILES) $(MAN_INDEX) - rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) - rm -f $(INDEX_SCRIPT) $(GLOSSARY_SCRIPT) \ - $(JAVASCRIPT_BUILD_SCRIPT) - rm -f erl_crash.dump errs core *~ + $(RM) ../html/js/*.js + $(RM) PR.template + $(RM) $(XMLDIR)/*.xml + $(RM) $(INDEX_FILES) $(MAN_INDEX) + $(RM) $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + $(RM) $(INDEX_SCRIPT) $(GLOSSARY_SCRIPT) $(JAVASCRIPT_BUILD_SCRIPT) + $(RM) erl_crash.dump errs core *~ + # ---------------------------------------------------- # Release Target # ---------------------------------------------------- include $(ERL_TOP)/make/otp_release_targets.mk +$(RELSYSDIR)/temporary: + $(INSTALL_DIR) $(RELSYSDIR)/temporary + release_docs_spec: docs $(INSTALL_DIR) "$(RELEASE_PATH)" $(INSTALL_DATA) $(INFO_FILES) "$(RELEASE_PATH)" @@ -268,13 +288,13 @@ release_docs_spec: docs $(INSTALL_DATA) \ $(TOP_PDF_FILE) $(RELSYSDIR)/pdf $(INSTALL_DIR) $(RELSYSDIR)/js - $(INSTALL_DATA) \ - $(JAVASCRIPT) $(RELSYSDIR)/js + $(INSTALL_DATA) $(JAVASCRIPT) $(RELSYSDIR)/js $(INSTALL_DATA) $(INDEX_FILES) $(MAN_INDEX) $(RELSYSDIR) $(INSTALL_DIR) $(RELSYSDIR)/docbuild $(INSTALL_DATA) $(INDEX_SCRIPT) $(MAN_INDEX_SCRIPT) $(JAVASCRIPT_BUILD_SCRIPT) \ $(INDEX_SRC) $(MAN_INDEX_SRC) $(JAVASCRIPT_BUILD_SCRIPT_SRC) \ $(TEMPLATES) $(RELSYSDIR)/docbuild + $(RM) -r $(RELSYSDIR)/temporary release_spec: 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/src/erl_html_tools.erl b/system/doc/top/src/erl_html_tools.erl index 28a0649658..dee1871342 100644 --- a/system/doc/top/src/erl_html_tools.erl +++ b/system/doc/top/src/erl_html_tools.erl @@ -508,7 +508,7 @@ subst_app(App, [{VSN,_Path,Link,Text} | VerInfos]) -> " <a href=\"",Link,"\" target=\"_top\">",uc(App), "</a>\n", " <a href=\"",Link,"\" target=\"_top\">",VSN,"</a>\n", - " <td class=appnums>\n", + " <br/>\n", subst_vsn(VerInfos), " </td>\n", " <td>\n", @@ -522,7 +522,7 @@ subst_vsn([{VSN,_Path,Link,_Text} | VSNs]) -> [ " <font size=\"2\"><a class=anum href=\"",Link,"\" target=\"_top\">", VSN, - "</a></font><br>\n", + "</a></font><br/>\n", subst_vsn(VSNs) ]; subst_vsn([]) -> diff --git a/system/doc/top/src/erlresolvelinks.erl b/system/doc/top/src/erlresolvelinks.erl index cfe8d0fa0b..c1285fa1c3 100644 --- a/system/doc/top/src/erlresolvelinks.erl +++ b/system/doc/top/src/erlresolvelinks.erl @@ -27,40 +27,28 @@ %%----------------------------------------------------------------- -module(erlresolvelinks). --export([make/0, make/1]). +-export([make/1]). -include_lib("kernel/include/file.hrl"). -define(JAVASCRIPT_NAME, "erlresolvelinks.js"). -make() -> - case os:getenv("ERL_TOP") of - false -> - io:format("Variable ERL_TOP is required\n",[]); - Value -> - make_from_src(Value, ".") - end. - -make([RootDir, DestDir]) -> - do_make(RootDir, DestDir); -make(RootDir) when is_atom(RootDir) -> - DestDir = filename:join(RootDir, "doc"), - do_make(RootDir, DestDir). - -do_make(_RootDir, _DestDir) -> - ok. +make([ErlTop, RootDir, DestDir]) -> + make(ErlTop, RootDir, DestDir). -make_from_src(RootDir, DestDir) -> +make(ErlTop, RootDir, DestDir) -> %% doc/Dir %% erts-Vsn %% lib/App-Vsn Name = ?JAVASCRIPT_NAME, - DocDirs0 = get_dirs(filename:join([RootDir, "system/doc"])), + DocDirs0 = get_dirs(filename:join([ErlTop, "system/doc"])), DocDirs = lists:map(fun({Dir, _DirPath}) -> D = filename:join(["doc", Dir]), {D, D} end, DocDirs0), - ErtsDirs = latest_app_dirs(RootDir, ""), - AppDirs = latest_app_dirs(RootDir, "lib"), + Released = ErlTop /= RootDir, + + ErtsDirs = latest_app_dirs(Released, RootDir, ""), + AppDirs = latest_app_dirs(Released, RootDir, "lib"), AllAppDirs = lists:map( @@ -106,30 +94,46 @@ is_dir({File, AFile}) -> false end. -latest_app_dirs(RootDir, Dir) -> +released_app_vsns([]) -> + []; +released_app_vsns([{AppVsn, Dir} | AVDirs]) -> + try + {ok, _} = file:read_file_info(filename:join([Dir, "doc", "html"])), + [App, Vsn] = string:tokens(AppVsn, "-"), + VsnNumList = vsnstr_to_numlist(Vsn), + [_Maj, _Min | _] = VsnNumList, + [{{App, VsnNumList}, AppVsn} | released_app_vsns(AVDirs)] + catch + _:_ -> released_app_vsns(AVDirs) + end. + +latest_app_dirs(Release, RootDir, Dir) -> ADir = filename:join(RootDir, Dir), RDirs0 = get_dirs(ADir), - RDirs1 = lists:filter(fun is_app_dir/1, RDirs0), - - SDirs0 = - lists:map(fun({App, Dir1}) -> - File = filename:join(Dir1, "vsn.mk"), - case file:read_file(File) of - {ok, Bin} -> - case re:run(Bin, ".*VSN\s*=\s*([0-9\.]+).*",[{capture,[1],list}]) of - {match, [VsnStr]} -> - VsnNumList = vsnstr_to_numlist(VsnStr), - {{App, VsnNumList}, App++"-"++VsnStr}; - nomatch -> - io:format("No VSN variable found in ~s\n", [File]), - error - end; - {error, Reason} -> - io:format("~p : ~s\n", [Reason, File]), - error - end - end, - RDirs1), + SDirs0 = case Release of + true -> + released_app_vsns(RDirs0); + false -> + lists:map(fun({App, Dir1}) -> + File = filename:join(Dir1, "vsn.mk"), + case file:read_file(File) of + {ok, Bin} -> + case re:run(Bin, ".*VSN\s*=\s*([0-9\.]+).*",[{capture,[1],list}]) of + {match, [VsnStr]} -> + VsnNumList = vsnstr_to_numlist(VsnStr), + {{App, VsnNumList}, App++"-"++VsnStr}; + nomatch -> + io:format("No VSN variable found in ~s\n", [File]), + error + end; + {error, Reason} -> + io:format("~p : ~s\n", [Reason, File]), + error + end + end, + lists:filter(fun is_app_dir/1, RDirs0)) + end, + SDirs1 = lists:keysort(1, SDirs0), App2Dirs = lists:foldr(fun({{App, _VsnNumList}, AppVsn}, Acc) -> case lists:keymember(App, 1, Acc) of 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/tutorial/Makefile b/system/doc/tutorial/Makefile index 70aba663b5..4c62deeffd 100644 --- a/system/doc/tutorial/Makefile +++ b/system/doc/tutorial/Makefile @@ -93,10 +93,9 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -_create_dirs := $(shell mkdir -p $(HTMLDIR)) $(HTMLDIR)/%.gif: %.gif - $(INSTALL_DATA) $< $@ + $(CP) $< $@ docs: html @@ -109,7 +108,8 @@ gifs: $(GIF_FILES:%=$(HTMLDIR)/%) debug opt: clean clean_docs: - rm -rf $(HTMLDIR) + rm -f $(XMLDIR)/*.xml + rm -f $(HTMLDIR)/*.gif $(HTMLDIR)/*.html rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ diff --git a/system/doc/tutorial/overview.xml b/system/doc/tutorial/overview.xml index 255c22f2c1..bd652b1e4b 100644 --- a/system/doc/tutorial/overview.xml +++ b/system/doc/tutorial/overview.xml @@ -245,13 +245,13 @@ Term = binary_to_term(Binary)</pre> </section> <section> - <title>IC</title> + <title>IC and CORBA</title> <p>IC (Erlang IDL Compiler) is an interface generator that, given an IDL interface specification, automatically generates stub code in Erlang, C, or Java. See the IC User's Guide and IC Reference Manual.</p> - <p>For details, see the <seealso marker="ic:ic">ic</seealso> - manual page in IC.</p> + <p>For details, see the + <url href="https://github.com/erlang/corba">corba repository</url>.</p> </section> <section> diff --git a/system/doc/xml/design_principles/.gitignore b/system/doc/xml/design_principles/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/design_principles/.gitignore diff --git a/system/doc/xml/efficiency_guide/.gitignore b/system/doc/xml/efficiency_guide/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/efficiency_guide/.gitignore diff --git a/system/doc/xml/embedded/.gitignore b/system/doc/xml/embedded/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/embedded/.gitignore 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 diff --git a/system/doc/xml/getting_started/.gitignore b/system/doc/xml/getting_started/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/getting_started/.gitignore diff --git a/system/doc/xml/installation_guide/.gitignore b/system/doc/xml/installation_guide/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/installation_guide/.gitignore diff --git a/system/doc/xml/oam/.gitignore b/system/doc/xml/oam/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/oam/.gitignore diff --git a/system/doc/xml/programming_examples/.gitignore b/system/doc/xml/programming_examples/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/programming_examples/.gitignore diff --git a/system/doc/xml/reference_manual/.gitignore b/system/doc/xml/reference_manual/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/reference_manual/.gitignore diff --git a/system/doc/xml/system_architecture_intro/.gitignore b/system/doc/xml/system_architecture_intro/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/system_architecture_intro/.gitignore diff --git a/system/doc/xml/system_principles/.gitignore b/system/doc/xml/system_principles/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/system_principles/.gitignore diff --git a/system/doc/xml/tutorial/.gitignore b/system/doc/xml/tutorial/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/system/doc/xml/tutorial/.gitignore |