From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/runtime_tools/doc/html/.gitignore | 0 lib/runtime_tools/doc/man3/.gitignore | 0 lib/runtime_tools/doc/man6/.gitignore | 0 lib/runtime_tools/doc/pdf/.gitignore | 0 lib/runtime_tools/doc/src/Makefile | 123 +++ lib/runtime_tools/doc/src/book.xml | 46 + lib/runtime_tools/doc/src/dbg.xml | 1187 ++++++++++++++++++++++ lib/runtime_tools/doc/src/erts_alloc_config.xml | 211 ++++ lib/runtime_tools/doc/src/fascicules.xml | 15 + lib/runtime_tools/doc/src/make.dep | 20 + lib/runtime_tools/doc/src/note.gif | Bin 0 -> 1539 bytes lib/runtime_tools/doc/src/notes.xml | 503 +++++++++ lib/runtime_tools/doc/src/notes_history.xml | 48 + lib/runtime_tools/doc/src/part_notes.xml | 38 + lib/runtime_tools/doc/src/part_notes_history.xml | 38 + lib/runtime_tools/doc/src/ref_man.xml | 38 + lib/runtime_tools/doc/src/runtime_tools_app.xml | 56 + lib/runtime_tools/doc/src/warning.gif | Bin 0 -> 1498 bytes 18 files changed, 2323 insertions(+) create mode 100644 lib/runtime_tools/doc/html/.gitignore create mode 100644 lib/runtime_tools/doc/man3/.gitignore create mode 100644 lib/runtime_tools/doc/man6/.gitignore create mode 100644 lib/runtime_tools/doc/pdf/.gitignore create mode 100644 lib/runtime_tools/doc/src/Makefile create mode 100644 lib/runtime_tools/doc/src/book.xml create mode 100644 lib/runtime_tools/doc/src/dbg.xml create mode 100644 lib/runtime_tools/doc/src/erts_alloc_config.xml create mode 100644 lib/runtime_tools/doc/src/fascicules.xml create mode 100644 lib/runtime_tools/doc/src/make.dep create mode 100644 lib/runtime_tools/doc/src/note.gif create mode 100644 lib/runtime_tools/doc/src/notes.xml create mode 100644 lib/runtime_tools/doc/src/notes_history.xml create mode 100644 lib/runtime_tools/doc/src/part_notes.xml create mode 100644 lib/runtime_tools/doc/src/part_notes_history.xml create mode 100644 lib/runtime_tools/doc/src/ref_man.xml create mode 100644 lib/runtime_tools/doc/src/runtime_tools_app.xml create mode 100644 lib/runtime_tools/doc/src/warning.gif (limited to 'lib/runtime_tools/doc') diff --git a/lib/runtime_tools/doc/html/.gitignore b/lib/runtime_tools/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/runtime_tools/doc/man3/.gitignore b/lib/runtime_tools/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/runtime_tools/doc/man6/.gitignore b/lib/runtime_tools/doc/man6/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/runtime_tools/doc/pdf/.gitignore b/lib/runtime_tools/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/runtime_tools/doc/src/Makefile b/lib/runtime_tools/doc/src/Makefile new file mode 100644 index 0000000000..dbbae81cfe --- /dev/null +++ b/lib/runtime_tools/doc/src/Makefile @@ -0,0 +1,123 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1999-2009. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% +# +include $(ERL_TOP)/make/target.mk + +# Make the docs target default. + +default: docs + +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(RUNTIME_TOOLS_VSN) +APPLICATION=runtime_tools + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = ref_man.xml +XML_REF3_FILES = dbg.xml erts_alloc_config.xml +XML_REF6_FILES = runtime_tools_app.xml + +XML_PART_FILES = part_notes.xml part_notes_history.xml +XML_CHAPTER_FILES = notes.xml notes_history.xml + +BOOK_FILES = book.xml + +XML_FILES = \ + $(BOOK_FILES) $(XML_CHAPTER_FILES) \ + $(XML_PART_FILES) $(XML_REF3_FILES) \ + $(XML_REF6_FILES) $(XML_APPLICATION_FILES) + +GIF_FILES = + +# ---------------------------------------------------- + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) +MAN6_FILES = $(XML_REF6_FILES:%_app.xml=$(MAN6DIR)/%.6) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +man: $(MAN3_FILES) $(MAN6_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +debug opt: + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(MAN6DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man6 + $(INSTALL_DATA) $(MAN6_FILES) $(RELEASE_PATH)/man/man6 + +release_spec: + diff --git a/lib/runtime_tools/doc/src/book.xml b/lib/runtime_tools/doc/src/book.xml new file mode 100644 index 0000000000..3f0dd7d55e --- /dev/null +++ b/lib/runtime_tools/doc/src/book.xml @@ -0,0 +1,46 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Runtime_Tools + Patrik Nyblom + + 1999-05-31 + A + book.sgml +
+ + + Runtime_Tools + + + + + + + + + + + + + diff --git a/lib/runtime_tools/doc/src/dbg.xml b/lib/runtime_tools/doc/src/dbg.xml new file mode 100644 index 0000000000..0e63649c09 --- /dev/null +++ b/lib/runtime_tools/doc/src/dbg.xml @@ -0,0 +1,1187 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + dbg + Patrik Nyblom (Claes Wikstrom) + + 1 + ETX/B/SFP (Kenneth Lundin) + + 96-11-07 + A + dbg.sgml +
+ dbg + The Text Based Trace Facility + +

This module implements a text based interface to the + trace/3 and the trace_pattern/2 BIFs. It makes it + possible to trace functions, processes and messages on text based + terminals. It can be used instead of, or as complement to, the + pman module. +

+

For some examples of how to use dbg from the Erlang + shell, see the simple example section. +

+

The utilities are also suitable to use in system testing on + large systems, where other tools have too much impact on the + system performance. Some primitive support for sequential tracing + is also included, see the advanced topics section. +

+ + + + fun2ms(LiteralFun) -> MatchSpec + Pseudo function that transforms fun syntax to match_spec. + + LiteralFun = fun() literal + MatchSpec = term() + + +

Pseudo function that by means of a parse_transform + translates the literalfun() typed as parameter in + the function call to a match specification as described in + the match_spec manual of ERTS users guide. + (with literal I mean that the fun() needs to + textually be written as the parameter of the function, it + cannot be held in a variable which in turn is passed to the + function).

+

The parse transform is implemented in the module + ms_transform and the source must include the + file ms_transform.hrl in STDLIB for this + pseudo function to work. Failing to include the hrl file in + the source will result in a runtime error, not a compile + time ditto. The include file is easiest included by adding + the line + -include_lib("stdlib/include/ms_transform.hrl"). to + the source file.

+

The fun() is very restricted, it can take only a + single parameter (the parameter list to match), a sole variable or a + list. It needs to use the is_XXX guard tests and one + cannot use language constructs that have no representation + in a match_spec (like if, case, + receive etc). The return value from the fun will be + the return value of the resulting match_spec.

+

Example:

+ 
+1> dbg:fun2ms(fun([M,N]) when N > 3 -> return_trace() end).
+[{['$1','$2'],[{'>','$2',3}],[{return_trace}]}]
+

Variables from the environment can be imported, so that this + works:

+ 
+2> X=3.
+3
+3> dbg:fun2ms(fun([M,N]) when N > X  -> return_trace() end).
+[{['$1','$2'],[{'>','$2',{const,3}}],[{return_trace}]}]
+

The imported variables will be replaced by match_spec + const expressions, which is consistent with the + static scoping for Erlang fun()s. Local or global + function calls can not be in the guard or body of the fun + however. Calls to builtin match_spec functions of course is + allowed:

