diff options
Diffstat (limited to 'lib/tools/doc')
| -rw-r--r-- | lib/tools/doc/src/cover.xml | 454 | ||||
| -rw-r--r-- | lib/tools/doc/src/cprof.xml | 199 | ||||
| -rw-r--r-- | lib/tools/doc/src/eprof.xml | 121 | ||||
| -rw-r--r-- | lib/tools/doc/src/fprof.xml | 358 | ||||
| -rw-r--r-- | lib/tools/doc/src/fprof_chapter.xml | 6 | ||||
| -rw-r--r-- | lib/tools/doc/src/lcnt.xml | 816 | ||||
| -rw-r--r-- | lib/tools/doc/src/make.xml | 36 | ||||
| -rw-r--r-- | lib/tools/doc/src/specs.xml | 1 | ||||
| -rw-r--r-- | lib/tools/doc/src/tags.xml | 56 | ||||
| -rw-r--r-- | lib/tools/doc/src/xref.xml | 430 |
10 files changed, 1064 insertions, 1413 deletions
diff --git a/lib/tools/doc/src/cover.xml b/lib/tools/doc/src/cover.xml index 0889a16f65..9bcaa9227d 100644 --- a/lib/tools/doc/src/cover.xml +++ b/lib/tools/doc/src/cover.xml @@ -115,12 +115,8 @@ </description> <funcs> <func> - <name since="">start() -> {ok,Pid} | {error,Reason}</name> + <name name="start" arity="0" since=""></name> <fsummary>Start Cover.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Reason = {already_started,Pid}</v> - </type> <desc> <p>Starts the Cover server which owns the Cover internal database. This function is called automatically by the other functions in @@ -128,312 +124,279 @@ </desc> </func> <func> - <name since="OTP 22.0">local_only() -> ok | {error,too_late}</name> + <name name="local_only" arity="0" since="OTP 22.0"></name> <fsummary>Only support running Cover on the local node.</fsummary> <desc> <p>Only support running Cover on the local node. This function - must be called before any modules have been compiled or any - nodes added. When running in this mode, modules will be Cover - compiled in a more efficient way, but the resulting code will - only work on the same node they were compiled on.</p> + must be called before any modules have been compiled or any + nodes added. When running in this mode, modules will be Cover + compiled in a more efficient way, but the resulting code will + only work on the same node they were compiled on.</p> </desc> </func> <func> - <name since="">start(Nodes) -> {ok,StartedNodes} | {error,not_main_node} | {error,local_only}</name> + <name name="start" arity="1" since=""></name> <fsummary>Start Cover on remote nodes.</fsummary> - <type> - <v>Nodes = StartedNodes = [atom()]</v> - </type> <desc> <p>Starts a Cover server on the each of given nodes, and loads all cover compiled modules. This call will fail if - <c>cover:local_only/0</c> has been called.</p> + <c>cover:local_only/0</c> has been called.</p> </desc> </func> <func> - <name since="">compile(ModFiles) -> Result | [Result]</name> - <name since="">compile(ModFiles, Options) -> Result | [Result]</name> - <name since="">compile_module(ModFiles) -> Result | [Result]</name> - <name since="">compile_module(ModFiles, Options) -> Result | [Result]</name> + <name name="compile" arity="1" since=""></name> + <name name="compile" arity="2" since=""></name> + <name name="compile_module" arity="1" since=""></name> + <name name="compile_module" arity="2" since=""></name> <fsummary>Compile one or more modules for Cover analysis.</fsummary> - <type> - <v>ModFiles = ModFile | [ModFile]</v> - <v>ModFile = Module | File</v> - <v> Module = atom()</v> - <v> File = string()</v> - <v>Options = [Option]</v> - <v> Option = {i,Dir} | {d,Macro} | {d,Macro,Value} | export_all</v> - <d>See <c>compile:file/2.</c></d> - <v>Result = {ok,Module} | {error,File} | {error,not_main_node}</v> - </type> + <type name="mod_files"/> + <type name="mod_file"/> + <type name="option"/> + <type_desc name="option">See <seemfa + marker="compiler:compile#file/2"><c>compile:file/2</c></seemfa>. + </type_desc> + <type name="compile_result"/> <desc> <p>Compiles a module for Cover analysis. The module is given by its - module name <c>Module</c> or by its file name <c>File</c>. - The <c>.erl</c> extension may be omitted. If the module is - located in another directory, the path has to be specified.</p> - <p><c>Options</c> is a list of compiler options which defaults to - <c>[]</c>. Only options defining include file directories and - macros are passed to <c>compile:file/2</c>, everything else is - ignored.</p> + module name <c><anno>Module</anno></c> or by its file name + <c><anno>File</anno></c>. The <c>.erl</c> extension may be + omitted. If the module is located in another directory, the + path has to be specified.</p> + <p><c><anno>Options</anno></c> is a list of compiler options + which defaults to <c>[]</c>. Only options defining include + file directories and macros are passed to <seemfa + marker="compiler:compile#file/2"><c>compile:file/2</c></seemfa>, + everything else is ignored.</p> <p>If the module is successfully Cover compiled, the function - returns <c>{ok,Module}</c>. Otherwise the function returns - <c>{error,File}</c>. Errors and warnings are printed as they - occur.</p> - <p>If a list of <c>ModFiles</c> is given as input, a list - of <c>Result</c> will be returned. The order of the returned - list is undefined.</p> + returns <c>{ok, <anno>Module</anno>}</c>. Otherwise the + function returns <c>{error, <anno>File</anno>}</c>. Errors and + warnings are printed as they occur.</p> + <p>If a list of <c><anno>ModFiles</anno></c> is given as + input, a list of <c><anno>Result</anno></c> will be returned. + The order of the returned list is undefined.</p> <p>Note that the internal database is (re-)initiated during the compilation, meaning any previously collected coverage data for the module will be lost.</p> </desc> </func> <func> - <name since="">compile_directory() -> [Result] | {error,Reason}</name> - <name since="">compile_directory(Dir) -> [Result] | {error,Reason}</name> - <name since="">compile_directory(Dir, Options) -> [Result] | {error,Reason}</name> + <name name="compile_directory" arity="0" since=""></name> + <name name="compile_directory" arity="1" since=""></name> + <name name="compile_directory" arity="2" since=""></name> <fsummary>Compile all modules in a directory for Cover analysis.</fsummary> - <type> - <v>Dir = string()</v> - <v>Options = [Option]</v> - <d>See <c>compile_module/1,2</c></d> - <v>Result = {ok,Module} | {error,File} | {error,not_main_node}</v> - <d>See <c>compile_module/1,2</c></d> - <v>Reason = eacces | enoent</v> - </type> + <type name="option"/> + <type_desc name="option">See <seemfa + marker="compiler:compile#file/2"><c>compile:file/2</c></seemfa>. + </type_desc> + <type name="file_error"/> + <type name="compile_result"/> <desc> <p>Compiles all modules (<c>.erl</c> files) in a directory - <c>Dir</c> for Cover analysis the same way as - <c>compile_module/1,2</c> and returns a list with the return - values.</p> - <p><c>Dir</c> defaults to the current working directory.</p> - <p>The function returns <c>{error,eacces}</c> if the directory is not - readable or <c>{error,enoent}</c> if the directory does not exist.</p> + <c><anno>Dir</anno></c> for Cover analysis the same way as + <seemfa marker="#compile_module/1"><c>compile_module/1,2</c></seemfa> + and returns a list with the return values.</p> + <p><c><anno>Dir</anno></c> defaults to the current working + directory.</p> + <p>The function returns <c>{error, eacces}</c> if the + directory is not readable or <c>{error, enoent}</c> if the + directory does not exist.</p> </desc> </func> <func> - <name since="">compile_beam(ModFiles) -> Result | [Result]</name> + <name name="compile_beam" arity="1" since=""></name> <fsummary>Compile one or more modules for Cover analysis, using existing beam(s).</fsummary> - <type> - <v>ModFiles = ModFile | [ModFile]</v> - <v>ModFile = Module | BeamFile</v> - <v> Module = atom()</v> - <v> BackendModule = atom()</v> - <v> BeamFile = string()</v> - <v>Result = {ok,Module} | {error,BeamFile} | {error,Reason}</v> - <v> Reason = non_existing | {no_abstract_code,BeamFile} | {{missing_backend,BackendModule},BeamFile} | {encrypted_abstract_code,BeamFile} | {already_cover_compiled,no_beam_found,Module} | not_main_node</v> - </type> + <type name="beam_mod_files"/> + <type name="beam_mod_file"/> + <type name="compile_beam_result"/> + <type name="compile_beam_rsn"/> <desc> - <p>Does the same as <c>compile/1,2</c>, but uses an existing - <c>.beam</c> file as base, i.e. the module is not compiled - from source. Thus <c>compile_beam/1</c> is faster than - <c>compile/1,2</c>.</p> + <p>Does the same as <seemfa + marker="#compile/1"><c>compile/1,2</c></seemfa>, but uses an + existing <c>.beam</c> file as base, that is, the module is not + compiled from source. Thus <c>compile_beam/1</c> is faster + than <c>compile/1,2</c>.</p> <p>Note that the existing <c>.beam</c> file must contain - <em>abstract code</em>, i.e. it must have been compiled with - the <c>debug_info</c> option. If not, the error reason - <c>{no_abstract_code,BeamFile}</c> is returned. + <em>abstract code</em>, that is, it must have been compiled with the + <seemfa marker="compiler:compile#file/2"><c>debug_info</c></seemfa> + option. If not, the error reason + <c>{no_abstract_code, <anno>BeamFile</anno>}</c> is returned. If the abstract code is encrypted, and no key is available for decrypting it, the error reason - <c>{encrypted_abstract_code,BeamFile}</c> is returned.</p> - <p>If only the module name (i.e. not the full name of the + <c>{encrypted_abstract_code, <anno>BeamFile</anno>}</c> + is returned.</p> + <p>If only the module name (that is, not the full name of the <c>.beam</c> file) is given to this function, the <c>.beam</c> file is found by calling - <c>code:which(Module)</c>. If no <c>.beam</c> file is found, + <c>code:which(<anno>Module</anno>)</c>. + If no <c>.beam</c> file is found, the error reason <c>non_existing</c> is returned. If the module is already cover compiled with <c>compile_beam/1</c>, the <c>.beam</c> file will be picked from the same location as the first time it was compiled. If the module is already - cover compiled with <c>compile/1,2</c>, there is no way to + cover compiled with <seemfa + marker="#compile/1"><c>compile/1,2</c></seemfa>, there is no way to find the correct <c>.beam</c> file, so the error reason - <c>{already_cover_compiled,no_beam_found,Module}</c> is + <c>{already_cover_compiled, no_beam_found, <anno>Module</anno>}</c> is returned.</p> - <p><c>{error,BeamFile}</c> is returned if the compiled code - cannot be loaded on the node.</p> - <p>If a list of <c>ModFiles</c> is given as input, a list - of <c>Result</c> will be returned. The order of the returned - list is undefined.</p> + <p><c>{error, <anno>BeamFile</anno>}</c> is returned if the compiled + code cannot be loaded on the node.</p> + <p>If a list of <c><anno>ModFiles</anno></c> is given as input, a list + of <c><anno>Result</anno></c> will be returned. The order of + the returned list is undefined.</p> </desc> </func> <func> - <name since="">compile_beam_directory() -> [Result] | {error,Reason}</name> - <name since="">compile_beam_directory(Dir) -> [Result] | {error,Reason}</name> + <name name="compile_beam_directory" arity="0" since=""></name> + <name name="compile_beam_directory" arity="1" since=""></name> <fsummary>Compile all .beam files in a directory for Cover analysis.</fsummary> - <type> - <v>Dir = string()</v> - <v>Result = See compile_beam/1</v> - <v>Reason = eacces | enoent</v> - </type> + <type name="compile_beam_result"/> + <type name="compile_beam_rsn"/> + <type name="file_error"/> <desc> <p>Compiles all modules (<c>.beam</c> files) in a directory - <c>Dir</c> for Cover analysis the same way as - <c>compile_beam/1</c> and returns a list with the return - values.</p> - <p><c>Dir</c> defaults to the current working directory.</p> - <p>The function returns <c>{error,eacces}</c> if the directory is not - readable or <c>{error,enoent}</c> if the directory does not exist.</p> + <c><anno>Dir</anno></c> for Cover analysis the same way as + <seemfa marker="#compile_beam/1"><c>compile_beam/1</c></seemfa> + and returns a list with the return values.</p> + <p><c><anno>Dir</anno></c> defaults to the current working directory.</p> + <p>The function returns <c>{error, eacces}</c> if the directory is not + readable or <c>{error, enoent}</c> if the directory does not exist.</p> </desc> </func> <func> - <name since="OTP 18.0">analyse() -> {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse(Modules) -> OneResult | {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse(Analysis) -> {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse(Level) -> {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse(Modules, Analysis) -> OneResult | {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse(Modules, Level) -> OneResult | {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse(Analysis, Level) -> {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse(Modules, Analysis, Level) -> OneResult | {result,Ok,Fail} | {error,not_main_node}</name> + <name name="analyse" arity="0" since="OTP 18.0"></name> + <name name="analyse" arity="1" clause_i="1" since=""></name> + <name name="analyse" arity="1" clause_i="2" since=""></name> + <name name="analyse" arity="1" clause_i="3" since=""></name> + <name name="analyse" arity="2" clause_i="1" since=""></name> + <name name="analyse" arity="2" clause_i="2" since=""></name> + <name name="analyse" arity="2" clause_i="3" since=""></name> + <name name="analyse" arity="3" since=""></name> <fsummary>Analyse one or more Cover compiled modules.</fsummary> - <type> - <v>Modules = Module | [Module]</v> - <v>Module = atom() </v> - <v>Analysis = coverage | calls</v> - <v>Level = line | clause | function | module</v> - <v>OneResult = {ok,{Module,Value}} | {ok,[{Item,Value}]} | {error, Error}</v> - <v> Item = Line | Clause | Function</v> - <v> Line = {M,N}</v> - <v> Clause = {M,F,A,C}</v> - <v> Function = {M,F,A}</v> - <v> M = F = atom()</v> - <v> N = A = C = integer()</v> - <v> Value = {Cov,NotCov} | Calls</v> - <v> Cov = NotCov = Calls = integer()</v> - <v> Error = {not_cover_compiled,Module}</v> - <v>Ok = [{Module,Value}] | [{Item,Value}]</v> - <v>Fail = [Error]</v> - </type> + <type name="analysis"/> + <type name="level"/> + <type name="modules"/> + <type name="one_result"/> + <type name="analyse_fail"/> + <type name="analyse_ok"/> + <type name="analyse_value"/> + <type name="analyse_item"/> <desc> <p>Performs analysis of one or more Cover compiled modules, as - specified by <c>Analysis</c> and <c>Level</c> (see above), by - examining the contents of the internal database.</p> - <p><c>Analysis</c> defaults to <c>coverage</c> and <c>Level</c> - defaults to <c>function</c>.</p> - <p>If <c>Modules</c> is an atom (one module), the return will - be <c>OneResult</c>, else the return will be - <c>{result,Ok,Fail}</c>.</p> - <p>If <c>Modules</c> is not given, all modules that have data - in the cover data table, are analysed. Note that this - includes both cover compiled modules and imported - modules.</p> + specified by <c><anno>Analysis</anno></c> and + <c><anno>Level</anno></c> (see above), by examining the + contents of the internal database.</p> + <p><c><anno>Analysis</anno></c> defaults to <c>coverage</c> + and <c><anno>Level</anno></c> defaults to <c>function</c>.</p> + <p>If <c><anno>Modules</anno></c> is an atom (one module), the return will + be <c><anno>OneResult</anno></c>, else the return will be + <c>{result, Ok, Fail}</c>.</p> + <p>If <c><anno>Modules</anno></c> is not given, all modules that have data + in the cover data table, are analysed. Note that this + includes both cover compiled modules and imported + modules.</p> <p>If a given module is not Cover compiled, this is indicated - by the error reason <c>{not_cover_compiled,Module}</c>.</p> + by the error reason <c>{not_cover_compiled, <anno>Module</anno>}</c>.</p> </desc> </func> <func> - <name since="OTP 18.0">analyse_to_file() -> {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse_to_file(Modules) -> Answer | {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse_to_file(Options) -> {result,Ok,Fail} | {error,not_main_node}</name> - <name since="">analyse_to_file(Modules,Options) -> Answer | {result,Ok,Fail} | {error,not_main_node}</name> + <name name="analyse_to_file" arity="0" since="OTP 18.0"></name> + <name name="analyse_to_file" arity="1" clause_i="1" since=""></name> + <name name="analyse_to_file" arity="1" clause_i="2" since=""></name> + <name name="analyse_to_file" arity="2" since=""></name> <fsummary>Detailed coverage analysis of one or more Cover compiled modules.</fsummary> - <type> - <v>Modules = Module | [Module]</v> - <v>Module = atom()</v> - <v>OutFile = OutDir = string()</v> - <v>Options = [Option]</v> - <v>Option = html | {outfile,OutFile} | {outdir,OutDir}</v> - <v>Answer = {ok,OutFile} | {error,Error}</v> - <v>Ok = [OutFile]</v> - <v>Fail = [Error]</v> - <v>Error = {not_cover_compiled,Module} | {file,File,Reason} | {no_source_code_found,Module}</v> - <v> File = string()</v> - <v> Reason = term()</v> - </type> + <type name="modules"/> + <type name="analyse_option"/> + <type name="analyse_answer"/> + <type name="analyse_file_ok"/> + <type name="analyse_file_fail"/> + <type name="analyse_rsn"/> <desc> <p>Makes copies of the source file for the given modules, where it for each executable line is specified how many times it has been executed.</p> - <p>The output file <c>OutFile</c> defaults to - <c>Module.COVER.out</c>, or <c>Module.COVER.html</c> if the - option <c>html</c> was used.</p> - <p>If <c>Modules</c> is an atom (one module), the return will - be <c>Answer</c>, else the return will be a - list, <c>{result,Ok,Fail}</c>.</p> - <p>If <c>Modules</c> is not given, all modules that have data - in the cover data table, are analysed. Note that this - includes both cover compiled modules and imported - modules.</p> + <p>The output file <c><anno>OutFile</anno></c> defaults to + <c><anno>Module</anno>.COVER.out</c>, or + <c><anno>Module</anno>.COVER.html</c> if the option + <c>html</c> was used.</p> + <p>If <c><anno>Modules</anno></c> is an atom (one module), the + return will be <c><anno>Answer</anno></c>, else the return + will be a list, <c>{result, Ok, Fail}</c>.</p> + <p>If <c><anno>Modules</anno></c> is not given, all modules + that have da ta in the cover data table, are analysed. Note + that this includes both cover compiled modules and imported + modules.</p> <p>If a module is not Cover compiled, this is indicated by the - error reason <c>{not_cover_compiled,Module}</c>.</p> + error reason <c>{not_cover_compiled, <anno>Module</anno>}</c>.</p> <p>If the source file and/or the output file cannot be opened using - <c>file:open/2</c>, the function returns - <c>{error,{file,File,Reason}}</c> where <c>File</c> is the file - name and <c>Reason</c> is the error reason.</p> + <seemfa marker="kernel:file#open/2"><c>file:open/2</c></seemfa>, + the function returns + <c>{error, {file, <anno>File</anno>, <anno>Reason</anno>}}</c> + where <c><anno>File</anno></c> is the file + name and <c><anno>Reason</anno></c> is the error reason.</p> <p>If a module was cover compiled from the <c>.beam</c> - file, i.e. using <c>compile_beam/1</c> or - <c>compile_beam_directory/0,1</c>, it is assumed that the + file, that is, using <seemfa + marker="#compile_beam/1"><c>compile_beam/1</c></seemfa> or + <seemfa + marker="#compile_beam_directory/0"><c>compile_beam_directory/0,1</c> + </seemfa>,it is assumed that the source code can be found in the same directory as the <c>.beam</c> file, in <c>../src</c> relative to that directory, or using the source path in - <c>Module:module_info(compile)</c>. When using the latter, + <c><anno>Module</anno>:module_info(compile)</c>. When using the latter, two paths are examined: first the one constructed by joining <c>../src</c> and the tail of the compiled path below a trailing <c>src</c> component, then the compiled path itself. If no source code is found, this is indicated by the error reason - <c>{no_source_code_found,Module}</c>.</p> + <c>{no_source_code_found, <anno>Module</anno>}</c>.</p> </desc> </func> <func> - <name since="OTP R14B02">async_analyse_to_file(Module) -> </name> - <name since="OTP R14B02">async_analyse_to_file(Module,Options) -> </name> - <name since="OTP R14B02">async_analyse_to_file(Module, OutFile) -> </name> - <name since="OTP R14B02">async_analyse_to_file(Module, OutFile, Options) -> pid()</name> + <name name="async_analyse_to_file" arity="1" since="OTP R14B02"></name> + <name name="async_analyse_to_file" arity="2" + clause_i="1" since="OTP R14B02"></name> + <name name="async_analyse_to_file" arity="2" + clause_i="2" since="OTP R14B02"></name> + <name name="async_analyse_to_file" arity="3" since="OTP R14B02"></name> <fsummary>Asynchronous call to analyse_to_file.</fsummary> - <type> - <v>Module = atom()</v> - <v>OutFile = string()</v> - <v>Options = [Option]</v> - <v>Option = html</v> - <v>Error = {not_cover_compiled,Module} | {file,File,Reason} | {no_source_code_found,Module} | not_main_node</v> - <v> File = string()</v> - <v> Reason = term()</v> - </type> + <type name="analyse_rsn"/> <desc> - <p>This function works exactly the same way as - <seemfa marker="#analyse_to_file/1">analyse_to_file</seemfa> except - that it is asynchronous instead of synchronous. The spawned process - will link with the caller when created. If an <c>Error</c> occurs - while doing the cover analysis the process will crash with the same - error reason as <seemfa marker="#analyse_to_file/1">analyse_to_file</seemfa> - would return.</p> + <p>This function works exactly the same way as + <seemfa marker="#analyse_to_file/1"><c>analyse_to_file</c></seemfa> except + that it is asynchronous instead of synchronous. The spawned process + will link with the caller when created. If an error of type + <c>analyse_rsn()</c> occurs + while doing the cover analysis the process will crash with the same + error reason as <seemfa marker="#analyse_to_file/1"><c>analyse_to_file</c></seemfa> + would return.</p> </desc> </func> <func> - <name since="">modules() -> [Module] | {error,not_main_node}</name> + <name name="modules" arity="0" since=""></name> <fsummary>Return all Cover compiled modules.</fsummary> - <type> - <v>Module = atom()</v> - </type> <desc> <p>Returns a list with all modules that are currently Cover compiled.</p> </desc> </func> <func> - <name since="">imported_modules() -> [Module] | {error,not_main_node}</name> + <name name="imported_modules" arity="0" since=""></name> <fsummary>Return all modules for which there are imported data.</fsummary> - <type> - <v>Module = atom()</v> - </type> <desc> <p>Returns a list with all modules for which there are imported data.</p> </desc> </func> <func> - <name since="">imported() -> [File] | {error,not_main_node}</name> + <name name="imported" arity="0" since=""></name> <fsummary>Return all imported files.</fsummary> - <type> - <v>File = string()</v> - </type> <desc> <p>Returns a list with all imported files.</p> </desc> </func> <func> - <name since="">which_nodes() -> [Node] | {error,not_main_node}</name> + <name name="which_nodes" arity="0" since=""></name> <fsummary>Return all nodes that are part of the coverage analysis.</fsummary> - <type> - <v>Node = atom()</v> - </type> <desc> <p>Returns a list with all nodes that are part of the coverage analysis. Note that the current node is not returned. This @@ -441,67 +404,56 @@ </desc> </func> <func> - <name since="">is_compiled(Module) -> {file,File} | false | {error,not_main_node}</name> + <name name="is_compiled" arity="1" since=""></name> <fsummary>Check if a module is Cover compiled.</fsummary> - <type> - <v>Module = atom()</v> - <v>Beam = string()</v> - </type> <desc> - <p>Returns <c>{file,File}</c> if the module <c>Module</c> is - Cover compiled, or <c>false</c> otherwise. <c>File</c> is - the <c>.erl</c> file used by <c>cover:compile_module/1,2</c> - or the <c>.beam</c> file used by <c>compile_beam/1</c>.</p> + <p>Returns <c>{file, <anno>File</anno>}</c> if the module + <c><anno>Module</anno></c> is + Cover compiled, or <c>false</c> otherwise. <c><anno>File</anno></c> is + the <c>.erl</c> file used by + <seemfa marker="#compile_module/1"><c>compile_module/1,2</c></seemfa> + or the <c>.beam</c> file used by + <seemfa marker="#compile_beam/1"><c>compile_beam/1</c></seemfa>.</p> </desc> </func> <func> - <name since="">reset(Module) -></name> - <name since="">reset() -> ok | {error,not_main_node}</name> + <name name="reset" arity="0" since=""></name> + <name name="reset" arity="1" since=""></name> <fsummary>Reset coverage data for Cover compiled modules.</fsummary> - <type> - <v>Module = atom()</v> - </type> <desc> <p>Resets all coverage data for a Cover compiled module - <c>Module</c> in the Cover database on all nodes. If the + <c><anno>Module</anno></c> in the Cover database on all nodes. If the argument is omitted, the coverage data will be reset for all modules known by Cover.</p> - <p>If <c>Module</c> is not Cover compiled, the function returns - <c>{error,{not_cover_compiled,Module}}</c>.</p> + <p>If <c><anno>Module</anno></c> is not Cover compiled, the function returns + <c>{error, {not_cover_compiled, <anno>Module</anno>}}</c>.</p> </desc> </func> <func> - <name since="">export(ExportFile)</name> - <name since="">export(ExportFile,Module) -> ok | {error,Reason}</name> + <name name="export" arity="1" since=""></name> + <name name="export" arity="2" since=""></name> <fsummary>Reset coverage data for Cover compiled modules.</fsummary> - <type> - <v>ExportFile = string()</v> - <v>Module = atom()</v> - <v>Reason = {not_cover_compiled,Module} | {cant_open_file,ExportFile,Reason} | not_main_node</v> - </type> + <type name="export_reason"/> <desc> - <p>Exports the current coverage data for <c>Module</c> to the - file <c>ExportFile</c>. It is recommended to name the - <c>ExportFile</c> with the extension <c>.coverdata</c>, since + <p>Exports the current coverage data for <c><anno>Module</anno></c> to the + file <c><anno>ExportFile</anno></c>. It is recommended to name the + <c><anno>ExportFile</anno></c> with the extension <c>.coverdata</c>, since other filenames cannot be read by the web based interface to cover.</p> - <p>If <c>Module</c> is not given, data for all Cover compiled + <p>If <c><anno>Module</anno></c> is not given, data for all Cover compiled or earlier imported modules is exported.</p> <p>This function is useful if coverage data from different systems is to be merged.</p> - <p>See also <c>cover:import/1</c></p> + <p>See also <seemfa marker="#import/1"><c>import/1</c></seemfa>.</p> </desc> </func> <func> - <name since="">import(ExportFile) -> ok | {error,Reason}</name> + <name name="import" arity="1" since=""></name> <fsummary>Reset coverage data for Cover compiled modules.</fsummary> - <type> - <v>ExportFile = string()</v> - <v>Reason = {cant_open_file,ExportFile,Reason} | not_main_node</v> - </type> <desc> - <p>Imports coverage data from the file <c>ExportFile</c> - created with <c>cover:export/1,2</c>. Any analysis performed + <p>Imports coverage data from the file <c><anno>ExportFile</anno></c> + created with <seemfa marker="#export/1"><c>export/1,2</c></seemfa>. + Any analysis performed after this will include the imported data.</p> <p>Note that when compiling a module <em>all existing coverage data is removed</em>, including imported data. If a module is already compiled when data is imported, the imported data is @@ -513,22 +465,19 @@ same file twice unless the module is first reset or compiled. The check is based on the filename, so you can easily fool the system by renaming your export file.</p> - <p>See also <c>cover:export/1,2</c></p> + <p>See also <seemfa marker="#export/1"><c>export/1,2</c></seemfa>.</p> </desc> </func> <func> - <name since="">stop() -> ok | {error,not_main_node}</name> + <name name="stop" arity="0" since=""></name> <fsummary>Stop Cover.</fsummary> <desc> <p>Stops the Cover server and unloads all Cover compiled code.</p> </desc> </func> <func> - <name since="">stop(Nodes) -> ok | {error,not_main_node}</name> + <name name="stop" arity="1" since=""></name> <fsummary>Stop Cover on remote nodes.</fsummary> - <type> - <v>Nodes = [atom()]</v> - </type> <desc> <p>Stops the Cover server and unloads all Cover compiled code on the given nodes. Data stored in the Cover database on the @@ -536,11 +485,8 @@ </desc> </func> <func> - <name since="OTP R16B">flush(Nodes) -> ok | {error,not_main_node}</name> + <name name="flush" arity="1" since="OTP R16B"></name> <fsummary>Collect cover data from remote nodes.</fsummary> - <type> - <v>Nodes = [atom()]</v> - </type> <desc> <p>Fetch data from the Cover database on the remote nodes and stored on the main node.</p> diff --git a/lib/tools/doc/src/cprof.xml b/lib/tools/doc/src/cprof.xml index 03675b3e49..3009adde07 100644 --- a/lib/tools/doc/src/cprof.xml +++ b/lib/tools/doc/src/cprof.xml @@ -60,69 +60,61 @@ of tracing since no trace message has to be generated. Some measurements indicates performance degradation in the vicinity of 10 percent. - <marker id="analyse"></marker> -</p> + </p> </description> <funcs> <func> - <name since="">analyse() -> {AllCallCount, ModAnalysisList}</name> - <name since="">analyse(Limit) -> {AllCallCount, ModAnalysisList}</name> - <name since="">analyse(Mod) -> ModAnalysis</name> - <name since="">analyse(Mod, Limit) -> ModAnalysis</name> + <name name="analyse" arity="0" since=""></name> + <name name="analyse" arity="1" clause_i="1" since=""></name> + <name name="analyse" arity="1" clause_i="2" since=""></name> + <name name="analyse" arity="2" since=""></name> <fsummary>Collect and analyse call counters.</fsummary> - <type> - <v>Limit = integer()</v> - <v>Mod = atom()</v> - <v>AllCallCount = integer()</v> - <v>ModAnalysisList = [ModAnalysis]</v> - <v>ModAnalysis = {Mod, ModCallCount, FuncAnalysisList}</v> - <v>ModCallCount = integer()</v> - <v>FuncAnalysisList = [{{Mod, Func, Arity}, FuncCallCount}]</v> - <v>Func = atom()</v> - <v>Arity = integer()</v> - <v>FuncCallCount = integer()</v> - </type> + <type name="mod_analysis_list"/> + <type name="mod_analysis"/> + <type name="func_analysis_list"/> <desc> <p>Collects and analyses the call counters presently in the - node for either module <c>Mod</c>, or for all modules + node for either module <c><anno>Mod</anno></c>, or for all modules (except <c>cprof</c> itself), and returns: </p> <taglist> - <tag><c>FuncAnalysisList</c></tag> + <tag><c><anno>FuncAnalysisList</anno></c></tag> <item>A list of tuples, one for each function in a module, in - decreasing <c>FuncCallCount</c> order.</item> - <tag><c>ModCallCount</c></tag> - <item>The sum of <c>FuncCallCount</c> values for all - functions in module <c>Mod</c>.</item> - <tag><c>AllCallCount</c></tag> - <item>The sum of <c>ModCallCount</c> values for all modules - concerned in <c>ModAnalysisList</c>.</item> - <tag><c>ModAnalysisList</c></tag> + decreasing <c><anno>FuncCallCount</anno></c> order.</item> + <tag><c><anno>ModCallCount</anno></c></tag> + <item>The sum of <c><anno>FuncCallCount</anno></c> values for all + functions in module <c><anno>Mod</anno></c>.</item> + <tag><c><anno>AllCallCount</anno></c></tag> + <item>The sum of <c><anno>ModCallCount</anno></c> values for all modules + concerned in <c><anno>ModAnalysisList</anno></c>.</item> + <tag><c><anno>ModAnalysisList</anno></c></tag> <item>A list of tuples, one for each module except - <c>cprof</c>, in decreasing <c>ModCallCount</c> order.</item> + <c>cprof</c>, in decreasing <c><anno>ModCallCount</anno></c> order.</item> </taglist> <p>If call counters are still running while <c>analyse/0..2</c> is executing, you might get an inconsistent result. This happens if the process executing <c>analyse/0..2</c> gets scheduled out so some other process can increment the counters that are being analysed, Calling - <c>pause()</c> before analysing takes care of the problem. + <seemfa marker="#pause/0"><c>pause()</c></seemfa> + before analysing takes care of the problem. </p> - <p>If the <c>Mod</c> argument is given, the result contains a - <c>ModAnalysis</c> tuple for module <c>Mod</c> only, - otherwise the result contains one <c>ModAnalysis</c> tuple - for all modules returned from <c>code:all_loaded()</c> - except <c>cprof</c> itself. + <p>If the <c><anno>Mod</anno></c> argument is given, the + result contains a <c><anno>ModAnalysis</anno></c> tuple for + module <c><anno>Mod</anno></c> only, otherwise the result + contains one <c><anno>ModAnalysis</anno></c> tuple for all + modules returned from <seemfa + marker="kernel:code#all_loaded/0"> + <c>code:all_loaded()</c></seemfa> except <c>cprof</c> itself. </p> - <p>All functions with a <c>FuncCallCount</c> lower than - <c>Limit</c> are excluded from <c>FuncAnalysisList</c>. They - are still included in <c>ModCallCount</c>, though. - The default value for <c>Limit</c> is <c>1</c>. - <marker id="pause_0"></marker> -</p> + <p>All functions with a <c><anno>FuncCallCount</anno></c> + lower than <c><anno>Limit</anno></c> are excluded from + <c><anno>FuncAnalysisList</anno></c>. They are still included + in <c><anno>ModCallCount</anno></c>, though. The default value + for <c><anno>Limit</anno></c> is <c>1</c>.</p> </desc> </func> <func> - <name since="">pause() -> integer()</name> + <name name="pause" arity="0" since=""></name> <fsummary>Pause running call count trace for all functions.</fsummary> <desc> <p>Pause call count tracing for all functions in all modules @@ -131,28 +123,21 @@ <c>(pause({'_','_','_'})+stop({on_load}))</c>. </p> <p>See also - <seeerl marker="#pause">pause/1..3</seeerl> below. - <marker id="pause"></marker> -</p> + <seemfa marker="#pause/1"><c>pause/1..3</c></seemfa> below. + </p> </desc> </func> <func> - <name since="">pause(FuncSpec) -> integer()</name> - <name since="">pause(Mod, Func) -> integer()</name> - <name since="">pause(Mod, Func, Arity) -> integer()</name> + <name name="pause" arity="1" since=""></name> + <name name="pause" arity="2" since=""></name> + <name name="pause" arity="3" since=""></name> <fsummary>Pause running call count trace for matching functions.</fsummary> - <type> - <v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v> - <v>Mod = atom()</v> - <v>Func = atom()</v> - <v>Arity = integer()</v> - <v>FS = term()</v> - </type> <desc> - <p>Pause call counters for matching functions in matching - modules. The <c>FS</c> argument can be used to - specify the first argument to - <c>erlang:trace_pattern/3</c>. See erlang(3). + + <p>Pause call counters for matching functions in matching + modules. The <c><anno>FS</anno></c> argument can be used to + specify the first argument to <seemfa + marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern/3</c></seemfa>. </p> <p>The call counters for all matching functions that has got call count breakpoints are paused at their current @@ -160,44 +145,35 @@ </p> <p>Return the number of matching functions that can have call count breakpoints, the same as - <c>start/0..3</c> with the same arguments would have - returned. - <marker id="restart"></marker> -</p> + <seemfa marker="#start/0"><c>start/0..3</c></seemfa> + with the same arguments would have returned. + </p> </desc> </func> <func> - <name since="">restart() -> integer()</name> - <name since="">restart(FuncSpec) -> integer()</name> - <name since="">restart(Mod, Func) -> integer()</name> - <name since="">restart(Mod, Func, Arity) -> integer()</name> + <name name="restart" arity="0" since=""></name> + <name name="restart" arity="1" since=""></name> + <name name="restart" arity="2" since=""></name> + <name name="restart" arity="3" since=""></name> <fsummary>Restart existing call counters for matching functions.</fsummary> - <type> - <v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v> - <v>Mod = atom()</v> - <v>Func = atom()</v> - <v>Arity = integer()</v> - <v>FS = term()</v> - </type> <desc> <p>Restart call counters for the matching functions in - matching modules that are call count traced. The <c>FS</c> - argument can be used to specify the first argument to - <c>erlang:trace_pattern/3</c>. See erlang(3). + matching modules that are call count traced. The <c><anno>FS</anno></c> + argument can be used to specify the first argument to <seemfa + marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern/3</c></seemfa>. </p> <p>The call counters for all matching functions that has got call count breakpoints are set to zero and running. </p> <p>Return the number of matching functions that can have call count breakpoints, the same as - <c>start/0..3</c> with the same arguments would have - returned. - <marker id="start_0"></marker> -</p> + <seemfa marker="#start/0"><c>start/0..3</c></seemfa> + with the same arguments would have returned. + </p> </desc> </func> <func> - <name since="">start() -> integer()</name> + <name name="start" arity="0" since=""></name> <fsummary>Start call count tracing for all functions.</fsummary> <desc> <p>Start call count tracing for all functions in all modules, @@ -206,28 +182,21 @@ <c>(start({'_','_','_'})+start({on_load}))</c>. </p> <p>See also - <seeerl marker="#start">start/1..3</seeerl> below. - <marker id="start"></marker> -</p> + <seemfa marker="#start/1"><c>start/1..3</c></seemfa> below. + </p> </desc> </func> <func> - <name since="">start(FuncSpec) -> integer()</name> - <name since="">start(Mod, Func) -> integer()</name> - <name since="">start(Mod, Func, Arity) -> integer()</name> + <name name="start" arity="1" since=""></name> + <name name="start" arity="2" since=""></name> + <name name="start" arity="3" since=""></name> <fsummary>Start call count tracing for matching functions.</fsummary> - <type> - <v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v> - <v>Mod = atom()</v> - <v>Func = atom()</v> - <v>Arity = integer()</v> - <v>FS = term()</v> - </type> <desc> <p>Start call count tracing for matching functions in matching - modules. The <c>FS</c> argument can be used to specify the - first argument to <c>erlang:trace_pattern/3</c>, for example - <c>on_load</c>. See erlang(3). + modules. The <c><anno>FS</anno></c> argument can be used to specify the + first argument to <seemfa + marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern/3</c></seemfa>, + for example <c>on_load</c>. </p> <p>Set call count breakpoints on the matching functions that has no call count breakpoints. Call counters @@ -235,12 +204,11 @@ </p> <p>Return the number of matching functions that has got call count breakpoints. - <marker id="stop_0"></marker> -</p> + </p> </desc> </func> <func> - <name since="">stop() -> integer()</name> + <name name="stop" arity="0" since=""></name> <fsummary>Stop call count tracing for all functions.</fsummary> <desc> <p>Stop call count tracing for all functions in all modules, @@ -249,36 +217,29 @@ <c>(stop({'_','_','_'})+stop({on_load}))</c>. </p> <p>See also - <seeerl marker="#stop">stop/1..3</seeerl> below. - <marker id="stop"></marker> -</p> + <seemfa marker="#stop/1"><c>stop/1..3</c></seemfa> below. + </p> </desc> </func> <func> - <name since="">stop(FuncSpec) -> integer()</name> - <name since="">stop(Mod, Func) -> integer()</name> - <name since="">stop(Mod, Func, Arity) -> integer()</name> + <name name="stop" arity="1" since=""></name> + <name name="stop" arity="2" since=""></name> + <name name="stop" arity="3" since=""></name> <fsummary>Stop call count tracing for matching functions.</fsummary> - <type> - <v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v> - <v>Mod = atom()</v> - <v>Func = atom()</v> - <v>Arity = integer()</v> - <v>FS = term()</v> - </type> <desc> <p>Stop call count tracing for matching functions in matching - modules. The <c>FS</c> argument can be used to specify the - first argument to <c>erlang:trace_pattern/3</c>, for example - <c>on_load</c>. See erlang(3). + modules. The <c><anno>FS</anno></c> argument can be used to specify the + first argument to <seemfa + marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern/3</c></seemfa>, + for example <c>on_load</c>. </p> <p>Remove call count breakpoints from the matching functions that has call count breakpoints. </p> <p>Return the number of matching functions that can have call count breakpoints, the same as - <c>start/0..3</c> with the same arguments would have - returned. + <seemfa marker="#start/0"><c>start/0..3</c></seemfa> + with the same arguments would have returned. </p> </desc> </func> diff --git a/lib/tools/doc/src/eprof.xml b/lib/tools/doc/src/eprof.xml index c200c1b94f..b10624751f 100644 --- a/lib/tools/doc/src/eprof.xml +++ b/lib/tools/doc/src/eprof.xml @@ -40,104 +40,87 @@ </description> <funcs> <func> - <name since="">start() -> {ok,Pid} | {error,Reason}</name> + <name name="start" arity="0" since=""></name> <fsummary>Start Eprof.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Reason = {already_started,Pid}</v> - </type> <desc> <p>Starts the Eprof server which holds the internal state of the collected data.</p> </desc> </func> <func> - <name since="">start_profiling(Rootset) -> profiling | {error, Reason}</name> - <name since="OTP R14B">start_profiling(Rootset,Pattern) -> profiling | {error, Reason}</name> - <name since="OTP R16B01">start_profiling(Rootset,Pattern,Options) -> profiling | {error, Reason}</name> + <name name="start_profiling" arity="1" since=""></name> + <name name="start_profiling" arity="2" since="OTP R14B"></name> + <name name="start_profiling" arity="3" since="OTP R16B01"></name> <fsummary>Start profiling.</fsummary> - <type> - <v>Rootset = [atom() | pid()]</v> - <v>Pattern = {Module, Function, Arity}</v> - <v>Module = Function = atom()</v> - <v>Arity = integer()</v> - <v>Options = [set_on_spawn]</v> - <v>Reason = term()</v> - </type> + <type name="trace_pattern_mfa"/> <desc> - <p>Starts profiling for the processes in <c>Rootset</c> (and any new + <p>Starts profiling for the processes in <c><anno>Rootset</anno></c> (and any new processes spawned from them). Information about activity in any profiled process is stored in the Eprof database.</p> - <p><c>Rootset</c> is a list of pids and registered names.</p> + <p><c><anno>Rootset</anno></c> is a list of pids and registered names.</p> <p>The function returns <c>profiling</c> if tracing could be enabled - for all processes in <c>Rootset</c>, or <c>error</c> otherwise.</p> + for all processes in <c><anno>Rootset</anno></c>, or <c>error</c> otherwise.</p> <p>A pattern can be selected to narrow the profiling. For instance a specific module can be selected, and only the code executed in that module will be profiled.</p> - <p>The <c>set_on_spawn</c> option will active call time tracing for - all processes spawned by processes in the rootset. This is - the default behaviour.</p> + <p>The <c>set_on_spawn</c> option will active call time tracing for + all processes spawned by processes in the rootset. This is + the default behaviour.</p> </desc> </func> <func> - <name since="">stop_profiling() -> profiling_stopped | profiling_already_stopped</name> + <name name="stop_profiling" arity="0" since=""></name> <fsummary>Stop profiling.</fsummary> <desc> - <p>Stops profiling started with <c>start_profiling/1</c> or - <c>profile/1</c>.</p> + <p>Stops profiling started with + <seemfa marker="#start_profiling/1"><c>start_profiling/1</c></seemfa> + or + <seemfa marker="#profile/1"><c>prifile/1</c></seemfa>.</p> </desc> </func> <func> - <name since="">profile(Fun) -> profiling | {error, Reason}</name> - <name since="">profile(Fun, Options) -> profiling | {error, Reason}</name> - <name since="">profile(Rootset) -> profiling | {error, Reason}</name> - <name since="">profile(Rootset,Fun) -> {ok, Value} | {error,Reason}</name> - <name since="OTP R14B">profile(Rootset,Fun,Pattern) -> {ok, Value} | {error, Reason}</name> - <name since="">profile(Rootset,Module,Function,Args) -> {ok, Value} | {error, Reason}</name> - <name since="OTP R14B">profile(Rootset,Module,Function,Args,Pattern) -> {ok, Value} | {error, Reason}</name> - <name since="OTP R16B01">profile(Rootset,Module,Function,Args,Pattern,Options) -> {ok, Value} | {error, Reason}</name> + <name name="profile" arity="1" clause_i="1" since=""></name> + <name name="profile" arity="2" clause_i="1" since=""></name> + <name name="profile" arity="1" clause_i="2" since=""></name> + <name name="profile" arity="2" clause_i="2" since=""></name> + <name name="profile" arity="3" since="OTP R14B"></name> + <name name="profile" arity="4" clause_i="1" since=""></name> + <name name="profile" arity="4" clause_i="2" since=""></name> + <name name="profile" arity="5" since="OTP R14B"></name> + <name name="profile" arity="6" since="OTP R16B01"></name> <fsummary>Start profiling.</fsummary> - <type> - <v>Rootset = [atom() | pid()]</v> - <v>Fun = fun() -> term() end</v> - <v>Pattern = {Module, Function, Arity}</v> - <v>Module = Function = atom()</v> - <v>Args = [term()]</v> - <v>Arity = integer()</v> - <v>Options = [set_on_spawn]</v> - <v>Value = Reason = term()</v> - </type> + <type name="trace_pattern_mfa"/> <desc> <p>This function first spawns a process <c>P</c> which evaluates - <c>Fun()</c> or <c>apply(Module,Function,Args)</c>. Then, it - starts profiling for <c>P</c> and the processes in <c>Rootset</c> + <c><anno>Fun</anno>()</c> or + <c>apply(<anno>Module</anno>,<anno>Function</anno>,<anno>Args</anno>)</c>. + Then, it starts profiling for <c>P</c> and the processes in + <c><anno>Rootset</anno></c> (and any new processes spawned from them). Information about activity in any profiled process is stored in the Eprof database.</p> - <p><c>Rootset</c> is a list of pids and registered names.</p> + <p><c><anno>Rootset</anno></c> is a list of pids and registered names.</p> <p>If tracing could be enabled for <c>P</c> and all processes in - <c>Rootset</c>, the function returns <c>{ok,Value}</c> when - <c>Fun()</c>/<c>apply</c> returns with the value <c>Value</c>, or - <c>{error,Reason}</c> if <c>Fun()</c>/<c>apply</c> fails with - exit reason <c>Reason</c>. Otherwise it returns <c>{error, Reason}</c> + <c><anno>Rootset</anno></c>, the function returns + <c>{ok,<anno>Value</anno>}</c> when + <c><anno>Fun</anno>()</c>/<c>apply</c> returns with the value + <c><anno>Value</anno></c>, or <c>{error,<anno>Reason</anno>}</c> + if <c><anno>Fun</anno>()</c>/<c>apply</c> fails with + exit reason <c><anno>Reason</anno></c>. Otherwise it returns + <c>{error, <anno>Reason</anno>}</c> immediately.</p> - <p>The <c>set_on_spawn</c> option will active call time tracing for - all processes spawned by processes in the rootset. This is - the default behaviour.</p> + <p>The <c>set_on_spawn</c> option will active call time tracing for + all processes spawned by processes in the rootset. This is + the default behaviour.</p> <p>The programmer must ensure that the function given as argument is truly synchronous and that no work continues after the function has returned a value.</p> </desc> </func> <func> - <name since="OTP R14B">analyze() -> ok</name> - <name since="OTP R14B">analyze(Type) -> ok</name> - <name since="OTP R14B">analyze(Type,Options) -> ok</name> + <name name="analyze" arity="0" since="OTP R14B"></name> + <name name="analyze" arity="1" since="OTP R14B"></name> + <name name="analyze" arity="2" since="OTP R14B"></name> <fsummary>Display profiling results per process.</fsummary> - <type> - <v>Type = procs | total</v> - <v>Options = [{filter, Filter} | {sort, Sort}</v> - <v>Filter = [{calls, integer()} | {time, float()}]</v> - <v>Sort = time | calls | mfa</v> - </type> + <type name="analyze_type"/> <desc> <p>Call this function when profiling has been stopped to display the results per process, that is:</p> @@ -145,26 +128,24 @@ <item>how much time has been used by each process, and</item> <item>in which function calls this time has been spent.</item> </list> - <p>Call <c>analyze</c> with <c>total</c> option when profiling has been stopped to display + <p>Call <c>analyze</c> with <c>total</c> option when profiling has been stopped to display the results per function call, that is in which function calls the time has been spent.</p> <p>Time is shown as percentage of total time and as absolute time.</p> </desc> </func> <func> - <name since="">log(File) -> ok</name> + <name name="log" arity="1" since=""></name> <fsummary>Activate logging of <c>eprof</c>printouts.</fsummary> - <type> - <v>File = atom() | string()</v> - </type> <desc> <p>This function ensures that the results displayed by - <c>analyze/0,1,2</c> are printed both to the file - <c>File</c> and the screen.</p> + <seemfa marker="#analyze/0"><c>analyze/0,1,2</c></seemfa> + are printed both to the file + <c><anno>File</anno></c> and the screen.</p> </desc> </func> <func> - <name since="">stop() -> stopped</name> + <name name="stop" arity="0" since=""></name> <fsummary>Stop Eprof.</fsummary> <desc> <p>Stops the Eprof server.</p> diff --git a/lib/tools/doc/src/fprof.xml b/lib/tools/doc/src/fprof.xml index b3ba4a200c..7a0b751e66 100644 --- a/lib/tools/doc/src/fprof.xml +++ b/lib/tools/doc/src/fprof.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2001</year><year>2018</year> + <year>2001</year><year>2020</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -96,47 +96,39 @@ </p> <p><c>fprof</c> can also skip the file step and trace to a tracer process that does the profiling in runtime. - <marker id="start"></marker> </p> </description> <funcs> <func> - <name since="">start() -> {ok, Pid} | {error, {already_started, Pid}}</name> + <name name="start" arity="0" since=""></name> <fsummary>Starts the <c>fprof</c> server.</fsummary> - <type> - <v>Pid = pid()</v> - </type> <desc> <p>Starts the <c>fprof</c> server. </p> <p>Note that it seldom needs to be started explicitly since it is automatically started by the functions that need a running server. - <marker id="stop"></marker> -</p> + </p> </desc> </func> <func> - <name since="">stop() -> ok</name> + <name name="stop" arity="0" since=""></name> <fsummary>Same as <c>stop(normal)</c>.</fsummary> <desc> <p>Same as <c>stop(normal)</c>.</p> </desc> </func> <func> - <name since="">stop(Reason) -> ok</name> + <name name="stop" arity="1" since=""></name> <fsummary>Stops the <c>fprof</c> server.</fsummary> - <type> - <v>Reason = term()</v> - </type> <desc> <p>Stops the <c>fprof</c> server. </p> - <p>The supplied <c>Reason</c> becomes the exit reason for the + <p>The supplied <c><anno>Reason</anno></c> becomes the exit reason for the server process. Default Any - <c>Reason</c> other than <c>kill</c> sends a request to the + <c><anno>Reason</anno></c> other than <c>kill</c> sends a request to the server and waits for it to clean up, reply and exit. If - <c>Reason</c> is <c>kill</c>, the server is bluntly killed. + <c><anno>Reason</anno></c> is <c>kill</c>, the server is bluntly killed. </p> <p>If the <c>fprof</c> server is not running, this function returns immediately with the same return value. @@ -145,63 +137,52 @@ <p>When the <c>fprof</c> server is stopped the collected raw profile data is lost.</p> </note> - <marker id="apply"></marker> </desc> </func> <func> - <name since="">apply(Func, Args) -> term()</name> - <fsummary>Same as <c>apply(Func, Args, [])</c>.</fsummary> - <type> - <v>Func = function() | {Module, Function}</v> - <v>Args = [term()]</v> - <v>Module = atom()</v> - <v>Function = atom()</v> - </type> + <name name="apply" arity="2" since=""></name> + <fsummary>Same as <c>apply(<anno>Func</anno>, <anno>Args</anno>, [])</c>. + </fsummary> <desc> - <p>Same as <c>apply(Func, Args, [])</c>.</p> + <p>Same as <c>apply(<anno>Func</anno>, <anno>Args</anno>, [])</c>.</p> </desc> </func> <func> - <name since="">apply(Module, Function, Args) -> term()</name> - <fsummary>Same as <c>apply({Module, Function}, Args, [])</c>.</fsummary> - <type> - <v>Args = [term()]</v> - <v>Module = atom()</v> - <v>Function = atom()</v> - </type> + <name name="apply" arity="3" clause_i="1" since=""></name> + <fsummary>Same as <c>apply({<anno>Module</anno>, <anno>Function</anno>}, + <anno>Args</anno>, [])</c>.</fsummary> <desc> - <p>Same as <c>apply({Module, Function}, Args, [])</c>.</p> + <p>Same as <c>apply({<anno>Module</anno>, <anno>Function</anno>}, + <anno>Args</anno>, [])</c>.</p> </desc> </func> <func> - <name since="">apply(Func, Args, OptionList) -> term()</name> - <fsummary>Calls <c>erlang:apply(Func, Args)</c>surrounded by<c>trace([start | OptionList])</c>and<c>trace(stop)</c>.</fsummary> - <type> - <v>Func = function() | {Module, Function}</v> - <v>Args = [term()]</v> - <v>OptionList = [Option]</v> - <v>Module = atom()</v> - <v>Function = atom()</v> - <v>Option = continue | start | {procs, PidList} | TraceStartOption</v> - </type> + <name name="apply" arity="3" clause_i="2" since=""></name> + <fsummary>Calls <c>erlang:apply(<anno>Func</anno>, <anno>Args</anno>)</c> + surrounded by <c>trace([start | <anno>OptionList</anno>])</c> + and <c>trace(stop)</c>.</fsummary> + <type name="apply_option"/> + <type name="trace_option"/> + <type name="pid_spec"/> <desc> - <p>Calls <c>erlang:apply(Func, Args)</c> surrounded by - <c>trace([start, ...])</c> and - <c>trace(stop)</c>. + <p>Calls <c>erlang:apply(<anno>Func</anno>, <anno>Args</anno>)</c> + surrounded by <c>trace([start, ...])</c> and <c>trace(stop)</c>. </p> <p>Some effort is made to keep the trace clean from unnecessary trace messages; tracing is started and stopped from a spawned - process while the <c>erlang:apply/2</c> call is made in the + process while the + <seemfa marker="erts:erlang#apply/2"><c>erlang:apply/2</c></seemfa> + call is made in the current process, only surrounded by <c>receive</c> and <c>send</c> statements towards the trace starting process. The trace starting process exits when not needed any more. </p> - <p>The <c>TraceStartOption</c> is any option allowed for - <c>trace/1</c>. The options - <c>[start, {procs, [self() | PidList]} | OptList]</c> + <p>The <c><anno>TraceStartOption</anno></c> is any option allowed for + <seemfa marker="#trace/1"><c>trace/1</c></seemfa>. The options + <c>[start, {procs, [self() | <anno>PidList</anno>]} | OptList]</c> are given to <c>trace/1</c>, where <c>OptList</c> is - <c>OptionList</c> with <c>continue</c>, <c>start</c> + <c><anno>OptionList</anno></c> with <c>continue</c>, <c>start</c> and <c>{procs, _}</c> options removed. </p> <p>The <c>continue</c> option inhibits the call to @@ -210,107 +191,88 @@ </desc> </func> <func> - <name since="">apply(Module, Function, Args, OptionList) -> term()</name> - <fsummary>Same as <c>apply({Module, Function}, Args, OptionList)</c>.</fsummary> - <type> - <v>Module = atom()</v> - <v>Function = atom()</v> - <v>Args = [term()]</v> - </type> + <name name="apply" arity="4" since=""></name> + <fsummary>Same as <c>apply({<anno>Module</anno>, <anno>Function</anno>}, + <anno>Args</anno>, <anno>OptionList</anno>)</c>.</fsummary> + <type name="apply_option"/> + <type name="trace_option"/> + <type name="pid_spec"/> <desc> <p>Same as - <c>apply({Module, Function}, Args, OptionList)</c>. + <c>apply({<anno>Module</anno>, <anno>Function</anno>}, + <anno>Args</anno>, <anno>OptionList</anno>)</c>. + </p> + <p><c><anno>OptionList</anno></c> is an option list allowed for + <seemfa marker="#apply/3"><c>apply/3</c></seemfa>. </p> - <p><c>OptionList</c> is an option list allowed for - <c>apply/3</c>. - <marker id="trace"></marker> -</p> </desc> </func> <func> - <name since="">trace(start, Filename) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>trace([start, {file, Filename}])</c>.</fsummary> - <type> - <v>Reason = term()</v> - </type> + <name name="trace" arity="2" clause_i="1" since=""></name> + <fsummary>Same as <c>trace([start, {file, <anno>Filename</anno>}])</c>. + </fsummary> <desc> - <p>Same as <c>trace([start, {file, Filename}])</c>.</p> + <p>Same as <c>trace([start, {file, <anno>Filename</anno>}])</c>.</p> </desc> </func> <func> - <name since="">trace(verbose, Filename) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>trace([start, verbose, {file, Filename}])</c>.</fsummary> - <type> - <v>Reason = term()</v> - </type> + <name name="trace" arity="2" clause_i="2" since=""></name> + <fsummary>Same as <c>trace([start, verbose, + {file, <anno>Filename</anno>}])</c>.</fsummary> <desc> <p>Same as - <c>trace([start, verbose, {file, Filename}])</c>.</p> + <c>trace([start, verbose, {file, <anno>Filename</anno>}])</c>.</p> </desc> </func> <func> - <name since="">trace(OptionName, OptionValue) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>trace([{OptionName, OptionValue}])</c>.</fsummary> - <type> - <v>OptionName = atom()</v> - <v>OptionValue = term()</v> - <v>Reason = term()</v> - </type> + <name name="trace" arity="2" clause_i="3" since=""></name> + <fsummary>Same as <c>trace([{<anno>OptionName</anno>, + <anno>OptionValue</anno>}])</c>.</fsummary> <desc> <p>Same as - <c>trace([{OptionName, OptionValue}])</c>.</p> + <c>trace([{<anno>OptionName</anno>, <anno>OptionValue</anno>}])</c>. + </p> </desc> </func> <func> - <name since="">trace(verbose) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> + <name name="trace" arity="1" clause_i="1" since=""></name> <fsummary>Same as <c>trace([start, verbose])</c>.</fsummary> - <type> - <v>Reason = term()</v> - </type> <desc> <p>Same as <c>trace([start, verbose])</c>.</p> </desc> </func> <func> - <name since="">trace(OptionName) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>trace([OptionName])</c>.</fsummary> - <type> - <v>OptionName = atom()</v> - <v>Reason = term()</v> - </type> + <name name="trace" arity="1" clause_i="2" since=""></name> + <fsummary>Same as <c>trace([<anno>OptionName</anno>])</c>.</fsummary> <desc> - <p>Same as <c>trace([OptionName])</c>.</p> + <p>Same as <c>trace([<anno>OptionName</anno>])</c>.</p> </desc> </func> <func> - <name since="">trace({OptionName, OptionValue}) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>trace([{OptionName, OptionValue}])</c>.</fsummary> - <type> - <v>OptionName = atom()</v> - <v>OptionValue = term()</v> - <v>Reason = term()</v> - </type> + <name name="trace" arity="1" clause_i="3" since=""></name> + <fsummary>Same as <c>trace([{<anno>OptionName</anno>, + <anno>OptionValue</anno>}])</c>.</fsummary> <desc> <p>Same as - <c>trace([{OptionName, OptionValue}])</c>.</p> + <c>trace([{<anno>OptionName</anno>, <anno>OptionValue</anno>}])</c>.</p> </desc> </func> <func> - <name since="">trace([Option]) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> + <name name="trace" arity="1" clause_i="4" since=""></name> <fsummary>Starts or stops tracing.</fsummary> - <type> - <v>Option = start | stop | {procs, PidSpec} | {procs, [PidSpec]} | verbose | {verbose, bool()} | file | {file, Filename} | {tracer, Tracer}</v> - <v>PidSpec = pid() | atom()</v> - <v>Tracer = pid() | port()</v> - <v>Reason = term()</v> - </type> + <type name="trace_option"/> + <type name="pid_spec"/> <desc> <p>Starts or stops tracing. </p> - <p><c>PidSpec</c> and <c>Tracer</c> are used in calls to - <c>erlang:trace(PidSpec, true, [{tracer, Tracer} | Flags])</c>, and <c>Filename</c> is used to call - <c>dbg:trace_port(file, Filename)</c>. Please see the - appropriate documentation.</p> + <p><c><anno>PidSpec</anno></c> and <c><anno>Tracer</anno></c> + are used in calls to + <c>erlang:trace(PidSpec, true, [{tracer, Tracer} | Flags])</c>, + and <c>Filename</c> is used to call + <c>dbg:trace_port(file, Filename)</c>. Please see + <seemfa marker="erts:erlang#trace/3"><c>erlang:trace/3</c></seemfa> + and + <seemfa marker="runtime_tools:dbg#trace_port/2"><c>dbg:trace_port/2</c></seemfa>.</p> <p>Option description:</p> <taglist> <tag><c>stop</c></tag> @@ -321,13 +283,13 @@ <item>Clears all tracing from the node and starts a new <c>fprof</c> trace. Either option <c>start</c> or <c>stop</c> must be specified, but not both.</item> - <tag><c>verbose</c>| <c>{verbose, bool()}</c></tag> + <tag><c>verbose</c> | <c>{verbose, boolean()}</c></tag> <item>The options <c>verbose</c> or <c>{verbose, true}</c> adds some trace flags that <c>fprof</c> does not need, but that may be interesting for general debugging purposes. This option is only allowed with the <c>start</c> option.</item> - <tag><c>cpu_time</c>| <c>{cpu_time, bool()}</c></tag> + <tag><c>cpu_time</c> | <c>{cpu_time, boolean()}</c></tag> <item>The options <c>cpu_time</c> or <c>{cpu_time, true}</c> makes the timestamps in the trace be in CPU time instead of wallclock time which is the default. This option is @@ -338,95 +300,77 @@ i.e. <c>erl +S 1 +sbt db</c>.</p> </warning> </item> - <tag><c>{procs, PidSpec}</c>| <c>{procs, [PidSpec]}</c></tag> + <tag><c>{procs, <anno>PidSpec</anno>}</c> | + <c>{procs, [<anno>PidSpec</anno>]}</c></tag> <item>Specifies which processes that shall be traced. If this option is not given, the calling process is traced. All processes spawned by the traced processes are also traced. This option is only allowed with the <c>start</c> option.</item> - <tag><c>file</c>| <c>{file, Filename}</c></tag> + <tag><c>file</c> | <c>{file, <anno>Filename</anno>}</c></tag> <item>Specifies the filename of the trace. If the option <c>file</c> is given, or none of these options are given, the file <c>"fprof.trace"</c> is used. This option is only allowed with the <c>start</c> option, - but not with the <c>{tracer, Tracer}</c> option.</item> - <tag><c>{tracer, Tracer}</c></tag> + but not with the <c>{tracer, <anno>Tracer</anno>}</c> option.</item> + <tag><c>{tracer, <anno>Tracer</anno>}</c></tag> <item>Specifies that trace to process or port shall be done instead of trace to file. This option is only allowed with the <c>start</c> option, - but not with the <c>{file, Filename}</c> option.</item> + but not with the <c>{file, <anno>Filename</anno>}</c> option.</item> </taglist> - <marker id="profile"></marker> </desc> </func> <func> - <name since="">profile() -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> + <name name="profile" arity="0" since=""></name> <fsummary>Same as <c>profile([])</c>.</fsummary> - <type> - <v>Reason = term()</v> - </type> <desc> <p>Same as <c>profile([])</c>.</p> </desc> </func> <func> - <name since="">profile(OptionName, OptionValue) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>profile([{OptionName, OptionValue}])</c>.</fsummary> - <type> - <v>OptionName = atom()</v> - <v>OptionValue = term()</v> - <v>Reason = term()</v> - </type> + <name name="profile" arity="2" since=""></name> + <fsummary>Same as <c>profile([{<anno>OptionName</anno>, + <anno>OptionValue</anno>}])</c>.</fsummary> <desc> <p>Same as - <c>profile([{OptionName, OptionValue}])</c>.</p> + <c>profile([{<anno>OptionName</anno>, <anno>OptionValue</anno>}])</c>.</p> </desc> </func> <func> - <name since="">profile(OptionName) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>profile([OptionName])</c>.</fsummary> - <type> - <v>OptionName = atom()</v> - <v>Reason = term()</v> - </type> + <name name="profile" arity="1" clause_i="1" since=""></name> + <fsummary>Same as <c>profile([<anno>OptionName</anno>])</c>.</fsummary> <desc> - <p>Same as <c>profile([OptionName])</c>.</p> + <p>Same as <c>profile([<anno>OptionName</anno>])</c>.</p> </desc> </func> <func> - <name since="">profile({OptionName, OptionValue}) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>profile([{OptionName, OptionValue}])</c>.</fsummary> - <type> - <v>OptionName = atom()</v> - <v>OptionValue = term()</v> - <v>Reason = term()</v> - </type> + <name name="profile" arity="1" clause_i="2" since=""></name> + <fsummary>Same as <c>profile([{<anno>OptionName</anno>, + <anno>OptionValue</anno>}])</c>.</fsummary> <desc> <p>Same as - <c>profile([{OptionName, OptionValue}])</c>.</p> + <c>profile([{<anno>OptionName</anno>, <anno>OptionValue</anno>}])</c>.</p> </desc> </func> <func> - <name since="">profile([Option]) -> ok | {ok, Tracer} | {error, Reason} | {'EXIT', ServerPid, Reason}</name> + <name name="profile" arity="1" clause_i="3" since=""></name> <fsummary>Compiles a trace into raw profile data held by the <c>fprof</c> server.</fsummary> - <type> - <v>Option = file | {file, Filename} | dump | {dump, Dump} | append | start | stop</v> - <v>Dump = pid() | Dumpfile | []</v> - <v>Tracer = pid()</v> - <v>Reason = term()</v> - </type> + <type name="profile_option"/> <desc> <p>Compiles a trace into raw profile data held by the <c>fprof</c> server. </p> - <p><c>Dumpfile</c> is used to call <c>file:open/2</c>, - and <c>Filename</c> is used to call - <c>dbg:trace_port(file, Filename)</c>. Please see the - appropriate documentation.</p> + <p><c><anno>Dumpfile</anno></c> is used to call <c>file:open/2</c>, + and <c><anno>Filename</anno></c> is used to call + <c>dbg:trace_port(file, <anno>Filename</anno>)</c>. Please see + <seemfa marker="kernel:file#open/2"><c>file:open/2</c></seemfa> + and + <seemfa marker="runtime_tools:dbg#trace_port/2"><c>dbg:trace_port/2</c></seemfa>.</p> <p>Option description:</p> <taglist> - <tag><c>file</c>| <c>{file, Filename}</c></tag> - <item>Reads the file <c>Filename</c> and creates raw + <tag><c>file</c> | <c>{file, <anno>Filename</anno>}</c></tag> + <item>Reads the file <c><anno>Filename</anno></c> and creates raw profile data that is stored in RAM by the <c>fprof</c> server. If the option <c>file</c> is given, or none of these options are given, the file @@ -435,12 +379,12 @@ read with the return value <c>ok</c> if successful. This option is not allowed with the <c>start</c> or <c>stop</c> options.</item> - <tag><c>dump</c>| <c>{dump, Dump}</c></tag> + <tag><c>dump</c> | <c>{dump, <anno>Dump</anno>}</c></tag> <item>Specifies the destination for the trace text dump. If this option is not given, no dump is generated, if it is <c>dump</c> the destination will be the caller's group leader, otherwise the destination - <c>Dump</c> is either the pid of an I/O device or + <c><anno>Dump</anno></c> is either the pid of an I/O device or a filename. And, finally, if the filename is <c>[]</c> - <c>"fprof.dump"</c> is used instead. This option is not allowed with the <c>stop</c> option.</item> @@ -448,94 +392,72 @@ <item>Causes the trace text dump to be appended to the destination file. This option is only allowed with the - <c>{dump, Dumpfile}</c> option.</item> + <c>{dump, <anno>Dumpfile</anno>}</c> option.</item> <tag><c>start</c></tag> <item>Starts a tracer process that profiles trace data in runtime. The call will return immediately with the return - value <c>{ok, Tracer}</c> if successful. + value <c>{ok, <anno>Tracer</anno>}</c> if successful. This option is not allowed with the <c>stop</c>, - <c>file</c> or <c>{file, Filename}</c> options.</item> + <c>file</c> or <c>{file, <anno>Filename</anno>}</c> options.</item> <tag><c>stop</c></tag> <item>Stops the tracer process that profiles trace data in runtime. The return value will be value <c>ok</c> if successful. This option is not allowed with the <c>start</c>, - <c>file</c> or <c>{file, Filename}</c> options.</item> + <c>file</c> or <c>{file, <anno>Filename</anno>}</c> options.</item> </taglist> - <marker id="analyse"></marker> </desc> </func> <func> - <name since="">analyse() -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> + <name name="analyse" arity="0" since=""></name> <fsummary>Same as <c>analyse([])</c>.</fsummary> - <type> - <v>Reason = term()</v> - </type> <desc> <p>Same as <c>analyse([])</c>.</p> </desc> </func> <func> - <name since="">analyse(OptionName, OptionValue) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>analyse([{OptionName, OptionValue}])</c>.</fsummary> - <type> - <v>OptionName = atom()</v> - <v>OptionValue = term()</v> - <v>Reason = term()</v> - </type> + <name name="analyse" arity="2" since=""></name> + <fsummary>Same as <c>analyse([{<anno>OptionName</anno>, + <anno>OptionValue</anno>}])</c>.</fsummary> <desc> <p>Same as - <c>analyse([{OptionName, OptionValue}])</c>.</p> + <c>analyse([{<anno>OptionName</anno>, <anno>OptionValue</anno>}])</c>.</p> </desc> </func> <func> - <name since="">analyse(OptionName) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>analyse([OptionName])</c>.</fsummary> - <type> - <v>OptionName = atom()</v> - <v>Reason = term()</v> - </type> + <name name="analyse" arity="1" clause_i="1" since=""></name> + <fsummary>Same as <c>analyse([<anno>OptionName</anno>])</c>.</fsummary> <desc> - <p>Same as <c>analyse([OptionName])</c>.</p> + <p>Same as <c>analyse([<anno>OptionName</anno>])</c>.</p> </desc> </func> <func> - <name since="">analyse({OptionName, OptionValue}) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> - <fsummary>Same as <c>analyse([{OptionName, OptionValue}])</c>.</fsummary> - <type> - <v>OptionName = atom()</v> - <v>OptionValue = term()</v> - <v>Reason = term()</v> - </type> + <name name="analyse" arity="1" clause_i="2" since=""></name> + <fsummary>Same as <c>analyse([{<anno>OptionName</anno>, + <anno>OptionValue</anno>}])</c>.</fsummary> <desc> <p>Same as - <c>analyse([{OptionName, OptionValue}])</c>.</p> + <c>analyse([{<anno>OptionName</anno>, <anno>OptionValue</anno>}])</c>.</p> </desc> </func> <func> - <name since="">analyse([Option]) -> ok | {error, Reason} | {'EXIT', ServerPid, Reason}</name> + <name name="analyse" arity="1" clause_i="3" since=""></name> <fsummary>Analyses raw profile data in the <c>fprof</c> server.</fsummary> - <type> - <v>Option = dest | {dest, Dest} | append | {cols, Cols} | callers | {callers, bool()} | no_callers | {sort, SortSpec} | totals | {totals, bool()} | details | {details, bool()} | no_details</v> - <v>Dest = pid() | Destfile</v> - <v>Cols = integer() >= 80</v> - <v>SortSpec = acc | own</v> - <v>Reason = term()</v> - </type> + <type name="analyse_option"/> <desc> <p>Analyses raw profile data in the <c>fprof</c> server. If called while there is no raw profile data available, <c>{error, no_profile}</c> is returned. </p> - <p><c>Destfile</c> is used to call <c>file:open/2</c>. - Please see the appropriate documentation.</p> + <p><c><anno>Destfile</anno></c> is used to call + <seemfa marker="kernel:file#open/2"><c>file:open/2</c></seemfa>.</p> <p>Option description:</p> <taglist> - <tag><c>dest</c>| <c>{dest, Dest}</c></tag> + <tag><c>dest</c> | <c>{dest, <anno>Dest</anno>}</c></tag> <item>Specifies the destination for the analysis. If this option is not given or it is <c>dest</c>, the destination will be the caller's group leader, - otherwise the destination <c>Dest</c> is either + otherwise the destination <c><anno>Dest</anno></c> is either the <c>pid()</c> of an I/O device or a filename. And, finally, if the filename is <c>[]</c> - <c>"fprof.analysis"</c> is used instead.</item> @@ -543,32 +465,32 @@ <item>Causes the analysis to be appended to the destination file. This option is only allowed with the - <c>{dest, Destfile}</c> option.</item> - <tag><c>{cols, Cols}</c></tag> + <c>{dest, <anno>Destfile</anno>}</c> option.</item> + <tag><c>{cols, <anno>Cols</anno>}</c></tag> <item>Specifies the number of columns in the analysis text. If this option is not given the number of columns is set to 80.</item> - <tag><c>callers</c>| <c>{callers, true}</c></tag> + <tag><c>callers</c> | <c>{callers, true}</c></tag> <item>Prints callers and called information in the analysis. This is the default.</item> - <tag><c>{callers, false}</c>| <c>no_callers</c></tag> + <tag><c>{callers, false}</c> | <c>no_callers</c></tag> <item>Suppresses the printing of callers and called information in the analysis.</item> - <tag><c>{sort, SortSpec}</c></tag> + <tag><c>{sort, <anno>SortSpec</anno>}</c></tag> <item>Specifies if the analysis should be sorted according to the ACC column, which is the default, or the OWN column. See <seeerl marker="#analysis">Analysis Format</seeerl> below.</item> - <tag><c>totals</c>| <c>{totals, true}</c></tag> + <tag><c>totals</c> | <c>{totals, true}</c></tag> <item>Includes a section containing call statistics for all calls regardless of process, in the analysis.</item> <tag><c>{totals, false}</c></tag> <item>Supresses the totals section in the analysis, which is the default.</item> - <tag><c>details</c>| <c>{details, true}</c></tag> + <tag><c>details</c> | <c>{details, true}</c></tag> <item>Prints call statistics for each process in the analysis. This is the default.</item> - <tag><c>{details, false}</c>| <c>no_details</c></tag> + <tag><c>{details, false}</c> | <c>no_details</c></tag> <item>Suppresses the call statistics for each process from the analysis.</item> </taglist> @@ -580,7 +502,7 @@ <marker id="analysis"></marker> <title>Analysis format</title> <p>This section describes the output format of the analyse - command. See <seeerl marker="#analyse">analyse/0</seeerl>. + command. See <seemfa marker="#analyse/0">analyse/0</seemfa>. </p> <p>The format is parsable with the standard Erlang parsing tools <c>erl_scan</c> and <c>erl_parse</c>, <c>file:consult/1</c> or @@ -900,7 +822,7 @@ create_file_slow(FD, M, N) -> </p> <p>Sometimes a function may unexpectedly waste a lot (some 10 ms or more depending on host machine OS) of OWN (and ACC) time, even - functions that does practically nothing at all. The problem may + functions that do practically nothing at all. The problem may be that the OS has chosen to schedule out the Erlang runtime system process for a while, and if the OS does not support high resolution cpu time measurements diff --git a/lib/tools/doc/src/fprof_chapter.xml b/lib/tools/doc/src/fprof_chapter.xml index 5d161ed2e6..8a452c372e 100644 --- a/lib/tools/doc/src/fprof_chapter.xml +++ b/lib/tools/doc/src/fprof_chapter.xml @@ -97,10 +97,10 @@ </p> <p>See the <seeerl marker="fprof">fprof(3)</seeerl> manual page for more options and arguments to the functions - <seeerl marker="fprof#trace">trace</seeerl>, - <seeerl marker="fprof#profile">profile</seeerl> + <seemfa marker="fprof#trace/2">trace</seemfa>, + <seemfa marker="fprof#profile/0">profile</seemfa> and - <seeerl marker="fprof#analyse">analyse</seeerl>. + <seemfa marker="fprof#analyse/0">analyse</seemfa>. </p> </section> diff --git a/lib/tools/doc/src/lcnt.xml b/lib/tools/doc/src/lcnt.xml index 94a56c239a..a494323d58 100644 --- a/lib/tools/doc/src/lcnt.xml +++ b/lib/tools/doc/src/lcnt.xml @@ -3,12 +3,12 @@ <erlref> <header> - <copyright> - <year>2009</year> - <year>2018</year> - <holder>Ericsson AB, All Rights Reserved</holder> - </copyright> - <legalnotice> + <copyright> + <year>2009</year> + <year>2020</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 @@ -22,332 +22,295 @@ limitations under the License. The Initial Developer of the Original Code is Ericsson AB. - </legalnotice> - - <title>lcnt</title> - <prepared>Björn-Egil Dahlberg</prepared> - <responsible>nobody</responsible> - <docno></docno> - <approved>nobody</approved> - <checked></checked> - <date>2009-11-26</date> - <rev>PA1</rev> - <file>lcnt.xml</file> + </legalnotice> + + <title>lcnt</title> + <prepared>Björn-Egil Dahlberg</prepared> + <responsible>nobody</responsible> + <docno></docno> + <approved>nobody</approved> + <checked></checked> + <date>2009-11-26</date> + <rev>PA1</rev> + <file>lcnt.xml</file> </header> <module since="OTP R13B04">lcnt</module> <modulesummary>A runtime system Lock Profiling tool.</modulesummary> <description> - <p>The <c>lcnt</c> module is used to profile the internal ethread locks in the - Erlang Runtime System. With <c>lcnt</c> enabled, internal counters in the - runtime system are updated each time a lock is taken. The counters stores - information about the number of acquisition tries and the number of collisions - that has occurred during the acquisition tries. The counters also record the - waiting time a lock has caused for a blocked thread when a collision has occurred. - </p> - <p> - The data produced by the lock counters will give an estimate on how well - the runtime system will behave from a parallelizable view point for the - scenarios tested. This tool was mainly developed to help Erlang runtime - developers iron out potential and generic bottlenecks. - </p> - <p>Locks in the emulator are named after what type of resource they protect and where - in the emulator they are initialized, those are lock 'classes'. Most of those - locks are also instantiated several times, and given unique identifiers, to increase - locking granularity. Typically an instantiated lock protects a disjunct set of - the resource, for example ets tables, processes or ports. In other cases it protects a - specific range of a resource, for example <c>pix_lock</c> which protects index to process - mappings, and is given a unique number within the class. A unique lock in <c>lcnt</c> - is referenced by a name (class) and an identifier: <c>{Name, Id}</c>. - </p> - <p>Some locks in the system are static and protects global resources, for example - <c>bif_timers</c> and the <c>run_queue</c> locks. Other locks are dynamic and not - necessarily long lived, for example process locks and ets-table locks. The - statistics data from short lived locks can be stored separately when the locks - are deleted. This behavior is by default turned off to save memory but can be - turned on via <c>lcnt:rt_opt({copy_save, true})</c>. The <c>lcnt:apply/1,2,3</c> - functions enables this behavior during profiling. - </p> + <p>The <c>lcnt</c> module is used to profile the internal ethread locks in the + Erlang Runtime System. With <c>lcnt</c> enabled, internal counters in the + runtime system are updated each time a lock is taken. The counters stores + information about the number of acquisition tries and the number of collisions + that has occurred during the acquisition tries. The counters also record the + waiting time a lock has caused for a blocked thread when a collision has occurred. + </p> + <p> + The data produced by the lock counters will give an estimate on how well + the runtime system will behave from a parallelizable view point for the + scenarios tested. This tool was mainly developed to help Erlang runtime + developers iron out potential and generic bottlenecks. + </p> + <p>Locks in the emulator are named after what type of resource they protect and where + in the emulator they are initialized, those are lock 'classes'. Most of those + locks are also instantiated several times, and given unique identifiers, to increase + locking granularity. Typically an instantiated lock protects a disjunct set of + the resource, for example ets tables, processes or ports. In other cases it protects a + specific range of a resource, for example <c>pix_lock</c> which protects index to process + mappings, and is given a unique number within the class. A unique lock in <c>lcnt</c> + is referenced by a name (class) and an identifier: <c>{Name, Id}</c>. + </p> + <p>Some locks in the system are static and protects global resources, for example + <c>bif_timers</c> and the <c>run_queue</c> locks. Other locks are dynamic and not + necessarily long lived, for example process locks and ets-table locks. The + statistics data from short lived locks can be stored separately when the locks + are deleted. This behavior is by default turned off to save memory but can be + turned on via <c>lcnt:rt_opt({copy_save, true})</c>. The <c>lcnt:apply/1,2,3</c> + functions enables this behavior during profiling. + </p> </description> <funcs> - <func> - <name since="OTP R13B04">start() -> {ok, Pid} | {error, {already_started, Pid}} </name> - <fsummary>Starts the lock profiler server.</fsummary> - <type> - <v>Pid = pid()</v> - </type> - <desc> - <p>Starts the lock profiler server. The server only act as a medium for the - user and performs filtering and printing of data collected by <c>lcnt:collect/1</c>. - </p> - </desc> - </func> - - <func> - <name since="OTP R13B04">stop() -> ok</name> - <fsummary>Stops the lock profiler server.</fsummary> - <desc> - <p>Stops the lock profiler server.</p> - </desc> - </func> - - <func> - <name since="OTP R13B04">collect() -> ok</name> - <fsummary>Same as <c>collect(node())</c>.</fsummary> - <desc><p>Same as <c>collect(node())</c>.</p></desc> - </func> - - <func> - <name since="OTP R13B04">collect(Node) -> ok</name> - <fsummary>Collects lock statistics from the runtime system.</fsummary> - <type> - <v>Node = node()</v> - </type> - <desc> - <p>Collects lock statistics from the runtime system. The function starts a - server if it is not already started. It then populates the server with lock - statistics. If the server held any lock statistics data before the collect then - that data is lost. - </p> - </desc> - </func> - - <func> - <name since="OTP R13B04">clear() -> ok</name> - <fsummary>Same as <c>clear(node())</c>.</fsummary> - <desc><p>Same as <c>clear(node())</c>.</p></desc> - </func> - - <func> - <name since="OTP R13B04">clear(Node) -> ok</name> - <fsummary>Clears the internal lock statistics from runtime system.</fsummary> - <type> - <v>Node = node()</v> - </type> - <desc> - <p>Clears the internal lock statistics from the runtime system. This does not clear the - data on the server only on runtime system. All counters for static locks are zeroed, - all dynamic locks currently alive are zeroed and all saved locks now destroyed are removed. - It also resets the duration timer. - </p> - </desc> - </func> - <func> - <name since="OTP R13B04">conflicts() -> ok</name> - <fsummary>Same as <c>conflicts([])</c>.</fsummary> - <desc><p>Same as <c>conflicts([])</c>.</p></desc> - </func> - <func> - <name since="OTP R13B04">conflicts([Option]) -> ok</name> - <fsummary>Prints a list of internal lock counters.</fsummary> - <type> - <v>Option = {sort, Sort} | {reverse, bool()} | {thresholds, [Thresholds]} | {print, [Print | {Print, integer()}]} | {max_locks, MaxLocks} | {combine, bool()}</v> - <v>Sort = name | id | type | tries | colls | ratio | time | entry</v> - <v>Thresholds = {tries, integer()} | {colls, integer()} | {time, integer()}</v> - <v>Print = name | id | type | entry | tries | colls | ratio | time | duration</v> - <v>MaxLocks = integer() | none</v> - </type> - <desc> - <p>Prints a list of internal locks and its statistics.</p> - <p>For option description, see <seemfa marker="#inspect/2">lcnt:inspect/2</seemfa>.</p> - </desc> - </func> - - <func> - <name since="OTP R13B04">locations() -> ok</name> - <fsummary>Same as <c>locations([])</c>.</fsummary> - <desc> - <p>Same as <c>locations([])</c>.</p> - </desc> - </func> - <func> - <name since="OTP R13B04">locations([Option]) -> ok</name> - <fsummary>Prints a list of internal lock counters by source code locations.</fsummary> - <type> - <v>Option = {sort, Sort} | {thresholds, [Thresholds]} | {print, [Print | {Print, integer()}]} | {max_locks, MaxLocks} | {combine, bool()}</v> - <v>Sort = name | id | type | tries | colls | ratio | time | entry</v> - <v>Thresholds = {tries, integer()} | {colls, integer()} | {time, integer()}</v> - <v>Print = name | id | type | entry | tries | colls | ratio | time | duration</v> - <v>MaxLocks = integer() | none</v> - </type> - <desc> - <p>Prints a list of internal lock counters by source code locations.</p> - <p>For option description, see <seemfa marker="#inspect/2">lcnt:inspect/2</seemfa>.</p> - </desc> - </func> - - <func> - <name since="OTP R13B04">inspect(Lock) -> ok</name> - <fsummary>Same as <c>inspect(Lock, [])</c>.</fsummary> - <desc><p>Same as <c>inspect(Lock, [])</c>.</p></desc> - </func> - <func> - <name since="OTP R13B04">inspect(Lock, [Option]) -> ok</name> - <fsummary>Prints a list of internal lock counters for a specific lock.</fsummary> - <type> - <v>Lock = Name | {Name, Id | [Id]}</v> - <v>Name = atom() | pid() | port()</v> - <v>Id = atom() | integer() | pid() | port()</v> - <v>Option = {sort, Sort} | {thresholds, [Thresholds]} | {print, [Print | {Print, integer()}]} | {max_locks, MaxLocks} | {combine, bool()} | {locations, bool()}</v> - <v>Sort = name | id | type | tries | colls | ratio | time</v> - <v>Thresholds = {tries, integer()} | {colls, integer()} | {time, integer()}</v> - <v>Print = name | id | type | entry | tries | colls | ratio | time | duration</v> - <v>MaxLocks = integer() | none</v> - </type> - <desc> - <p>Prints a list of internal lock counters for a specific lock.</p> - <p>Lock <c>Name</c> and <c>Id</c> for ports and processes are interchangeable with the use of <c>lcnt:swap_pid_keys/0</c> and is the reason why <c>pid()</c> and <c>port()</c> options can be used in both <c>Name</c> and <c>Id</c> space. Both pids and ports are special identifiers with stripped creation and can be recreated with <seemfa marker="#pid/3">lcnt:pid/2,3</seemfa> and <seemfa marker="#port/2">lcnt:port/1,2</seemfa>. </p> - <p>Option description:</p> - <taglist> - <tag><c>{combine, bool()}</c></tag> - <item>Combine the statistics from different instances of a lock class. - <br/>Default: <c>true</c> - </item> - - <tag><c>{locations, bool()}</c></tag> - <item>Print the statistics by source file and line numbers. - <br/>Default: <c>false</c> - </item> - - <tag><c>{max_locks, MaxLocks}</c></tag> - <item>Maximum number of locks printed or no limit with <c>none</c>. - <br/>Default: <c>20</c> - </item> - - <tag><c>{print, PrintOptions}</c></tag> - <item>Printing options: - <taglist> - <tag><c>name</c></tag> - <item>Named lock or named set of locks (classes). The same name used for initializing the lock in the VM.</item> - - <tag><c>id</c></tag> - <item>Internal id for set of locks, not always unique. This could be table name for ets tables (db_tab), port id for ports, integer identifiers for allocators, etc.</item> - - <tag><c>type</c></tag> - <item>Type of lock: <c>rw_mutex</c>, <c>mutex</c>, <c>spinlock</c>, <c>rw_spinlock</c> or <c>proclock</c>.</item> - - <tag><c>entry</c></tag> - <item>In combination with <c>{locations, true}</c> this option prints the lock operations source file and line number entry-points along with statistics for each entry. </item> - - <tag><c>tries</c></tag> - <item>Number of acquisitions of this lock.</item> - - <tag><c>colls</c></tag> - <item>Number of collisions when a thread tried to acquire this lock. This is when a trylock is EBUSY, a write try on read held rw_lock, a try read on write held rw_lock, a thread tries to lock an already locked lock. (Internal states supervises this).</item> - - <tag><c>ratio</c></tag> - <item>The ratio between the number of collisions and the number of tries (acquisitions) in percentage.</item> - - <tag><c>time</c></tag> - <item>Accumulated waiting time for this lock. This could be greater than actual wall clock time, it is accumulated for all threads. Trylock conflicts does not accumulate time.</item> - - <tag><c>duration</c></tag> - <item>Percentage of accumulated waiting time of wall clock time. This percentage can be higher than 100% since accumulated time is from all threads.</item> - </taglist> - <br/>Default: <c>[name,id,tries,colls,ratio,time,duration]</c> - </item> - - <tag><c>{reverse, bool()}</c></tag> - <item>Reverses the order of sorting. - <br/>Default: <c>false</c> - </item> - - <tag><c>{sort, Sort}</c></tag> - <item>Column sorting orders. - <br/>Default: <c>time</c> - </item> - - <tag><c>{thresholds, Thresholds}</c></tag> - <item>Filtering thresholds. Anything values above the threshold value are passed through. - <br/>Default: <c>[{tries, 0}, {colls, 0}, {time, 0}]</c> - </item> - - </taglist> - - </desc> - </func> - - <func> - <name since="OTP R13B04">information() -> ok</name> - <fsummary>Prints lcnt server state and generic information about collected lock statistics.</fsummary> - <desc> - <p>Prints lcnt server state and generic information about collected lock statistics.</p> - </desc> - </func> - - <func> - <name since="OTP R13B04">swap_pid_keys() -> ok</name> - <fsummary>Swaps places on <c>Name</c> and <c>Id</c> space for ports and processes.</fsummary> - <desc> - <p>Swaps places on <c>Name</c> and <c>Id</c> space for ports and processes.</p> - </desc> - </func> - - <func> - <name since="OTP R13B04">load(Filename) -> ok</name> - <fsummary>Restores previously saved data to the server.</fsummary> - <type> - <v>Filename = filename()</v> - </type> - <desc> - <p>Restores previously saved data to the server.</p> - </desc> - </func> - - <func> - <name since="OTP R13B04">save(Filename) -> ok</name> - <fsummary>Saves the collected data to file.</fsummary> - <type> - <v>Filename = filename()</v> - </type> - <desc> - <p>Saves the collected data to file.</p> - </desc> - </func> + <func> + <name name="start" arity="0" since="OTP R13B04"></name> + <fsummary>Starts the lock profiler server.</fsummary> + <desc> + <p>Starts the lock profiler server. The server only act as a medium for the + user and performs filtering and printing of data collected by <c>lcnt:collect/1</c>. + </p> + </desc> + </func> + + <func> + <name name="stop" arity="0" since="OTP R13B04"></name> + <fsummary>Stops the lock profiler server.</fsummary> + <desc> + <p>Stops the lock profiler server.</p> + </desc> + </func> + + <func> + <name name="collect" arity="0" since="OTP R13B04"></name> + <fsummary>Same as <c>collect(node())</c>.</fsummary> + <desc><p>Same as <c>collect(node())</c>.</p></desc> + </func> + + <func> + <name name="collect" arity="1" since="OTP R13B04"></name> + <fsummary>Collects lock statistics from the runtime system.</fsummary> + <desc> + <p>Collects lock statistics from the runtime system. The function starts a + server if it is not already started. It then populates the server with lock + statistics. If the server held any lock statistics data before the collect then + that data is lost. + </p> + </desc> + </func> + + <func> + <name name="clear" arity="0" since="OTP R13B04"></name> + <fsummary>Same as <c>clear(node())</c>.</fsummary> + <desc><p>Same as <c>clear(node())</c>.</p></desc> + </func> + + <func> + <name name="clear" arity="1" since="OTP R13B04"></name> + <fsummary>Clears the internal lock statistics from runtime system.</fsummary> + <desc> + <p>Clears the internal lock statistics from the runtime system. This does not clear the + data on the server only on runtime system. All counters for static locks are zeroed, + all dynamic locks currently alive are zeroed and all saved locks now destroyed are removed. + It also resets the duration timer. + </p> + </desc> + </func> + <func> + <name name="conflicts" arity="0" since="OTP R13B04"></name> + <fsummary>Same as <c>conflicts([])</c>.</fsummary> + <desc><p>Same as <c>conflicts([])</c>.</p></desc> + </func> + <func> + <name name="conflicts" arity="1" since="OTP R13B04"></name> + <fsummary>Prints a list of internal lock counters.</fsummary> + <type name="option"/> + <type name="print"/> + <type name="sort"/> + <type name="threshold"/> + <desc> + <p>Prints a list of internal locks and its statistics.</p> + <p>For option description, see <seemfa marker="#inspect/2"><c>lcnt:inspect/2</c></seemfa>.</p> + </desc> + </func> + + <func> + <name name="locations" arity="0" since="OTP R13B04"></name> + <fsummary>Same as <c>locations([])</c>.</fsummary> + <desc> + <p>Same as <c>locations([])</c>.</p> + </desc> + </func> + <func> + <name name="locations" arity="1" since="OTP R13B04"></name> + <fsummary>Prints a list of internal lock counters by source code locations.</fsummary> + <type name="option"/> + <type name="print"/> + <type name="sort"/> + <type name="threshold"/> + <desc> + <p>Prints a list of internal lock counters by source code locations.</p> + <p>For option description, see <seemfa marker="#inspect/2"><c>lcnt:inspect/2</c></seemfa>.</p> + </desc> + </func> + + <func> + <name name="inspect" arity="1" since="OTP R13B04"></name> + <fsummary>Same as <c>inspect(<anno>Lock</anno>, [])</c>.</fsummary> + <desc><p>Same as <c>inspect(<anno>Lock</anno>, [])</c>.</p></desc> + </func> + <func> + <name name="inspect" arity="2" since="OTP R13B04"></name> + <fsummary>Prints a list of internal lock counters for a specific lock.</fsummary> + <type name="option"/> + <type name="print"/> + <type name="sort"/> + <type name="threshold"/> + <desc> + <p>Prints a list of internal lock counters for a specific lock.</p> + <p>Lock <c><anno>Name</anno></c> and <c><anno>Id</anno></c> + for ports and processes are interchangeable with the use of + <seemfa marker="#swap_pid_keys/0"><c>lcnt:swap_pid_keys/0</c></seemfa> + and is the reason why <c>pid()</c> + and <c>port()</c> options can be used in both + <c><anno>Name</anno></c> and <c><anno>Id</anno></c> space. + Both pids and ports are special identifiers with stripped + creation and can be recreated with + <seemfa marker="#pid/3"><c>lcnt:pid/2,3</c></seemfa> and + <seemfa marker="#port/2"><c>lcnt:port/1,2</c></seemfa>.</p> + <p>Option description:</p> + <taglist> + <tag><c>{combine, boolean()}</c></tag> + <item>Combine the statistics from different instances of a lock class. + <br/>Default: <c>true</c> + </item> + + <tag><c>{locations, boolean()}</c></tag> + <item>Print the statistics by source file and line numbers. + <br/>Default: <c>false</c> + </item> + + <tag><c>{max_locks, <anno>MaxLocks</anno>}</c></tag> + <item>Maximum number of locks printed or no limit with <c>none</c>. + <br/>Default: <c>20</c> + </item> + + <tag><c>{print, <anno>PrintOptions</anno>}</c></tag> + <item>Printing options: + <taglist> + <tag><c>name</c></tag> + <item>Named lock or named set of locks (classes). The same name used for initializing the lock in the VM.</item> + + <tag><c>id</c></tag> + <item>Internal id for set of locks, not always unique. This could be table name for ets tables (db_tab), port id for ports, integer identifiers for allocators, etc.</item> + + <tag><c>type</c></tag> + <item>Type of lock: <c>rw_mutex</c>, <c>mutex</c>, <c>spinlock</c>, <c>rw_spinlock</c> or <c>proclock</c>.</item> + + <tag><c>entry</c></tag> + <item>In combination with <c>{locations, true}</c> this option prints the lock operations source file and line number entry-points along with statistics for each entry. </item> + + <tag><c>tries</c></tag> + <item>Number of acquisitions of this lock.</item> + + <tag><c>colls</c></tag> + <item>Number of collisions when a thread tried to acquire this lock. This is when a trylock is EBUSY, a write try on read held rw_lock, a try read on write held rw_lock, a thread tries to lock an already locked lock. (Internal states supervises this).</item> + + <tag><c>ratio</c></tag> + <item>The ratio between the number of collisions and the number of tries (acquisitions) in percentage.</item> + + <tag><c>time</c></tag> + <item>Accumulated waiting time for this lock. This could be greater than actual wall clock time, it is accumulated for all threads. Trylock conflicts does not accumulate time.</item> + + <tag><c>duration</c></tag> + <item>Percentage of accumulated waiting time of wall clock time. This percentage can be higher than 100% since accumulated time is from all threads.</item> + </taglist> + <br/>Default: <c>[name,id,tries,colls,ratio,time,duration]</c> + </item> + + <tag><c>{reverse, boolean()}</c></tag> + <item>Reverses the order of sorting. + <br/>Default: <c>false</c> + </item> + + <tag><c>{sort, <anno>Sort</anno>}</c></tag> + <item>Column sorting orders. + <br/>Default: <c>time</c> + </item> + + <tag><c>{thresholds, <anno>Thresholds</anno>}</c></tag> + <item>Filtering thresholds. Anything values above the threshold value are passed through. + <br/>Default: <c>[{tries, 0}, {colls, 0}, {time, 0}]</c> + </item> + + </taglist> + + </desc> + </func> + + <func> + <name name="information" arity="0" since="OTP R13B04"></name> + <fsummary>Prints lcnt server state and generic information about collected lock statistics.</fsummary> + <desc> + <p>Prints lcnt server state and generic information about collected lock statistics.</p> + </desc> + </func> + + <func> + <name name="swap_pid_keys" arity="0" since="OTP R13B04"></name> + <fsummary>Swaps places on <c>Name</c> and <c>Id</c> space for ports and processes.</fsummary> + <desc> + <p>Swaps places on <c>Name</c> and <c>Id</c> space for ports and processes.</p> + </desc> + </func> + + <func> + <name name="load" arity="1" since="OTP R13B04"></name> + <fsummary>Restores previously saved data to the server.</fsummary> + <desc> + <p>Restores previously saved data to the server.</p> + </desc> + </func> + + <func> + <name name="save" arity="1" since="OTP R13B04"></name> + <fsummary>Saves the collected data to file.</fsummary> + <desc> + <p>Saves the collected data to file.</p> + </desc> + </func> </funcs> <funcs> <fsdescription> - <title>Convenience functions</title> - <p>The following functions are used for convenience.</p> + <title>Convenience functions</title> + <p>The following functions are used for convenience.</p> </fsdescription> - <func> - <name since="OTP R13B04">apply(Fun) -> term()</name> - <fsummary>Same as <c>apply(Fun, [])</c>.</fsummary> - <type> - <v>Fun = fun()</v> - </type> - <desc> - <p>Same as <c>apply(Fun, [])</c>.</p> - </desc> - </func> - <func> - <name since="OTP R13B04">apply(Fun, Args) -> term()</name> - <fsummary>Same as <c>apply(Module, Function, Args)</c>.</fsummary> - <type> - <v>Fun = fun()</v> - <v>Args = [term()]</v> - </type> - <desc> - <p>Same as <c>apply(Module, Function, Args)</c>.</p> - </desc> - </func> - <func> - <name since="OTP R13B04">apply(Module, Function, Args) -> term()</name> - <fsummary>Clears counters, applies function and collects the profiling results.</fsummary> - <type> - <v>Module = atom()</v> - <v>Function = atom()</v> - <v>Args = [term()]</v> - </type> - <desc> - <p> Clears the lock counters and then setups the instrumentation to save all destroyed locks. - After setup the function is called, passing the elements in <c>Args</c> as arguments. - When the function returns the statistics are immediately collected to the server. After the - collection the instrumentation is returned to its previous behavior. - The result of the applied function is returned. - </p> + <func> + <name name="apply" arity="1" since="OTP R13B04"></name> + <fsummary>Same as <c>apply(<anno>Fun</anno>, [])</c>.</fsummary> + <desc> + <p>Same as <c>apply(<anno>Fun</anno>, [])</c>.</p> + </desc> + </func> + <func> + <name name="apply" arity="2" since="OTP R13B04"></name> + <fsummary>Clears counters, applies function and collects the profiling results.</fsummary> + <desc> + <p> Clears the lock counters and then setups the instrumentation to save all destroyed locks. + After setup the function is called, passing the elements in <c><anno>Args</anno></c> as arguments. + When the function returns the statistics are immediately collected to the server. After the + collection the instrumentation is returned to its previous behavior. + The result of the applied function is returned. + </p> <warning> <p> This function should only be used for micro-benchmarks; it sets <c>copy_save</c> @@ -355,41 +318,42 @@ out of memory. </p> </warning> - </desc> - </func> - - <func> - <name since="OTP R13B04">pid(Id, Serial) -> pid()</name> - <fsummary>Same as <c>pid(node(), Id, Serial)</c>.</fsummary> - <desc><p>Same as <c>pid(node(), Id, Serial)</c>.</p></desc> - </func> - <func> - <name since="OTP R13B04">pid(Node, Id, Serial) -> pid()</name> - <fsummary>Creates a process id with creation 0.</fsummary> - <type> - <v>Node = node()</v> - <v>Id = integer()</v> - <v>Serial = integer()</v> - </type> - <desc> - <p>Creates a process id with creation 0.</p> - </desc> - </func> - - <func> - <name since="OTP R13B04">port(Id) -> port()</name> - <fsummary>Same as <c>port(node(), Id)</c>.</fsummary> - <desc><p>Same as <c>port(node(), Id)</c>.</p></desc> - </func> - <func> - <name since="OTP R13B04">port(Node, Id) -> port()</name> - <fsummary>Creates a port id with creation 0.</fsummary> - <type> - <v>Node = node()</v> - <v>Id = integer()</v> - </type> - <desc><p>Creates a port id with creation 0.</p></desc> - </func> + </desc> + </func> + <func> + <name name="apply" arity="3" since="OTP R13B04"></name> + <fsummary>Same as <c>apply(fun() -> erlang:apply(<anno>Module</anno>, + <anno>Function</anno>, <anno>Args</anno>) end)</c>.</fsummary> + <desc> + <p>Same as <c>apply(fun() -> erlang:apply(<anno>Module</anno>, + <anno>Function</anno>, <anno>Args</anno>) end)</c>.</p> + </desc> + </func> + <func> + <name name="pid" arity="2" since="OTP R13B04"></name> + <fsummary>Same as <c>pid(node(), <anno>Id</anno>, + <anno>Serial</anno>)</c>.</fsummary> + <desc><p>Same as <c>pid(node(), <anno>Id</anno>, + <anno>Serial</anno>)</c>.</p></desc> + </func> + <func> + <name name="pid" arity="3" since="OTP R13B04"></name> + <fsummary>Creates a process id with creation 0.</fsummary> + <desc> + <p>Creates a process id with creation 0.</p> + </desc> + </func> + + <func> + <name name="port" arity="1" since="OTP R13B04"></name> + <fsummary>Same as <c>port(node(), <anno>Id</anno>)</c>.</fsummary> + <desc><p>Same as <c>port(node(), <anno>Id</anno>)</c>.</p></desc> + </func> + <func> + <name name="port" arity="2" since="OTP R13B04"></name> + <fsummary>Creates a port id with creation 0.</fsummary> + <desc><p>Creates a port id with creation 0.</p></desc> + </func> </funcs> @@ -397,80 +361,74 @@ <funcs> <fsdescription> - <title>Internal runtime lock counter controllers</title> - <p> The following functions control the behavior of the internal counters. </p> + <title>Internal runtime lock counter controllers</title> + <p> The following functions control the behavior of the internal counters. </p> </fsdescription> - <func> - <name since="OTP R13B04">rt_collect() -> [lock_counter_data()]</name> - <fsummary>Same as <c>rt_collect(node())</c>.</fsummary> - <desc> <p>Same as <c>rt_collect(node())</c>.</p> </desc> - </func> - <func> - <name since="OTP R13B04">rt_collect(Node) -> [lock_counter_data()]</name> - <fsummary>Returns a list of raw lock counter data.</fsummary> - <type> - <v>Node = node()</v> - </type> - <desc> <p>Returns a list of raw lock counter data.</p> </desc> - </func> - - <func> - <name since="OTP R13B04">rt_clear() -> ok</name> - <fsummary>Same as <c>rt_clear(node())</c>.</fsummary> - <desc> <p>Same as <c>rt_clear(node())</c>.</p> </desc> - </func> - <func> - <name since="OTP R13B04">rt_clear(Node) -> ok</name> - <fsummary>Clears the internal counters.</fsummary> - <type> - <v>Node = node()</v> - </type> - <desc> <p>Clear the internal counters. Same as <c>lcnt:clear(Node)</c>.</p></desc> - </func> - - <func> - <name since="OTP 20.1">rt_mask() -> [category_atom()]</name> + <func> + <name name="rt_collect" arity="0" since="OTP R13B04"></name> + <fsummary>Same as <c>rt_collect(node())</c>.</fsummary> + <type name="lock_counter_data"/> + <desc> <p>Same as <c>rt_collect(node())</c>.</p> </desc> + </func> + <func> + <name name="rt_collect" arity="1" since="OTP R13B04"></name> + <fsummary>Returns a list of raw lock counter data.</fsummary> + <type name="lock_counter_data"/> + <desc> <p>Returns a list of raw lock counter data.</p> </desc> + </func> + + <func> + <name name="rt_clear" arity="0" since="OTP R13B04"></name> + <fsummary>Same as <c>rt_clear(node())</c>.</fsummary> + <desc> <p>Same as <c>rt_clear(node())</c>.</p> </desc> + </func> + <func> + <name name="rt_clear" arity="1" since="OTP R13B04"></name> + <fsummary>Clears the internal counters.</fsummary> + <desc> <p>Clear the internal counters. Same as + <seemfa marker="#clear/1"><c>lcnt:clear(<anno>Node</anno>)</c></seemfa>. + </p></desc> + </func> + + <func> + <name name="rt_mask" arity="0" since="OTP 20.1"></name> <fsummary>Same as <c>rt_mask(node())</c>.</fsummary> + <type name="category_atom"/> <desc><p>Same as <c>rt_mask(node())</c>.</p></desc> </func> <func> - <name since="OTP 20.1">rt_mask(Node) -> [category_atom()]</name> + <name name="rt_mask" arity="1" clause_i="1" since="OTP 20.1"></name> <fsummary>Returns the current lock category mask.</fsummary> - <type> - <v>Node = node()</v> - </type> + <type name="category_atom"/> <desc> <p> - Refer to <c>rt_mask/2</c> for a list of valid categories. All + Refer to + <seemfa marker="#rt_mask/2"><c>rt_mask/2</c></seemfa>. + for a list of valid categories. All categories are enabled by default. </p> </desc> </func> <func> - <name since="OTP 20.1">rt_mask(Categories) -> ok | {error, copy_save_enabled}</name> - <fsummary>Same as <c>rt_mask(node(), Categories)</c>.</fsummary> - <type> - <v>Categories = [atom()]</v> - </type> - <desc><p>Same as <c>rt_mask(node(), Categories)</c>.</p></desc> + <name name="rt_mask" arity="1" clause_i="2" since="OTP 20.1"></name> + <fsummary>Same as <c>rt_mask(node(), <anno>Categories</anno>)</c>.</fsummary> + <type name="category_atom"/> + <desc><p>Same as <c>rt_mask(node(), <anno>Categories</anno>)</c>.</p></desc> </func> <func> - <name since="OTP 20.1">rt_mask(Node, Categories) -> ok | {error, copy_save_enabled}</name> + <name name="rt_mask" arity="2" since="OTP 20.1"></name> <fsummary>Changes the lock category mask.</fsummary> - <type> - <v>Node = node()</v> - <v>Categories = [atom()]</v> - </type> + <type name="category_atom"/> <desc> <p> Sets the lock category mask to the given categories. </p> <p> This will fail if the <c>copy_save</c> option is enabled; see - <c>lcnt:rt_opt/2</c>. + <seemfa marker="#rt_opt/2"><c>lcnt:rt_opt/2</c></seemfa>. </p> <p>Valid categories are:</p> <list> @@ -490,24 +448,20 @@ </desc> </func> - <func> - <name since="OTP R13B04">rt_opt({Type, bool()}) -> bool()</name> - <fsummary>Same as <c>rt_opt(node(), {Type, Opt})</c>.</fsummary> - <desc> <p>Same as <c>rt_opt(node(), {Type, Opt})</c>.</p> </desc> - </func> - <func> - <name since="OTP R13B04">rt_opt(Node, {Type, bool()}) -> bool()</name> - <fsummary>Changes the lock counter behavior and returns the previous behaviour.</fsummary> - <type> - <v>Node = node()</v> - <v>Type = copy_save | process_locks</v> - </type> - <desc> - <p>Option description:</p> - <taglist> - <tag><c>{copy_save, bool()}</c></tag> - <item>Retains the statistics of destroyed locks. - <br/>Default: <c>false</c> + <func> + <name name="rt_opt" arity="1" since="OTP R13B04"></name> + <fsummary>Same as <c>rt_opt(node(), {<anno>Type</anno>, <anno>Value</anno>})</c>.</fsummary> + <desc> <p>Same as <c>rt_opt(node(), {<anno>Type</anno>, <anno>Value</anno>})</c>.</p> </desc> + </func> + <func> + <name name="rt_opt" arity="2" since="OTP R13B04"></name> + <fsummary>Changes the lock counter behavior and returns the previous behaviour.</fsummary> + <desc> + <p>Option description:</p> + <taglist> + <tag><c>{copy_save, boolean()}</c></tag> + <item>Retains the statistics of destroyed locks. + <br/>Default: <c>false</c> <warning> <p> This option will use a lot of memory when enabled, which must be @@ -517,20 +471,20 @@ category mask. </p> </warning> - </item> + </item> - <tag><c>{process_locks, bool()}</c></tag> - <item>Profile process locks, equal to adding <c>process</c> to the lock category mask; + <tag><c>{process_locks, boolean()}</c></tag> + <item>Profile process locks, equal to adding <c>process</c> to the lock category mask; see <c>lcnt:rt_mask/2</c> - <br/>Default: <c>true</c> - </item> - </taglist> - </desc> - </func> + <br/>Default: <c>true</c> + </item> + </taglist> + </desc> + </func> </funcs> <section> - <title>See Also</title> - <p> <seeguide marker="lcnt_chapter">LCNT User's Guide</seeguide></p> + <title>See Also</title> + <p> <seeguide marker="lcnt_chapter">LCNT User's Guide</seeguide></p> </section> </erlref> diff --git a/lib/tools/doc/src/make.xml b/lib/tools/doc/src/make.xml index 4c66fecaf1..06ba06bcbe 100644 --- a/lib/tools/doc/src/make.xml +++ b/lib/tools/doc/src/make.xml @@ -38,13 +38,9 @@ </description> <funcs> <func> - <name since="">all() -> up_to_date | error</name> - <name since="">all(Options) -> up_to_date | error</name> + <name name="all" arity="0" since=""></name> + <name name="all" arity="1" since=""></name> <fsummary>Compile a set of modules.</fsummary> - <type> - <v>Options = [Option]</v> - <v> Option = noexec | load | netload | {emake, Emake} | <compiler option></v> - </type> <desc> <p>This function determines the set of modules to compile and the compile options to use, by first looking for the <c>emake</c> make @@ -64,7 +60,7 @@ <p>As a side effect, the function prints the name of each module it tries to compile. If compilation fails for a module, the make procedure stops and <c>error</c> is returned.</p> - <p><c>Options</c> is a list of make- and compiler options. + <p><c><anno>Options</anno></c> is a list of make- and compiler options. The following make options exist:</p> <list type="bulleted"> <item><c>noexec</c> <br></br> @@ -77,29 +73,24 @@ <item><c>netload</c> <br></br> Net load mode. Loads all recompiled modules on all known nodes.</item> - <item><c>{emake, Emake}</c> <br></br> + <item><c>{emake, <anno>Emake</anno>}</c> <br></br> Rather than reading the <c>Emakefile</c> specify configuration explicitly.</item> </list> <p>All items in <c>Options</c> that are not make options are assumed to be compiler options and are passed as-is to - <c>compile:file/2</c>. <c>Options</c> defaults to <c>[]</c>.</p> + <seemfa marker="compiler:compile#file/2"><c>compile:file/2</c></seemfa>. + <c><anno>Options</anno></c> defaults to <c>[]</c>.</p> </desc> </func> <func> - <name since="">files(ModFiles) -> up_to_date | error</name> - <name since="">files(ModFiles, Options) -> up_to_date | error</name> + <name name="files" arity="1" since=""></name> + <name name="files" arity="2" since=""></name> <fsummary>Compile a set of modules.</fsummary> - <type> - <v>ModFiles = [Module | File]</v> - <v> Module = atom()</v> - <v> File = string()</v> - <v>Options = [Option]</v> - <v> Option = noexec | load | netload | <compiler option></v> - </type> <desc> - <p><c>files/1,2</c> does exactly the same thing as <c>all/0,1</c> but - for the specified <c>ModFiles</c>, which is a list of module or + <p><c>files/1,2</c> does exactly the same thing as + <seemfa marker="#all/0"><c>all/0,1</c></seemfa> but + for the specified <c><anno>ModFiles</anno></c>, which is a list of module or file names. The file extension <c>.erl</c> may be omitted.</p> <p>The <c>Emakefile</c> (if it exists) in the current directory is searched for compiler options for each module. If @@ -111,7 +102,8 @@ <section> <title>Emakefile</title> - <p><c>make:all/0,1</c> and <c>make:files/1,2</c> first looks for + <p><seemfa marker="#all/0"><c>make:all/0,1</c></seemfa> and + <seemfa marker="#files/1"><c>make:files/1,2</c></seemfa> first looks for <c>{emake, Emake}</c> in options, then in the current working directory for a file named <c>Emakefile</c>. If present <c>Emake</c> should contain elements like this:</p> @@ -123,7 +115,7 @@ Modules. <list type="bulleted"> <item>a module name, e.g. <c>file1</c></item> <item>a module name in another directory, - e.g. <c>../foo/file3</c></item> + e.g. <c>'../foo/file3'</c></item> <item>a set of modules specified with a wildcards, e.g. <c>'file*'</c></item> <item>a wildcard indicating all modules in current directory, diff --git a/lib/tools/doc/src/specs.xml b/lib/tools/doc/src/specs.xml index 0b5b7b171c..4f7223e2bc 100644 --- a/lib/tools/doc/src/specs.xml +++ b/lib/tools/doc/src/specs.xml @@ -1,5 +1,6 @@ <?xml version="1.0" encoding="utf-8" ?> <specs xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="../specs/specs_cprof.xml"/> <xi:include href="../specs/specs_fprof.xml"/> <xi:include href="../specs/specs_make.xml"/> <xi:include href="../specs/specs_lcnt.xml"/> diff --git a/lib/tools/doc/src/tags.xml b/lib/tools/doc/src/tags.xml index d73e7e3365..45b6f45f11 100644 --- a/lib/tools/doc/src/tags.xml +++ b/lib/tools/doc/src/tags.xml @@ -42,56 +42,76 @@ </description> <funcs> <func> - <name since="">file(File [, Options])</name> - <fsummary>Create a <c>TAGS</c>file for the file <c>File</c>.</fsummary> + <name name="file" arity="1" since=""></name> + <name name="file" arity="2" since=""></name> + <fsummary>Create a <c>TAGS</c>file for the file <c><anno>File</anno></c>. + </fsummary> + <type name="option"/> <desc> - <p>Create a <c>TAGS</c> file for the file <c>File</c>.</p> + <p>Create a <c>TAGS</c> file for the file <c><anno>File</anno></c>.</p> </desc> </func> <func> - <name since="">files(FileList [, Options])</name> - <fsummary>Create a TAGS file for the files in the list<c>FileList</c>.</fsummary> + <name name="files" arity="1" since=""></name> + <name name="files" arity="2" since=""></name> + <fsummary>Create a TAGS file for the files in the list + <c><anno>FileList</anno></c>.</fsummary> + <type name="option"/> <desc> <p>Create a TAGS file for the files in the list - <c>FileList</c>.</p> + <c><anno>FileList</anno></c>.</p> </desc> </func> <func> - <name since="">dir(Dir [, Options])</name> - <fsummary>Create a TAGS file for all files in directory<c>Dir</c>.</fsummary> + <name name="dir" arity="1" since=""></name> + <name name="dir" arity="2" since=""></name> + <fsummary>Create a TAGS file for all files in directory<c><anno>Dir</anno></c>. + </fsummary> + <type name="option"/> <desc> <p>Create a TAGS file for all files in directory - <c>Dir</c>.</p> + <c><anno>Dir</anno></c>.</p> </desc> </func> <func> - <name since="">dirs(DirList [, Options])</name> + <name name="dirs" arity="1" since=""></name> + <name name="dirs" arity="2" since=""></name> <fsummary>Create a TAGS file for all files in any directory in<c>DirList</c>.</fsummary> + <type name="option"/> <desc> <p>Create a TAGS file for all files in any directory in - <c>DirList</c>.</p> + <c><anno>DirList</anno></c>.</p> </desc> </func> <func> - <name since="">subdir(Dir [, Options])</name> - <fsummary>Descend recursively down the directory <c>Dir</c>and create a <c>TAGS</c>file based on all files found.</fsummary> + <name name="subdir" arity="1" since=""></name> + <name name="subdir" arity="2" since=""></name> + <fsummary>Descend recursively down the directory <c><anno>Dir</anno></c> + and create a <c>TAGS</c> file based on all files found.</fsummary> + <type name="option"/> <desc> - <p>Descend recursively down the directory <c>Dir</c> and + <p>Descend recursively down the directory <c><anno>Dir</anno></c> and create a <c>TAGS</c> file based on all files found.</p> </desc> </func> <func> - <name since="">subdirs(DirList [, Options])</name> - <fsummary>Descend recursively down all the directories in<c>DirList</c>and create a <c>TAGS</c>file based on all files found.</fsummary> + <name name="subdirs" arity="1" since=""></name> + <name name="subdirs" arity="2" since=""></name> + <fsummary>Descend recursively down all the directories in + <c><anno>DirList</anno></c> and create a <c>TAGS</c>file based + on all files found.</fsummary> + <type name="option"/> <desc> <p>Descend recursively down all the directories in - <c>DirList</c> and create a <c>TAGS</c> file based on all + <c><anno>DirList</anno></c> and create a <c>TAGS</c> file based on all files found.</p> </desc> </func> <func> - <name since="">root([Options])</name> + <name name="root" arity="0" since=""></name> + <name name="root" arity="1" since=""></name> <fsummary>Create a <c>TAGS</c>file covering all files in the Erlang distribution.</fsummary> + <type name="option"/> <desc> <p>Create a <c>TAGS</c> file covering all files in the Erlang distribution.</p> diff --git a/lib/tools/doc/src/xref.xml b/lib/tools/doc/src/xref.xml index 72cc5c6c39..45f5abae5d 100644 --- a/lib/tools/doc/src/xref.xml +++ b/lib/tools/doc/src/xref.xml @@ -708,40 +708,69 @@ Two functions (modules, necessary to set up module data again is called, all user variables are forgotten. </p> - <p><em>Types</em></p> - <pre> -application() = atom() -arity() = int() | -1 -bool() = true | false -call() = {atom(), atom()} | funcall() -constant() = mfa() | module() | application() | release() -directory() = string() -file() = string() -funcall() = {mfa(), mfa()} -function() = atom() -int() = integer() >= 0 -library() = atom() -library_path() = path() | code_path -mfa() = {module(), function(), arity()} -mode() = functions | modules -module() = atom() -release() = atom() -string_position() = int() | at_end -variable() = atom() -xref() = atom() | pid() </pre> </description> + <datatypes> + <datatype> + <name name="application"></name> + </datatype> + <datatype> + <name name="call"></name> + </datatype> + <datatype> + <name name="constant"></name> + </datatype> + <datatype> + <name name="directory"></name> + </datatype> + <datatype> + <name name="file"></name> + </datatype> + <datatype> + <name name="file_error"></name> + </datatype> + <datatype> + <name name="funcall"></name> + </datatype> + <datatype> + <name name="function_name"></name> + </datatype> + <datatype> + <name name="library"></name> + </datatype> + <datatype> + <name name="library_path"></name> + </datatype> + <datatype> + <name name="mode"></name> + </datatype> + <datatype> + <name name="path"></name> + </datatype> + <datatype> + <name name="release"></name> + </datatype> + <datatype> + <name name="string_position"></name> + </datatype> + <datatype> + <name name="variable"></name> + </datatype> + <datatype> + <name name="xarity"></name> + </datatype> + <datatype> + <name name="xmfa"></name> + </datatype> + <datatype> + <name name="xref"></name> + </datatype> + </datatypes> <funcs> <func> - <name since="">add_application(Xref, Directory [, Options]) -> {ok, application()} | Error</name> + <name name="add_application" arity="2" since=""></name> + <name name="add_application" arity="3" since=""></name> <fsummary>Add the modules of an application.</fsummary> - <type> - <v>Directory = directory()</v> - <v>Error = {error, module(), Reason}</v> - <v>Options = [Option] | Option</v> - <v>Option = {builtins, bool()} | {name, application()} | {verbose, bool()} | {warnings, bool()}</v> - <v>Reason = {application_clash, {application(), directory(), directory()}} | {file_error, file(), error()} | {invalid_filename, term()} | {invalid_options, term()} | - see also add_directory -</v> - <v>Xref = xref()</v> - </type> + <type name="add_dir_rsn"/> <desc> <p>Adds an application, the modules of the application and <seeerl marker="#module_data">module data</seeerl> of the modules to an <seeerl marker="#xref_server">Xref server</seeerl>. @@ -764,17 +793,10 @@ xref() = atom() | pid() </pre> </desc> </func> <func> - <name since="">add_directory(Xref, Directory [, Options]) -> {ok, Modules} | Error</name> + <name name="add_directory" arity="2" since=""></name> + <name name="add_directory" arity="3" since=""></name> <fsummary>Add the modules in a directory.</fsummary> - <type> - <v>Directory = directory()</v> - <v>Error = {error, module(), Reason}</v> - <v>Modules = [module()]</v> - <v>Options = [Option] | Option</v> - <v>Option = {builtins, bool()} | {recurse, bool()} | {verbose, bool()} | {warnings, bool()}</v> - <v>Reason = {file_error, file(), error()} | {invalid_filename, term()} | {invalid_options, term()} | {unrecognized_file, file()} | - error from beam_lib:chunks/2 -</v> - <v>Xref = xref()</v> - </type> + <type name="add_dir_rsn"/> <desc> <p>Adds the modules found in the given directory and the <seeerl marker="#module_data">modules' data</seeerl> to an <seeerl marker="#xref_server">Xref server</seeerl>. @@ -794,16 +816,10 @@ xref() = atom() | pid() </pre> </desc> </func> <func> - <name since="">add_module(Xref, File [, Options]) -> {ok, module()} | Error</name> + <name name="add_module" arity="2" since=""></name> + <name name="add_module" arity="3" since=""></name> <fsummary>Add a module.</fsummary> - <type> - <v>Error = {error, module(), Reason}</v> - <v>File = file()</v> - <v>Options = [Option] | Option</v> - <v>Option = {builtins, bool()} | {verbose, bool()} | {warnings, bool()}</v> - <v>Reason = {file_error, file(), error()} | {invalid_filename, term()} | {invalid_options, term()} | {module_clash, {module(), file(), file()}} | {no_debug_info, file()} | - error from beam_lib:chunks/2 -</v> - <v>Xref = xref()</v> - </type> + <type name="add_mod_rsn"/> <desc> <p>Adds a module and its <seeerl marker="#module_data">module data</seeerl> to an <seeerl marker="#xref_server">Xref server</seeerl>. The module will not be member of any application. @@ -817,16 +833,10 @@ xref() = atom() | pid() </pre> </desc> </func> <func> - <name since="">add_release(Xref, Directory [, Options]) -> {ok, release()} | Error</name> + <name name="add_release" arity="2" since=""></name> + <name name="add_release" arity="3" since=""></name> <fsummary>Add the modules of a release.</fsummary> - <type> - <v>Directory = directory()</v> - <v>Error = {error, module(), Reason}</v> - <v>Options = [Option] | Option</v> - <v>Option = {builtins, bool()} | {name, release()} | {verbose, bool()} | {warnings, bool()}</v> - <v>Reason = {application_clash, {application(), directory(), directory()}} | {file_error, file(), error()} | {invalid_filename, term()} | {invalid_options, term()} | {release_clash, {release(), directory(), directory()}} | - see also add_directory -</v> - <v>Xref = xref()</v> - </type> + <type name="add_dir_rsn"/> <desc> <p>Adds a release, the applications of the release, the modules of the applications, and <seeerl marker="#module_data">module data</seeerl> of the @@ -852,22 +862,16 @@ xref() = atom() | pid() </pre> </desc> </func> <func> - <name since="">analyze(Xref, Analysis [, Options]) -> {ok, Answer} | Error</name> + <name name="analyze" arity="2" since=""></name> + <name name="analyze" arity="3" since=""></name> <fsummary>Evaluate a predefined analysis.</fsummary> - <type> - <v>Analysis = undefined_function_calls | undefined_functions | locals_not_used | exports_not_used | deprecated_function_calls | {deprecated_function_calls, DeprFlag} | deprecated_functions | {deprecated_functions, DeprFlag} | {call, FuncSpec} | {use, FuncSpec} | {module_call, ModSpec} | {module_use, ModSpec} | {application_call, AppSpec} | {application_use, AppSpec} | {release_call, RelSpec} | {release_use, RelSpec}</v> - <v>Answer = [term()]</v> - <v>AppSpec = application() | [application()]</v> - <v>DeprFlag = next_version | next_major_release | eventually</v> - <v>Error = {error, module(), Reason}</v> - <v>FuncSpec = mfa() | [mfa()]</v> - <v>ModSpec = module() | [module()]</v> - <v>Options = [Option] | Option</v> - <v>Option = {verbose, bool()}</v> - <v>RelSpec = release() | [release()]</v> - <v>Reason = {invalid_options, term()} | {parse_error, string_position(), term()} | {unavailable_analysis, term()} | {unknown_analysis, term()} | {unknown_constant, string()} | {unknown_variable, variable()}</v> - <v>Xref = xref()</v> - </type> + <type name="analysis"/> + <type name="app_spec"/> + <type name="depr_flag"/> + <type name="func_spec"/> + <type name="mod_spec"/> + <type name="rel_spec"/> + <type name="analyze_rsn"/> <desc> <p> <marker id="analyze"></marker> Evaluates a predefined analysis. @@ -890,69 +894,62 @@ Evaluates a predefined analysis. </item> <tag><c>deprecated_function_calls</c>(*)</tag> <item>Returns a list of external calls to <seeerl marker="#deprecated_function">deprecated functions</seeerl>.</item> - <tag><c>{deprecated_function_calls, DeprFlag}</c>(*)</tag> + <tag><c>{deprecated_function_calls, <anno>DeprFlag</anno>}</c>(*)</tag> <item>Returns a list of external calls to deprecated - functions. If <c>DeprFlag</c> is equal to + functions. If <c><anno>DeprFlag</anno></c> is equal to <c>next_version</c>, calls to functions to be removed in - next version are returned. If <c>DeprFlag</c> is equal to + next version are returned. If <c><anno>DeprFlag</anno></c> is equal to <c>next_major_release</c>, calls to functions to be removed in next major release are returned as well as calls to functions to be removed in next version. Finally, - if <c>DeprFlag</c> is equal to <c>eventually</c>, all + if <c><anno>DeprFlag</anno></c> is equal to <c>eventually</c>, all calls to functions to be removed are returned, including calls to functions to be removed in next version or next major release.</item> <tag><c>deprecated_functions</c></tag> <item>Returns a list of externally used deprecated functions.</item> - <tag><c>{deprecated_functions, DeprFlag}</c></tag> + <tag><c>{deprecated_functions, <anno>DeprFlag</anno>}</c></tag> <item>Returns a list of externally used deprecated - functions. If <c>DeprFlag</c> is equal to + functions. If <c><anno>DeprFlag</anno></c> is equal to <c>next_version</c>, functions to be removed in next - version are returned. If <c>DeprFlag</c> is equal to + version are returned. If <c><anno>DeprFlag</anno></c> is equal to <c>next_major_release</c>, functions to be removed in next major release are returned as well as functions to be - removed in next version. Finally, if <c>DeprFlag</c> is + removed in next version. Finally, if <c><anno>DeprFlag</anno></c> is equal to <c>eventually</c>, all functions to be removed are returned, including functions to be removed in next version or next major release.</item> - <tag><c>{call, FuncSpec}</c>(*)</tag> + <tag><c>{call, <anno>FuncSpec</anno>}</c>(*)</tag> <item>Returns a list of functions called by some of the given functions.</item> - <tag><c>{use, FuncSpec}</c>(*)</tag> + <tag><c>{use, <anno>FuncSpec</anno>}</c>(*)</tag> <item>Returns a list of functions that use some of the given functions.</item> - <tag><c>{module_call, ModSpec}</c></tag> + <tag><c>{module_call, <anno>ModSpec</anno>}</c></tag> <item>Returns a list of modules called by some of the given modules.</item> - <tag><c>{module_use, ModSpec}</c></tag> + <tag><c>{module_use, <anno>ModSpec</anno>}</c></tag> <item>Returns a list of modules that use some of the given modules.</item> - <tag><c>{application_call, AppSpec}</c></tag> + <tag><c>{application_call, <anno>AppSpec</anno>}</c></tag> <item>Returns a list of applications called by some of the given applications.</item> - <tag><c>{application_use, AppSpec}</c></tag> + <tag><c>{application_use, <anno>AppSpec</anno>}</c></tag> <item>Returns a list of applications that use some of the given applications.</item> - <tag><c>{release_call, RelSpec}</c></tag> + <tag><c>{release_call, <anno>RelSpec</anno>}</c></tag> <item>Returns a list of releases called by some of the given releases.</item> - <tag><c>{release_use, RelSpec}</c></tag> + <tag><c>{release_use, <anno>RelSpec</anno>}</c></tag> <item>Returns a list of releases that use some of the given releases.</item> </taglist> </desc> </func> <func> - <name since="">d(Directory) -> [DebugInfoResult] | [NoDebugInfoResult] | Error</name> + <name name="d" arity="1" since=""></name> <fsummary>Check the modules in a directory using the code path.</fsummary> - <type> - <v>Directory = directory()</v> - <v>DebugInfoResult = {deprecated, [funcall()]} | {undefined, [funcall()]} | {unused, [mfa()]}</v> - <v>Error = {error, module(), Reason}</v> - <v>NoDebugInfoResult = {deprecated, [mfa()]} | {undefined, [mfa()]}</v> - <v>Reason = {file_error, file(), error()} | {invalid_filename, term()} | {unrecognized_file, file()} | - error from beam_lib:chunks/2 -</v> - </type> <desc> <p>The modules found in the given directory are checked for calls to <seeerl marker="#deprecated_function">deprecated functions</seeerl>, calls to <seeerl marker="#undefined_function">undefined functions</seeerl>, @@ -984,76 +981,46 @@ Evaluates a predefined analysis. </desc> </func> <func> - <name since="">forget(Xref) -> ok</name> - <name since="">forget(Xref, Variables) -> ok | Error</name> + <name name="forget" arity="1" since=""></name> + <name name="forget" arity="2" since=""></name> <fsummary>Remove user variables and their values.</fsummary> - <type> - <v>Error = {error, module(), Reason}</v> - <v>Reason = {not_user_variable, term()}</v> - <v>Variables = [variable()] | variable()</v> - <v>Xref = xref()</v> - </type> <desc> <p><c>forget/1</c> and <c>forget/2</c> remove all or some of - the <seeerl marker="#user_variable">user variables</seeerl> of an <seeerl marker="#xref_server">xref server</seeerl>.</p> + the <seeerl marker="#user_variable">user variables</seeerl> of an <seeerl marker="#xref_server">Xref server</seeerl>.</p> </desc> </func> <func> - <name since="">format_error(Error) -> Chars</name> + <name name="format_error" arity="1" since=""></name> <fsummary>Return an English description of an Xref error reply.</fsummary> - <type> - <v>Error = {error, module(), term()}</v> - <v>Chars = [char() | Chars]</v> - </type> <desc> <p>Given the error returned by any function of this module, the function <c>format_error</c> returns a descriptive string of the error in English. For file errors, the function - <c>format_error/1</c> in the <c>file</c> module is called.</p> + <seemfa marker="kernel:file#format_error/1"><c>file:format_error/1</c></seemfa> + is called.</p> </desc> </func> <func> - <name since="">get_default(Xref) -> [{Option, Value}]</name> - <name since="">get_default(Xref, Option) -> {ok, Value} | Error</name> + <name name="get_default" arity="1" since=""></name> + <name name="get_default" arity="2" since=""></name> <fsummary>Return the default values of options.</fsummary> - <type> - <v>Error = {error, module(), Reason}</v> - <v>Option = builtins | recurse | verbose | warnings</v> - <v>Reason = {invalid_options, term()}</v> - <v>Value = bool()</v> - <v>Xref = xref()</v> - </type> <desc> <p>Returns the default values of one or more options.</p> </desc> </func> <func> - <name since="">get_library_path(Xref) -> {ok, LibraryPath}</name> + <name name="get_library_path" arity="1" since=""></name> <fsummary>Return the library path.</fsummary> - <type> - <v>LibraryPath = library_path()</v> - <v>Xref = xref()</v> - </type> <desc> <p>Returns the <seeerl marker="#library_path">library path</seeerl>.</p> </desc> </func> <func> - <name since="">info(Xref) -> [Info]</name> - <name since="">info(Xref, Category) -> [{Item, [Info]}]</name> - <name since="">info(Xref, Category, Items) -> [{Item, [Info]}]</name> + <name name="info" arity="1" since=""></name> + <name name="info" arity="2" since=""></name> + <name name="info" arity="3" since=""></name> <fsummary>Return information about an Xref server.</fsummary> - <type> - <v>Application = [] | [application()]</v> - <v>Category = modules | applications | releases | libraries</v> - <v>Info = {application, Application} | {builtins, bool()} | {directory, directory()} | {library_path, library_path()} | {mode, mode()} | {no_analyzed_modules, int()} | {no_applications, int()} | {no_calls, {NoResolved, NoUnresolved}} | {no_function_calls, {NoLocal, NoResolvedExternal, NoUnresolved}} | {no_functions, {NoLocal, NoExternal}} | {no_inter_function_calls, int()} | {no_releases, int()} | {release, Release} | {version, Version}</v> - <v>Item = module() | application() | release() | library()</v> - <v>Items = Item | [Item]</v> - <v>NoLocal = NoExternal = NoResolvedExternal, NoResolved = NoUnresolved = int()</v> - <v>Release = [] | [release()]</v> - <v>Version = [int()]</v> - <v>Xref = xref()</v> - </type> + <type name="info"/> <desc> <p>The <c>info</c> functions return information as a list of pairs {Tag, term()} in some order about the state and the @@ -1225,21 +1192,12 @@ Evaluates a predefined analysis. </desc> </func> <func> - <name since="">m(Module) -> [DebugInfoResult] | [NoDebugInfoResult] | Error</name> - <name since="">m(File) -> [DebugInfoResult] | [NoDebugInfoResult] | Error</name> + <name name="m" arity="1" since=""></name> <fsummary>Check a module using the code path.</fsummary> - <type> - <v>DebugInfoResult = {deprecated, [funcall()]} | {undefined, [funcall()]} | {unused, [mfa()]}</v> - <v>Error = {error, module(), Reason}</v> - <v>File = file()</v> - <v>Module = module()</v> - <v>NoDebugInfoResult = {deprecated, [mfa()]} | {undefined, [mfa()]}</v> - <v>Reason = {file_error, file(), error()} | {interpreted, module()} | {invalid_filename, term()} | {cover_compiled, module()} | {no_such_module, module()} | - error from beam_lib:chunks/2 -</v> - </type> <desc> <p>The given BEAM file (with or without the <c>.beam</c> extension) or the file found by calling - <c>code:which(Module)</c> is checked for calls to <seeerl marker="#deprecated_function">deprecated functions</seeerl>, calls to <seeerl marker="#undefined_function">undefined functions</seeerl>, + <c>code:which(<anno>Module</anno>)</c> is checked for calls to <seeerl marker="#deprecated_function">deprecated functions</seeerl>, calls to <seeerl marker="#undefined_function">undefined functions</seeerl>, and for unused local functions. The code path is used as <seeerl marker="#library_path">library path</seeerl>. </p> @@ -1268,25 +1226,13 @@ Evaluates a predefined analysis. </desc> </func> <func> - <name since="">q(Xref, Query [, Options]) -> {ok, Answer} | Error</name> + <name name="q" arity="2" since=""></name> + <name name="q" arity="3" since=""></name> <fsummary>Evaluate a query.</fsummary> - <type> - <v>Answer = false | [constant()] | [Call] | [Component] | int() | [DefineAt] | [CallAt] | [AllLines]</v> - <v>Call = call() | ComponentCall</v> - <v>ComponentCall = {Component, Component}</v> - <v>Component = [constant()]</v> - <v>DefineAt = {mfa(), LineNumber}</v> - <v>CallAt = {funcall(), LineNumbers}</v> - <v>AllLines = {{DefineAt, DefineAt}, LineNumbers}</v> - <v>Error = {error, module(), Reason}</v> - <v>LineNumbers = [LineNumber]</v> - <v>LineNumber = int()</v> - <v>Options = [Option] | Option</v> - <v>Option = {verbose, bool()}</v> - <v>Query = string() | atom()</v> - <v>Reason = {invalid_options, term()} | {parse_error, string_position(), term()} | {type_error, string()} | {type_mismatch, string(), string()} | {unknown_analysis, term()} | {unknown_constant, string()} | {unknown_variable, variable()} | {variable_reassigned, string()}</v> - <v>Xref = xref()</v> - </type> + <type name="answer"/> + <type name="define_at"/> + <type name="component"/> + <type name="q_rsn"/> <desc> <p>Evaluates a <seeerl marker="#query">query</seeerl> in the context of an <seeerl marker="#xref_server">Xref server</seeerl>, and returns the value of the last @@ -1299,9 +1245,10 @@ Evaluates a predefined analysis. <item>A set of constants is represented by a sorted list without duplicates of <c>constant()</c>.</item> <item>A set of strongly connected components is a sorted list - without duplicates of <c>Component</c>.</item> + without duplicates of <c><anno>Component</anno></c>.</item> <item>A set of calls between strongly connected components is - a sorted list without duplicates of <c>ComponentCall</c>.</item> + a sorted list without duplicates of + <c><anno>ComponentCall</anno></c>.</item> <item>A chain of calls is represented by a list of <c>constant()</c>. The list contains the From vertex of every call and the To vertex of the last call.</item> @@ -1311,56 +1258,39 @@ Evaluates a predefined analysis. <c>digraph</c> representation) is represented by the atom <c>'closure()'</c>.</item> <item>A set of line numbered functions is represented by a sorted - list without duplicates of <c>DefineAt</c>.</item> + list without duplicates of <c><anno>DefineAt</anno></c>.</item> <item>A set of line numbered function calls is represented by - a sorted list without duplicates of <c>CallAt</c>.</item> + a sorted list without duplicates of <c><anno>CallAt</anno></c>.</item> <item>A set of line numbered functions and function calls is represented by a sorted list without duplicates of <c>AllLines</c>.</item> </list> - <p>For both <c>CallAt</c> and <c>AllLines</c> it holds that for - no list element is <c>LineNumbers</c> an empty list; such + <p>For both <c><anno>CallAt</anno></c> and <c><anno>AllLines</anno></c> + it holds that for + no list element is <c><anno>LineNumbers</anno></c> an empty list; such elements have been removed. The constants of <c>component</c> - and the integers of <c>LineNumbers</c> are sorted and without - duplicates. + and the integers of <c><anno>LineNumbers</anno></c> are sorted and + without duplicates. </p> </desc> </func> <func> - <name since="">remove_application(Xref, Applications) -> ok | Error</name> + <name name="remove_application" arity="2" since=""></name> <fsummary>Remove applications and their modules.</fsummary> - <type> - <v>Applications = application() | [application()]</v> - <v>Error = {error, module(), Reason}</v> - <v>Reason = {no_such_application, application()}</v> - <v>Xref = xref()</v> - </type> <desc> <p>Removes applications and their modules and <seeerl marker="#module_data">module data</seeerl> from an <seeerl marker="#xref_server">Xref server</seeerl>.</p> </desc> </func> <func> - <name since="">remove_module(Xref, Modules) -> ok | Error</name> + <name name="remove_module" arity="2" since=""></name> <fsummary>Remove analyzed modules.</fsummary> - <type> - <v>Error = {error, module(), Reason}</v> - <v>Modules = module() | [module()]</v> - <v>Reason = {no_such_module, module()}</v> - <v>Xref = xref()</v> - </type> <desc> <p>Removes <seeerl marker="#analyzed_module">analyzed modules</seeerl> and <seeerl marker="#module_data">module data</seeerl> from an <seeerl marker="#xref_server">Xref server</seeerl>.</p> </desc> </func> <func> - <name since="">remove_release(Xref, Releases) -> ok | Error</name> + <name name="remove_release" arity="2" since=""></name> <fsummary>Remove releases and their applications and modules.</fsummary> - <type> - <v>Error = {error, module(), Reason}</v> - <v>Reason = {no_such_release, release()}</v> - <v>Releases = release() | [release()]</v> - <v>Xref = xref()</v> - </type> <desc> <p>Removes releases and their applications, modules and <seeerl marker="#module_data">module data</seeerl> from an @@ -1368,17 +1298,10 @@ Evaluates a predefined analysis. </desc> </func> <func> - <name since="">replace_application(Xref, Application, Directory [, Options]) -> {ok, application()} | Error</name> + <name name="replace_application" arity="3" since=""></name> + <name name="replace_application" arity="4" since=""></name> <fsummary>Replace an application's modules.</fsummary> - <type> - <v>Application = application()</v> - <v>Directory = directory()</v> - <v>Error = {error, module(), Reason}</v> - <v>Options = [Option] | Option</v> - <v>Option = {builtins, bool()} | {verbose, bool()} | {warnings, bool()}</v> - <v>Reason = {no_such_application, application()} | - see also add_application -</v> - <v>Xref = xref()</v> - </type> + <type name="add_dir_rsn"/> <desc> <p>Replaces the modules of an application with other modules read from an application directory. Release membership of the @@ -1389,18 +1312,10 @@ Evaluates a predefined analysis. </desc> </func> <func> - <name since="">replace_module(Xref, Module, File [, Options]) -> {ok, module()} | Error</name> + <name name="replace_module" arity="3" since=""></name> + <name name="replace_module" arity="4" since=""></name> <fsummary>Replace an analyzed module.</fsummary> - <type> - <v>Error = {error, module(), Reason}</v> - <v>File = file()</v> - <v>Module = module()</v> - <v>Options = [Option] | Option</v> - <v>Option = {verbose, bool()} | {warnings, bool()}</v> - <v>ReadModule = module()</v> - <v>Reason = {module_mismatch, module(), ReadModule} | {no_such_module, module()} | - see also add_module -</v> - <v>Xref = xref()</v> - </type> + <type name="add_mod_rsn"/> <desc> <p>Replaces <seeerl marker="#module_data">module data</seeerl> of an <seeerl marker="#analyzed_module">analyzed module</seeerl> with data read from a BEAM file. Application membership of the @@ -1414,18 +1329,9 @@ Evaluates a predefined analysis. </desc> </func> <func> - <name since="">set_default(Xref, Option, Value) -> {ok, OldValue} | Error</name> - <name since="">set_default(Xref, OptionValues) -> ok | Error</name> + <name name="set_default" arity="3" since=""></name> + <name name="set_default" arity="2" since=""></name> <fsummary>Set the default values of options.</fsummary> - <type> - <v>Error = {error, module(), Reason}</v> - <v>OptionValues = [OptionValue] | OptionValue</v> - <v>OptionValue = {Option, Value}</v> - <v>Option = builtins | recurse | verbose | warnings</v> - <v>Reason = {invalid_options, term()}</v> - <v>Value = bool()</v> - <v>Xref = xref()</v> - </type> <desc> <p>Sets the default value of one or more options. The options that can be set this way are:</p> @@ -1440,16 +1346,9 @@ Evaluates a predefined analysis. </desc> </func> <func> - <name since="">set_library_path(Xref, LibraryPath [, Options]) -> ok | Error</name> + <name name="set_library_path" arity="2" since=""></name> + <name name="set_library_path" arity="3" since=""></name> <fsummary>Set the library path and finds the library modules.</fsummary> - <type> - <v>Error = {error, module(), Reason}</v> - <v>LibraryPath = library_path()</v> - <v>Options = [Option] | Option</v> - <v>Option = {verbose, bool()}</v> - <v>Reason = {invalid_options, term()} | {invalid_path, term()}</v> - <v>Xref = xref()</v> - </type> <desc> <p>Sets the <seeerl marker="#library_path">library path</seeerl>. If the given path is a list of directories, the set of <seeerl marker="#library_module">library modules</seeerl> is @@ -1466,7 +1365,8 @@ Evaluates a predefined analysis. each used <seeerl marker="#library_module">library module</seeerl> while setting up module data. On the other hand, if there are only a few modules that are used but not analyzed, using <c>code_path</c> may be faster - than setting the library path to <c>code:get_path()</c>. + than setting the library path to + <seemfa marker="kernel:code#get_path/0"> <c>code:get_path()</c></seemfa>. </p> <p>If the library path is set to <c>code_path</c>, the set of library modules is not determined, and the <c>info</c> @@ -1474,61 +1374,41 @@ Evaluates a predefined analysis. </desc> </func> <func> - <name since="">start(NameOrOptions) -> Return</name> + <name name="start" arity="1" since=""></name> <fsummary>Create an Xref server.</fsummary> - <type> - <v>NameOrOptions = Name | Options</v> - <v>Name = atom()</v> - <v>Options = [Option] | Option</v> - <v>Option = {xref_mode, mode()} | term()</v> - <v>Return = {ok, pid()} | {error, {already_started, pid()}}</v> - </type> <desc> <p>Creates an <seeerl marker="#xref_server">Xref server</seeerl>. The process may optionally be given a name. The default <seeerl marker="#mode">mode</seeerl> is <c>functions</c>. Options that are not recognized by Xref - are passed on to <c>gen_server:start/4</c>.</p> + are passed on to + <seemfa marker="stdlib:gen_server#start/4"><c>gen_server:start/4</c></seemfa>.</p> </desc> </func> <func> - <name since="">start(Name, Options) -> Return</name> + <name name="start" arity="2" since=""></name> <fsummary>Create an Xref server.</fsummary> - <type> - <v>Name = atom()</v> - <v>Options = [Option] | Option</v> - <v>Option = {xref_mode, mode()} | term()</v> - <v>Return = {ok, pid()} | {error, {already_started, pid()}}</v> - </type> <desc> <p>Creates an <seeerl marker="#xref_server">Xref server</seeerl> with a given name. The default <seeerl marker="#mode">mode</seeerl> is <c>functions</c>. Options that are not recognized by Xref - are passed on to <c>gen_server:start/4</c>.</p> + are passed on to + <seemfa marker="stdlib:gen_server#start/4"><c>gen_server:start/4</c></seemfa>.</p> </desc> </func> <func> - <name since="">stop(Xref)</name> + <name name="stop" arity="1" since=""></name> <fsummary>Delete an Xref server.</fsummary> - <type> - <v>Xref = xref()</v> - </type> <desc> <p>Stops an <seeerl marker="#xref_server">Xref server</seeerl>.</p> </desc> </func> <func> - <name since="">update(Xref [, Options]) -> {ok, Modules} | Error</name> + <name name="update" arity="1" since=""></name> + <name name="update" arity="2" since=""></name> <fsummary>Replace newly compiled analyzed modules.</fsummary> - <type> - <v>Error = {error, module(), Reason}</v> - <v>Modules = [module()]</v> - <v>Options = [Option] | Option</v> - <v>Option = {verbose, bool()} | {warnings, bool()}</v> - <v>Reason = {invalid_options, term()} | {module_mismatch, module(), ReadModule} | - see also add_module -</v> - <v>Xref = xref()</v> - </type> + <type name="add_mod_rsn"/> <desc> <p>Replaces the <seeerl marker="#module_data">module data</seeerl> of all <seeerl marker="#analyzed_module">analyzed modules</seeerl> the BEAM files of which have been modified since last read by an @@ -1539,15 +1419,9 @@ Evaluates a predefined analysis. </desc> </func> <func> - <name since="">variables(Xref [, Options]) -> {ok, [VariableInfo]}</name> + <name name="variables" arity="1" since=""></name> + <name name="variables" arity="2" since=""></name> <fsummary>Return the names of variables.</fsummary> - <type> - <v>Options = [Option] | Option</v> - <v>Option = predefined | user | {verbose, bool()}</v> - <v>Reason = {invalid_options, term()}</v> - <v>VariableInfo = {predefined, [variable()]} | {user, [variable()]}</v> - <v>Xref = xref()</v> - </type> <desc> <p>Returns a sorted lists of the names of the variables of an <seeerl marker="#xref_server">Xref server</seeerl>. |