diff options
Diffstat (limited to 'system/doc')
| -rw-r--r-- | system/doc/design_principles/make.dep | 31 | ||||
| -rw-r--r-- | system/doc/design_principles/spec_proc.xml | 48 | ||||
| -rw-r--r-- | system/doc/design_principles/sup_princ.xml | 14 | ||||
| -rw-r--r-- | system/doc/efficiency_guide/make.dep | 16 | ||||
| -rw-r--r-- | system/doc/efficiency_guide/profiling.xml | 57 | ||||
| -rw-r--r-- | system/doc/embedded/make.dep | 14 | ||||
| -rw-r--r-- | system/doc/getting_started/make.dep | 14 | ||||
| -rw-r--r-- | system/doc/installation_guide/make.dep | 13 | ||||
| -rw-r--r-- | system/doc/oam/make.dep | 26 | ||||
| -rw-r--r-- | system/doc/programming_examples/make.dep | 20 | ||||
| -rw-r--r-- | system/doc/reference_manual/expressions.xml | 12 | ||||
| -rw-r--r-- | system/doc/reference_manual/make.dep | 16 | ||||
| -rw-r--r-- | system/doc/system_architecture_intro/make.dep | 13 | ||||
| -rw-r--r-- | system/doc/system_principles/make.dep | 14 | ||||
| -rw-r--r-- | system/doc/top/src/erl_html_tools.erl | 10 | ||||
| -rw-r--r-- | system/doc/tutorial/make.dep | 35 |
16 files changed, 89 insertions, 264 deletions
diff --git a/system/doc/design_principles/make.dep b/system/doc/design_principles/make.dep deleted file mode 100644 index 05dd2333fb..0000000000 --- a/system/doc/design_principles/make.dep +++ /dev/null @@ -1,31 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/gandalf/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: applications.tex appup_cookbook.tex book.tex \ - des_princ.tex distributed_applications.tex \ - events.tex fsm.tex gen_server_concepts.tex \ - included_applications.tex part.tex release_handling.tex \ - release_structure.tex spec_proc.tex sup_princ.tex - -# ---------------------------------------------------- -# Pictures that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: sup6.ps - -book.dvi: dist1.ps dist2.ps dist3.ps dist4.ps dist5.ps - -book.dvi: clientserver.ps - -book.dvi: inclappls.ps - -book.dvi: sup4.ps sup5.ps - diff --git a/system/doc/design_principles/spec_proc.xml b/system/doc/design_principles/spec_proc.xml index f0f62891b6..a1c862e004 100644 --- a/system/doc/design_principles/spec_proc.xml +++ b/system/doc/design_principles/spec_proc.xml @@ -411,30 +411,48 @@ loop(...) -> <p>To implement a user-defined behaviour, write code similar to code for a special process but calling functions in a callback module for handling specific tasks.</p> - <p>If it is desired that the compiler should warn for missing - callback functions, as it does for the OTP behaviours, implement - and export the function:</p> + <p>If it is desired that the compiler should warn for missing callback + functions, as it does for the OTP behaviours, add callback attributes in the + behaviour module to describe the expected callbacks:</p> + <code type="none"> +-callback Name1(Arg1_1, Arg1_2, ..., Arg1_N1) -> Res1. +-callback Name2(Arg2_1, Arg2_2, ..., Arg2_N2) -> Res2. +... +-callback NameM(ArgM_1, ArgM_2, ..., ArgM_NM) -> ResM.</code> + <p>where <c>NameX</c> are the names of the expected callbacks and + <c>ArgX_Y</c>, <c>ResX</c> are types as they are described in Specifications + for functions in <seealso marker="../reference_manual/typespec">Types and + Function Specifications</seealso>. The whole syntax of spec attributes is + supported by callback attributes.</p> + <p>Alternatively you may directly implement and export the function:</p> <code type="none"> behaviour_info(callbacks) -> [{Name1,Arity1},...,{NameN,ArityN}].</code> - <p>where each <c>{Name,Arity}</c> specifies the name and arity of - a callback function.</p> + <p>where each <c>{Name,Arity}</c> specifies the name and arity of a callback + function. This function is otherwise automatically generated by the compiler + using the callback attributes.</p> <p>When the compiler encounters the module attribute - <c>-behaviour(Behaviour).</c> in a module <c>Mod</c>, it will call - <c>Behaviour:behaviour_info(callbacks)</c> and compare the result - with the set of functions actually exported from <c>Mod</c>, and - issue a warning if any callback function is missing.</p> + <c>-behaviour(Behaviour).</c> in a module <c>Mod</c>, it will call + <c>Behaviour:behaviour_info(callbacks)</c> and compare the result with the + set of functions actually exported from <c>Mod</c>, and issue a warning if + any callback function is missing.</p> <p>Example:</p> <code type="none"> %% User-defined behaviour module -module(simple_server). -export([start_link/2,...]). --export([behaviour_info/1]). -behaviour_info(callbacks) -> - [{init,1}, - {handle_req,1}, - {terminate,0}]. +-callback init(State :: term()) -> 'ok'. +-callback handle_req(Req :: term(), State :: term()) -> {'ok', Reply :: term()}. +-callback terminate() -> 'ok'. + +%% Alternatively you may define: +%% +%% -export([behaviour_info/1]). +%% behaviour_info(callbacks) -> +%% [{init,1}, +%% {handle_req,2}, +%% {terminate,0}]. start_link(Name, Module) -> proc_lib:start_link(?MODULE, init, [self(), Name, Module]). @@ -452,7 +470,7 @@ init(Parent, Name, Module) -> -module(db). -behaviour(simple_server). --export([init/0, handle_req/1, terminate/0]). +-export([init/0, handle_req/2, terminate/0]). ...</code> </section> diff --git a/system/doc/design_principles/sup_princ.xml b/system/doc/design_principles/sup_princ.xml index 2748f21bbe..a432f9458b 100644 --- a/system/doc/design_principles/sup_princ.xml +++ b/system/doc/design_principles/sup_princ.xml @@ -181,8 +181,16 @@ init(...) -> terminated using <c>exit(Child, kill)</c>.</item> <item>If the child process is another supervisor, it should be set to <c>infinity</c> to give the subtree enough time to - shutdown.</item> + shutdown. It is also allowed to set it to <c>infinity</c>, if the + child process is a worker.</item> </list> + <warning> + <p>Be careful by setting the <c>Shutdown</c> strategy to + <c>infinity</c> when the child process is a worker. Because, in this + situation, the termination of the supervision tree depends on the + child process, it must be implemented in a safe way and its cleanup + procedure must always return.</p> + </warning> </item> <item> <p><c>Type</c> specifies if the child process is a supervisor or @@ -341,6 +349,10 @@ call:start_link(id1)</code> supervisor:terminate_child(Sup, Pid)</code> <p>where <c>Sup</c> is the pid, or name, of the supervisor and <c>Pid</c> is the pid of the child.</p> + <p>Because a <c>simple_one_for_one</c> supervisor could have many children, + it shuts them all down at same time. So, order in which they are stopped is + not defined. For the same reason, it could have an overhead with regards to + the <c>Shutdown</c> strategy.</p> </section> <section> diff --git a/system/doc/efficiency_guide/make.dep b/system/doc/efficiency_guide/make.dep deleted file mode 100644 index afa3bd0516..0000000000 --- a/system/doc/efficiency_guide/make.dep +++ /dev/null @@ -1,16 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: advanced.tex binaryhandling.tex book.tex commoncaveats.tex \ - drivers.tex functions.tex introduction.tex listhandling.tex \ - myths.tex part.tex processes.tex profiling.tex \ - tablesDatabases.tex - diff --git a/system/doc/efficiency_guide/profiling.xml b/system/doc/efficiency_guide/profiling.xml index 13165a0ede..65ba4b3369 100644 --- a/system/doc/efficiency_guide/profiling.xml +++ b/system/doc/efficiency_guide/profiling.xml @@ -40,9 +40,13 @@ <p>Erlang/OTP contains several tools to help finding bottlenecks.</p> - <p><c>fprof</c> and <c>eprof</c> provide the most detailed information - about where the time is spent, but they significantly slow downs the - programs they profile.</p> + <p><c>fprof</c> provide the most detailed information + about where the time is spent, but it significantly slows down the + program it profiles.</p> + + <p><c>eprof</c> provides time information of each function used + in the program. No callgraph is produced but <c>eprof</c> has + considerable less impact on the program profiled.</p> <p>If the program is too big to be profiled by <c>fprof</c> or <c>eprof</c>, <c>cover</c> and <c>cprof</c> could be used to locate parts of the @@ -50,7 +54,7 @@ <c>eprof</c>.</p> <p><c>cover</c> provides execution counts per line per process, - with less overhead than <c>fprof/eprof</c>. Execution counts can + with less overhead than <c>fprof</c>. Execution counts can with some caution be used to locate potential performance bottlenecks. The most lightweight tool is <c>cprof</c>, but it only provides execution counts on a function basis (for all processes, not per process).</p> @@ -102,35 +106,45 @@ <section> <title>fprof</title> - <p><c>fprof</c> measures the execution time for each function, + <p> + <c>fprof</c> measures the execution time for each function, both own time i.e how much time a function has used for its own execution, and accumulated time i.e. including called functions. The values are displayed per process. You also get to know how many times each function has been called. <c>fprof</c> is based on trace to file in order to minimize runtime performance impact. Using fprof is just a - matter of calling a few library functions, see fprof manual - page under the application tools.</p> - <p><c>fprof</c> was introduced in version R8 of Erlang/OTP. Its - predecessor <c>eprof</c> that is based on the Erlang trace BIFs, - is still available, see eprof manual page under the - application tools. Eprof shows how much time has been used by - each process, and in which function calls this time has been - spent. Time is shown as percentage of total time, not as - absolute time.</p> + matter of calling a few library functions, see + <seealso marker="tools:fprof">fprof</seealso> + manual page under the application tools.<c>fprof</c> was introduced in + version R8 of Erlang/OTP. + </p> </section> + <section> + <title>eprof</title> + <p> + <c>eprof</c> is based on the Erlang trace_info BIFs. Eprof shows how much time has been used by + each process, and in which function calls this time has been + spent. Time is shown as percentage of total time and absolute time. + See <seealso marker="tools:eprof">eprof</seealso> for + additional information. + </p> + </section> + <section> <title>cover</title> - <p><c>cover</c>'s primary use is coverage analysis to verify + <p> + <c>cover</c>'s primary use is coverage analysis to verify test cases, making sure all relevant code is covered. <c>cover</c> counts how many times each executable line of code is executed when a program is run. This is done on a per module basis. Of course this information can be used to determine what code is run very frequently and could therefore be subject for optimization. Using cover is just a matter of - calling a few library functions, see cover manual - page under the application tools.</p> + calling a few library functions, see + <seealso marker="tools:cover">cover</seealso> + manual page under the application tools.</p> </section> <section> @@ -139,8 +153,11 @@ <c>cover</c> regarding features. It counts how many times each function is called when the program is run, on a per module basis. <c>cprof</c> has a low performance degradation effect (versus - <c>fprof</c> and <c>eprof</c>) and does not need to recompile - any modules to profile (versus <c>cover</c>).</p> + <c>fprof</c>) and does not need to recompile + any modules to profile (versus <c>cover</c>). + See <seealso marker="tools:cprof">cprof</seealso> manual page for additional + information. + </p> </section> <section> @@ -170,7 +187,7 @@ <cell align="left" valign="middle"><c>eprof </c></cell> <cell align="left" valign="middle">per process/function to screen/file </cell> <cell align="left" valign="middle">medium </cell> - <cell align="left" valign="middle">significant slowdown </cell> + <cell align="left" valign="middle">small slowdown </cell> <cell align="left" valign="middle">yes </cell> <cell align="left" valign="middle">only total </cell> <cell align="left" valign="middle">no </cell> diff --git a/system/doc/embedded/make.dep b/system/doc/embedded/make.dep deleted file mode 100644 index 9949a3ac96..0000000000 --- a/system/doc/embedded/make.dep +++ /dev/null @@ -1,14 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: book.tex embedded_nt.tex embedded_solaris.tex \ - part.tex vxworks.tex - diff --git a/system/doc/getting_started/make.dep b/system/doc/getting_started/make.dep deleted file mode 100644 index 69b177f77c..0000000000 --- a/system/doc/getting_started/make.dep +++ /dev/null @@ -1,14 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: book.tex conc_prog.tex intro.tex part.tex \ - records_macros.tex robustness.tex seq_prog.tex - diff --git a/system/doc/installation_guide/make.dep b/system/doc/installation_guide/make.dep deleted file mode 100644 index 3878f4ac9d..0000000000 --- a/system/doc/installation_guide/make.dep +++ /dev/null @@ -1,13 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: book.tex install-binary.tex part.tex verification.tex - diff --git a/system/doc/oam/make.dep b/system/doc/oam/make.dep deleted file mode 100644 index 3694df9f1b..0000000000 --- a/system/doc/oam/make.dep +++ /dev/null @@ -1,26 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: book.tex oam_intro.tex part.tex - -# ---------------------------------------------------- -# Source inlined when transforming from source to LaTeX -# ---------------------------------------------------- - -oam_intro.tex: ../../../system/doc/definitions/term.defs - -# ---------------------------------------------------- -# Pictures that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: snmp_model_1.ps snmp_model_2.ps snmp_model_3.ps \ - terminology.ps - diff --git a/system/doc/programming_examples/make.dep b/system/doc/programming_examples/make.dep deleted file mode 100644 index b0655f56b3..0000000000 --- a/system/doc/programming_examples/make.dep +++ /dev/null @@ -1,20 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: bit_syntax.tex book.tex funs.tex list_comprehensions.tex \ - part.tex records.tex - -# ---------------------------------------------------- -# Source inlined when transforming from source to LaTeX -# ---------------------------------------------------- - -funs.tex: fun_test.erl funparse.erl funs1.erl - diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index 5673f2494e..c24b1110a4 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -883,9 +883,8 @@ Ei = Value | and UTF-32, respectively.</p> <p>When constructing a segment of a <c>utf</c> type, <c>Value</c> - must be an integer in one of the ranges 0..16#D7FF, - 16#E000..16#FFFD, or 16#10000..16#10FFFF - (i.e. a valid Unicode code point). Construction + must be an integer in the range 0..16#D7FF or + 16#E000....16#10FFFF. Construction will fail with a <c>badarg</c> exception if <c>Value</c> is outside the allowed ranges. The size of the resulting binary segment depends on the type and/or <c>Value</c>. For <c>utf8</c>, @@ -900,14 +899,13 @@ Ei = Value | <c><![CDATA[<<$a/utf8,$b/utf8,$c/utf8>>]]></c>.</p> <p>A successful match of a segment of a <c>utf</c> type results - in an integer in one of the ranges 0..16#D7FF, 16#E000..16#FFFD, - or 16#10000..16#10FFFF - (i.e. a valid Unicode code point). The match will fail if returned value + in an integer in the range 0..16#D7FF or 16#E000..16#10FFFF. + The match will fail if returned value would fall outside those ranges.</p> <p>A segment of type <c>utf8</c> will match 1 to 4 bytes in the binary, if the binary at the match position contains a valid UTF-8 sequence. - (See RFC-2279 or the Unicode standard.)</p> + (See RFC-3629 or the Unicode standard.)</p> <p>A segment of type <c>utf16</c> may match 2 or 4 bytes in the binary. The match will fail if the binary at the match position does not contain diff --git a/system/doc/reference_manual/make.dep b/system/doc/reference_manual/make.dep deleted file mode 100644 index 0e7687448c..0000000000 --- a/system/doc/reference_manual/make.dep +++ /dev/null @@ -1,16 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: book.tex code_loading.tex data_types.tex distributed.tex \ - errors.tex expressions.tex functions.tex introduction.tex \ - macros.tex modules.tex part.tex patterns.tex \ - ports.tex processes.tex records.tex - diff --git a/system/doc/system_architecture_intro/make.dep b/system/doc/system_architecture_intro/make.dep deleted file mode 100644 index 6b7bd860a0..0000000000 --- a/system/doc/system_architecture_intro/make.dep +++ /dev/null @@ -1,13 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: book.tex part.tex sys_arch_intro.tex - diff --git a/system/doc/system_principles/make.dep b/system/doc/system_principles/make.dep deleted file mode 100644 index 28753ca5a0..0000000000 --- a/system/doc/system_principles/make.dep +++ /dev/null @@ -1,14 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: book.tex create_target.tex error_logging.tex \ - part.tex system_principles.tex - diff --git a/system/doc/top/src/erl_html_tools.erl b/system/doc/top/src/erl_html_tools.erl index bb6a9a9f0a..1e2b8c86af 100644 --- a/system/doc/top/src/erl_html_tools.erl +++ b/system/doc/top/src/erl_html_tools.erl @@ -624,17 +624,9 @@ lines_to_key_value([Line | Lines]) -> end. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% Extensions to the 'regexp' module. +% Regular expression helpers. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% is_match(Ex, Re) -> -%% case regexp:first_match(Ex, Re) of -%% {match, _, _} -> -%% true; -%% nomatch -> -%% false -%% end. - %% -type gsub(String, RegExp, Fun, Acc) -> subres(). %% Substitute every match of the regular expression RegExp with the %% string returned from the function Fun(Match, Acc). Accept pre-parsed diff --git a/system/doc/tutorial/make.dep b/system/doc/tutorial/make.dep deleted file mode 100644 index e9f77ab439..0000000000 --- a/system/doc/tutorial/make.dep +++ /dev/null @@ -1,35 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: book.tex c_port.tex c_portdriver.tex cnode.tex \ - erl_interface.tex example.tex introduction.tex \ - overview.tex part.tex - -# ---------------------------------------------------- -# Source inlined when transforming from source to LaTeX -# ---------------------------------------------------- - -c_port.tex: port.c - -c_portdriver.tex: port_driver.c - -cnode.tex: complex3.erl - -example.tex: complex.c - -# ---------------------------------------------------- -# Pictures that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: port.ps - -book.dvi: port_driver.ps - |