+ 
+4> dbg:fun2ms(fun([M,N]) when N > X, is_atomm(M)  -> return_trace() end).
+Error: fun containing local erlang function calls ('is_atomm' called in guard) cannot be translated into match_spec
+{error,transform_error}
+5> dbg:fun2ms(fun([M,N]) when N > X, is_atom(M)  -> return_trace() end).
+[{['$1','$2'],[{'>','$2',{const,3}},{is_atom,'$1'}],[{return_trace}]}]
+

As you can see by the example, the function can be called from + the shell too. The fun() needs to be literally in the + call when used from the shell as well. Other means than the + parse_transform are used in the shell case, but more or less + the same restrictions apply (the exception being records, + as they are not handled by the shell).

+ +

If the parse_transform is not applied to a module which calls this + pseudo function, the call will fail in runtime (with a + badarg). The module dbg actually exports a + function with this name, but it should never really be called + except for when using the function in the shell. If the + parse_transform is properly applied by including + the ms_transform.hrl header file, compiled code + will never call the function, but the function call is + replaced by a literal match_spec.

+ +

More information is provided by the ms_transform + manual page in STDLIB.

+ + + + h() -> ok + Give a list of available help items on standard output. + +

Gives a list of items for brief online help.

+ + + + h(Item) -> ok + Give brief help for an item. + + Item = atom() + + +

Gives a brief help text for functions in the dbg module. The + available items can be listed with dbg:h/0

+ + + + p(Item) -> {ok, MatchDesc} | {error, term()} + Trace messages to and from Item. + +

Equivalent to p(Item, [m]).

+ + + + p(Item, Flags) -> {ok, MatchDesc} | {error, term()} + Trace Item according to Flags. + + MatchDesc = [MatchNum] + MatchNum = {matched, node(), integer()} | {matched, node(), 0, RPCError} + RPCError = term() + + +

Traces Item in accordance to the value specified + by Flags. The variation of Item is listed below:

+ + If the Item is a pid(), the corresponding + process is traced. The process may be a remote process + (on another Erlang node). The node must be in the list of + traced nodes (seen/1 and tracer/0/2/3). + If the Item is the atom all, all processes in the + system as well as all processes created hereafter are + to be traced. This also affects all nodes added with the + n/1 or tracer/0/2/3 function. + If the Item is the atom new, no currently existing + processes are affected, but every process created after the + call is.This also affects all nodes added with the + n/1 or tracer/0/2/3 function. + If the Item is the atom existing, all + existing processes are traced, but new processes will not + be affected.This also affects all nodes added with the + n/1 or tracer/0/2/3 function. + If the Item is an atom other than all, + new or existing, the process with the + corresponding registered name is traced.The process may be a + remote process (on another Erlang node). The node must be added + with the n/1 or tracer/0/2/3 function. + If the Item is an integer, the process ]]> is + traced. + If the Item is a tuple {X, Y, Z}, the + process ]]> is + traced. + If the Item is a string "]]> + as returned from pid_to_list/1, the process + ]]> is traced. + +

Flags can be a single atom, + or a list of flags. The available flags are: +

+ + s (send) + +

Traces the messages the process sends.

+ + r (receive) + +

Traces the messages the process receives.

+ + m (messages) + +

Traces the messages the process receives and sends.

+ + c (call) + +

Traces global function calls for the process + according to the trace patterns set in the system (see tp/2).

+ + p (procs) + +

Traces process related events to the process.

+ + sos (set on spawn) + +

Lets all processes created by the traced + process inherit the trace flags + of the traced process.

+ + sol (set on link) + +

Lets another process, P2, inherit the + trace flags of the traced + process whenever the traced process links to P2.

+ + sofs (set on first spawn) + +

This is the same as sos, but only + for the first process spawned by the traced process.

+ + sofl (set on first link) + +

This is the same as sol, but only for + the first call to + link/1 by the traced process.

+ + all + +

Sets all flags.

+ + clear + +

Clears all flags. +

+ + +

The list can also include any of the flags allowed in + erlang:trace/3

+

The function returns either an error tuple or a tuple + {ok, List}. The List consists of + specifications of how many processes that matched (in the + case of a pure pid() exactly 1). The specification of + matched processes is {matched, Node, N}. If the + remote processor call,rpc, to a remote node fails, + the rpc error message is delivered as a fourth + argument and the number of matched processes are 0. Note + that the result {ok, List} may contain a list where + rpc calls to one, several or even all nodes failed.

+ + + + c(Mod, Fun, Args) + Evaluate apply(M,F,Args)with alltrace flags set. + +

Equivalent to c(Mod, Fun, Args, all).

+ + + + c(Mod, Fun, Args, Flags) + Evaluate apply(M,F,Args)with Flagstrace flags set. + +

Evaluates the expression apply(Mod, Fun, Args) with the trace + flags in Flags set. This is a convenient way to trace processes + from the Erlang shell.

+ + + + i() -> ok + Display information about all traced processes. + +

Displays information about all traced processes.

+ + + + tp(Module,MatchSpec) + Set pattern for traced global function calls + +

Same as tp({Module, '_', '_'}, MatchSpec)

+ + + + tp(Module,Function,MatchSpec) + Set pattern for traced global function calls + +

Same as tp({Module, Function, '_'}, MatchSpec)

+ + + + tp(Module, Function, Arity, MatchSpec) + Set pattern for traced global function calls + +

Same as tp({Module, Function, Arity}, MatchSpec)

+ + + + tp({Module, Function, Arity}, MatchSpec) -> {ok, MatchDesc} | {error, term()} + Set pattern for traced global function calls + + Module = atom() | '_' + Function = atom() | '_' + Arity = integer() |'_' + MatchSpec = integer() | atom() | [] | match_spec() + MatchDesc = [MatchInfo] + MatchInfo = {saved, integer()} | MatchNum + MatchNum = {matched, node(), integer()} | {matched, node(), 0, RPCError} + + +

This function enables call trace for one or more + functions. All exported functions matching the {Module, Function, Arity} argument will be concerned, but the + match_spec() may further narrow down the set of function + calls generating trace messages.

+

For a description of the match_spec() syntax, + please turn to the + User's guide part of the online + documentation for the runtime system (erts). The + chapter Match Specification in Erlang explains the + general match specification "language".

+

The Module, Function and/or Arity parts of the tuple may + be specified as the atom '_' which is a "wild-card" + matching all modules/functions/arities. Note, if the + Module is specified as '_', the Function and Arity + parts have to be specified as '_' too. The same holds for the + Functions relation to the Arity.

+

All nodes added with n/1 or tracer/0/2/3 will + be affected by this call, and if Module is not '_' + the module will be loaded on all nodes.

+

The function returns either an error tuple or a tuple + {ok, List}. The List consists of specifications of how + many functions that matched, in the same way as the processes + are presented in the return value of p/2.

+

There may be a tuple {saved, N} in the return value, + if the MatchSpec is other + than []. The integer N may then be used in + subsequent calls to this function and will stand as an + "alias" for the given expression. There are also built-in + aliases named with atoms (see also ltp/0 below).

+

If an error is returned, it can be due to errors in + compilation of the match specification. Such errors are + presented as a list of tuples {error, string()} where + the string is a textual explanation of the compilation + error. An example:

+ 
+(x@y)4> dbg:tp({dbg,ltp,0},[{[],[],[{message, two, arguments}, {noexist}]}]).
+{error,
+ [{error,"Special form 'message' called with wrong number of
+          arguments in {message,two,arguments}."},
+  {error,"Function noexist/1 does_not_exist."}]}
+ + + + tpl(Module,MatchSpec) + Set pattern for traced local (as well as global) function calls + +

Same as tpl({Module, '_', '_'}, MatchSpec)

+ + + + tpl(Module,Function,MatchSpec) + Set pattern for traced local (as well as global) function calls + +

Same as tpl({Module, Function, '_'}, MatchSpec)

+ + + + tpl(Module, Function, Arity, MatchSpec) + Set pattern for traced local (as well as global) function calls + +

Same as tpl({Module, Function, Arity}, MatchSpec)

+ + + + tpl({Module, Function, Arity}, MatchSpec) -> {ok, MatchDesc} | {error, term()} + Set pattern for traced local (as well as global) function calls + +

This function works as tp/2, but enables + tracing for local calls (and local functions) as well as for + global calls (and functions).

+ + + + ctp() + Clear call trace pattern for the specified functions + +

Same as ctp({'_', '_', '_'})

+ + + + ctp(Module) + Clear call trace pattern for the specified functions + +

Same as ctp({Module, '_', '_'})

+ + + + ctp(Module, Function) + Clear call trace pattern for the specified functions + +

Same as ctp({Module, Function, '_'})

+ + + + ctp(Module, Function, Arity) + Clear call trace pattern for the specified functions + +

Same as ctp({Module, Function, Arity})

+ + + + ctp({Module, Function, Arity}) -> {ok, MatchDesc} | {error, term()} + Clear call trace pattern for the specified functions + + Module = atom() | '_' + Function = atom() | '_' + Arity = integer() | '_' + MatchDesc = [MatchNum] + MatchNum = {matched, node(), integer()} | {matched, node(), 0, RPCError} + + +

This function disables call tracing on the specified + functions. The semantics of the parameter is the same + as for the corresponding function specification in + tp/2 or tpl/2. Both local and global call trace + is disabled.

+

The return value reflects how many functions that matched, + and is constructed as described in tp/2. No tuple + {saved, N} is however ever returned (for obvious reasons).

+ + + + ctpl() + Clear call trace pattern for the specified functions + +

Same as ctpl({'_', '_', '_'})

+ + + + ctpl(Module) + Clear call trace pattern for the specified functions + +

Same as ctpl({Module, '_', '_'})

+ + + + ctpl(Module, Function) + Clear call trace pattern for the specified functions + +

Same as ctpl({Module, Function, '_'})

+ + + + ctpl(Module, Function, Arity) + Clear call trace pattern for the specified functions + +

Same as ctpl({Module, Function, Arity})

+ + + + ctpl({Module, Function, Arity}) -> {ok, MatchDesc} | {error, term()} + Clear call trace pattern for the specified functions + +

This function works as ctp/1, but only disables + tracing set up with tpl/2 (not with tp/2).

+ + + + ctpg() + Clear call trace pattern for the specified functions + +

Same as ctpg({'_', '_', '_'})

+ + + + ctpg(Module) + Clear call trace pattern for the specified functions + +

Same as ctpg({Module, '_', '_'})

+ + + + ctpg(Module, Function) + >Clear call trace pattern for the specified functions + +

Same as ctpg({Module, Function, '_'})

+ + + + ctpg(Module, Function, Arity) + >Clear call trace pattern for the specified functions + +

Same as ctpg({Module, Function, Arity})

+ + + + ctpg({Module, Function, Arity}) -> {ok, MatchDesc} | {error, term()} + Clear call trace pattern for the specified functions + +

This function works as ctp/1, but only disables + tracing set up with tp/2 (not with tpl/2).

+ + + + ltp() -> ok + List saved and built-in match specifications on the console. + +

Use this function to recall all match specifications previously + used in the session (i. e. previously saved during calls + to tp/2, and built-in match specifications. + This is very useful, as a complicated + match_spec can be quite awkward to write. Note that the + match specifications are lost if stop/0 is called.

+

Match specifications used can be saved in a file (if a + read-write file system is present) for use in later + debugging sessions, see wtp/1 and rtp/1

+ + + + dtp() -> ok + Delete all saved match specifications. + +

Use this function to "forget" all match specifications + saved during calls to tp/2. + This is useful when one wants to restore other match + specifications from a file with rtp/1. Use + dtp/1 to delete specific saved match specifications.

+ + + + dtp(N) -> ok + Delete a specific saved match_spec. + + N = integer() + + +

Use this function to "forget" a specific match specification + saved during calls to tp/2.

+ + + + wtp(Name) -> ok | {error, IOError} + Write all saved and built-in match specifications to a file + + Name = string() + IOError = term() + + +

This function will save all match specifications saved + during the session (during calls to tp/2) + and built-in match specifications in a text + file with the name designated by Name. The format + of the file is textual, why it can be edited with an + ordinary text editor, and then restored with + rtp/1.

+

Each match spec in the file ends with a full stop + (.) and new (syntactically correct) match + specifications can be added to the file manually.

+

The function returns ok or an error tuple where the + second element contains the I/O error that made the + writing impossible.

+ + + + rtp(Name) -> ok | {error, Error} + Read saved match specifications from file. + + Name = string() + Error = term() + + +

This function reads match specifications from a file + (possibly) generated by the wtp/1 function. It checks + the syntax of all match specifications and verifies that + they are correct. The error handling principle is "all or + nothing", i. e. if some of the match specifications are + wrong, none of the specifications are added to the list of + saved match specifications for the running system.

+

The match specifications in the file are merged + with the current match specifications, so that no duplicates + are generated. Use ltp/0 to see what numbers were + assigned to the specifications from the file.

+

The function will return an error, either due to I/O + problems (like a non existing or non readable file) or due + to file format problems. The errors from a bad format file + are in a more or less textual format, which will give a hint + to what's causing the problem. +

+ + + + n(Nodename) -> {ok, Nodename} | {error, Reason} + Add a remote node to the list of traced nodes + + Nodename = atom() + Reason = term() + + +

The dbg server keeps a list of nodes where tracing + should be performed. Whenever a tp/2 call or a + p/2 call is made, it is executed for all nodes in this + list including the local node (except for p/2 with a + specific pid() as first argument, in which case the + command is executed only on the node where the designated + process resides). +

+

This function adds a remote node (Nodename) to the + list of nodes where tracing is performed. It starts a tracer + process on the remote node, which will send all trace messages + to the tracer process on the local node (via the Erlang + distribution). If no tracer process is running on the local + node, the error reason no_local_tracer is returned. The + tracer process on the local node must be started with the + tracer/0/2 function. +

+

If Nodename is the local node, the error reason + cant_add_local_node is returned. +

+

If a trace port (seetrace_port/2) is + running on the local node, remote nodes can not be traced with + a tracer process. The error reason + cant_trace_remote_pid_to_local_port is returned. A + trace port can however be started on the remote node with the + tracer/3 function. +

+

The function will also return an error if the node + Nodename is not reachable.

+ + + + cn(Nodename) -> ok + Clear a node from the list of traced nodes. + + Nodename = atom() + + +

Clears a node from the list of traced nodes. Subsequent + calls to tp/2 and p/2 will not consider that + node, but tracing already activated on the node will continue + to be in effect.

+

Returns ok, cannot fail.

+ + + + ln() -> ok + Show the list of traced nodes on the console. + +

Shows the list of traced nodes on the console.

+ + + + tracer() -> {ok, pid()} | {error, already_started} + Start a tracer server that handles trace messages. + +

This function starts a server on the local node that will + be the recipient of all trace messages. All subsequent calls + to p/2 will result in messages sent to the newly + started trace server.

+

A trace server started in this way will simply display the + trace messages in a formatted way in the Erlang shell + (i. e. use io:format). See tracer/2 for a description + of how the trace message handler can be customized. +

+

To start a similar tracer on a remote node, use n/1.

+ + + + tracer(Type, Data) -> {ok, pid()} | {error, Error} + Start a tracer server with additional parameters + + Type = port | process + Data = PortGenerator | HandlerSpec + HandlerSpec = {HandlerFun, InitialData} + HandlerFun = fun() (two arguments) + InitialData = term() + PortGenerator = fun() (no arguments) + Error = term() + + +

This function starts a tracer server with additional + parameters on the local node. The first parameter, the + Type, indicates if trace messages should be handled + by a receiving process (process) or by a tracer port + (port). For a description about tracer ports see + trace_port/2. +

+

If Type is a process, a message handler function can + be specified (HandlerSpec). The handler function, which + should be a fun taking two arguments, will be called + for each trace message, with the first argument containing the + message as it is and the second argument containing the return + value from the last invocation of the fun. The initial value + of the second parameter is specified in the InitialData + part of the HandlerSpec. The HandlerFun may + chose any appropriate action to take when invoked, and can + save a state for the next invocation by returning it. +

+

If Type is a port, then the second parameter should + be a fun which takes no arguments and returns a + newly opened trace port when called. Such a fun is + preferably generated by calling trace_port/2. +

+

If an error is returned, it can either be due to a tracer + server already running ({error,already_started}) or + due to the HandlerFun throwing an exception. +

+

To start a similar tracer on a remote node, use + tracer/3. +

+ + + + tracer(Nodename, Type, Data) -> {ok, Nodename} | {error, Reason} + Start a tracer server on given node with additional parameters + + Nodename = atom() + + +

This function is equivalent to tracer/2, but acts on + the given node. A tracer is started on the node + (Nodename) and the node is added to the list of traced + nodes. +

+ +

This function is not equivalent to n/1. While + n/1 starts a process tracer which redirects all trace + information to a process tracer on the local node (i.e. the + trace control node), tracer/3 starts a tracer of any + type which is independent of the tracer on the trace control + node.

+ +

For details, seetracer/2.

+ + + + trace_port(Type, Parameters) -> fun() + Create and returns a trace port generatingfun + + Type = ip | file + Parameters = Filename | WrapFilesSpec | IPPortSpec + Filename = string() | [string()] | atom() + WrapFilesSpec = {Filename, wrap, Suffix} | {Filename, wrap, Suffix, WrapSize} | {Filename, wrap, Suffix, WrapSize, WrapCnt} + Suffix = string() + WrapSize = integer() >= 0 | {time, WrapTime} + WrapTime = integer() >= 1 + WrapCnt = integer() >= 1 + IpPortSpec = PortNumber | {PortNumber, QueSize} + PortNumber = integer() + QueSize = integer() + + +

This function creates a trace port generating fun. + The fun takes no arguments and returns a newly opened + trace port. The return value from this function is suitable as + a second parameter to tracer/2, i. e. dbg:tracer(port, dbg:trace_port(ip, 4711)).

+

A trace port is an + Erlang port to a dynamically linked in driver that handles + trace messages directly, without the overhead of sending them + as messages in the Erlang virtual machine.

+

Two trace drivers are currently implemented, the + file and the ip trace drivers. The file driver + sends all trace messages into one or several binary files, + from where they later can be fetched and processed with the + trace_client/2 function. The ip driver opens a TCP/IP + port where it listens for connections. When a client + (preferably started by calling trace_client/2 on + another Erlang node) connects, all trace messages are sent + over the IP network for further processing by the remote + client.

+

Using a trace port significantly lowers the overhead + imposed by using tracing.

+

The file trace driver expects a filename or a wrap files + specification as parameter. A file is written with a high + degree of buffering, why all trace messages are not + guaranteed to be saved in the file in case of a system + crash. That is the price to pay for low tracing overhead.

+

A wrap files specification is used to limit the disk + space consumed by the trace. The trace is written to a + limited number of files each with a limited size. + The actual filenames are Filename ++ SeqCnt ++ Suffix, where SeqCnt counts as a decimal string + from 0 to WrapCnt and then around again from + 0. When a trace term written to + the current file makes it longer than WrapSize, + that file is closed, if the number of files in this + wrap trace is as many as WrapCnt the oldest file + is deleted then a new file is opened to become the current. + Thus, when a wrap trace has been stopped, there are at most + WrapCnt trace files saved with a size of at least + WrapSize (but not much bigger), except for + the last file that might even be empty. The default values + are WrapSize = 128*1024 and WrapCnt = 8.

+

The SeqCnt values in the filenames are all in the + range 0 through WrapCnt with a gap in the + circular sequence. The gap is needed to find the end of the + trace.

+

If the WrapSize is specified as + {time, WrapTime}, the current file is closed when it + has been open more than WrapTime milliseconds, + regardless of it being empty or not.

+

The ip trace driver has a queue of QueSize messages + waiting to be delivered. If the driver cannot deliver messages + as fast as they are produced by the runtime system, a special + message is sent, which indicates how many messages that are + dropped. That message will arrive at the handler function + specified in trace_client/3 as the tuple {drop, N} where N is the number of consecutive messages + dropped. In case of heavy tracing, drop's are likely to occur, + and they surely occur if no client is reading the trace + messages.

+ + + + flush_trace_port() + Equivalent to flush_trace_port(node()). + +

Equivalent to flush_trace_port(node()).

+ + + + flush_trace_port(Nodename) -> ok | {error, Reason} + Flush internal data buffers in a trace driver on the given node. + +

Equivalent to trace_port_control(Nodename,flush).

+ + + + trace_port_control(Operation) + Equivalent to trace_port_control(node(),Operation). + +

Equivalent to trace_port_control(node(),Operation).

+ + + + trace_port_control(Nodename,Operation) -> ok | {ok, Result} | {error, Reason} + Perform a control operation on the active trace port driver on the given node. + + Nodename = atom() + + +

This function is used to do a control operation on the + active trace port driver on the given node + (Nodename). Which operations that are allowed as well + as their return values are depending on which trace driver + that is used.

+

Returns either ok or {ok, Result} + if the operation was successful, or {error, Reason} + if the current tracer is a process + or if it is a port not supporting the operation.

+

The allowed values for Operation are:

+ + flush + +

This function is used to flush the internal buffers + held by a trace port driver. Currently only the + file trace driver supports this operation. + Returns ok.

+ + get_listen_port + +

Returns {ok, IpPort} where IpPortis + the IP port number used by the driver listen socket. + Only the ip trace driver supports this operation.

+ + + + + + trace_client(Type, Parameters) -> pid() + Start a trace client that reads messages created by a trace port driver + + Type = ip | file | follow_file + Parameters = Filename | WrapFilesSpec | IPClientPortSpec + Filename = string() | [string()] | atom() + WrapFilesSpec = see trace_port/2 + Suffix = string() + IpClientPortSpec = PortNumber | {Hostname, PortNumber} + PortNumber = integer() + Hostname = string() + + +

This function starts a trace client that reads the output + created by a trace port driver and handles it in mostly the + same way as a tracer process created by the tracer/0 + function.

+

If Type is file, the client reads all trace + messages stored in the file named Filename or + specified by WrapFilesSpec (must be the same as used + when creating the trace, see trace_port/2) + and let's the default handler function format the + messages on the console. This is one way to interpret the data + stored in a file by the file trace port driver.

+

If Type is follow_file, the client behaves as + in the file case, but keeps trying to read (and + process) more data + from the file until stopped by stop_trace_client/1. + WrapFilesSpec is not allowed as second argument + for this Type.

+

If Type is ip, the client connects to the + TCP/IP port PortNumber on the host Hostname, + from where it reads trace messages until the TCP/IP connection + is closed. If no Hostname is specified, the local host + is assumed.

+

As an example, one can let trace messages be sent over the + network to another Erlang node (preferably not + distributed), where the formatting occurs:

+

On the node stack there's an Erlang node + ant@stack, in the shell, type the following:

+ 
+ant@stack> dbg:tracer(port, dbg:trace_port(ip,4711)).
+<0.17.0>
+ant@stack> dbg:p(self(), send).
+{ok,1}
+

All trace messages are now sent to the trace port driver, + which in turn listens for connections on the TCP/IP port + 4711. If we want to see the messages on another node, + preferably on another host, we do like this:

+ 
+-> dbg:trace_client(ip, {"stack", 4711}).
+<0.42.0>
+

If we now send a message from the shell on the node + ant@stack, where all sends from the shell are traced:

+ 
+ant@stack> self() ! hello.
+hello
+

The following will appear at the console on the node that + started the trace client:

+ 
+(<0.23.0>) <0.23.0> ! hello
+(<0.23.0>) <0.22.0> ! {shell_rep,<0.23.0>,{value,hello,[],[]}}
+

The last line is generated due to internal message passing + in the Erlang shell. The process id's will vary.

+ + + + trace_client(Type, Parameters, HandlerSpec) -> pid() + Start a trace client that reads messages created by a trace port driver, with a user defined handler + + Type = ip | file | follow_file + Parameters = Filename | WrapFilesSpec | IPClientPortSpec + Filename = string() | [string()] | atom() + WrapFilesSpec = see trace_port/2 + Suffix = string() + IpClientPortSpec = PortNumber | {Hostname, PortNumber} + PortNumber = integer() + Hostname = string() + HandlerSpec = {HandlerFun, InitialData} + HandlerFun = fun() (two arguments) + InitialData = term() + + +

This function works exactly as trace_client/2, but + allows you to write your own handler function. The handler + function works mostly as the one described in + tracer/2, but will also have to be prepared to handle + trace messages of the form {drop, N}, where N is + the number of dropped messages. This pseudo trace message will + only occur if the ip trace driver is used.

+

For trace type file, the pseudo trace message + end_of_trace will appear at the end of the trace. The + return value from the handler function is in this case + ignored.

+ + + + stop_trace_client(Pid) -> ok + Stop a trace client gracefully. + + Pid = pid() + + +

This function shuts down a previously started trace + client. The Pid argument is the process id returned + from the trace_client/2 or trace_client/3 call.

+ + + + get_tracer() + Equivalent to get_tracer(node()). + +

Equivalent to get_tracer(node()).

+ + + + get_tracer(Nodename) -> {ok, Tracer} + Return the process or port to which all trace messages are sent. + + Nodename = atom() + Tracer = port() | pid() + + +

Returns the process or port to which all trace + messages are sent.

+ + + + stop() -> stopped + Stop the dbgserver and the tracing of all processes. + +

Stops the dbg server and clears all trace flags for + all processes and all trace patterns for all functions. Also + shuts down all trace clients and closes all trace ports.

+

Note that no trace patterns are affected by this + function.

+ + + + stop_clear() -> stopped + Stop the dbgserver and the tracing of all processes, and clears trace patterns. + +

Same as stop/0, but also clears all trace patterns on local + and global functions calls.

+ + + + +
+ + Simple examples - tracing from the shell +

The simplest way of tracing from the Erlang shell is to use + dbg:c/3 or dbg:c/4, e.g. tracing the function + dbg:get_tracer/0:

+ 
+(tiger@durin)84> dbg:c(dbg,get_tracer,[]).
+(<0.154.0>) <0.152.0> ! {<0.154.0>,{get_tracer,tiger@durin}}
+(<0.154.0>) out {dbg,req,1}
+(<0.154.0>) << {dbg,{ok,<0.153.0>}}
+(<0.154.0>) in {dbg,req,1}
+(<0.154.0>) << timeout
+{ok,<0.153.0>}
+(tiger@durin)85>
+

Another way of tracing from the shell is to explicitly start a + tracer and then set the trace flags of your + choice on the processes you want to trace, e.g. trace messages and + process events:

+ 
+(tiger@durin)66> Pid = spawn(fun() -> receive {From,Msg} -> From ! Msg end end).
+<0.126.0>
+(tiger@durin)67> dbg:tracer().
+{ok,<0.128.0>}
+(tiger@durin)68> dbg:p(Pid,[m,procs]).
+{ok,[{matched,tiger@durin,1}]}
+(tiger@durin)69> Pid ! {self(),hello}.
+(<0.126.0>) << {<0.116.0>,hello}
+{<0.116.0>,hello}
+(<0.126.0>) << timeout
+(<0.126.0>) <0.116.0> ! hello
+(<0.126.0>) exit normal
+(tiger@durin)70> flush().
+Shell got hello
+ok
+(tiger@durin)71>
+

If you set the call trace flag, you also have to set a + trace pattern for the functions you want to trace:

+ 
+(tiger@durin)77> dbg:tracer().
+{ok,<0.142.0>}
+(tiger@durin)78> dbg:p(all,call).
+{ok,[{matched,tiger@durin,3}]}
+(tiger@durin)79> dbg:tp(dbg,get_tracer,0,[]).
+{ok,[{matched,tiger@durin,1}]}
+(tiger@durin)80> dbg:get_tracer().
+(<0.116.0>) call dbg:get_tracer()
+{ok,<0.143.0>}
+(tiger@durin)81> dbg:tp(dbg,get_tracer,0,[{'_',[],[{return_trace}]}]).
+{ok,[{matched,tiger@durin,1},{saved,1}]}
+(tiger@durin)82> dbg:get_tracer().
+(<0.116.0>) call dbg:get_tracer()
+(<0.116.0>) returned from dbg:get_tracer/0 -> {ok,<0.143.0>}
+{ok,<0.143.0>}
+(tiger@durin)83>
+
+ +
+ + Advanced topics - combining with seq_trace +

The dbg module is primarily targeted towards + tracing through the erlang:trace/3 function. It is + sometimes desired to trace messages in a more delicate way, which + can be done with the help of the seq_trace module. +

+

seq_trace implements sequential tracing (known in the + AXE10 world, and sometimes called "forlopp tracing"). dbg + can interpret messages generated from seq_trace and the + same tracer function for both types of tracing can be used. The + seq_trace messages can even be sent to a trace port for + further analysis. +

+

As a match specification can turn on sequential tracing, the + combination of dbg and seq_trace can be quite + powerful. This brief example shows a session where sequential + tracing is used:

+ 
+1> dbg:tracer().
+{ok,<0.30.0>}
+2> {ok, Tracer} = dbg:get_tracer().
+{ok,<0.31.0>}
+3> seq_trace:set_system_tracer(Tracer).
+false
+4> dbg:tp(dbg, get_tracer, 0, [{[],[],[{set_seq_token, send, true}]}]).
+{ok,[{matched,nonode@nohost,1},{saved,1}]}
+5> dbg:p(all,call).
+{ok,[{matched,nonode@nohost,22}]}
+6> dbg:get_tracer(), seq_trace:set_token([]).
+(<0.25.0>) call dbg:get_tracer()
+SeqTrace [0]: (<0.25.0>) <0.30.0> ! {<0.25.0>,get_tracer} [Serial: {2,4}]
+SeqTrace [0]: (<0.30.0>) <0.25.0> ! {dbg,{ok,<0.31.0>}} [Serial: {4,5}]
+{1,0,5,<0.30.0>,4}
+

This session sets the system_tracer to the same process as + the ordinary tracer process (i. e. <0.31.0>) and sets the + trace pattern for the function dbg:get_tracer to one that + has the action of setting a sequential token. When the function + is called by a traced process (all processes are traced in this + case), the process gets "contaminated" by the token and + seq_trace messages are sent both for the server request + and the response. The seq_trace:set_token([]) after the + call clears the seq_trace token, why no messages are sent + when the answer propagates via the shell to the console port. + The output would otherwise have been more noisy.

+
+ +
+ Note of caution +

When tracing function calls on a group leader process (an IO process), there is risk + of causing a deadlock. This will happen if a group leader process generates a trace + message and the tracer process, by calling the trace handler function, sends an IO + request to the same group leader. The problem can only occur if the trace handler + prints to tty using an io function such as format/2. Note that when + dbg:p(all,call) is called, IO processes are also traced. + Here's an example:

+ 
+%% Using a default line editing shell
+1> dbg:tracer(process, {fun(Msg,_) -> io:format("~p~n", [Msg]), 0 end, 0}).
+{ok,<0.37.0>}
+2> dbg:p(all, [call]).
+{ok,[{matched,nonode@nohost,25}]}
+3> dbg:tp(mymod,[{'_',[],[]}]).
+{ok,[{matched,nonode@nohost,0},{saved,1}]}
+4> mymod: % TAB pressed here
+%% -- Deadlock --
+

Here's another example:

+ 
+%% Using a shell without line editing (oldshell)
+1> dbg:tracer(process).
+{ok,<0.31.0>}
+2> dbg:p(all, [call]).
+{ok,[{matched,nonode@nohost,25}]}
+3> dbg:tp(lists,[{'_',[],[]}]).
+{ok,[{matched,nonode@nohost,0},{saved,1}]}
+% -- Deadlock --
+

The reason we get a deadlock in the first example is because when TAB is pressed + to expand the function name, the group leader (which handles character input) calls + mymod:module_info(). This generates a trace message which, in turn, causes the + tracer process to send an IO request to the group leader (by calling io:format/2). + We end up in a deadlock.

+

In the second example we use the default trace handler function. This handler + prints to tty by sending IO requests to the user process. When Erlang is + started in oldshell mode, the shell process will have user as its + group leader and so will the tracer process in this example. Since user calls + functions in lists we end up in a deadlock as soon as the first IO request is sent.

+

Here are a few suggestions for how to avoid deadlock:

+ + Don't trace the group leader of the tracer process. If tracing has been switched on + for all processes, call dbg:p(TracerGLPid,clear) to stop tracing the group leader + (TracerGLPid). process_info(TracerPid,group_leader) tells you + which process this is (TracerPid is returned from dbg:get_tracer/0). + Don't trace the user process if using the default trace handler function. + In your own trace handler function, call erlang:display/1 instead of an + io function or, if user is not used as group leader, print to + user instead of the default group leader. Example: + io:format(user,Str,Args). + +
+ + diff --git a/lib/runtime_tools/doc/src/erts_alloc_config.xml b/lib/runtime_tools/doc/src/erts_alloc_config.xml new file mode 100644 index 0000000000..5e7cbe4172 --- /dev/null +++ b/lib/runtime_tools/doc/src/erts_alloc_config.xml @@ -0,0 +1,211 @@ + + + + +
+ + 20072009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erts_alloc_config + Rickard Green + 1 + 07-05-30 + 1 + erts_alloc_config.sgml +
+ erts_alloc_config + Configuration tool for erts_alloc + + +

erts_alloc_config is currently an experimental + tool and might be subject to backward incompatible + changes.

+ +

erts_alloc(3) is an + Erlang Run-Time System internal memory allocator library. + erts_alloc_config is intended to be used to aid creation + of an erts_alloc(3) + configuration that is suitable for a limited number of runtime + scenarios. The configuration that erts_alloc_config + produce is intended as a suggestion, and may need to be + adjusted manually.

+

The configuration is created based on information about a number + of runtime scenarios. It is obviously impossible to foresee every + runtime scenario that can occur. The important scenarios are + those that cause maximum or minimum load on specific memory + allocators. Load in this context is total size of memory blocks + allocated.

+

The current implementation of erts_alloc_config concentrate + on configuration of multi-block carriers. Information gathered + when a runtime scenario is saved is mainly current and maximum use + of multi-block carriers. If a parameter that change the use of + multi-block carriers is changed, a previously generated + configuration is invalid and erts_alloc_config needs + to be run again. It is mainly the single block carrier threshold + that effects the use of multi-block carriers, but other + single-block carrier parameters might as well. If another value of + a single block carrier parameter than the default is desired, use + the desired value when running erts_alloc_config.

+

A configuration is created in the following way:

+ + +

Pass the +Mea config + command-line flag to the Erlang runtime system you are going + to use for creation of the allocator configuration. It will + disable features that prevent erts_alloc_config from + doing it's job. Note, you should not use this flag + when using the created configuration. Also note that it is + important that you use the same + amount of schedulers + when creating the configuration as you are going the use on + the system using the configuration.

+ + +

Run your applications with different scenarios (the more + the better) and save information about each scenario by calling + save_scenario/0. + It may be hard to know when the applications are at an (for + erts_alloc_config) important runtime scenario. A good + approach may therefore be to call + save_scenario/0 + repeatedly, e.g. once every tenth second. Note that it is + important that your applications reach the runtime scenarios + that are important for erts_alloc_config when you are + saving scenarios; otherwise, the configuration may perform + bad.

+ + +

When you have covered all scenarios, call + make_config/1 + in order to create a configuration. The configuration is + written to a file that you have chosen. This configuration + file can later be read by an Erlang runtime-system at + startup. Pass the command line argument + -args_file FileName + to the erl(1) command.

+ + +

The configuration produced by erts_alloc_config may + need to be manually adjusted as already stated. Do not modify the + file produced by erts_alloc_config; instead, put your + modifications in another file and load this file after the + file produced by erts_alloc_config. That is, put the + -args_file FileName + argument that reads your modification file later on the + command-line than the + -args_file FileName + argument that reads the configuration file produced by + erts_alloc_config. If a memory allocation parameter + appear multiple times, the last version of will be used, i.e., + you can override parameters in the configuration file produced + by erts_alloc_config. Doing it this way simplifies + things when you want to rerun erts_alloc_config.

+ + + +

The configuration created by erts_alloc_config may + perform bad, ever horrible, for runtime scenarios that are very + different from the ones saved when creating the + configuration. You are, therefore, advised to rerun + erts_alloc_config if the applications run when the + configuration was made are changed, or if the load on the + applications have changed since the configuration was made. You + are also advised to rerun erts_alloc_config if the Erlang + runtime system used is changed.

+ +

erts_alloc_config saves information about runtime scenarios + and performs computations in a server that is automatically + started. The server register itself under the name + '__erts_alloc_config__'.

+ + + + save_scenario() -> ok | {error, Error} + Saves information about current runtime scenario + + Error = term() + + +

save_scenario/0 saves information about the current + runtime scenario. This information will later be used when + make_config/0, + or make_config/1 + is called.

+

The first time save_scenario/0 is called a server + will be started. This server will save runtime scenarios. All + saved scenarios can be removed by calling + stop/0.

+ + + + make_config() -> ok | {error, Error} + Creates an erts_alloc configuration + + Error = term() + + +

This is the same as calling + make_config(group_leader()).

+ + + + make_config(FileNameOrIODev) -> ok | {error, Error} + Creates an erts_alloc configuration + + FileNameOrIODev = string() | io_device() + Error = term() + + +

make_config/1 uses the information previously saved by + save_scenario/0 + in order to produce an erts_alloc configuration. At + least one scenario have had to be saved. All scenarios + previously saved will be used when creating the + configuration.

+

If FileNameOrIODev is a string(), + make_config/1 will use FileNameOrIODev as a + filename. A file named FileNameOrIODev is created and + the configuration will be written to that file. If + FileNameOrIODev is an + io_device() (see the + documentation of the module + io), the configuration + will be written to the io device.

+ + + + stop() -> ok | {error, Error} + + + Error = term() + + +

Stops the server that saves runtime scenarios.

+ + + + +
+ See Also +

erts_alloc(3), + erl(1), + io(3)

+
+ + + diff --git a/lib/runtime_tools/doc/src/fascicules.xml b/lib/runtime_tools/doc/src/fascicules.xml new file mode 100644 index 0000000000..5230dc7e90 --- /dev/null +++ b/lib/runtime_tools/doc/src/fascicules.xml @@ -0,0 +1,15 @@ + + + + + + Reference Manual + + + Release Notes + + + Off-Print + + + diff --git a/lib/runtime_tools/doc/src/make.dep b/lib/runtime_tools/doc/src/make.dep new file mode 100644 index 0000000000..85eae88adf --- /dev/null +++ b/lib/runtime_tools/doc/src/make.dep @@ -0,0 +1,20 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex dbg.tex erts_alloc_config.tex refman.tex \ + runtime_tools_app.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: refman.xml + diff --git a/lib/runtime_tools/doc/src/note.gif b/lib/runtime_tools/doc/src/note.gif new file mode 100644 index 0000000000..6fffe30419 Binary files /dev/null and b/lib/runtime_tools/doc/src/note.gif differ diff --git a/lib/runtime_tools/doc/src/notes.xml b/lib/runtime_tools/doc/src/notes.xml new file mode 100644 index 0000000000..3262e4819b --- /dev/null +++ b/lib/runtime_tools/doc/src/notes.xml @@ -0,0 +1,503 @@ + + + + +
+ + 20042009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Runtime_Tools Release Notes + + + + + notes.xml +
+

This document describes the changes made to the Runtime_Tools + application.

+ +
Runtime_Tools 1.8.2 + +
Improvements and New Features + + +

+ The documentation is now built with open source tools + (xsltproc and fop) that exists on most platforms. One + visible change is that the frames are removed.

+

+ Own Id: OTP-8201

+ + +
+ +
+ +
Runtime_Tools 1.8.1 + +
Fixed Bugs and Malfunctions + + +

+ Makefile.in has been updated to use the LDFLAGS + environment variable (if set). (Thanks to Davide + Pesavento.)

+

+ Own Id: OTP-8157

+ + +
+ +
+ +
Runtime_Tools 1.8 + +
Improvements and New Features + + +

+ etop would crash if the emulator's custom + allocators had been turned off (e.g. using the + +Meamin option).

+

+ Own Id: OTP-7519

+ + +

The copyright notices have been updated.

+

+ Own Id: OTP-7851

+ + +

Now, dbg:p/2 accepts {X,Y,Z} process specification as + stated in the documentation. It also now accepts + "<X.Y.Z>" like from erlang:pid_to_list/1.

+

There is now a pre-saved match spec in dbg that saves + a lot of typing. Use dbg:ltp/0 to find out more...

+

+ Own Id: OTP-7867

+ + +
+ +
+ +
Runtime_Tools 1.7.3 + +
Fixed Bugs and Malfunctions + + +

Fixed a timestamp problem where some events could be + sent out of order. Minor fixes to presentation of + data.

+

+ Own Id: OTP-7544 Aux Id: otp-7442

+ + +
+ +
+ +
Runtime_Tools 1.7.2 + +
Fixed Bugs and Malfunctions + + +

etop now collects process information faster + and more reliably than before (a race condition reported + by Igor Goryachev has been eliminated).

+

Trace messages could be lost when ttb:stop/0 + was called.

+

+ Own Id: OTP-7164

+ + +
+ +
+ +
Runtime_Tools 1.7.1 + +
Improvements and New Features + + +

The documentation has been updated so as to reflect + the last updates of the Erlang shell as well as the minor + modifications of the control sequence p of the + io_lib module.

Superfluous empty lines have + been removed from code examples and from Erlang shell + examples.

+

+ Own Id: OTP-6944 Aux Id: OTP-6554, OTP-6911

+ + +

Memory management improvements especially for the + runtime system with SMP support:

The + runtime system with SMP support can now use multiple, + thread specific instances of most memory allocators. This + improves performance since it reduces lock contention in + the memory allocators. It may however increase memory + usage for some applications. The runtime system with SMP + support will by default enable this feature on most + allocators. The amount of instances used can be + configured. driver_alloc(), + driver_realloc(), and driver_free() now use + their own erts specific memory allocator instead of the + default malloc() implementation on the system. + The default configuration of some + allocators have been changed to fit applications that use + much memory better. Some new + erts_alloc configuration parameters have been + added. erts_alloc_config has been + modified to be able to create configurations suitable for + multiple instances of allocators. The + returned value from erlang:system_info({allocator, + Alloc}) has been changed. This since an allocator may + now run in multiple instances.

If you + for some reason want the memory allocators to be + configured as before, you can pass the +Mea r11b + command-line argument to erl.

For more + information see the erts_alloc(3), the + erts_alloc_config(3), and the erlang(3) + documentation.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7100

+ + +
+ +
+ +
Runtime_Tools 1.7 + +
Fixed Bugs and Malfunctions + + +

+ dbg could leave traced processes in a suspended + state if the tracer process was killed with exit reason + kill.

+

+ erlang:suspend_process/2 has been introduced which + accepts an option list as second argument. For more + information see the erlang(3) documentation.

+

+ Processes suspended via + erlang:suspend_process/[1,2] will now be + automatically resumed if the process that called + erlang:suspend_process/[1,2] terminates.

+

+ Processes could previously be suspended by one process + and resumed by another unless someone was tracing the + suspendee. This is not possible anymore. The + process resuming a process has to be the one + that suspended it.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-6946

+ + +
+ + +
Improvements and New Features + + +

+ The undocumented and unsupported function + dbg:tracer/1 has been removed. The undocumented, + unsupported, and broken function dbg:i/1 has been + removed.

+

+ Own Id: OTP-6939

+ + +
+ +
+ +
Runtime_Tools 1.6.8 + +
Fixed Bugs and Malfunctions + + +

+ In this release the following has been fixed and + enhanced: Autostart: It is now possible to configure + modules that shall be loaded by the autostart mechanism. + This because it is not certain that all application + systems make use of the OTP boot script to set up paths + to all Erlang modules. Runtime_tools/Inviso: A bug in the + fetch_log functionality has been fixed. Further a bug + that was (supposedly) fixed in a previous patch + concerning meta-tracer write_ti has been fixed (again) in + this patch. A bug in inviso_as_lib making remote + autostart config file updates fail has been fixed. + Inviso: inviso_tool has been given a flush API.

+

+ Own Id: OTP-6918

+ + +
+ +
+
Runtime_Tools 1.6.7 + +
Improvements and New Features + + +

+ The following bugs/improvements have been done: Internal + interworking between inviso_rt and inviso_rt_meta. The + call function used by inviso_rt to call inviso_rt_meta is + now protected with a monitor. Inviso_rt_meta now includes + the timestamp of the incoming meta trace message when + calling the call-callback. (Makes it possible to add a + "better" timestamp to the ti-file.) Bug in inviso_tool + making it not remove trace patterns when terminating. Bug + in internal function h_start_session making inviso_tool + crash if there were no active nodes to start the session + on. The user-inviso_tool and inviso API-inviso control + component request/response gen_server protocols had + default time-out. Since many trace operations can be time + consuming, a longer time-out is necessary. Improved + overload protection. It is now possible to let the + overload protection renew itself (e.g after an exit from + an external overload protector). Inviso_rt_meta now fully + uses the exception_trace match spec action term. Run + Trace Case API (as in contrast to activate and deactivate + trace case APIs) in inviso_tool. Flush trace-port API + added to inviso. Get_session_data API added to + inviso_tool. Improved inviso_tool:stop making it possible + to name nodes which shall not have their trace patterns + removed when inviso_tool terminates. Bug in handling of + writing multiple ti-entries if returned from a + call/return_from call-back in inviso_rt_meta Process + trace flags are no longer explicitly removed by the + inviso_tool when it terminates. Not necessary. + Inviso_tool get_autostart_data adopted to standard + autostarter.

+

+ *** INCOMPATIBILITY with Meta trace call-backs are called + with different arguments now. ***

+

+ Own Id: OTP-6881

+ + +
+ +
+ +
+ Runtime_Tools 1.6.6 + +
+ Fixed Bugs and Malfunctions + + +

A bug in inviso_rt_meta caused an ETS table containing + information on initiated (init_tpm) functions to be lost + when suspending tracing. Further an enhancement to + inviso_rt has been introduced making it possible to + activate process trace flags based on globally registered + names. It is then not an error to activate a global name + on a node where the name does not reside. The process + count in the return value will simply be set to zero + (hence exactly one node in the NodeResult part of the + return value will indicate one matching process found). A + bug was found in fetch_log API. At the same time the + fetch_log functionality was enhanced to also offer flow + control making fetcher processes send chunks of + transferred file data at a slower pace.

+

Own Id: OTP-6703

+ + +
+ +
+ Improvements and New Features + + +

Minor Makefile changes.

+

Own Id: OTP-6689 Aux Id: OTP-6742

+ + +

An experimental tool called erts_alloc_config + has been added. erts_alloc_config is intended to + be used to aid creation of an erts_alloc + configuration that is suitable for a limited number of + runtime scenarios. For more information see the + erts_alloc_config(3) documentation.

+

Own Id: OTP-6700

+ + +
+
+ +
+ Runtime_Tools 1.6.5 + +
+ Improvements and New Features + + +

Misc improvements.

+

Own Id: OTP-6576

+ + +
+
+ +
+ Runtime_Tools 1.6.4 + +
+ Improvements and New Features + + +

This application has been updated to eliminate warnings + by Dialyzer.

+

Own Id: OTP-6551

+ + +
+
+ +
+ Runtime_Tools 1.6.3 + +
+ Fixed Bugs and Malfunctions + + +

This ticket includes several improvements and bugfixes to + both runtime_tools and inviso. The overload mechanism can + now also react to incoming messages. This is useful if + an external overload watch-dog is used. Some improvements + of variable bindings has been done to the default + autostart mechanism - inviso_autostart_server. Autostart + "jobs" can now be done in parallel, allowing for some + jobs to hang waiting for some parts of the traced system + to become ready before proceeding. Previously when using + named meta-match-specs (tpm_ms) ending up with zero + match-specs still kept the meta trace pattern active. + This caused zero match-specs to be equal to unlimited + meta tracing on that particular function. If the internal + database becomes empty of meta match specs, meta trace + pattern is removed for that function. Standard public + loop data in the inviso runtime meta tracer process is + now extended to a 2-tuple. The functions ctp/1 and ctpl/1 + are added making it possible to remove trace patterns for + a list of functions rather than one by one. + Inviso_rt_meta will now accept a list of binaries to be + output into the trace information file, in additions to a + single binary. Further it is also possible to make own + output to the trace information file using the write_ti/1 + function. An error was discovered in inviso_rt making the + inviso_rt_meta remain rather than terminate if the + inviso_rt terminated due to "running alone" (not allowed + to run without a control component). A new tool, + inviso_tool, has been added to the inviso application.

+

Own Id: OTP-6426

+ + +
+
+ +
+ Runtime_Tools 1.6.2 + +
+ Fixed Bugs and Malfunctions + + +

Several minor bugs and race conditions eliminated in the + runtime_tools and observer applications.

+

Own Id: OTP-6265

+ + +
+
+ +
+ Runtime_Tools 1.6.1 + +
+ Improvements and New Features + + +

There are new BIFs erlang:spawn_monitor/1,3, + and the new option monitor for + spawn_opt/2,3,4,5.

+

The observer_backend module has been updated to + handle the new BIFs.

+

Own Id: OTP-6281

+ + +
+
+ +
+ Runtime_Tools 1.6 +

Added the runtime part of the Inviso tracer, see the new Inviso + application for more information. This also meant adding an + application callback module and an application supervisor tree + for Runtime_Tools.

+
+ +
+ Runtime_Tools 1.5.1.1 + +
+ Improvements and New Features + + +

The dbg manual page has been updated with information + about how to avoid deadlock when tracing.

+

Own Id: OTP-5373 Aux Id: seq9729

+ + +
+
+ +
+ Runtime_Tools 1.5.1 + +
+ Fixed Bugs and Malfunctions + + +

Linked in drivers in the Crypto, and Asn1 applications + are now compiled with the -D_THREAD_SAFE and + -D_REENTRANT switches on unix when the emulator has + thread support enabled.

+

Linked in drivers on MacOSX are not compiled with the + undocumented -lbundle1.o switch anymore. Thanks to + Sean Hinde who sent us a patch.

+

Linked in driver in Crypto, and port programs in SSL, now + compiles on OSF1.

+

Minor Makefile improvements in Runtime_Tools.

+

Own Id: OTP-5346

+ + +
+
+ + diff --git a/lib/runtime_tools/doc/src/notes_history.xml b/lib/runtime_tools/doc/src/notes_history.xml new file mode 100644 index 0000000000..587d935e0a --- /dev/null +++ b/lib/runtime_tools/doc/src/notes_history.xml @@ -0,0 +1,48 @@ + + + + +
+ + 2006 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + Runtime_Tools Release Notes History + + + + +
+ +
+ Runtime_Tools 1.5 + +
+ Fixed Bugs and Malfunctions + + +

Trace IP port with port number 0 can now be opened on + 64-bit.

+

Own Id: OTP-5023

+ + +
+
+ + diff --git a/lib/runtime_tools/doc/src/part_notes.xml b/lib/runtime_tools/doc/src/part_notes.xml new file mode 100644 index 0000000000..6f7f610da0 --- /dev/null +++ b/lib/runtime_tools/doc/src/part_notes.xml @@ -0,0 +1,38 @@ + + + + +
+ + 20042009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Runtime_Tools Release Notes + + + + +
+ +

Runtime_Tools provides low footprint tracing/debugging + tools suitable for inclusion in a production system.

+

For information about older versions, see + Release Notes History.

+ + + + diff --git a/lib/runtime_tools/doc/src/part_notes_history.xml b/lib/runtime_tools/doc/src/part_notes_history.xml new file mode 100644 index 0000000000..cdd727780c --- /dev/null +++ b/lib/runtime_tools/doc/src/part_notes_history.xml @@ -0,0 +1,38 @@ + + + + +
+ + 2006 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + Runtime_Tools Release Notes History + + + + +
+ +

Runtime_Tools provides low footprint tracing/debugging + tools suitable for inclusion in a production system.

+ + + + diff --git a/lib/runtime_tools/doc/src/ref_man.xml b/lib/runtime_tools/doc/src/ref_man.xml new file mode 100644 index 0000000000..579efcd969 --- /dev/null +++ b/lib/runtime_tools/doc/src/ref_man.xml @@ -0,0 +1,38 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Runtime_Tools Reference Manual + Patrik Nyblom + + 1999-05-27 + A +
+ +

Runtime_Tools provides low footprint tracing/debugging + tools suitable for inclusion in a production system.

+ + + + + + diff --git a/lib/runtime_tools/doc/src/runtime_tools_app.xml b/lib/runtime_tools/doc/src/runtime_tools_app.xml new file mode 100644 index 0000000000..e31c8cb5f7 --- /dev/null +++ b/lib/runtime_tools/doc/src/runtime_tools_app.xml @@ -0,0 +1,56 @@ + + + + +
+ + 1999 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + runtime_tools + Patrik Nyblom + Patrik Nyblom + + + + 1999-05-27 + PA1 + runtime_tools_app.sgml +
+ runtime_tools + The Runtime tools Application + +

This chapter describes the Runtime_Tools application in OTP, + which provides low footprint tracing/debugging tools suitable + for inclusion in a production system.

+ + +
+ Configuration +

There are currently no configuration parameters available for + this application. +

+
+ +
+ SEE ALSO +

application(3)

+
+ + diff --git a/lib/runtime_tools/doc/src/warning.gif b/lib/runtime_tools/doc/src/warning.gif new file mode 100644 index 0000000000..96af52360e Binary files /dev/null and b/lib/runtime_tools/doc/src/warning.gif differ -- cgit v1.2.3