diff options
| author | Sverker Eriksson <[email protected]> | 2017-08-30 20:55:08 +0200 |
|---|---|---|
| committer | Sverker Eriksson <[email protected]> | 2017-08-30 20:55:08 +0200 |
| commit | 7c67bbddb53c364086f66260701bc54a61c9659c (patch) | |
| tree | 92ab0d4b91d5e2f6e7a3f9d61ea25089e8a71fe0 /erts/doc/src | |
| parent | 97dc5e7f396129222419811c173edc7fa767b0f8 (diff) | |
| parent | 3b7a6ffddc819bf305353a593904cea9e932e7dc (diff) | |
| download | otp-7c67bbddb53c364086f66260701bc54a61c9659c.tar.gz otp-7c67bbddb53c364086f66260701bc54a61c9659c.tar.bz2 otp-7c67bbddb53c364086f66260701bc54a61c9659c.zip | |
Merge tag 'OTP-19.0' into sverker/19/binary_to_atom-utf8-crash/ERL-474/OTP-14590
Diffstat (limited to 'erts/doc/src')
39 files changed, 14894 insertions, 4548 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index 89d7c85a86..b96cbbce40 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -1,18 +1,19 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2012. All Rights Reserved. +# Copyright Ericsson AB 1997-2016. 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/. +# 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 # -# 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. +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. # # %CopyrightEnd% # @@ -49,12 +50,14 @@ XML_REF1_FILES = epmd.xml \ XML_REF3_EFILES = \ erl_prim_loader.xml \ erlang.xml \ + erl_tracer.xml \ init.xml \ zlib.xml XML_REF3_FILES = \ driver_entry.xml \ erl_nif.xml \ + erl_tracer.xml \ erl_driver.xml \ erl_prim_loader.xml \ erlang.xml \ @@ -78,6 +81,7 @@ XML_CHAPTER_FILES = \ erl_ext_dist.xml \ erl_dist_protocol.xml \ communication.xml \ + time_correction.xml \ notes.xml \ notes_history.xml @@ -138,7 +142,7 @@ man: $(MAN1_FILES) $(MAN3_FILES) gifs: $(GIF_FILES:%=$(HTMLDIR)/%) -$(INFO_FILE): $(INFO_FILE_SRC) ../../vsn.mk +$(INFO_FILE): $(INFO_FILE_SRC) $(ERL_TOP)/make/$(TARGET)/otp.mk sed -e 's;%RELEASE%;$(SYSTEM_VSN);' $(INFO_FILE_SRC) > $(INFO_FILE) @@ -152,18 +156,9 @@ clean: rm -f $(SPECDIR)/* rm -f errs core *~ -$(SPECDIR)/specs_driver_entry.xml: - escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ - -o$(dir $@) -module driver_entry -$(SPECDIR)/specs_erl_nif.xml: - escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ - -o$(dir $@) -module erl_nif -$(SPECDIR)/specs_erl_driver.xml: +$(SPECDIR)/specs_%.xml: escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ - -o$(dir $@) -module erl_driver -$(SPECDIR)/specs_erts_alloc.xml: - escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ - -o$(dir $@) -module erts_alloc + -o$(dir $@) -module $(patsubst $(SPECDIR)/specs_%.xml,%,$@) # ---------------------------------------------------- # Release Target @@ -176,6 +171,8 @@ release_docs_spec: docs $(INSTALL_DIR) "$(RELSYSDIR)/doc/html" $(INSTALL_DATA) $(HTMLDIR)/* \ "$(RELSYSDIR)/doc/html" + $(INSTALL_DATA) $(ERL_TOP)/erts/example/time_compat.erl \ + "$(RELSYSDIR)/doc/html" $(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)" $(INSTALL_DIR) "$(RELEASE_PATH)/man/man3" $(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3" diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index e512c19e05..0b04f8f70e 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -1,24 +1,25 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2001</year><year>2013</year> + <year>2001</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. - + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + </legalnotice> <title>The Abstract Format</title> @@ -34,24 +35,24 @@ <p></p> <p>This document describes the standard representation of parse trees for Erlang programs as Erlang terms. This representation is known as the <em>abstract format</em>. - Functions dealing with such parse trees are <c><![CDATA[compile:forms/[1,2]]]></c> + Functions dealing with such parse trees are <c>compile:forms/[1,2]</c> and functions in the modules - <c><![CDATA[epp]]></c>, - <c><![CDATA[erl_eval]]></c>, - <c><![CDATA[erl_lint]]></c>, - <c><![CDATA[erl_pp]]></c>, - <c><![CDATA[erl_parse]]></c>, + <c>epp</c>, + <c>erl_eval</c>, + <c>erl_lint</c>, + <c>erl_pp</c>, + <c>erl_parse</c>, and - <c><![CDATA[io]]></c>. + <c>io</c>. They are also used as input and output for parse transforms (see the module - <c><![CDATA[compile]]></c>).</p> - <p>We use the function <c><![CDATA[Rep]]></c> to denote the mapping from an Erlang source - construct <c><![CDATA[C]]></c> to its abstract format representation <c><![CDATA[R]]></c>, and write - <c><![CDATA[R = Rep(C)]]></c>. + <c>compile</c>).</p> + <p>We use the function <c>Rep</c> to denote the mapping from an Erlang source + construct <c>C</c> to its abstract format representation <c>R</c>, and write + <c>R = Rep(C)</c>. </p> - <p>The word <c><![CDATA[LINE]]></c> below represents an integer, and denotes the + <p>The word <c>LINE</c> below represents an integer, and denotes the number of the line in the source file where the construction occurred. - Several instances of <c><![CDATA[LINE]]></c> in the same construction may denote + Several instances of <c>LINE</c> in the same construction may denote different lines.</p> <p>Since operators are not terms in their own right, when operators are mentioned below, the representation of an operator should be taken to @@ -60,71 +61,106 @@ </p> <section> - <title>Module declarations and forms</title> + <title>Module Declarations and Forms</title> <p>A module declaration consists of a sequence of forms that are either function declarations or attributes.</p> <list type="bulleted"> <item>If D is a module declaration consisting of the forms - <c><![CDATA[F_1]]></c>, ..., <c><![CDATA[F_k]]></c>, then - Rep(D) = <c><![CDATA[[Rep(F_1), ..., Rep(F_k)]]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-module(Mod)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,module,Mod}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-export([Fun_1/A_1, ..., Fun_k/A_k])]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,export,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-import(Mod,[Fun_1/A_1, ..., Fun_k/A_k])]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,import,{Mod,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-compile(Options)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,compile,Options}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-file(File,Line)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,file,{File,Line}}]]></c>.</item> - <item>If F is a record declaration <c><![CDATA[-record(Name,{V_1, ..., V_k})]]></c>, then - Rep(F) = - <c><![CDATA[{attribute,LINE,record,{Name,[Rep(V_1), ..., Rep(V_k)]}}]]></c>. For Rep(V), see below.</item> - <item>If F is a wild attribute <c><![CDATA[-A(T)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,A,T}]]></c>. + <c>F_1</c>, ..., <c>F_k</c>, then + Rep(D) = <c>[Rep(F_1), ..., Rep(F_k)]</c>.</item> + <item>If F is an attribute <c>-export([Fun_1/A_1, ..., Fun_k/A_k])</c>, then + Rep(F) = <c>{attribute,LINE,export,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}</c>.</item> + <item>If F is an attribute <c>-import(Mod,[Fun_1/A_1, ..., Fun_k/A_k])</c>, then + Rep(F) = <c>{attribute,LINE,import,{Mod,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}}</c>.</item> + <item>If F is an attribute <c>-module(Mod)</c>, then + Rep(F) = <c>{attribute,LINE,module,Mod}</c>.</item> + <item>If F is an attribute <c>-file(File,Line)</c>, then + Rep(F) = <c>{attribute,LINE,file,{File,Line}}</c>.</item> + <item>If F is a function declaration + <c>Name Fc_1 ; ... ; Name Fc_k</c>, + where each <c>Fc_i</c> is a function clause with a + pattern sequence of the same length <c>Arity</c>, then + Rep(F) = <c>{function,LINE,Name,Arity,[Rep(Fc_1), ...,Rep(Fc_k)]}</c>. + </item> + <item>If F is a function specification + <c>-Spec Name Ft_1; ...; Ft_k</c>, + where <c>Spec</c> is either the atom <c>spec</c> or the atom + <c>callback</c>, and each <c>Ft_i</c> is a possibly constrained + function type with an argument sequence of the same length + <c>Arity</c>, then Rep(F) = + <c>{attribute,Line,Spec,{{Name,Arity},[Rep(Ft_1), ..., Rep(Ft_k)]}}</c>. + </item> + <item>If F is a function specification + <c>-spec Mod:Name Ft_1; ...; Ft_k</c>, + where each <c>Ft_i</c> is a possibly constrained + function type with an argument sequence of the same length + <c>Arity</c>, then Rep(F) = + <c>{attribute,Line,spec,{{Mod,Name,Arity},[Rep(Ft_1), ..., Rep(Ft_k)]}}</c>. + </item> + <item>If F is a record declaration + <c>-record(Name,{V_1, ..., V_k})</c>, + where each <c>V_i</c> is a record field, then Rep(F) = + <c>{attribute,LINE,record,{Name,[Rep(V_1), ..., Rep(V_k)]}}</c>. + For Rep(V), see below.</item> + <item>If F is a type declaration + <c>-Type Name(V_1, ..., V_k) :: T</c>, where + <c>Type</c> is either the atom <c>type</c> or the atom <c>opaque</c>, + each <c>V_i</c> is a variable, and <c>T</c> is a type, then Rep(F) = + <c>{attribute,LINE,Type,{Name,Rep(T),[Rep(V_1), ..., Rep(V_k)]}}</c>. + </item> + <item>If F is a wild attribute <c>-A(T)</c>, then + Rep(F) = <c>{attribute,LINE,A,T}</c>. <br></br></item> - <item>If F is a function declaration <c><![CDATA[Name Fc_1 ; ... ; Name Fc_k]]></c>, - where each <c><![CDATA[Fc_i]]></c> is a function clause with a - pattern sequence of the same length <c><![CDATA[Arity]]></c>, then - Rep(F) = <c><![CDATA[{function,LINE,Name,Arity,[Rep(Fc_1), ...,Rep(Fc_k)]}]]></c>.</item> </list> <section> - <title>Record fields</title> + <title>Record Fields</title> <p>Each field in a record declaration may have an optional - explicit default initializer expression</p> + explicit default initializer expression, as well as an + optional type.</p> <list type="bulleted"> - <item>If V is <c><![CDATA[A]]></c>, then - Rep(V) = <c><![CDATA[{record_field,LINE,Rep(A)}]]></c>.</item> - <item>If V is <c><![CDATA[A = E]]></c>, then - Rep(V) = <c><![CDATA[{record_field,LINE,Rep(A),Rep(E)}]]></c>.</item> + <item>If V is <c>A</c>, then + Rep(V) = <c>{record_field,LINE,Rep(A)}</c>.</item> + <item>If V is <c>A = E</c>, + where <c>E</c> is an expression, then + Rep(V) = <c>{record_field,LINE,Rep(A),Rep(E)}</c>.</item> + <item>If V is <c>A :: T</c>, where <c>T</c> is a type, then Rep(V) = + <c>{typed_record_field,{record_field,LINE,Rep(A)},Rep(T)}</c>. + </item> + <item>If V is <c>A = E :: T</c>, where + <c>E</c> is an expression and <c>T</c> is a type, then Rep(V) = + <c>{typed_record_field,{record_field,LINE,Rep(A),Rep(E)},Rep(T)}</c>. + </item> </list> </section> <section> - <title>Representation of parse errors and end of file</title> + <title>Representation of Parse Errors and End-of-file</title> <p>In addition to the representations of forms, the list that represents - a module declaration (as returned by functions in <c><![CDATA[erl_parse]]></c> and - <c><![CDATA[epp]]></c>) may contain tuples <c><![CDATA[{error,E}]]></c> and <c><![CDATA[{warning,W}]]></c>, denoting - syntactically incorrect forms and warnings, and <c><![CDATA[{eof,LINE}]]></c>, denoting an end - of stream encountered before a complete form had been parsed.</p> + a module declaration (as returned by functions in <c>erl_parse</c> and + <c>epp</c>) may contain tuples <c>{error,E}</c> and + <c>{warning,W}</c>, denoting syntactically incorrect forms and + warnings, and <c>{eof,LINE}</c>, denoting an end-of-stream + encountered before a complete form had been parsed.</p> </section> </section> <section> - <title>Atomic literals</title> + <title>Atomic Literals</title> <p>There are five kinds of atomic literals, which are represented in the same way in patterns, expressions and guards:</p> <list type="bulleted"> - <item>If L is an integer or character literal, then - Rep(L) = <c><![CDATA[{integer,LINE,L}]]></c>.</item> + <item>If L is an atom literal, then + Rep(L) = <c>{atom,LINE,L}</c>.</item> + <item>If L is a character literal, then + Rep(L) = <c>{char,LINE,L}</c>.</item> <item>If L is a float literal, then - Rep(L) = <c><![CDATA[{float,LINE,L}]]></c>.</item> + Rep(L) = <c>{float,LINE,L}</c>.</item> + <item>If L is an integer literal, then + Rep(L) = <c>{integer,LINE,L}</c>.</item> <item>If L is a string literal consisting of the characters - <c><![CDATA[C_1]]></c>, ..., <c><![CDATA[C_k]]></c>, then - Rep(L) = <c><![CDATA[{string,LINE,[C_1, ..., C_k]}]]></c>.</item> - <item>If L is an atom literal, then - Rep(L) = <c><![CDATA[{atom,LINE,L}]]></c>.</item> + <c>C_1</c>, ..., <c>C_k</c>, then + Rep(L) = <c>{string,LINE,[C_1, ..., C_k]}</c>.</item> </list> <p>Note that negative integer and float literals do not occur as such; they are parsed as an application of the unary negation operator.</p> @@ -132,47 +168,59 @@ <section> <title>Patterns</title> - <p>If <c><![CDATA[Ps]]></c> is a sequence of patterns <c><![CDATA[P_1, ..., P_k]]></c>, then - Rep(Ps) = <c><![CDATA[[Rep(P_1), ..., Rep(P_k)]]]></c>. Such sequences occur as the + <p>If Ps is a sequence of patterns <c>P_1, ..., P_k</c>, then + Rep(Ps) = <c>[Rep(P_1), ..., Rep(P_k)]</c>. Such sequences occur as the list of arguments to a function or fun.</p> <p>Individual patterns are represented as follows:</p> <list type="bulleted"> - <item>If P is an atomic literal L, then Rep(P) = Rep(L).</item> - <item>If P is a compound pattern <c><![CDATA[P_1 = P_2]]></c>, then - Rep(P) = <c><![CDATA[{match,LINE,Rep(P_1),Rep(P_2)}]]></c>.</item> - <item>If P is a variable pattern <c><![CDATA[V]]></c>, then - Rep(P) = <c><![CDATA[{var,LINE,A}]]></c>, - where A is an atom with a printname consisting of the same characters as - <c><![CDATA[V]]></c>.</item> - <item>If P is a universal pattern <c><![CDATA[_]]></c>, then - Rep(P) = <c><![CDATA[{var,LINE,'_'}]]></c>.</item> - <item>If P is a tuple pattern <c><![CDATA[{P_1, ..., P_k}]]></c>, then - Rep(P) = <c><![CDATA[{tuple,LINE,[Rep(P_1), ..., Rep(P_k)]}]]></c>.</item> - <item>If P is a nil pattern <c><![CDATA[[]]]></c>, then - Rep(P) = <c><![CDATA[{nil,LINE}]]></c>.</item> - <item>If P is a cons pattern <c><![CDATA[[P_h | P_t]]]></c>, then - Rep(P) = <c><![CDATA[{cons,LINE,Rep(P_h),Rep(P_t)}]]></c>.</item> - <item>If E is a binary pattern <c><![CDATA[<<P_1:Size_1/TSL_1, ..., P_k:Size_k/TSL_k>>]]></c>, then - Rep(E) = <c><![CDATA[{bin,LINE,[{bin_element,LINE,Rep(P_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(P_k),Rep(Size_k),Rep(TSL_k)}]}]]></c>. + <item>If P is an atomic literal <c>L</c>, then Rep(P) = Rep(L).</item> + <item>If P is a bit string pattern + <c><<P_1:Size_1/TSL_1, ..., P_k:Size_k/TSL_k>></c>, where each + <c>Size_i</c> is an expression that can be evaluated to an integer + and each <c>TSL_i</c> is a type specificer list, then + Rep(P) = <c>{bin,LINE,[{bin_element,LINE,Rep(P_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(P_k),Rep(Size_k),Rep(TSL_k)}]}</c>. For Rep(TSL), see below. - An omitted <c><![CDATA[Size]]></c> is represented by <c><![CDATA[default]]></c>. An omitted <c><![CDATA[TSL]]></c> - (type specifier list) is represented by <c><![CDATA[default]]></c>.</item> - <item>If P is <c><![CDATA[P_1 Op P_2]]></c>, where <c><![CDATA[Op]]></c> is a binary operator (this - is either an occurrence of <c><![CDATA[++]]></c> applied to a literal string or character + An omitted <c>Size_i</c> is represented by <c>default</c>. + An omitted <c>TSL_i</c> is represented by <c>default</c>.</item> + <item>If P is a compound pattern <c>P_1 = P_2</c>, then + Rep(P) = <c>{match,LINE,Rep(P_1),Rep(P_2)}</c>.</item> + <item>If P is a cons pattern <c>[P_h | P_t]</c>, then + Rep(P) = <c>{cons,LINE,Rep(P_h),Rep(P_t)}</c>.</item> + <item>If P is a map pattern <c>#{A_1, ..., A_k}</c>, where each + <c>A_i</c> is an association <c>P_i_1 := P_i_2</c>, then Rep(P) = + <c>{map,LINE,[Rep(A_1), ..., Rep(A_k)]}</c>. For Rep(A), see + below.</item> + <item>If P is a nil pattern <c>[]</c>, then + Rep(P) = <c>{nil,LINE}</c>.</item> + <item>If P is an operator pattern <c>P_1 Op P_2</c>, + where <c>Op</c> is a binary operator (this is either an occurrence + of <c>++</c> applied to a literal string or character list, or an occurrence of an expression that can be evaluated to a number at compile time), - then Rep(P) = <c><![CDATA[{op,LINE,Op,Rep(P_1),Rep(P_2)}]]></c>.</item> - <item>If P is <c><![CDATA[Op P_0]]></c>, where <c><![CDATA[Op]]></c> is a unary operator (this is an - occurrence of an expression that can be evaluated to a number at compile - time), then Rep(P) = <c><![CDATA[{op,LINE,Op,Rep(P_0)}]]></c>.</item> - <item>If P is a record pattern <c><![CDATA[#Name{Field_1=P_1, ..., Field_k=P_k}]]></c>, - then Rep(P) = - <c><![CDATA[{record,LINE,Name, [{record_field,LINE,Rep(Field_1),Rep(P_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(P_k)}]}]]></c>.</item> - <item>If P is <c><![CDATA[#Name.Field]]></c>, then - Rep(P) = <c><![CDATA[{record_index,LINE,Name,Rep(Field)}]]></c>.</item> - <item>If P is <c><![CDATA[( P_0 )]]></c>, then - Rep(P) = <c><![CDATA[Rep(P_0)]]></c>, - i.e., patterns cannot be distinguished from their bodies.</item> + then Rep(P) = <c>{op,LINE,Op,Rep(P_1),Rep(P_2)}</c>.</item> + <item>If P is an operator pattern <c>Op P_0</c>, + where <c>Op</c> is a unary operator (this is an occurrence of + an expression that can be evaluated to a number at compile + time), then Rep(P) = <c>{op,LINE,Op,Rep(P_0)}</c>.</item> + <item>If P is a parenthesized pattern <c>( P_0 )</c>, then + Rep(P) = <c>Rep(P_0)</c>, + that is, parenthesized patterns cannot be distinguished from their + bodies.</item> + <item>If P is a record field index pattern <c>#Name.Field</c>, + where <c>Field</c> is an atom, then + Rep(P) = <c>{record_index,LINE,Name,Rep(Field)}</c>.</item> + <item>If P is a record pattern + <c>#Name{Field_1=P_1, ..., Field_k=P_k}</c>, + where each <c>Field_i</c> is an atom or <c>_</c>, then Rep(P) = + <c>{record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(P_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(P_k)}]}</c>.</item> + <item>If P is a tuple pattern <c>{P_1, ..., P_k}</c>, then + Rep(P) = <c>{tuple,LINE,[Rep(P_1), ..., Rep(P_k)]}</c>.</item> + <item>If P is a universal pattern <c>_</c>, then + Rep(P) = <c>{var,LINE,'_'}</c>.</item> + <item>If P is a variable pattern <c>V</c>, then + Rep(P) = <c>{var,LINE,A}</c>, + where A is an atom with a printname consisting of the same characters as + <c>V</c>.</item> </list> <p>Note that every pattern has the same source form as some expression, and is represented the same way as the corresponding expression.</p> @@ -180,258 +228,436 @@ <section> <title>Expressions</title> - <p>A body B is a sequence of expressions <c><![CDATA[E_1, ..., E_k]]></c>, and - Rep(B) = <c><![CDATA[[Rep(E_1), ..., Rep(E_k)]]]></c>.</p> + <p>A body B is a nonempty sequence of expressions <c>E_1, ..., E_k</c>, + and Rep(B) = <c>[Rep(E_1), ..., Rep(E_k)]</c>.</p> <p>An expression E is one of the following alternatives:</p> <list type="bulleted"> - <item>If P is an atomic literal <c><![CDATA[L]]></c>, then - Rep(P) = Rep(L).</item> - <item>If E is <c><![CDATA[P = E_0]]></c>, then - Rep(E) = <c><![CDATA[{match,LINE,Rep(P),Rep(E_0)}]]></c>.</item> - <item>If E is a variable <c><![CDATA[V]]></c>, then - Rep(E) = <c><![CDATA[{var,LINE,A}]]></c>, - where <c><![CDATA[A]]></c> is an atom with a printname consisting of the same - characters as <c><![CDATA[V]]></c>.</item> - <item>If E is a tuple skeleton <c><![CDATA[{E_1, ..., E_k}]]></c>, then - Rep(E) = <c><![CDATA[{tuple,LINE,[Rep(E_1), ..., Rep(E_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[[]]]></c>, then - Rep(E) = <c><![CDATA[{nil,LINE}]]></c>.</item> - <item>If E is a cons skeleton <c><![CDATA[[E_h | E_t]]]></c>, then - Rep(E) = <c><![CDATA[{cons,LINE,Rep(E_h),Rep(E_t)}]]></c>.</item> - <item>If E is a binary constructor <c><![CDATA[<<V_1:Size_1/TSL_1, ..., V_k:Size_k/TSL_k>>]]></c>, then - Rep(E) = <c><![CDATA[{bin,LINE,[{bin_element,LINE,Rep(V_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(V_k),Rep(Size_k),Rep(TSL_k)}]}]]></c>. + <item>If E is an atomic literal <c>L</c>, then Rep(E) = Rep(L).</item> + <item>If E is a bit string comprehension + <c><<E_0 || Q_1, ..., Q_k>></c>, + where each <c>Q_i</c> is a qualifier, then + Rep(E) = <c>{bc,LINE,Rep(E_0),[Rep(Q_1), ..., Rep(Q_k)]}</c>. + For Rep(Q), see below.</item> + <item>If E is a bit string constructor + <c><<E_1:Size_1/TSL_1, ..., E_k:Size_k/TSL_k>></c>, + where each <c>Size_i</c> is an expression and each + <c>TSL_i</c> is a type specificer list, then Rep(E) = + <c>{bin,LINE,[{bin_element,LINE,Rep(E_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(E_k),Rep(Size_k),Rep(TSL_k)}]}</c>. For Rep(TSL), see below. - An omitted <c><![CDATA[Size]]></c> is represented by <c><![CDATA[default]]></c>. An omitted <c><![CDATA[TSL]]></c> - (type specifier list) is represented by <c><![CDATA[default]]></c>.</item> - <item>If E is <c><![CDATA[E_1 Op E_2]]></c>, where <c><![CDATA[Op]]></c> is a binary operator, - then Rep(E) = <c><![CDATA[{op,LINE,Op,Rep(E_1),Rep(E_2)}]]></c>.</item> - <item>If E is <c><![CDATA[Op E_0]]></c>, where <c><![CDATA[Op]]></c> is a unary operator, then - Rep(E) = <c><![CDATA[{op,LINE,Op,Rep(E_0)}]]></c>.</item> - <item>If E is <c><![CDATA[#Name{Field_1=E_1, ..., Field_k=E_k}]]></c>, then - Rep(E) = - <c><![CDATA[{record,LINE,Name, [{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}]]></c>.</item> - <item>If E is <c><![CDATA[E_0#Name{Field_1=E_1, ..., Field_k=E_k}]]></c>, then - Rep(E) = - <c><![CDATA[{record,LINE,Rep(E_0),Name, [{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}]]></c>.</item> - <item>If E is <c><![CDATA[#Name.Field]]></c>, then - Rep(E) = <c><![CDATA[{record_index,LINE,Name,Rep(Field)}]]></c>.</item> - <item>If E is <c><![CDATA[E_0#Name.Field]]></c>, then - Rep(E) = <c><![CDATA[{record_field,LINE,Rep(E_0),Name,Rep(Field)}]]></c>.</item> - <item>If E is <c><![CDATA[catch E_0]]></c>, then - Rep(E) = <c><![CDATA[{'catch',LINE,Rep(E_0)}]]></c>.</item> - <item>If E is <c><![CDATA[E_0(E_1, ..., E_k)]]></c>, then - Rep(E) = <c><![CDATA[{call,LINE,Rep(E_0),[Rep(E_1), ..., Rep(E_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[E_m:E_0(E_1, ..., E_k)]]></c>, then - Rep(E) = - <c><![CDATA[{call,LINE,{remote,LINE,Rep(E_m),Rep(E_0)},[Rep(E_1), ..., Rep(E_k)]}]]></c>.</item> - <item>If E is a list comprehension <c><![CDATA[[E_0 || W_1, ..., W_k]]]></c>, - where each <c><![CDATA[W_i]]></c> is a generator or a filter, then - Rep(E) = <c><![CDATA[{lc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}]]></c>. For Rep(W), see + An omitted <c>Size_i</c> is represented by <c>default</c>. + An omitted <c>TSL_i</c> is represented by <c>default</c>.</item> + <item>If E is a block expression <c>begin B end</c>, + where <c>B</c> is a body, then + Rep(E) = <c>{block,LINE,Rep(B)}</c>.</item> + <item>If E is a case expression <c>case E_0 of Cc_1 ; ... ; Cc_k end</c>, + where <c>E_0</c> is an expression and each <c>Cc_i</c> is a + case clause then Rep(E) = + <c>{'case',LINE,Rep(E_0),[Rep(Cc_1), ..., Rep(Cc_k)]}</c>.</item> + <item>If E is a catch expression <c>catch E_0</c>, then + Rep(E) = <c>{'catch',LINE,Rep(E_0)}</c>.</item> + <item>If E is a cons skeleton <c>[E_h | E_t]</c>, then + Rep(E) = <c>{cons,LINE,Rep(E_h),Rep(E_t)}</c>.</item> + <item>If E is a fun expression <c>fun Name/Arity</c>, then + Rep(E) = <c>{'fun',LINE,{function,Name,Arity}}</c>.</item> + <item>If E is a fun expression + <c>fun Module:Name/Arity</c>, then Rep(E) = + <c>{'fun',LINE,{function,Rep(Module),Rep(Name),Rep(Arity)}}</c>. + (Before the R15 release: Rep(E) = + <c>{'fun',LINE,{function,Module,Name,Arity}}</c>.)</item> + <item>If E is a fun expression <c>fun Fc_1 ; ... ; Fc_k end</c>, + where each <c>Fc_i</c> is a function clause then Rep(E) = + <c>{'fun',LINE,{clauses,[Rep(Fc_1), ..., Rep(Fc_k)]}}</c>.</item> + <item>If E is a fun expression + <c>fun Name Fc_1 ; ... ; Name Fc_k end</c>, + where <c>Name</c> is a variable and each + <c>Fc_i</c> is a function clause then Rep(E) = + <c>{named_fun,LINE,Name,[Rep(Fc_1), ..., Rep(Fc_k)]}</c>. + </item> + <item>If E is a function call <c>E_0(E_1, ..., E_k)</c>, then + Rep(E) = <c>{call,LINE,Rep(E_0),[Rep(E_1), ..., Rep(E_k)]}</c>.</item> + <item>If E is a function call <c>E_m:E_0(E_1, ..., E_k)</c>, + then Rep(E) = + <c>{call,LINE,{remote,LINE,Rep(E_m),Rep(E_0)},[Rep(E_1), ..., Rep(E_k)]}</c>. + </item> + <item>If E is an if expression <c>if Ic_1 ; ... ; Ic_k end</c>, + where each <c>Ic_i</c> is an if clause then Rep(E) = + <c>{'if',LINE,[Rep(Ic_1), ..., Rep(Ic_k)]}</c>.</item> + <item>If E is a list comprehension <c>[E_0 || Q_1, ..., Q_k]</c>, + where each <c>Q_i</c> is a qualifier, then Rep(E) = + <c>{lc,LINE,Rep(E_0),[Rep(Q_1), ..., Rep(Q_k)]}</c>. For Rep(Q), see below.</item> - <item>If E is a binary comprehension <c><![CDATA[<<E_0 || W_1, ..., W_k>>]]></c>, - where each <c><![CDATA[W_i]]></c> is a generator or a filter, then - Rep(E) = <c><![CDATA[{bc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}]]></c>. For Rep(W), see + <item>If E is a map creation <c>#{A_1, ..., A_k}</c>, + where each <c>A_i</c> is an association <c>E_i_1 => E_i_2</c> + or <c>E_i_1 := E_i_2</c>, then Rep(E) = + <c>{map,LINE,[Rep(A_1), ..., Rep(A_k)]}</c>. For Rep(A), see below.</item> - <item>If E is <c><![CDATA[begin B end]]></c>, where <c><![CDATA[B]]></c> is a body, then - Rep(E) = <c><![CDATA[{block,LINE,Rep(B)}]]></c>.</item> - <item>If E is <c><![CDATA[if Ic_1 ; ... ; Ic_k end]]></c>, - where each <c><![CDATA[Ic_i]]></c> is an if clause then - Rep(E) = - <c><![CDATA[{'if',LINE,[Rep(Ic_1), ..., Rep(Ic_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[case E_0 of Cc_1 ; ... ; Cc_k end]]></c>, - where <c><![CDATA[E_0]]></c> is an expression and each <c><![CDATA[Cc_i]]></c> is a - case clause then - Rep(E) = - <c><![CDATA[{'case',LINE,Rep(E_0),[Rep(Cc_1), ..., Rep(Cc_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[try B catch Tc_1 ; ... ; Tc_k end]]></c>, - where <c><![CDATA[B]]></c> is a body and each <c><![CDATA[Tc_i]]></c> is a catch clause then + <item>If E is a map update <c>E_0#{A_1, ..., A_k}</c>, + where each <c>A_i</c> is an association <c>E_i_1 => E_i_2</c> + or <c>E_i_1 := E_i_2</c>, then Rep(E) = + <c>{map,LINE,Rep(E_0),[Rep(A_1), ..., Rep(A_k)]}</c>. + For Rep(A), see below.</item> + <item>If E is a match operator expression <c>P = E_0</c>, + where <c>P</c> is a pattern, then + Rep(E) = <c>{match,LINE,Rep(P),Rep(E_0)}</c>.</item> + <item>If E is nil, <c>[]</c>, then + Rep(E) = <c>{nil,LINE}</c>.</item> + <item>If E is an operator expression <c>E_1 Op E_2</c>, + where <c>Op</c> is a binary operator other than the match + operator <c>=</c>, then + Rep(E) = <c>{op,LINE,Op,Rep(E_1),Rep(E_2)}</c>.</item> + <item>If E is an operator expression <c>Op E_0</c>, + where <c>Op</c> is a unary operator, then + Rep(E) = <c>{op,LINE,Op,Rep(E_0)}</c>.</item> + <item>If E is a parenthesized expression <c>( E_0 )</c>, then + Rep(E) = <c>Rep(E_0)</c>, that is, parenthesized + expressions cannot be distinguished from their bodies.</item> + <item>If E is a receive expression <c>receive Cc_1 ; ... ; Cc_k end</c>, + where each <c>Cc_i</c> is a case clause then Rep(E) = + <c>{'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)]}</c>.</item> + <item>If E is a receive expression + <c>receive Cc_1 ; ... ; Cc_k after E_0 -> B_t end</c>, + where each <c>Cc_i</c> is a case clause, + <c>E_0</c> is an expression and <c>B_t</c> is a body, then Rep(E) = + <c>{'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)],Rep(E_0),Rep(B_t)}</c>.</item> + <item>If E is a record creation + <c>#Name{Field_1=E_1, ..., Field_k=E_k}</c>, + where each <c>Field_i</c> is an atom or <c>_</c>, then Rep(E) = + <c>{record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}</c>.</item> + <item>If E is a record field access <c>E_0#Name.Field</c>, + where <c>Field</c> is an atom, then + Rep(E) = <c>{record_field,LINE,Rep(E_0),Name,Rep(Field)}</c>.</item> + <item>If E is a record field index <c>#Name.Field</c>, + where <c>Field</c> is an atom, then + Rep(E) = <c>{record_index,LINE,Name,Rep(Field)}</c>.</item> + <item>If E is a record update + <c>E_0#Name{Field_1=E_1, ..., Field_k=E_k}</c>, + where each <c>Field_i</c> is an atom, then Rep(E) = + <c>{record,LINE,Rep(E_0),Name,[{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}</c>.</item> + <item>If E is a tuple skeleton <c>{E_1, ..., E_k}</c>, then + Rep(E) = <c>{tuple,LINE,[Rep(E_1), ..., Rep(E_k)]}</c>.</item> + <item>If E is a try expression <c>try B catch Tc_1 ; ... ; Tc_k end</c>, + where <c>B</c> is a body and each <c>Tc_i</c> is a catch clause then Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],[]}]]></c>.</item> - <item>If E is <c><![CDATA[try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n end]]></c>, - where <c><![CDATA[B]]></c> is a body, - each <c><![CDATA[Cc_i]]></c> is a case clause and - each <c><![CDATA[Tc_j]]></c> is a catch clause then + <c>{'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],[]}</c>.</item> + <item>If E is a try expression + <c>try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n end</c>, + where <c>B</c> is a body, + each <c>Cc_i</c> is a case clause and + each <c>Tc_j</c> is a catch clause then Rep(E) = + <c>{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],[]}</c>.</item> + <item>If E is a try expression <c>try B after A end</c>, + where <c>B</c> and <c>A</c> are bodies then Rep(E) = + <c>{'try',LINE,Rep(B),[],[],Rep(A)}</c>.</item> + <item>If E is a try expression + <c>try B of Cc_1 ; ... ; Cc_k after A end</c>, + where <c>B</c> and <c>A</c> are a bodies and + each <c>Cc_i</c> is a case clause then Rep(E) = + <c>{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[],Rep(A)}</c>.</item> + <item>If E is a try expression + <c>try B catch Tc_1 ; ... ; Tc_k after A end</c>, + where <c>B</c> and <c>A</c> are bodies and + each <c>Tc_i</c> is a catch clause then Rep(E) = + <c>{'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],Rep(A)}</c>.</item> + <item>If E is a try expression + <c>try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n after A end</c>, + where <c>B</c> and <c>A</c> are a bodies, + each <c>Cc_i</c> is a case clause, and + each <c>Tc_j</c> is a catch clause then Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],[]}]]></c>.</item> - <item>If E is <c><![CDATA[try B after A end]]></c>, - where <c><![CDATA[B]]></c> and <c><![CDATA[A]]></c> are bodies then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[],[],Rep(A)}]]></c>.</item> - <item>If E is <c><![CDATA[try B of Cc_1 ; ... ; Cc_k after A end]]></c>, - where <c><![CDATA[B]]></c> and <c><![CDATA[A]]></c> are a bodies and - each <c><![CDATA[Cc_i]]></c> is a case clause then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[],Rep(A)}]]></c>.</item> - <item>If E is <c><![CDATA[try B catch Tc_1 ; ... ; Tc_k after A end]]></c>, - where <c><![CDATA[B]]></c> and <c><![CDATA[A]]></c> are bodies and - each <c><![CDATA[Tc_i]]></c> is a catch clause then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],Rep(A)}]]></c>.</item> - <item>If E is <c><![CDATA[try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n after A end]]></c>, - where <c><![CDATA[B]]></c> and <c><![CDATA[A]]></c> are a bodies, - each <c><![CDATA[Cc_i]]></c> is a case clause and - each <c><![CDATA[Tc_j]]></c> is a catch clause then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],Rep(A)}]]></c>.</item> - <item>If E is <c><![CDATA[receive Cc_1 ; ... ; Cc_k end]]></c>, - where each <c><![CDATA[Cc_i]]></c> is a case clause then - Rep(E) = - <c><![CDATA[{'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[receive Cc_1 ; ... ; Cc_k after E_0 -> B_t end]]></c>, - where each <c><![CDATA[Cc_i]]></c> is a case clause, - <c><![CDATA[E_0]]></c> is an expression and <c><![CDATA[B_t]]></c> is a body, then - Rep(E) = - <c><![CDATA[{'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)],Rep(E_0),Rep(B_t)}]]></c>.</item> - <item>If E is <c><![CDATA[fun Name / Arity]]></c>, then - Rep(E) = <c><![CDATA[{'fun',LINE,{function,Name,Arity}}]]></c>.</item> - <item>If E is <c><![CDATA[fun Module:Name/Arity]]></c>, then - Rep(E) = <c><![CDATA[{'fun',LINE,{function,Rep(Module),Rep(Name),Rep(Arity)}}]]></c>. - (Before the R15 release: Rep(E) = <c><![CDATA[{'fun',LINE,{function,Module,Name,Arity}}]]></c>.)</item> - <item>If E is <c><![CDATA[fun Fc_1 ; ... ; Fc_k end]]></c> - where each <c><![CDATA[Fc_i]]></c> is a function clause then Rep(E) = - <c><![CDATA[{'fun',LINE,{clauses,[Rep(Fc_1), ..., Rep(Fc_k)]}}]]></c>.</item> - <item>If E is <c><![CDATA[( E_0 )]]></c>, then - Rep(E) = <c><![CDATA[Rep(E_0)]]></c>, - i.e., parenthesized expressions cannot be distinguished from their bodies.</item> + <c>{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],Rep(A)}</c>.</item> + <item>If E is a variable <c>V</c>, then Rep(E) = <c>{var,LINE,A}</c>, + where <c>A</c> is an atom with a printname consisting of the same + characters as <c>V</c>.</item> </list> <section> - <title>Generators and filters</title> - <p>When W is a generator or a filter (in the body of a list or binary comprehension), then:</p> + <title>Qualifiers</title> + <p>A qualifier Q is one of the following alternatives:</p> <list type="bulleted"> - <item>If W is a generator <c><![CDATA[P <- E]]></c>, where <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[E]]></c> - is an expression, then - Rep(W) = <c><![CDATA[{generate,LINE,Rep(P),Rep(E)}]]></c>.</item> - <item>If W is a generator <c><![CDATA[P <= E]]></c>, where <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[E]]></c> - is an expression, then - Rep(W) = <c><![CDATA[{b_generate,LINE,Rep(P),Rep(E)}]]></c>.</item> - <item>If W is a filter <c><![CDATA[E]]></c>, which is an expression, then - Rep(W) = <c><![CDATA[Rep(E)]]></c>.</item> + <item>If Q is a filter <c>E</c>, where <c>E</c> is an expression, then + Rep(Q) = <c>Rep(E)</c>.</item> + <item>If Q is a generator <c>P <- E</c>, where <c>P</c> is + a pattern and <c>E</c> is an expression, then + Rep(Q) = <c>{generate,LINE,Rep(P),Rep(E)}</c>.</item> + <item>If Q is a bit string generator + <c>P <= E</c>, where <c>P</c> is + a pattern and <c>E</c> is an expression, then + Rep(Q) = <c>{b_generate,LINE,Rep(P),Rep(E)}</c>.</item> </list> </section> <section> - <title>Binary element type specifiers</title> - <p>A type specifier list TSL for a binary element is a sequence of type - specifiers <c><![CDATA[TS_1 - ... - TS_k]]></c>. - Rep(TSL) = <c><![CDATA[[Rep(TS_1), ..., Rep(TS_k)]]]></c>.</p> - <p>When TS is a type specifier for a binary element, then:</p> + <title>Bit String Element Type Specifiers</title> + <p>A type specifier list TSL for a bit string element is a sequence + of type specifiers <c>TS_1 - ... - TS_k</c>, and + Rep(TSL) = <c>[Rep(TS_1), ..., Rep(TS_k)]</c>.</p> <list type="bulleted"> - <item>If TS is an atom <c><![CDATA[A]]></c>, Rep(TS) = <c><![CDATA[A]]></c>.</item> - <item>If TS is a couple <c><![CDATA[A:Value]]></c> where <c><![CDATA[A]]></c> is an atom and <c><![CDATA[Value]]></c> - is an integer, Rep(TS) = <c><![CDATA[{A, Value}]]></c>.</item> + <item>If TS is a type specifier <c>A</c>, where <c>A</c> is an atom, + then Rep(TS) = <c>A</c>.</item> + <item>If TS is a type specifier <c>A:Value</c>, + where <c>A</c> is an atom and <c>Value</c> is an integer, + then Rep(TS) = <c>{A,Value}</c>.</item> + </list> + </section> + + <section> + <title>Associations</title> + <p>An association A is one of the following alternatives:</p> + <list type="bulleted"> + <item>If A is an association <c>K => V</c>, + then Rep(A) = <c>{map_field_assoc,LINE,Rep(K),Rep(V)}</c>. + </item> + <item>If A is an association <c>K := V</c>, + then Rep(A) = <c>{map_field_exact,LINE,Rep(K),Rep(V)}</c>. + </item> </list> </section> </section> <section> <title>Clauses</title> - <p>There are function clauses, if clauses, case clauses + <p>There are function clauses, if clauses, case clauses and catch clauses.</p> - <p>A clause <c><![CDATA[C]]></c> is one of the following alternatives:</p> + <p>A clause <c>C</c> is one of the following alternatives:</p> <list type="bulleted"> - <item>If C is a function clause <c><![CDATA[( Ps ) -> B]]></c> - where <c><![CDATA[Ps]]></c> is a pattern sequence and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,Rep(Ps),[],Rep(B)}]]></c>.</item> - <item>If C is a function clause <c><![CDATA[( Ps ) when Gs -> B]]></c> - where <c><![CDATA[Ps]]></c> is a pattern sequence, - <c><![CDATA[Gs]]></c> is a guard sequence and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,Rep(Ps),Rep(Gs),Rep(B)}]]></c>.</item> - <item>If C is an if clause <c><![CDATA[Gs -> B]]></c> - where <c><![CDATA[Gs]]></c> is a guard sequence and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[],Rep(Gs),Rep(B)}]]></c>.</item> - <item>If C is a case clause <c><![CDATA[P -> B]]></c> - where <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep(P)],[],Rep(B)}]]></c>.</item> - <item>If C is a case clause <c><![CDATA[P when Gs -> B]]></c> - where <c><![CDATA[P]]></c> is a pattern, - <c><![CDATA[Gs]]></c> is a guard sequence and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep(P)],Rep(Gs),Rep(B)}]]></c>.</item> - <item>If C is a catch clause <c><![CDATA[P -> B]]></c> - where <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep({throw,P,_})],[],Rep(B)}]]></c>.</item> - <item>If C is a catch clause <c><![CDATA[X : P -> B]]></c> - where <c><![CDATA[X]]></c> is an atomic literal or a variable pattern, - <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep({X,P,_})],[],Rep(B)}]]></c>.</item> - <item>If C is a catch clause <c><![CDATA[P when Gs -> B]]></c> - where <c><![CDATA[P]]></c> is a pattern, <c><![CDATA[Gs]]></c> is a guard sequence - and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep({throw,P,_})],Rep(Gs),Rep(B)}]]></c>.</item> - <item>If C is a catch clause <c><![CDATA[X : P when Gs -> B]]></c> - where <c><![CDATA[X]]></c> is an atomic literal or a variable pattern, - <c><![CDATA[P]]></c> is a pattern, <c><![CDATA[Gs]]></c> is a guard sequence - and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep({X,P,_})],Rep(Gs),Rep(B)}]]></c>.</item> + <item>If C is a case clause <c>P -> B</c>, + where <c>P</c> is a pattern and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep(P)],[],Rep(B)}</c>.</item> + <item>If C is a case clause <c>P when Gs -> B</c>, + where <c>P</c> is a pattern, + <c>Gs</c> is a guard sequence and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep(P)],Rep(Gs),Rep(B)}</c>.</item> + <item>If C is a catch clause <c>P -> B</c>, + where <c>P</c> is a pattern and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep({throw,P,_})],[],Rep(B)}</c>.</item> + <item>If C is a catch clause <c>X : P -> B</c>, + where <c>X</c> is an atomic literal or a variable pattern, + <c>P</c> is a pattern, and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep({X,P,_})],[],Rep(B)}</c>.</item> + <item>If C is a catch clause <c>P when Gs -> B</c>, + where <c>P</c> is a pattern, <c>Gs</c> is a guard sequence, + and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep({throw,P,_})],Rep(Gs),Rep(B)}</c>.</item> + <item>If C is a catch clause <c>X : P when Gs -> B</c>, + where <c>X</c> is an atomic literal or a variable pattern, + <c>P</c> is a pattern, <c>Gs</c> is a guard sequence, + and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep({X,P,_})],Rep(Gs),Rep(B)}</c>.</item> + <item>If C is a function clause <c>( Ps ) -> B</c>, + where <c>Ps</c> is a pattern sequence and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,Rep(Ps),[],Rep(B)}</c>.</item> + <item>If C is a function clause <c>( Ps ) when Gs -> B</c>, + where <c>Ps</c> is a pattern sequence, + <c>Gs</c> is a guard sequence and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,Rep(Ps),Rep(Gs),Rep(B)}</c>.</item> + <item>If C is an if clause <c>Gs -> B</c>, + where <c>Gs</c> is a guard sequence and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[],Rep(Gs),Rep(B)}</c>.</item> </list> </section> <section> <title>Guards</title> - <p>A guard sequence Gs is a sequence of guards <c><![CDATA[G_1; ...; G_k]]></c>, and - Rep(Gs) = <c><![CDATA[[Rep(G_1), ..., Rep(G_k)]]]></c>. If the guard sequence is - empty, Rep(Gs) = <c><![CDATA[[]]]></c>.</p> - <p>A guard G is a nonempty sequence of guard tests <c><![CDATA[Gt_1, ..., Gt_k]]></c>, and - Rep(G) = <c><![CDATA[[Rep(Gt_1), ..., Rep(Gt_k)]]]></c>.</p> - <p>A guard test <c><![CDATA[Gt]]></c> is one of the following alternatives:</p> + <p>A guard sequence Gs is a sequence of guards <c>G_1; ...; G_k</c>, and + Rep(Gs) = <c>[Rep(G_1), ..., Rep(G_k)]</c>. If the guard sequence is + empty, Rep(Gs) = <c>[]</c>.</p> + <p>A guard G is a nonempty sequence of guard tests + <c>Gt_1, ..., Gt_k</c>, and Rep(G) = + <c>[Rep(Gt_1), ..., Rep(Gt_k)]</c>.</p> + <p>A guard test <c>Gt</c> is one of the following alternatives:</p> <list type="bulleted"> - <item>If Gt is an atomic literal L, then Rep(Gt) = Rep(L).</item> - <item>If Gt is a variable pattern <c><![CDATA[V]]></c>, then - Rep(Gt) = <c><![CDATA[{var,LINE,A}]]></c>, - where A is an atom with a printname consisting of the same characters as - <c><![CDATA[V]]></c>.</item> - <item>If Gt is a tuple skeleton <c><![CDATA[{Gt_1, ..., Gt_k}]]></c>, then - Rep(Gt) = <c><![CDATA[{tuple,LINE,[Rep(Gt_1), ..., Rep(Gt_k)]}]]></c>.</item> - <item>If Gt is <c><![CDATA[[]]]></c>, then - Rep(Gt) = <c><![CDATA[{nil,LINE}]]></c>.</item> - <item>If Gt is a cons skeleton <c><![CDATA[[Gt_h | Gt_t]]]></c>, then - Rep(Gt) = <c><![CDATA[{cons,LINE,Rep(Gt_h),Rep(Gt_t)}]]></c>.</item> - <item>If Gt is a binary constructor <c><![CDATA[<<Gt_1:Size_1/TSL_1, ..., Gt_k:Size_k/TSL_k>>]]></c>, then - Rep(Gt) = <c><![CDATA[{bin,LINE,[{bin_element,LINE,Rep(Gt_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(Gt_k),Rep(Size_k),Rep(TSL_k)}]}]]></c>. + <item>If Gt is an atomic literal <c>L</c>, then Rep(Gt) = Rep(L).</item> + <item>If Gt is a bit string constructor + <c><<Gt_1:Size_1/TSL_1, ..., Gt_k:Size_k/TSL_k>></c>, + where each <c>Size_i</c> is a guard test and each + <c>TSL_i</c> is a type specificer list, then + Rep(Gt) = <c>{bin,LINE,[{bin_element,LINE,Rep(Gt_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(Gt_k),Rep(Size_k),Rep(TSL_k)}]}</c>. For Rep(TSL), see above. - An omitted <c><![CDATA[Size]]></c> is represented by <c><![CDATA[default]]></c>. An omitted <c><![CDATA[TSL]]></c> - (type specifier list) is represented by <c><![CDATA[default]]></c>.</item> - <item>If Gt is <c><![CDATA[Gt_1 Op Gt_2]]></c>, where <c><![CDATA[Op]]></c> - is a binary operator, then Rep(Gt) = <c><![CDATA[{op,LINE,Op,Rep(Gt_1),Rep(Gt_2)}]]></c>.</item> - <item>If Gt is <c><![CDATA[Op Gt_0]]></c>, where <c><![CDATA[Op]]></c> is a unary operator, then - Rep(Gt) = <c><![CDATA[{op,LINE,Op,Rep(Gt_0)}]]></c>.</item> - <item>If Gt is <c><![CDATA[#Name{Field_1=Gt_1, ..., Field_k=Gt_k}]]></c>, then - Rep(E) = - <c><![CDATA[{record,LINE,Name, [{record_field,LINE,Rep(Field_1),Rep(Gt_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(Gt_k)}]}]]></c>.</item> - <item>If Gt is <c><![CDATA[#Name.Field]]></c>, then - Rep(Gt) = <c><![CDATA[{record_index,LINE,Name,Rep(Field)}]]></c>.</item> - <item>If Gt is <c><![CDATA[Gt_0#Name.Field]]></c>, then - Rep(Gt) = <c><![CDATA[{record_field,LINE,Rep(Gt_0),Name,Rep(Field)}]]></c>.</item> - <item>If Gt is <c><![CDATA[A(Gt_1, ..., Gt_k)]]></c>, where <c><![CDATA[A]]></c> is an atom, then - Rep(Gt) = <c><![CDATA[{call,LINE,Rep(A),[Rep(Gt_1), ..., Rep(Gt_k)]}]]></c>.</item> - <item>If Gt is <c><![CDATA[A_m:A(Gt_1, ..., Gt_k)]]></c>, where <c><![CDATA[A_m]]></c> is - the atom <c><![CDATA[erlang]]></c> and <c><![CDATA[A]]></c> is an atom or an operator, then - Rep(Gt) = <c><![CDATA[{call,LINE,{remote,LINE,Rep(A_m),Rep(A)},[Rep(Gt_1), ..., Rep(Gt_k)]}]]></c>.</item> - <item>If Gt is <c><![CDATA[{A_m,A}(Gt_1, ..., Gt_k)]]></c>, where <c><![CDATA[A_m]]></c> is - the atom <c><![CDATA[erlang]]></c> and <c><![CDATA[A]]></c> is an atom or an operator, then - Rep(Gt) = <c><![CDATA[{call,LINE,Rep({A_m,A}),[Rep(Gt_1), ..., Rep(Gt_k)]}]]></c>.</item> - <item>If Gt is <c><![CDATA[( Gt_0 )]]></c>, then - Rep(Gt) = <c><![CDATA[Rep(Gt_0)]]></c>, - i.e., parenthesized guard tests cannot be distinguished from their bodies.</item> + An omitted <c>Size_i</c> is represented by <c>default</c>. + An omitted <c>TSL_i</c> is represented by <c>default</c>.</item> + <item>If Gt is a cons skeleton <c>[Gt_h | Gt_t]</c>, then + Rep(Gt) = <c>{cons,LINE,Rep(Gt_h),Rep(Gt_t)}</c>.</item> + <item>If Gt is a function call <c>A(Gt_1, ..., Gt_k)</c>, + where <c>A</c> is an atom, then Rep(Gt) = + <c>{call,LINE,Rep(A),[Rep(Gt_1), ..., Rep(Gt_k)]}</c>.</item> + <item>If Gt is a function call <c>A_m:A(Gt_1, ..., Gt_k)</c>, + where <c>A_m</c> is the atom <c>erlang</c> and <c>A</c> is + an atom or an operator, then Rep(Gt) = + <c>{call,LINE,{remote,LINE,Rep(A_m),Rep(A)},[Rep(Gt_1), ..., Rep(Gt_k)]}</c>.</item> + <item>If Gt is a map creation <c>#{A_1, ..., A_k}</c>, + where each <c>A_i</c> is an association <c>Gt_i_1 => Gt_i_2</c> + or <c>Gt_i_1 := Gt_i_2</c>, then Rep(Gt) = + <c>{map,LINE,[Rep(A_1), ..., Rep(A_k)]}</c>. For Rep(A), see + above.</item> + <item>If Gt is a map update <c>Gt_0#{A_1, ..., A_k}</c>, where each + <c>A_i</c> is an association <c>Gt_i_1 => Gt_i_2</c> + or <c>Gt_i_1 := Gt_i_2</c>, then Rep(Gt) = + <c>{map,LINE,Rep(Gt_0),[Rep(A_1), ..., Rep(A_k)]}</c>. + For Rep(A), see above.</item> + <item>If Gt is nil, <c>[]</c>, + then Rep(Gt) = <c>{nil,LINE}</c>.</item> + <item>If Gt is an operator guard test <c>Gt_1 Op Gt_2</c>, + where <c>Op</c> is a binary operator other than the match + operator <c>=</c>, then + Rep(Gt) = <c>{op,LINE,Op,Rep(Gt_1),Rep(Gt_2)}</c>.</item> + <item>If Gt is an operator guard test <c>Op Gt_0</c>, + where <c>Op</c> is a unary operator, then + Rep(Gt) = <c>{op,LINE,Op,Rep(Gt_0)}</c>.</item> + <item>If Gt is a parenthesized guard test <c>( Gt_0 )</c>, then + Rep(Gt) = <c>Rep(Gt_0)</c>, that is, parenthesized + guard tests cannot be distinguished from their bodies.</item> + <item>If Gt is a record creation + <c>#Name{Field_1=Gt_1, ..., Field_k=Gt_k}</c>, + where each <c>Field_i</c> is an atom or <c>_</c>, then Rep(Gt) = + <c>{record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(Gt_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(Gt_k)}]}</c>.</item> + <item>If Gt is a record field access <c>Gt_0#Name.Field</c>, + where <c>Field</c> is an atom, then + Rep(Gt) = <c>{record_field,LINE,Rep(Gt_0),Name,Rep(Field)}</c>.</item> + <item>If Gt is a record field index <c>#Name.Field</c>, + where <c>Field</c> is an atom, then + Rep(Gt) = <c>{record_index,LINE,Name,Rep(Field)}</c>.</item> + <item>If Gt is a tuple skeleton <c>{Gt_1, ..., Gt_k}</c>, then + Rep(Gt) = <c>{tuple,LINE,[Rep(Gt_1), ..., Rep(Gt_k)]}</c>.</item> + <item>If Gt is a variable pattern <c>V</c>, then + Rep(Gt) = <c>{var,LINE,A}</c>, where A is an atom with + a printname consisting of the same characters as <c>V</c>.</item> </list> <p>Note that every guard test has the same source form as some expression, and is represented the same way as the corresponding expression.</p> </section> <section> - <title>The abstract format after preprocessing</title> - <p>The compilation option <c><![CDATA[debug_info]]></c> can be given to the - compiler to have the abstract code stored in - the <c><![CDATA[abstract_code]]></c> chunk in the BEAM file + <title>Types</title> + <list type="bulleted"> + <item>If T is an annotated type <c>A :: T_0</c>, + where <c>A</c> is a variable, then Rep(T) = + <c>{ann_type,LINE,[Rep(A),Rep(T_0)]}</c>.</item> + <item>If T is an atom or integer literal L, then Rep(T) = Rep(L). + </item> + <item>If T is a bit string type <c><<_:M,_:_*N>></c>, + where <c>M</c> and <c>N</c> are singleton integer types, then Rep(T) = + <c>{type,LINE,binary,[Rep(M),Rep(N)]}</c>.</item> + <item>If T is the empty list type <c>[]</c>, then Rep(T) = + <c>{type,Line,nil,[]}</c>.</item> + <item>If T is a fun type <c>fun()</c>, then Rep(T) = + <c>{type,LINE,'fun',[]}</c>.</item> + <item>If T is a fun type <c>fun((...) -> T_0)</c>, then + Rep(T) = <c>{type,LINE,'fun',[{type,LINE,any},Rep(T_0)]}</c>. + </item> + <item>If T is a fun type <c>fun(Ft)</c>, where + <c>Ft</c> is a function type, + then Rep(T) = <c>Rep(Ft)</c>. For Rep(Ft), see below.</item> + <item>If T is an integer range type <c>L .. H</c>, + where <c>L</c> and <c>H</c> are singleton integer types, then + Rep(T) = <c>{type,LINE,range,[Rep(L),Rep(H)]}</c>.</item> + <item>If T is a map type <c>map()</c>, then Rep(T) = + <c>{type,LINE,map,any}</c>.</item> + <item>If T is a map type <c>#{A_1, ..., A_k}</c>, where each + <c>A_i</c> is an association type, then Rep(T) = + <c>{type,LINE,map,[Rep(A_1), ..., Rep(A_k)]}</c>. + For Rep(A), see below.</item> + <item>If T is an operator type <c>T_1 Op T_2</c>, + where <c>Op</c> is a binary operator (this is an occurrence of + an expression that can be evaluated to an integer at compile + time), then + Rep(T) = <c>{op,LINE,Op,Rep(T_1),Rep(T_2)}</c>.</item> + <item>If T is an operator type <c>Op T_0</c>, where <c>Op</c> is a + unary operator (this is an occurrence of + an expression that can be evaluated to an integer at compile time), + then Rep(T) = <c>{op,LINE,Op,Rep(T_0)}</c>.</item> + <item>If T is <c>( T_0 )</c>, then Rep(T) = <c>Rep(T_0)</c>, + that is, parenthesized types cannot be distinguished from their + bodies.</item> + <item>If T is a predefined (or built-in) type <c>N(T_1, ..., T_k)</c>, + then Rep(T) = + <c>{type,LINE,N,[Rep(T_1), ..., Rep(T_k)]}</c>.</item> + <item>If T is a record type <c>#Name{F_1, ..., F_k}</c>, + where each <c>F_i</c> is a record field type, then Rep(T) = + <c>{type,LINE,record,[Rep(Name),Rep(F_1), ..., Rep(F_k)]}</c>. + For Rep(F), see below.</item> + <item>If T is a remote type <c>M:N(T_1, ..., T_k)</c>, then Rep(T) = + <c>{remote_type,LINE,[Rep(M),Rep(N),[Rep(T_1), ..., Rep(T_k)]]}</c>. + </item> + <item>If T is a tuple type <c>tuple()</c>, then Rep(T) = + <c>{type,LINE,tuple,any}</c>.</item> + <item>If T is a tuple type <c>{T_1, ..., T_k}</c>, then Rep(T) = + <c>{type,LINE,tuple,[Rep(T_1), ..., Rep(T_k)]}</c>.</item> + <item>If T is a type union <c>T_1 | ... | T_k</c>, then Rep(T) = + <c>{type,LINE,union,[Rep(T_1), ..., Rep(T_k)]}</c>.</item> + <item>If T is a type variable <c>V</c>, then Rep(T) = + <c>{var,LINE,A}</c>, where <c>A</c> is an atom with a printname + consisting of the same characters as <c>V</c>. A type variable + is any variable except underscore (<c>_</c>).</item> + <item>If T is a user-defined type <c>N(T_1, ..., T_k)</c>, + then Rep(T) = + <c>{user_type,LINE,N,[Rep(T_1), ..., Rep(T_k)]}</c>.</item> + </list> + + <section> + <title>Function Types</title> + <p>A function type Ft is one of the following alternatives:</p> + <list type="bulleted"> + <item>If Ft is a constrained function type <c>Ft_1 when Fc</c>, + where <c>Ft_1</c> is a function type and + <c>Fc</c> is a function constraint, then Rep(T) = + <c>{type,LINE,bounded_fun,[Rep(Ft_1),Rep(Fc)]}</c>. + For Rep(Fc), see below.</item> + <item>If Ft is a function type <c>(T_1, ..., T_n) -> T_0</c>, + where each <c>T_i</c> is a type, then + Rep(Ft) = <c>{type,LINE,'fun',[{type,LINE,product,[Rep(T_1), + ..., Rep(T_n)]},Rep(T_0)]}</c>.</item> + </list> + </section> + + <section> + <title>Function Constraints</title> + <p>A function constraint Fc is a nonempty sequence of constraints + <c>C_1, ..., C_k</c>, and + Rep(Fc) = <c>[Rep(C_1), ..., Rep(C_k)]</c>.</p> + <list type="bulleted"> + <item>If C is a constraint <c>is_subtype(V, T)</c> or <c>V :: T</c>, + where <c>V</c> is a type variable and <c>T</c> is a type, then + Rep(C) = <c>{type,LINE,constraint,[{atom,LINE,is_subtype},[Rep(V),Rep(T)]]}</c>. + </item> + </list> + </section> + + <section> + <title>Association Types</title> + <list type="bulleted"> + <item>If A is an association type <c>K => V</c>, where + <c>K</c> and <c>V</c> are types, then Rep(A) = + <c>{type,LINE,map_field_assoc,[Rep(K),Rep(V)]}</c>.</item> + <item>If A is an association type <c>K := V</c>, where + <c>K</c> and <c>V</c> are types, then Rep(A) = + <c>{type,LINE,map_field_exact,[Rep(K),Rep(V)]}</c>.</item> + </list> + </section> + + <section> + <title>Record Field Types</title> + <list type="bulleted"> + <item>If F is a record field type <c>Name :: Type</c>, + where <c>Type</c> is a type, then Rep(F) = + <c>{type,LINE,field_type,[Rep(Name),Rep(Type)]}</c>.</item> + </list> + </section> + </section> + + <section> + <title>The Abstract Format After Preprocessing</title> + <p>The compilation option <c>debug_info</c> can be given to the + compiler to have the abstract code stored in + the <c>abstract_code</c> chunk in the BEAM file (for debugging purposes).</p> - <p>In OTP R9C and later, the <c><![CDATA[abstract_code]]></c> chunk will + <p>In OTP R9C and later, the <c>abstract_code</c> chunk will contain</p> - <p><c><![CDATA[{raw_abstract_v1,AbstractCode}]]></c></p> - <p>where <c><![CDATA[AbstractCode]]></c> is the abstract code as described + <p><c>{raw_abstract_v1,AbstractCode}</c></p> + <p>where <c>AbstractCode</c> is the abstract code as described in this document.</p> <p>In releases of OTP prior to R9C, the abstract code after some more processing was stored in the BEAM file. The first element of the - tuple would be either <c><![CDATA[abstract_v1]]></c> (R7B) or <c><![CDATA[abstract_v2]]></c> + tuple would be either <c>abstract_v1</c> (R7B) or <c>abstract_v2</c> (R8B).</p> </section> </chapter> diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml index 038950b54d..e283acc1b4 100644 --- a/erts/doc/src/alt_dist.xml +++ b/erts/doc/src/alt_dist.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2000</year><year>2011</year> + <year>2000</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/book.xml b/erts/doc/src/book.xml index 00a2888685..a0780c91d9 100644 --- a/erts/doc/src/book.xml +++ b/erts/doc/src/book.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE book SYSTEM "book.dtd"> <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header titlestyle="normal"> <copyright> - <year>1997</year><year>2009</year> + <year>1997</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/communication.xml b/erts/doc/src/communication.xml index 61a9b0e716..1eb05310e9 100644 --- a/erts/doc/src/communication.xml +++ b/erts/doc/src/communication.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2012</year><year>2013</year> + <year>2012</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/crash_dump.xml b/erts/doc/src/crash_dump.xml index 8f5515baca..0b827ae583 100644 --- a/erts/doc/src/crash_dump.xml +++ b/erts/doc/src/crash_dump.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>1999</year><year>2013</year> + <year>1999</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -55,10 +56,12 @@ emulator or the operating system can be reconfigured to avoid the crash, which is why interpreting the crash dump correctly is important.</p> + <p>On systems that support OS signals, it is also possible to stop + the runtime system and generate a crash dump by sending the SIGUSR1.</p> <p>The erlang crash dump is a readable text file, but it might not be very easy to read. Using the Crashdump Viewer tool in the <c><![CDATA[observer]]></c> application will simplify the task. This is an - HTML based tool for browsing Erlang crash dumps.</p> + wx-widget based tool for browsing Erlang crash dumps.</p> <section> <marker id="general_info"></marker> @@ -66,8 +69,9 @@ <p>The first part of the dump shows the creation time for the dump, a slogan indicating the reason for the dump, the system version, of the node from which the dump originates, the compile time of - the emulator running the originating node and the number of - atoms in the atom table. + the emulator running the originating node, the number of + atoms in the atom table and the runtime system thread that caused + the crash dump to happen. </p> <section> @@ -113,8 +117,9 @@ sockets/pipes can be used simultaneously by Erlang (due to limitations in the Unix <c><![CDATA[select]]></c> call). The number of open regular files is not affected by this.</item> - <item>"Received SIGUSR1" - The SIGUSR1 signal was sent to the - Erlang machine (Unix only).</item> + <item>"Received SIGUSR1" - Sending the SIGUSR1 signal to a + Erlang machine (Unix only) forces a crash dump. This slogan reflects + that the Erlang machine crash-dumped due to receiving that signal.</item> <item>"Kernel pid terminated (<em>Who</em>) (<em>Exit-reason</em>)" - The kernel supervisor has detected a failure, usually that the <c><![CDATA[application_controller]]></c> @@ -167,6 +172,60 @@ </section> <section> + <marker id="scheduler"></marker> + <title>Scheduler information</title> + <p>Under the tag <em>=scheduler</em> information about the current state + and statistics of the schedulers in the runtime system is displayed. + On OSs that do allow instant suspension of other threads, the data within + this section will reflect what the runtime system looks like at the moment + when the crash happens.</p> + <p>The following fields can exist for a process:</p> + <taglist> + <tag><em>=scheduler:id</em></tag> + <item>Header, states the scheduler identifier.</item> + <tag><em>Scheduler Sleep Info Flags</em></tag> + <item>If empty the scheduler was doing some work. + If not empty the scheduler is either in some state of sleep, + or suspended. This entry is only present in a SMP enabled emulator</item> + <tag><em>Scheduler Sleep Info Aux Work</em></tag> + <item>If not empty, a scheduler internal auxiliary work is scheduled + to be done.</item> + <tag><em>Current Port</em></tag> + <item>The port identifier of the port that is currently being + executed by the scheduler.</item> + <tag><em>Current Process</em></tag> + <item>The process identifier of the process that is currently being + executed by the scheduler. If there is such a process this entry is + followed by the <em>State</em>,<em>Internal State</em>, + <em>Program Counter</em>, <em>CP</em> of that same process. See + <seealso marker="#processes">Process Information</seealso> for a + description what the different entries mean. Keep in mind that + this is a snapshot of what the entries are exactly when the crash + dump is starting to be generated. Therefore they will most likely + be different (and more telling) then the entries for the same + processes found in the <em>=proc</em> section. If there is no currently + running process, only the <em>Current Process</em> entry will be printed. + </item> + <tag><em>Current Process Limited Stack Trace</em></tag> + <item>This entry only shows up if there is a current process. It is very + similar to <seealso marker="#proc_data"><em>=proc_stack</em></seealso>, + except that only the function frames are printed (i.e. the stack variables + are omited). It is also limited to only print the top and bottom part + of the stack. If the stack is small (less that 512 slots) then the + entire stack will be printed. If not, an entry stating + <code>skipping ## slots</code> will be printed where ## is + replaced by the number of slots that has been skipped.</item> + <tag><em>Run Queue</em></tag> + <item>Displays statistics about how many processes and ports + of different priorities are scheduled on this scheduler.</item> + <tag><em>** crashed **</em></tag> + <item>This entry is normally not printed. It signifies that getting + the rest of the information about this scheduler failed for some reason. + </item> + </taglist> + </section> + + <section> <marker id="memory"></marker> <title>Memory information</title> <p>Under the tag <em>=memory</em> you will find information similar @@ -308,6 +367,9 @@ <item>The number of live argument registers. The argument registers, if any are live, will follow. These may contain the arguments of the function if they are not yet moved to the stack.</item> + <item><em>Internal State</em></item> + <item>A more detailed internal represantation of the state of + this process.</item> </taglist> <p>See also the section about <seealso marker="#proc_data">process data</seealso>.</p> </section> @@ -333,18 +395,38 @@ <tag><em>Name</em></tag> <item>The name of the table, regardless of whether it is a <c><![CDATA[named_table]]></c> or not.</item> - <tag><em>Buckets</em></tag> + <tag><em>Hash table, Buckets</em></tag> <item>This occurs if the table is a hash table, i.e. if it is not an <c><![CDATA[ordered_set]]></c>.</item> + <tag><em>Hash table, Chain Length</em></tag> + <item>Only applicable for hash tables. Contains statistics about the + hash table, such as the max, min and avg chain length. Having a max much + larger than the avg, and a std dev much larger that + the expected std dev is a sign that the hashing of the terms is + behaving badly for some reason.</item> <tag><em>Ordered set (AVL tree), Elements</em></tag> <item>This occurs only if the table is an <c><![CDATA[ordered_set]]></c>. (The number of elements is the same as the number of objects in the table.)</item> + <tag><em>Fixed</em></tag> + <item>If the table is fixed using ets:safe_fixtable or some internal + mechanism.</item> <tag><em>Objects</em></tag> <item>The number of objects in the table</item> <tag><em>Words</em></tag> <item>The number of words (usually 4 bytes/word) allocated to data in the table.</item> + <tag><em>Type</em></tag> + <item>The type of the table, i.e. <c>set</c>, <c>bag</c>, + <c>dublicate_bag</c> or <c>ordered_set</c>.</item> + <tag><em>Compressed</em></tag> + <item>If this table was compressed.</item> + <tag><em>Protection</em></tag> + <item>The protection of this table.</item> + <tag><em>Write Concurrency</em></tag> + <item>If write_concurrency was enabled for this table.</item> + <tag><em>Read Concurrency</em></tag> + <item>If read_concurrency was enabled for this table.</item> </taglist> </section> diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml index 52283879c7..4bef5e1388 100644 --- a/erts/doc/src/driver.xml +++ b/erts/doc/src/driver.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2001</year><year>2011</year> + <year>2001</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml index c37138e7b1..ae7f264d0c 100644 --- a/erts/doc/src/driver_entry.xml +++ b/erts/doc/src/driver_entry.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> <header> <copyright> - <year>2001</year><year>2012</year> + <year>2001</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -110,6 +111,8 @@ <p>When the driver has passed the <c>driver_entry</c> over to the emulator, the driver is <em>not</em> allowed to modify the <c>driver_entry</c>.</p> + <p>If compiling a driver for static inclusion via --enable-static-drivers you + have to define STATIC_ERLANG_DRIVER before the DRIVER_INIT declaration.</p> <note> <p>Do <em>not</em> declare the <c>driver_entry</c> <c>const</c>. This since the emulator needs to modify the <c>handle</c>, and the <c>handle2</c> @@ -123,7 +126,7 @@ <section> <title>DATA TYPES</title> <taglist> - <tag><b>ErlDrvEntry</b></tag> + <tag><em>ErlDrvEntry</em></tag> <item> <p/> <code type="none"> @@ -208,7 +211,7 @@ typedef struct erl_drv_entry { number >= 0 or a pointer, or if the driver can't be started, one of three error codes should be returned:</p> <p>ERL_DRV_ERROR_GENERAL - general error, no error code</p> - <p>ERL_DRV_ERROR_ERRNO - error with error code in erl_errno</p> + <p>ERL_DRV_ERROR_ERRNO - error with error code in <c>errno</c></p> <p>ERL_DRV_ERROR_BADARG - error, badarg</p> <p>If an error code is returned, the port isn't started.</p> </item> @@ -232,6 +235,7 @@ typedef struct erl_drv_entry { </item> <tag><marker id="ready_input"/>void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event)</tag> + <item/> <tag><marker id="ready_output"/>void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event)</tag> <item> <p>This is called when a driver event (given in the @@ -433,7 +437,14 @@ typedef struct erl_drv_entry { <seealso marker="erl_driver#erl_drv_busy_msgq_limits">erl_drv_busy_msgq_limits()</seealso> function. </item> - </taglist> + <tag><c>ERL_DRV_FLAG_USE_INIT_ACK</c></tag> + <item>When this flag is given the linked-in driver has to manually + acknowledge that the port has been successfully started using + <seealso marker="erl_driver#erl_drv_init_ack">erl_drv_init_ack()</seealso>. + This allows the implementor to make the erlang:open_port exit with + badarg after some initial asynchronous initialization has been done. + </item> + </taglist> </item> <tag>void *handle2</tag> <item> diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd.xml index 3e7005410f..d9f580d081 100644 --- a/erts/doc/src/epmd.xml +++ b/erts/doc/src/epmd.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -36,7 +37,7 @@ <comsummary> <p>Erlang Port Mapper Daemon</p> <taglist> - <tag><c><![CDATA[epmd [-d|-debug] [DbgExtra...] [-port No] [-daemon] [-relaxed_command_check]]]></c></tag> + <tag><c><![CDATA[epmd [-d|-debug] [DbgExtra...] [-address Addresses] [-port No] [-daemon] [-relaxed_command_check]]]></c></tag> <item> <p>Starts the port mapper daemon</p> </item> @@ -58,12 +59,12 @@ of the IP address and a port number. The name of the node is an atom on the form of <c><![CDATA[Name@Node]]></c>. The job of the <c><![CDATA[epmd]]></c> daemon is to keep track of which - node name listens on which address. Hence, <c><![CDATA[epmd]]></c> map + node name listens on which address. Hence, <c><![CDATA[epmd]]></c> maps symbolic node names to machine addresses.</p> <p>The TCP/IP <c>epmd</c> daemon actually only keeps track of - the <c>Name</c> (first) part of an Erlang node name, the <c>Host</c> - part (whatever is after the <c><![CDATA[@]]></c> is implicit in the + the <c>Name</c> (first) part of an Erlang node name. The <c>Host</c> + part (whatever is after the <c><![CDATA[@]]></c>) is implicit in the node name where the <c>epmd</c> daemon was actually contacted, as is the IP address where the Erlang node can be reached. Consistent and correct TCP naming services are @@ -77,12 +78,12 @@ <p>The daemon is started automatically by the <c>erl</c> command if the node is to be distributed and there is no running instance present. If automatically launched, - environment variables has to be used to alter the behavior of + environment variables have to be used to alter the behavior of the daemon. See the <seealso marker="#environment_variables">Environment variables</seealso> section below.</p> - <p>If the -daemon argument is not given, the + <p>If the -daemon argument is not given, <c><![CDATA[epmd]]></c> runs as a normal program with the controlling terminal of the shell in which it is started. Normally, it should run as a daemon.</p> @@ -122,7 +123,7 @@ comma-separated list of IP addresses and on the loopback address (which is implicitly added to the list if it has not been specified). This can also be set using the - <c><![CDATA[ERL_EPMD_ADDRESS]]></c> environment variable, see the + <c><![CDATA[ERL_EPMD_ADDRESS]]></c> environment variable. See the section <seealso marker="#environment_variables">Environment variables</seealso> below.</p> </item> @@ -130,7 +131,7 @@ <item> <p>Let this instance of epmd listen to another TCP port than default 4369. This can also be set using the - <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the + <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable. See the section <seealso marker="#environment_variables">Environment variables</seealso> below</p> </item> @@ -153,7 +154,7 @@ <p>With relaxed command checking, the <c>epmd</c> daemon can be killed from the localhost with i.e. <c>epmd -kill</c> even if there are active nodes registered. Normally only daemons with an empty node database can be killed with the <c>epmd -kill</c> command.</p> </item> <item> - <p>The <c>epmd -stop</c> command (and the corresponding messages to epmd, as can be given using <c>erl_interface/ei</c>) is normally always ignored, as it opens up for strange situation when two nodes of the same name can be alive at the same time. A node unregisters itself by just closing the connection to epmd, why the <c>stop</c> command was only intended for use in debugging situations.</p> + <p>The <c>epmd -stop</c> command (and the corresponding messages to epmd, as can be given using <c>erl_interface/ei</c>) is normally always ignored, as it opens up the possibility of a strange situation where two nodes of the same name can be alive at the same time. A node unregisters itself by just closing the connection to epmd, which is why the <c>stop</c> command was only intended for use in debugging situations.</p> <p>With relaxed command checking enabled, you can forcibly unregister live nodes.</p> </item> </list> @@ -166,7 +167,7 @@ <section> <marker id="debug_flags"></marker> <title>DbgExtra options</title> - <p>These options are purely for debugging and testing epmd clients, they should not be used in normal operation.</p> + <p>These options are purely for debugging and testing epmd clients. They should not be used in normal operation.</p> <taglist> <tag><c><![CDATA[-packet_timeout Seconds]]></c></tag> @@ -177,9 +178,9 @@ </item> <tag><c><![CDATA[-delay_accept Seconds]]></c></tag> <item> - <p>To simulate a busy server you can insert a delay between epmd - gets notified about that a new connection is requested and - when the connections gets accepted.</p> + <p>To simulate a busy server you can insert a delay between when epmd + gets notified that a new connection is requested and + when the connection gets accepted.</p> </item> <tag><c><![CDATA[-delay_write Seconds]]></c></tag> <item> @@ -191,15 +192,15 @@ <section> <marker id="interactive_flags"></marker> <title>Interactive options</title> - <p>These options make <c>epmd</c> run as an interactive command displaying the results of sending queries ta an already running instance of <c>epmd</c>. The epmd contacted is always on the local node, but the <c>-port</c> option can be used to select between instances if several are running using different port on the host.</p> + <p>These options make <c>epmd</c> run as an interactive command, displaying the results of sending queries to an already running instance of <c>epmd</c>. The epmd contacted is always on the local node, but the <c>-port</c> option can be used to select between instances if several are running using different ports on the host.</p> <taglist> <tag><c><![CDATA[-port No]]></c></tag> <item> <p>Contacts the <c>epmd</c> listening on the given TCP port number (default 4369). This can also be set using the - <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable, see the + <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable. See the section <seealso marker="#environment_variables">Environment - variables</seealso> below</p> + variables</seealso> below.</p> </item> <tag><c><![CDATA[-names]]></c></tag> <item> @@ -210,7 +211,7 @@ <p>Kill the currently running <c>epmd</c>.</p> <p>Killing the running <c>epmd</c> is only allowed if <c>epmd - -names</c> show an empty database or + -names</c> shows an empty database or <c>-relaxed_command_check</c> was given when the running instance of <c>epmd</c> was started. Note that <c>-relaxed_command_check</c> is given when starting the @@ -228,7 +229,7 @@ <p>This command can only be used when contacting <c>epmd</c> instances started with the <c>-relaxed_command_check</c> flag. Note that relaxed command checking has to be enabled for - the <c>epmd</c> daemon contacted, When running epmd + the <c>epmd</c> daemon contacted. When running epmd interactively, <c>-relaxed_command_check</c> has no effect.</p> </item> @@ -259,7 +260,7 @@ <item> <p>If set prior to start, the <c>epmd</c> daemon will behave as if the <c>-relaxed_command_check</c> option was given at - start-up. If consequently setting this option before starting + start-up. Consequently, if this option is set before starting the Erlang virtual machine, the automatically started <c>epmd</c> will accept the <c>-kill</c> and <c>-stop</c> commands without restrictions.</p> @@ -287,8 +288,8 @@ remote hosts. However, only the query commands are answered (and acted upon) if the query comes from a remote host. It is always an error to try to register a nodename if the client is not a process - located on the same host as the <c>epmd</c> instance is running on, - why such requests are considered hostile and the connection is + located on the same host as the <c>epmd</c> instance is running on- + such requests are considered hostile and the connection is immediately closed.</p> <p>The queries accepted from remote nodes are:</p> @@ -307,3 +308,4 @@ </comref> + diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 70569b1c6c..37387f2c59 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -137,7 +138,7 @@ see <seealso marker="kernel:app">app(4)</seealso> and <seealso marker="kernel:application">application(3)</seealso>.</p> </item> - <tag><marker id="args_file"><c><![CDATA[-args_file FileName]]></c></marker></tag> + <tag><marker id="args_file"/><c><![CDATA[-args_file FileName]]></c></tag> <item> <p>Command line arguments are read from the file <c><![CDATA[FileName]]></c>. The arguments read from the file replace the @@ -202,7 +203,7 @@ <seealso marker="kernel:app">app(4)</seealso> and <seealso marker="kernel:application">application(3)</seealso>.</p> </item> - <tag><marker id="connect_all"><c><![CDATA[-connect_all false]]></c></marker></tag> + <tag><marker id="connect_all"/><c><![CDATA[-connect_all false]]></c></tag> <item> <p>If this flag is present, <c><![CDATA[global]]></c> will not maintain a fully connected network of distributed Erlang nodes, and then @@ -287,7 +288,7 @@ <p>Makes <c><![CDATA[init]]></c> write some debug information while interpreting the boot script.</p> </item> - <tag><marker id="instr"><c><![CDATA[-instr]]></c>(emulator flag)</marker></tag> + <tag><marker id="instr"/><c><![CDATA[-instr]]></c>(emulator flag)</tag> <item> <p>Selects an instrumented Erlang runtime system (virtual machine) to run, instead of the ordinary one. When running an @@ -337,7 +338,8 @@ <seealso marker="kernel:net_kernel">net_kernel(3)</seealso>. It is also ensured that <c><![CDATA[epmd]]></c> runs on the current host before Erlang is started. See - <seealso marker="epmd">epmd(1)</seealso>.</p> + <seealso marker="epmd">epmd(1)</seealso> and the + <seealso marker="#start_epmd"><c>-start_epmd</c></seealso> option.</p> <p>The name of the node will be <c><![CDATA[Name@Host]]></c>, where <c><![CDATA[Host]]></c> is the fully qualified host name of the current host. For short names, use the <c><![CDATA[-sname]]></c> flag instead.</p> @@ -370,7 +372,7 @@ path, similar to <c><![CDATA[code:add_pathsa/1]]></c>. See <seealso marker="kernel:code">code(3)</seealso>. As an alternative to <c>-pa</c>, if several directories are - to be prepended to the code and the directories have a + to be prepended to the code path and the directories have a common parent directory, that parent directory could be specified in the <c>ERL_LIBS</c> environment variable. See <seealso marker="kernel:code">code(3)</seealso>.</p> @@ -381,6 +383,33 @@ similar to <c><![CDATA[code:add_pathsz/1]]></c>. See <seealso marker="kernel:code">code(3)</seealso>.</p> </item> + <tag><c><![CDATA[-path Dir1 Dir2 ...]]></c></tag> + <item> + <p>Replaces the path specified in the boot script. See + <seealso marker="sasl:script">script(4)</seealso>.</p> + </item> + <tag><c><![CDATA[-proto_dist Proto]]></c></tag> + <item> + <p>Specify a protocol for Erlang distribution.</p> + <taglist> + <tag><c>inet_tcp</c></tag> + <item> + <p>TCP over IPv4 (the default)</p> + </item> + <tag><c>inet_tls</c></tag> + <item> + <p>distribution over TLS/SSL</p> + </item> + <tag><c>inet6_tcp</c></tag> + <item> + <p>TCP over IPv6</p> + </item> + </taglist> + <p>For example, to start up IPv6 distributed nodes:</p> +<pre> +% <input>erl -name [email protected] -proto_dist inet6_tcp</input> +</pre> + </item> <tag><c><![CDATA[-remsh Node]]></c></tag> <item> <p>Starts Erlang with a remote shell connected to <c><![CDATA[Node]]></c>.</p> @@ -435,7 +464,22 @@ flag and those running with the <c><![CDATA[-name]]></c> flag, as node names must be unique in distributed Erlang systems.</p> </item> - <tag><marker id="smp"><c><![CDATA[-smp [enable|auto|disable]]]></c></marker></tag> + <tag><marker id="start_epmd"/><c>-start_epmd true | false</c></tag> + <item> + + <p>Specifies whether Erlang should start + <seealso marker="epmd">epmd</seealso> on startup. By default + this is <c>true</c>, but if you prefer to start epmd + manually, set this to <c>false</c>.</p> + + <p>This only applies if Erlang is started as a distributed node, + i.e. if <c>-name</c> or <c>-sname</c> is specified. Otherwise, + epmd is not started even if <c>-start_epmd true</c> is given.</p> + + <p>Note that a distributed node will fail to start if epmd is + not running.</p> + </item> + <tag><marker id="smp"/><c><![CDATA[-smp [enable|auto|disable]]]></c></tag> <item> <p><c>-smp enable</c> and <c>-smp</c> starts the Erlang runtime system with SMP support enabled. This may fail if no runtime @@ -461,7 +505,7 @@ <p><c><![CDATA[erl]]></c> invokes the code for the Erlang emulator (virtual machine), which supports the following flags:</p> <taglist> - <tag><marker id="async_thread_stack_size"><c><![CDATA[+a size]]></c></marker></tag> + <tag><marker id="async_thread_stack_size"/><c><![CDATA[+a size]]></c></tag> <item> <p>Suggested stack size, in kilowords, for threads in the async-thread pool. Valid range is 16-8192 kilowords. The @@ -476,7 +520,7 @@ suggestion, and it might even be ignored on some platforms.</p> </item> - <tag><marker id="async_thread_pool_size"><c><![CDATA[+A size]]></c></marker></tag> + <tag><marker id="async_thread_pool_size"/><c><![CDATA[+A size]]></c></tag> <item> <p>Sets the number of threads in async thread pool, valid range is 0-1024. If thread support is available, the default is 10.</p> @@ -495,21 +539,35 @@ <c><![CDATA[werl]]></c>, not <c><![CDATA[erl]]></c> (<c><![CDATA[oldshell]]></c>). Note also that <c><![CDATA[Ctrl-Break]]></c> is used instead of <c><![CDATA[Ctrl-C]]></c> on Windows.</p> </item> - <tag><c><![CDATA[+c]]></c></tag> - <item> - <p>Disable compensation for sudden changes of system time.</p> - <p>Normally, <c><![CDATA[erlang:now/0]]></c> will not immediately reflect - sudden changes in the system time, in order to keep timers - (including <c><![CDATA[receive-after]]></c>) working. Instead, the time - maintained by <c><![CDATA[erlang:now/0]]></c> is slowly adjusted towards - the new system time. (Slowly means in one percent adjustments; - if the time is off by one minute, the time will be adjusted - in 100 minutes.)</p> - <p>When the <c><![CDATA[+c]]></c> option is given, this slow adjustment - will not take place. Instead <c><![CDATA[erlang:now/0]]></c> will always - reflect the current system time. Note that timers are based - on <c><![CDATA[erlang:now/0]]></c>. If the system time jumps, timers - then time out at the wrong time.</p> + <tag><marker id="+c"/><c><![CDATA[+c true | false]]></c></tag> + <item> + <p>Enable or disable + <seealso marker="time_correction#Time_Correction">time correction</seealso>:</p> + <taglist> + <tag><c>true</c></tag> + <item><p>Enable time correction. This is the default if + time correction is supported on the specific platform.</p></item> + + <tag><c>false</c></tag> + <item><p>Disable time correction.</p></item> + </taglist> + <p>For backwards compatibility, the boolean value can be omitted. + This is interpreted as <c>+c false</c>. + </p> + </item> + <tag><marker id="+C_"/><c><![CDATA[+C no_time_warp | single_time_warp | multi_time_warp]]></c></tag> + <item> + <p>Set + <seealso marker="time_correction#Time_Warp_Modes">time warp mode</seealso>: + </p> + <taglist> + <tag><c>no_time_warp</c></tag> + <item><p><seealso marker="time_correction#No_Time_Warp_Mode">No Time Warp Mode</seealso> (the default)</p></item> + <tag><c>single_time_warp</c></tag> + <item><p><seealso marker="time_correction#Single_Time_Warp_Mode">Single Time Warp Mode</seealso></p></item> + <tag><c>multi_time_warp</c></tag> + <item><p><seealso marker="time_correction#Multi_Time_Warp_Mode">Multi Time Warp Mode</seealso></p></item> + </taglist> </item> <tag><c><![CDATA[+d]]></c></tag> <item> @@ -522,9 +580,10 @@ core dump and no crash dump if an internal error is detected.</p> <p>Calling <c>erlang:halt/1</c> with a string argument will still - produce a crash dump.</p> + produce a crash dump. On Unix systems, sending an emulator process + a SIGUSR1 signal will also force a crash dump.</p> </item> - <tag><c><![CDATA[+e Number]]></c></tag> + <tag><marker id="+e"/><c><![CDATA[+e Number]]></c></tag> <item> <p>Set max number of ETS tables.</p> </item> @@ -535,12 +594,15 @@ </item> <tag><marker id="file_name_encoding"></marker><c><![CDATA[+fnl]]></c></tag> <item> - <p>The VM works with file names as if they are encoded using the ISO-latin-1 encoding, disallowing Unicode characters with codepoints beyond 255. This is default on operating systems that have transparent file naming, i.e. all Unixes except MacOSX.</p> - <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names.</p> + <p>The VM works with file names as if they are encoded using the ISO-latin-1 encoding, disallowing Unicode characters with codepoints beyond 255.</p> + <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names. Note that this value also applies to command-line parameters and environment variables (see <seealso marker="stdlib:unicode_usage#unicode_in_environment_and_parameters">STDLIB User's Guide</seealso>).</p> </item> <tag><c><![CDATA[+fnu[{w|i|e}]]]></c></tag> <item> - <p>The VM works with file names as if they are encoded using UTF-8 (or some other system specific Unicode encoding). This is the default on operating systems that enforce Unicode encoding, i.e. Windows and MacOSX.</p> + <p>The VM works with file names as if they are encoded using + UTF-8 (or some other system specific Unicode encoding). This + is the default on operating systems that enforce Unicode + encoding, i.e. Windows and MacOS X.</p> <p>The <c>+fnu</c> switch can be followed by <c>w</c>, <c>i</c>, or <c>e</c> to control the way wrongly encoded file names are to be reported. <c>w</c> means that a warning is @@ -552,11 +614,16 @@ encountered. <c>w</c> is the default. Note that <c>file:read_link/1</c> will always return an error if the link points to an invalid file name.</p> - <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names.</p> + <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names. Note that this value also applies to command-line parameters and environment variables (see <seealso marker="stdlib:unicode_usage#unicode_in_environment_and_parameters">STDLIB User's Guide</seealso>).</p> </item> <tag><c><![CDATA[+fna[{w|i|e}]]]></c></tag> <item> - <p>Selection between <c>+fnl</c> and <c>+fnu</c> is done based on the current locale settings in the OS, meaning that if you have set your terminal for UTF-8 encoding, the filesystem is expected to use the same encoding for file names (use with care).</p> + <p>Selection between <c>+fnl</c> and <c>+fnu</c> is done based + on the current locale settings in the OS, meaning that if you + have set your terminal for UTF-8 encoding, the filesystem is + expected to use the same encoding for file names. This is + default on all operating systems except MacOS X and + Windows.</p> <p>The <c>+fna</c> switch can be followed by <c>w</c>, <c>i</c>, or <c>e</c>. This will have effect if the locale settings cause the behavior of <c>+fnu</c> to be selected. @@ -564,7 +631,7 @@ settings cause the behavior of <c>+fnl</c> to be selected, then <c>w</c>, <c>i</c>, or <c>e</c> will not have any effect.</p> - <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names.</p> + <p>See <seealso marker="stdlib:unicode_usage#unicode_file_names">STDLIB User's Guide</seealso> for more infomation about unicode file names. Note that this value also applies to command-line parameters and environment variables (see <seealso marker="stdlib:unicode_usage#unicode_in_environment_and_parameters">STDLIB User's Guide</seealso>).</p> </item> <tag><c><![CDATA[+hms Size]]></c></tag> <item> @@ -576,6 +643,45 @@ <p>Sets the default binary virtual heap size of processes to the size <c><![CDATA[Size]]></c>.</p> </item> + <tag><marker id="+hmax"/><c><![CDATA[+hmax Size]]></c></tag> + <item> + <p>Sets the default maximum heap size of processes to the size + <c><![CDATA[Size]]></c>. If <c>+hmax</c> is not given, the default is <c>0</c> + which means that no maximum heap size is used. + For more information, see the documentation of + <seealso marker="erlang#process_flag_max_heap_size"> + <c>process_flag(max_heap_size, MaxHeapSize)</c></seealso>.</p> + </item> + <tag><marker id="+hmaxel"/><c><![CDATA[+hmaxel true|false]]></c></tag> + <item> + <p>Sets whether to send an error logger message for processes that reach + the maximum heap size or not. If <c>+hmaxel</c> is not given, the default is <c>true</c>. + For more information, see the documentation of + <seealso marker="erlang#process_flag_max_heap_size"> + <c>process_flag(max_heap_size, MaxHeapSize)</c></seealso>.</p> + </item> + <tag><marker id="+hmaxk"/><c><![CDATA[+hmaxk true|false]]></c></tag> + <item> + <p>Sets whether to kill processes that reach the maximum heap size or not. If + <c>+hmaxk</c> is not given, the default is <c>true</c>. For more information, + see the documentation of + <seealso marker="erlang#process_flag_max_heap_size"> + <c>process_flag(max_heap_size, MaxHeapSize)</c></seealso>.</p> + </item> + <tag><c><![CDATA[+hpds Size]]></c></tag> + <item> + <p>Sets the initial process dictionary size of processes to the size + <c><![CDATA[Size]]></c>.</p> + </item> + <tag><marker id="+hmqd"/><c>+hmqd off_heap|on_heap</c></tag> + <item><p> + Sets the default value for the process flag + <c>message_queue_data</c>. If <c>+hmqd</c> is not + passed, <c>on_heap</c> will be the default. For more information, + see the documentation of + <seealso marker="erlang#process_flag_message_queue_data"><c>process_flag(message_queue_data, + MQD)</c></seealso>. + </p></item> <tag><c><![CDATA[+K true | false]]></c></tag> <item> <p>Enables or disables the kernel poll functionality if @@ -596,7 +702,7 @@ information about the file names and line numbers. </p> </item> - <tag><marker id="erts_alloc"><c><![CDATA[+MFlag Value]]></c></marker></tag> + <tag><marker id="erts_alloc"/><c><![CDATA[+MFlag Value]]></c></tag> <item> <p>Memory allocator specific flags, see <seealso marker="erts_alloc">erts_alloc(3)</seealso> for @@ -635,10 +741,10 @@ debugging.</item> </taglist> </item> - <tag><marker id="+pc"/><marker id="printable_character_range"><c><![CDATA[+pc Range]]></c></marker></tag> + <tag><marker id="+pc"/><marker id="printable_character_range"/><c><![CDATA[+pc Range]]></c></tag> <item> <p>Sets the range of characters that the system will consider printable in heuristic detection of strings. This typically affects the shell, debugger and io:format functions (when ~tp is used in the format string).</p> - <p>Currently two values for the <c>Range</c> are supported: + <p>Currently two values for the <c>Range</c> are supported:</p> <taglist> <tag><c>latin1</c></tag> <item>The default. Only characters in the ISO-latin-1 range can be considered printable, which means @@ -653,11 +759,10 @@ example your font does not cover all Unicode characters.</item> </taglist> - </p> <p>Se also <seealso marker="stdlib:io#printable_range/0"> io:printable_range/0</seealso>.</p> </item> - <tag><marker id="+P"/><marker id="max_processes"><c><![CDATA[+P Number|legacy]]></c></marker></tag> + <tag><marker id="+P"/><marker id="max_processes"/><c><![CDATA[+P Number|legacy]]></c></tag> <item> <p>Sets the maximum number of simultaneously existing processes for this system if a <c>Number</c> is passed as value. Valid range for @@ -677,7 +782,7 @@ circumstances be extremely expensive. The legacy algoritm is deprecated, and the <c>legacy</c> option is scheduled for removal in OTP-R18.</p> </item> - <tag><marker id="+Q"/><marker id="max_ports"><c><![CDATA[+Q Number|legacy]]></c></marker></tag> + <tag><marker id="+Q"/><marker id="max_ports"/><c><![CDATA[+Q Number|legacy]]></c></tag> <item> <p>Sets the maximum number of simultaneously existing ports for this system if a Number is passed as value. Valid range for <c>Number</c> @@ -708,7 +813,7 @@ circumstances be extremely expensive. The legacy algoritm is deprecated, and the <c>legacy</c> option is scheduled for removal in OTP-R18.</p> </item> - <tag><marker id="compat_rel"><c><![CDATA[+R ReleaseNumber]]></c></marker></tag> + <tag><marker id="compat_rel"/><c><![CDATA[+R ReleaseNumber]]></c></tag> <item> <p>Sets the compatibility mode.</p> <p>The distribution mechanism is not backwards compatible by @@ -728,7 +833,7 @@ <item> <p>Force ets memory block to be moved on realloc.</p> </item> - <tag><marker id="+rg"><c><![CDATA[+rg ReaderGroupsLimit]]></c></marker></tag> + <tag><marker id="+rg"/><c><![CDATA[+rg ReaderGroupsLimit]]></c></tag> <item> <p>Limits the amount of reader groups used by read/write locks optimized for read operations in the Erlang runtime system. By @@ -746,29 +851,133 @@ schedulers to logical processors</seealso>, since the reader groups are distributed better between schedulers.</p> </item> - <tag><marker id="+S"><c><![CDATA[+S Schedulers:SchedulerOnline]]></c></marker></tag> - <item> - <p>Sets the amount of scheduler threads to create and scheduler - threads to set online when SMP support has been enabled. - Valid range for both values are 1-1024. If the - Erlang runtime system is able to determine the amount - of logical processors configured and logical processors available, - <c>Schedulers</c> will default to logical processors configured, - and <c>SchedulersOnline</c> will default to logical processors - available; otherwise, the default values will be 1. <c>Schedulers</c> - may be omitted if <c>:SchedulerOnline</c> is not and vice versa. The - amount of schedulers online can be changed at run time via + <tag><marker id="+S"/><c><![CDATA[+S Schedulers:SchedulerOnline]]></c></tag> + <item> + <p>Sets the number of scheduler threads to create and scheduler + threads to set online when SMP support has been enabled. The maximum for + both values is 1024. If the Erlang runtime system is able to determine the + amount of logical processors configured and logical processors available, + <c>Schedulers</c> will default to logical processors configured, and + <c>SchedulersOnline</c> will default to logical processors available; + otherwise, the default values will be 1. <c>Schedulers</c> may be omitted + if <c>:SchedulerOnline</c> is not and vice versa. The number of schedulers + online can be changed at run time via <seealso marker="erlang#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>. </p> - <p>This flag will be ignored if the emulator doesn't have + <p>If <c>Schedulers</c> or <c>SchedulersOnline</c> is specified as a + negative number, the value is subtracted from the default number of + logical processors configured or logical processors available, respectively. + </p> + <p>Specifying the value 0 for <c>Schedulers</c> or <c>SchedulersOnline</c> + resets the number of scheduler threads or scheduler threads online respectively + to its default value. + </p> + <p>This option is ignored if the emulator doesn't have SMP support enabled (see the <seealso marker="#smp">-smp</seealso> flag).</p> </item> + <tag><marker id="+SP"/><c><![CDATA[+SP SchedulersPercentage:SchedulersOnlinePercentage]]></c></tag> + <item> + <p>Similar to <seealso marker="#+S">+S</seealso> but uses percentages to set the + number of scheduler threads to create, based on logical processors configured, + and scheduler threads to set online, based on logical processors available, when + SMP support has been enabled. Specified values must be greater than 0. For example, + <c>+SP 50:25</c> sets the number of scheduler threads to 50% of the logical processors + configured and the number of scheduler threads online to 25% of the logical processors available. + <c>SchedulersPercentage</c> may be omitted if <c>:SchedulersOnlinePercentage</c> is + not and vice versa. The number of schedulers online can be changed at run time via + <seealso marker="erlang#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>. + </p> + <p>This option interacts with <seealso marker="#+S">+S</seealso> settings. + For example, on a system with 8 logical cores configured and 8 logical cores + available, the combination of the options <c>+S 4:4 +SP 50:25</c> (in either order) + results in 2 scheduler threads (50% of 4) and 1 scheduler thread online (25% of 4). + </p> + <p>This option is ignored if the emulator doesn't have + SMP support enabled (see the <seealso marker="#smp">-smp</seealso> + flag).</p> + </item> + <tag><marker id="+SDcpu"/><c><![CDATA[+SDcpu DirtyCPUSchedulers:DirtyCPUSchedulersOnline]]></c></tag> + <item> + <p>Sets the number of dirty CPU scheduler threads to create and dirty + CPU scheduler threads to set online when threading support has been + enabled. The maximum for both values is 1024, and each value is further + limited by the settings for normal schedulers: the number of dirty CPU + scheduler threads created cannot exceed the number of normal scheduler + threads created, and the number of dirty CPU scheduler threads online + cannot exceed the number of normal scheduler threads online (see the + <seealso marker="#+S">+S</seealso> and <seealso marker="#+SP">+SP</seealso> + flags for more details). By default, the number of dirty CPU scheduler + threads created equals the number of normal scheduler threads created, + and the number of dirty CPU scheduler threads online equals the number + of normal scheduler threads online. <c>DirtyCPUSchedulers</c> may be + omitted if <c>:DirtyCPUSchedulersOnline</c> is not and vice versa. The + number of dirty CPU schedulers online can be changed at run time via + <seealso marker="erlang#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>. + </p> + <p> + The amount of dirty CPU schedulers is limited by the amount of + normal schedulers in order to limit the effect on processes + executing on ordinary schedulers. If the amount of dirty CPU + schedulers was allowed to be unlimited, dirty CPU bound jobs would + potentially starve normal jobs. + </p> + <p>This option is ignored if the emulator doesn't have threading support + enabled. Currently, <em>this option is experimental</em> and is supported only + if the emulator was configured and built with support for dirty schedulers + enabled (it's disabled by default). + </p> + </item> + <tag><marker id="+SDPcpu"/><c><![CDATA[+SDPcpu DirtyCPUSchedulersPercentage:DirtyCPUSchedulersOnlinePercentage]]></c></tag> + <item> + <p>Similar to <seealso marker="#+SDcpu">+SDcpu</seealso> but uses percentages to set the + number of dirty CPU scheduler threads to create and number of dirty CPU scheduler threads + to set online when threading support has been enabled. Specified values must be greater + than 0. For example, <c>+SDPcpu 50:25</c> sets the number of dirty CPU scheduler threads + to 50% of the logical processors configured and the number of dirty CPU scheduler threads + online to 25% of the logical processors available. <c>DirtyCPUSchedulersPercentage</c> may + be omitted if <c>:DirtyCPUSchedulersOnlinePercentage</c> is not and vice versa. The + number of dirty CPU schedulers online can be changed at run time via + <seealso marker="erlang#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>. + </p> + <p>This option interacts with <seealso marker="#+SDcpu">+SDcpu</seealso> settings. + For example, on a system with 8 logical cores configured and 8 logical cores available, + the combination of the options <c>+SDcpu 4:4 +SDPcpu 50:25</c> (in either order) results + in 2 dirty CPU scheduler threads (50% of 4) and 1 dirty CPU scheduler thread online (25% of 4). + </p> + <p>This option is ignored if the emulator doesn't have threading support + enabled. Currently, <em>this option is experimental</em> and is supported only + if the emulator was configured and built with support for dirty schedulers + enabled (it's disabled by default). + </p> + </item> + <tag><marker id="+SDio"/><c><![CDATA[+SDio DirtyIOSchedulers]]></c></tag> + <item> + <p>Sets the number of dirty I/O scheduler threads to create when threading + support has been enabled. The valid range is 0-1024. By default, the number + of dirty I/O scheduler threads created is 10, same as the default number of + threads in the <seealso marker="#async_thread_pool_size">async thread pool + </seealso>. + </p> + <p> + The amount of dirty IO schedulers is not limited by the amount of + normal schedulers <seealso marker="#+SDcpu">like the amount of + dirty CPU schedulers</seealso>. This since only I/O bound work is + expected to execute on dirty I/O schedulers. If the user should schedule CPU + bound jobs on dirty I/O schedulers, these jobs might starve ordinary + jobs executing on ordinary schedulers. + </p> + <p>This option is ignored if the emulator doesn't have threading support + enabled. Currently, <em>this option is experimental</em> and is supported only + if the emulator was configured and built with support for dirty schedulers + enabled (it's disabled by default). + </p> + </item> <tag><c><![CDATA[+sFlag Value]]></c></tag> <item> <p>Scheduling specific flags.</p> <taglist> - <tag><marker id="+sbt"><c>+sbt BindType</c></marker></tag> + <tag><marker id="+sbt"/><c>+sbt BindType</c></tag> <item> <p>Set scheduler bind type.</p> <p>Schedulers can also be bound using the @@ -892,7 +1101,7 @@ <seealso marker="erlang#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>. </p> </item> - <tag><marker id="+sbwt"><c>+sbwt none|very_short|short|medium|long|very_long</c></marker></tag> + <tag><marker id="+sbwt"/><c>+sbwt none|very_short|short|medium|long|very_long</c></tag> <item> <p>Set scheduler busy wait threshold. Default is <c>medium</c>. The threshold determines how long schedulers should busy @@ -902,7 +1111,7 @@ without prior notice. </p> </item> - <tag><marker id="+scl"><c>+scl true|false</c></marker></tag> + <tag><marker id="+scl"/><c>+scl true|false</c></tag> <item> <p>Enable or disable scheduler compaction of load. By default scheduler compaction of load is enabled. When enabled, load @@ -913,9 +1122,13 @@ when schedulers frequently run out of work. When disabled, the frequency with which schedulers run out of work will not be taken into account by the load balancing logic. + <br/> <c>+scl false</c> is similar to + <seealso marker="#+sub">+sub true</seealso> with the difference + that <c>+sub true</c> also will balance scheduler utilization + between schedulers. </p> </item> - <tag><marker id="+sct"><c>+sct CpuTopology</c></marker></tag> + <tag><marker id="+sct"/><c>+sct CpuTopology</c></tag> <item> <list type="bulleted"> <item><c><![CDATA[<Id> = integer(); when 0 =< <Id> =< 65535]]></c></item> @@ -1037,7 +1250,24 @@ <p>For more information, see <seealso marker="erlang#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso>.</p> </item> - <tag><marker id="+sfwi"><c>+sfwi Interval</c></marker></tag> + <tag><marker id="+secio"/><c>+secio true|false</c></tag> + <item> + <p>Enable or disable eager check I/O scheduling. The default + is currently <c>true</c>. The default was changed from <c>false</c> + to <c>true</c> as of erts version 7.0. The behaviour before this + flag was introduced corresponds to <c>+secio false</c>.</p> + <p>The flag effects when schedulers will check for I/O + operations possible to execute, and when such I/O operations + will execute. As the name of the parameter implies, + schedulers will be more eager to check for I/O when + <c>true</c> is passed. This however also implies that + execution of outstanding I/O operation will not be + prioritized to the same extent as when <c>false</c> is + passed.</p> + <p><seealso marker="erlang#system_info_eager_check_io"><c>erlang:system_info(eager_check_io)</c></seealso> + returns the value of this parameter used when starting the VM.</p> + </item> + <tag><marker id="+sfwi"/><c>+sfwi Interval</c></tag> <item> <p>Set scheduler forced wakeup interval. All run queues will be scanned each <c>Interval</c> milliseconds. While there are @@ -1046,12 +1276,12 @@ disables this feature, which also is the default. </p> <p>This feature has been introduced as a temporary workaround - for lengthy executing native code, and native code that do not + for long-executing native code, and native code that does not bump reductions properly in OTP. When these bugs have be fixed the <c>+sfwi</c> flag will be removed. </p> </item> - <tag><marker id="+stbt"><c>+stbt BindType</c></marker></tag> + <tag><marker id="+stbt"/><c>+stbt BindType</c></tag> <item> <p>Try to set scheduler bind type. The same as the <seealso marker="#+sbt">+sbt</seealso> flag with the exception of @@ -1059,7 +1289,30 @@ documentation of the <seealso marker="#+sbt">+sbt</seealso> flag. </p> </item> - <tag><marker id="+swct"><c>+sws very_eager|eager|medium|lazy|very_lazy</c></marker></tag> + <tag><marker id="+sub"/><c>+sub true|false</c></tag> + <item> + <p>Enable or disable + <seealso marker="erts:erlang#statistics_scheduler_wall_time">scheduler + utilization</seealso> balancing of load. By default scheduler + utilization balancing is disabled and instead scheduler + compaction of load is enabled which will strive for a load + distribution which causes as many scheduler threads as possible + to be fully loaded (i.e., not run out of work). When scheduler + utilization balancing is enabled the system will instead try to + balance scheduler utilization between schedulers. That is, + strive for equal scheduler utilization on all schedulers. + <br/> <c>+sub true</c> is only supported on + systems where the runtime system detects and uses a monotonically + increasing high resolution clock. On other systems, the runtime + system will fail to start. + <br/> <c>+sub true</c> implies + <seealso marker="#+scl">+scl false</seealso>. The difference + between <c>+sub true</c> and <c>+scl false</c> is that + <c>+scl false</c> will not try to balance the scheduler + utilization. + </p> + </item> + <tag><marker id="+swct"/><c>+swct very_eager|eager|medium|lazy|very_lazy</c></tag> <item> <p> Set scheduler wake cleanup threshold. Default is <c>medium</c>. @@ -1073,7 +1326,7 @@ <p><em>NOTE:</em> This flag may be removed or changed at any time without prior notice. </p> </item> - <tag><marker id="+sws"><c>+sws default|legacy</c></marker></tag> + <tag><marker id="+sws"/><c>+sws default|legacy</c></tag> <item> <p> Set scheduler wakeup strategy. Default strategy changed in erts-5.10/OTP-R16A. This strategy was previously known as <c>proposal</c> in OTP-R15. The <c>legacy</c> strategy was used as default from R13 up to and including R15. @@ -1081,7 +1334,7 @@ <p><em>NOTE:</em> This flag may be removed or changed at any time without prior notice. </p> </item> - <tag><marker id="+swt"><c>+swt very_low|low|medium|high|very_high</c></marker></tag> + <tag><marker id="+swt"/><c>+swt very_low|low|medium|high|very_high</c></tag> <item> <p>Set scheduler wakeup threshold. Default is <c>medium</c>. The threshold determines when to wake up sleeping schedulers @@ -1095,23 +1348,23 @@ without prior notice. </p> </item> - <tag><marker id="+spp"><c>+spp Bool</c></marker></tag> + <tag><marker id="+spp"/><c>+spp Bool</c></tag> <item> <p>Set default scheduler hint for port parallelism. If set to - <c>true</c>, the VM will schedule port tasks when it by this can - improve the parallelism in the system. If set to <c>false</c>, - the VM will try to perform port tasks immediately and by this - improve latency at the expense of parallelism. If this - flag has not been passed, the default scheduler hint for port - parallelism is currently <c>false</c>. The default used can be - inspected in runtime by calling - <seealso marker="erlang#system_info_port_parallelism">erlang:system_info(port_parallelism)</seealso>. + <c>true</c>, the VM will schedule port tasks when doing so will + improve parallelism in the system. If set to <c>false</c>, the VM + will try to perform port tasks immediately, improving latency at the + expense of parallelism. If this flag has not been passed, the + default scheduler hint for port parallelism is currently + <c>false</c>. The default used can be inspected in runtime by + calling <seealso + marker="erlang#system_info_port_parallelism">erlang:system_info(port_parallelism)</seealso>. The default can be overriden on port creation by passing the <seealso marker="erlang#open_port_parallelism">parallelism</seealso> - option to - <seealso marker="erlang#open_port/2">open_port/2</seealso></p>. + option to <seealso + marker="erlang#open_port/2">open_port/2</seealso></p>. </item> - <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag> + <tag><marker id="sched_thread_stack_size"/><c><![CDATA[+sss size]]></c></tag> <item> <p>Suggested stack size, in kilowords, for scheduler threads. Valid range is 4-8192 kilowords. The default stack size @@ -1119,11 +1372,11 @@ </item> </taglist> </item> - <tag><marker id="+t"><c><![CDATA[+t size]]></c></marker></tag> + <tag><marker id="+t"/><c><![CDATA[+t size]]></c></tag> <item> <p>Set the maximum number of atoms the VM can handle. Default is 1048576.</p> </item> - <tag><marker id="+T"><c><![CDATA[+T Level]]></c></marker></tag> + <tag><marker id="+T"/><c><![CDATA[+T Level]]></c></tag> <item> <p>Enables modified timing and sets the modified timing level. Currently valid range is 0-9. The timing of the runtime system @@ -1161,13 +1414,14 @@ <item> <p>Verbose.</p> </item> - <tag><c><![CDATA[+W w | i]]></c></tag> + <tag><c><![CDATA[+W w | i | e]]></c></tag> <item> <p>Sets the mapping of warning messages for <c><![CDATA[error_logger]]></c>. Messages sent to the error logger using one of the warning - routines can be mapped either to errors (default), warnings - (<c><![CDATA[+W w]]></c>), or info reports (<c><![CDATA[+W i]]></c>). The current - mapping can be retrieved using + routines can be mapped either to errors (<c><![CDATA[+W e]]></c>), + warnings (<c><![CDATA[+W w]]></c>), or info reports + (<c><![CDATA[+W i]]></c>). The default is warnings. + The current mapping can be retrieved using <c><![CDATA[error_logger:warning_map/0]]></c>. See <seealso marker="kernel:error_logger#warning_map/0">error_logger(3)</seealso> for further information.</p> @@ -1176,7 +1430,7 @@ <item> <p>Miscellaneous flags.</p> <taglist> - <tag><marker id="+zdbbl"><c>+zdbbl size</c></marker></tag> + <tag><marker id="+zdbbl"/><c>+zdbbl size</c></tag> <item> <p>Set the distribution buffer busy limit (<seealso marker="erlang#system_info_dist_buf_busy_limit">dist_buf_busy_limit</seealso>) @@ -1189,6 +1443,18 @@ give lower latency and higher throughput at the expense of higher memory usage.</p> </item> + <tag><marker id="+zdntgc"/><c>+zdntgc time</c></tag> + <item> + <p>Set the delayed node table garbage collection time + (<seealso marker="erlang#system_info_delayed_node_table_gc">delayed_node_table_gc</seealso>) + in seconds. Valid values are either <c>infinity</c> or + an integer in the range [0-100000000]. Default is 60.</p> + <p>Node table entries that are not referred will linger + in the table for at least the amount of time that this + parameter determines. The lingering prevents repeated + deletions and insertions in the tables from occurring. + </p> + </item> </taglist> </item> </taglist> @@ -1251,7 +1517,7 @@ </item> </taglist> </item> - <tag><marker id="ERL_AFLAGS"><c><![CDATA[ERL_AFLAGS]]></c></marker></tag> + <tag><marker id="ERL_AFLAGS"/><c><![CDATA[ERL_AFLAGS]]></c></tag> <item> <p>The content of this environment variable will be added to the beginning of the command line for <c><![CDATA[erl]]></c>.</p> @@ -1261,7 +1527,7 @@ the <c><![CDATA[-extra]]></c> section, i.e. the end of the command line following after an <c><![CDATA[-extra]]></c> flag.</p> </item> - <tag><marker id="ERL_ZFLAGS"><c><![CDATA[ERL_ZFLAGS]]></c></marker> and <marker id="ERL_FLAGS"><c><![CDATA[ERL_FLAGS]]></c></marker></tag> + <tag><marker id="ERL_ZFLAGS"/><c><![CDATA[ERL_ZFLAGS]]></c> and <marker id="ERL_FLAGS"/><c><![CDATA[ERL_FLAGS]]></c></tag> <item> <p>The content of these environment variables will be added to the end of the command line for <c><![CDATA[erl]]></c>.</p> diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml index 84f4be208d..25f601a235 100644 --- a/erts/doc/src/erl_dist_protocol.xml +++ b/erts/doc/src/erl_dist_protocol.xml @@ -1,24 +1,25 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> <year>2007</year> - <year>2013</year> + <year>2015</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. The Initial Developer of the Original Code is Ericsson AB. </legalnotice> @@ -363,14 +364,14 @@ If Result > 0, the packet only consists of [119, Result]. NodeInfo is, as expressed in Erlang: </p> <code> - io:format("active name ~ts at port ~p, fd = ~p ~n", + io:format("active name ~ts at port ~p, fd = ~p~n", [NodeName, Port, Fd]). </code> <p> or </p> <code> - io:format("old/unused name ~ts at port ~p, fd = ~p~n", + io:format("old/unused name ~ts at port ~p, fd = ~p ~n", [NodeName, Port, Fd]). </code> @@ -548,10 +549,10 @@ If Result > 0, the packet only consists of [119, Result]. --> </section> - <marker id="distribution_handshake"/> <section> <title>Distribution Handshake</title> <p> + <marker id="distribution_handshake"/> This section describes the distribution handshake protocol introduced in the OTP-R6 release of Erlang/OTP. This description was previously located in @@ -929,11 +930,14 @@ DiB == gen_digest(ChA,ICA) ? <tag><c>SEND</c></tag> <item> <p> - <c>{2, Cookie, ToPid}</c> + <c>{2, Unused, ToPid}</c> </p> <p> <em>Note</em> followed by <c>Message</c> </p> + <p> + <c>Unused</c> is kept for backward compatibility + </p> </item> <tag><c>EXIT</c></tag> @@ -960,11 +964,14 @@ DiB == gen_digest(ChA,ICA) ? <tag><c>REG_SEND</c></tag> <item> <p> - <c>{6, FromPid, Cookie, ToName}</c> + <c>{6, FromPid, Unused, ToName}</c> </p> <p> <em>Note</em> followed by <c>Message</c> </p> + <p> + <c>Unused</c> is kept for backward compatibility + </p> </item> <tag><c>GROUP_LEADER</c></tag> @@ -990,11 +997,14 @@ DiB == gen_digest(ChA,ICA) ? <tag><c>SEND_TT</c></tag> <item> <p> - <c>{12, Cookie, ToPid, TraceToken}</c> + <c>{12, Unused, ToPid, TraceToken}</c> </p> <p> <em>Note</em> followed by <c>Message</c> </p> + <p> + <c>Unused</c> is kept for backward compatibility + </p> </item> <tag><c>EXIT_TT</c></tag> @@ -1007,11 +1017,14 @@ DiB == gen_digest(ChA,ICA) ? <tag><c>REG_SEND_TT</c></tag> <item> <p> - <c>{16, FromPid, Cookie, ToName, TraceToken}</c> + <c>{16, FromPid, Unused, ToName, TraceToken}</c> </p> <p> <em>Note</em> followed by <c>Message</c> </p> + <p> + <c>Unused</c> is kept for backward compatibility + </p> </item> <tag><c>EXIT2_TT</c></tag> diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index efe0483b31..82215ead46 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> <header> <copyright> - <year>2001</year><year>2013</year> + <year>2001</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -222,7 +223,7 @@ asynchronous function calls, using a thread pool provided by Erlang. There is also a select call, that can be used for asynchronous drivers.</item> - <tag><marker id="multi_threading">Multi-threading</marker></tag> + <tag><marker id="multi_threading"/>Multi-threading</tag> <item> <p>A POSIX thread like API for multi-threading is provided. The Erlang driver thread API only provide a subset of the functionality @@ -296,7 +297,7 @@ <item><p>A driver can add and later remove drivers.</p></item> <tag>Monitoring processes</tag> <item><p>A driver can monitor a process that does not own a port.</p></item> - <tag><marker id="version_management">Version management</marker></tag> + <tag><marker id="version_management"/>Version management</tag> <item> <p>Version management is enabled for drivers that have set the <seealso marker="driver_entry#extended_marker">extended_marker</seealso> @@ -315,10 +316,13 @@ <c>ERL_DRV_EXTENDED_MINOR_VERSION</c> will be incremented when new features are added. The runtime system uses the minor version of the driver to determine what features to use. - The runtime system will refuse to load a driver if the major + The runtime system will normally refuse to load a driver if the major versions differ, or if the major versions are equal and the minor version used by the driver is greater than the one used - by the runtime system.</p> + by the runtime system. Old drivers with lower major versions + will however be allowed after a bump of the major version during + a transition period of two major releases. Such old drivers might + however fail if deprecated features are used.</p> <p>The emulator will refuse to load a driver that does not use the extended driver interface, to allow for 64-bit capable drivers, @@ -343,6 +347,16 @@ the driver does not handle sizes that overflow an <c>int</c> all will work as before.</p> </item> + <tag><marker id="time_measurement"/>Time Measurement</tag> + <item><p>Support for time measurement in drivers:</p> + <list> + <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item> + <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item> + <item><seealso marker="#erl_drv_monotonic_time"><c>erl_drv_monotonic_time()</c></seealso></item> + <item><seealso marker="#erl_drv_time_offset"><c>erl_drv_time_offset()</c></seealso></item> + <item><seealso marker="#erl_drv_convert_time_unit"><c>erl_drv_convert_time_unit()</c></seealso></item> + </list> + </item> </taglist> </section> @@ -380,12 +394,12 @@ <item> <p> Rewrite driver callback - <c><seealso marker="driver_entry#control">control</seealso></c> + <seealso marker="driver_entry#control"><c>control</c></seealso> to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>. </p> <p> Rewrite driver callback - <c><seealso marker="driver_entry#call">call</seealso></c> + <seealso marker="driver_entry#call"><c>call</c></seealso> to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>. </p> <note> @@ -403,19 +417,19 @@ <item> <p> Driver callback - <c><seealso marker="driver_entry#output">output</seealso></c> + <seealso marker="driver_entry#output"><c>output</c></seealso> now gets <c>ErlDrvSizeT</c> as 3rd argument instead of previously <c>int</c>. </p> <p> Driver callback - <c><seealso marker="driver_entry#control">control</seealso></c> + <seealso marker="driver_entry#control"><c>control</c></seealso> now gets <c>ErlDrvSizeT</c> as 4th and 6th arguments instead of previously <c>int</c>. </p> <p> Driver callback - <c><seealso marker="driver_entry#call">call</seealso></c> + <seealso marker="driver_entry#call"><c>call</c></seealso> now gets <c>ErlDrvSizeT</c> as 4th and 6th arguments instead of previously <c>int</c>. </p> @@ -543,6 +557,7 @@ typedef struct ErlDrvSysInfo { int scheduler_threads; int nif_major_version; int nif_minor_version; + int dirty_scheduler_support; } ErlDrvSysInfo; </code> @@ -607,6 +622,10 @@ typedef struct ErlDrvSysInfo { <tag><c>nif_minor_version</c></tag> <item>The value of <c>ERL_NIF_MINOR_VERSION</c> when the runtime system was compiled. </item> + <tag><c>dirty_scheduler_support</c></tag> + <item>A value <c>!= 0</c> if the runtime system has support for dirty scheduler threads; + otherwise <c>0</c>. + </item> </taglist> </item> <tag><marker id="ErlDrvBinary"/>ErlDrvBinary</tag> @@ -666,7 +685,7 @@ typedef struct ErlDrvBinary { <item> <p>The <c>ErlDrvData</c> is a handle to driver-specific data, passed to the driver call-backs. It is a pointer, and is - most often type casted to a specific pointer in the driver.</p> + most often type cast to a specific pointer in the driver.</p> </item> <tag>SysIOVec</tag> <item> @@ -745,7 +764,7 @@ typedef struct ErlIOVec { created and decrement it once when the port associated with the lock terminates. The emulator will also increment the reference count when an async job is enqueued and decrement - it after an async job has been invoked, or canceled. Besides + it after an async job has been invoked. Besides this, it is the responsibility of the driver to ensure that the reference count does not reach zero before the last use of the lock by the driver has been made. The reference count @@ -851,6 +870,24 @@ typedef struct ErlIOVec { <seealso marker="#erl_drv_tsd_get">erl_drv_tsd_get()</seealso>. </p> </item> + <tag><marker id="ErlDrvTime"/>ErlDrvTime</tag> + <item> + <p>A signed 64-bit integer type for representation of time.</p> + </item> + <tag><marker id="ErlDrvTimeUnit"/>ErlDrvTimeUnit</tag> + <item> + <p>An enumeration of time units supported by the driver API:</p> + <taglist> + <tag><c>ERL_DRV_SEC</c></tag> + <item><p>Seconds</p></item> + <tag><c>ERL_DRV_MSEC</c></tag> + <item><p>Milliseconds</p></item> + <tag><c>ERL_DRV_USEC</c></tag> + <item><p>Microseconds</p></item> + <tag><c>ERL_DRV_NSEC</c></tag> + <item><p>Nanoseconds</p></item> + </taglist> + </item> </taglist> </section> @@ -1014,7 +1051,12 @@ typedef struct ErlIOVec { <fsummary>Read a system timestamp</fsummary> <desc> <marker id="driver_get_now"></marker> - <p>This function reads a timestamp into the memory pointed to by + <warning><p><em>This function is deprecated! Do not use it!</em> + Use <seealso marker="#erl_drv_monotonic_time"><c>erl_drv_monotonic_time()</c></seealso> + (perhaps in combination with + <seealso marker="#erl_drv_time_offset"><c>erl_drv_time_offset()</c></seealso>) + instead.</p></warning> + <p>This function reads a timestamp into the memory pointed to by the parameter <c>now</c>. See the description of <seealso marker="#ErlDrvNowData">ErlDrvNowData</seealso> for specification of its fields. </p> <p>The return value is 0 unless the <c>now</c> pointer is not @@ -1056,7 +1098,7 @@ typedef struct ErlIOVec { returned. Another thread may still be using the event object internally. To safely close an event object call <c>driver_select</c> with <c>ERL_DRV_USE</c> and <c>on==0</c>. That - will clear all events and then call + will clear all events and then call <seealso marker="driver_entry#stop_select">stop_select</seealso> when it is safe to close the event object. <c>ERL_DRV_USE</c> should be set together with the first event @@ -1068,7 +1110,7 @@ typedef struct ErlIOVec { <p>ERL_DRV_USE was added in OTP release R13. Old drivers will still work as before. But it is recommended to update them to use <c>ERL_DRV_USE</c> and <c>stop_select</c> to make sure that event objects are closed in a safe way.</p> - </note> + </note> <p>The return value is 0 (failure, -1, only if the <c>ready_input</c>/<c>ready_output</c> is <c>NULL</c>).</p> @@ -1524,7 +1566,7 @@ typedef struct ErlIOVec { <marker id="remove_driver_entry"></marker> <p>This function removes a driver entry <c>de</c> previously added with <c>add_driver_entry</c>.</p> - <p>Driver entries added by the <c>erl_ddll</c> erlang interface can + <p>Driver entries added by the <c>erl_ddll</c> erlang interface can not be removed by using this interface.</p> </desc> </func> @@ -1742,15 +1784,19 @@ typedef struct ErlIOVec { term consists of one to four elements in the array. The term first has a term type, and then arguments. The <c>port</c> parameter specifies the sending port.</p> - <p>Tuple and lists (with the exception of strings, see below), + <p>Tuples, maps and lists (with the exception of strings, see below), are built in reverse polish notation, so that to build a tuple, the elements are given first, and then the tuple - term, with a count. Likewise for lists.</p> + term, with a count. Likewise for lists and maps.</p> <p>A tuple must be specified with the number of elements. (The elements precede the <c>ERL_DRV_TUPLE</c> term.)</p> <p>A list must be specified with the number of elements, including the tail, which is the last term preceding <c>ERL_DRV_LIST</c>.</p> + <p>A map must be specified with the number of key-value pairs <c>N</c>. + The key-value pairs must precede the <c>ERL_DRV_MAP</c> in this order: + <c>key1,value1,key2,value2,...,keyN,valueN</c>. + Duplicate keys are not allowed.</p> <p>The special term <c>ERL_DRV_STRING_CONS</c> is used to "splice" in a string in a list, a string given this way is not a list per se, but the elements are elements of the @@ -1758,7 +1804,7 @@ typedef struct ErlIOVec { <pre> Term type Argument(s) =========================================== -ERL_DRV_NIL +ERL_DRV_NIL ERL_DRV_ATOM ErlDrvTermData atom (from driver_mk_atom(char *string)) ERL_DRV_INT ErlDrvSInt integer ERL_DRV_UINT ErlDrvUInt integer @@ -1774,16 +1820,17 @@ ERL_DRV_PID ErlDrvTermData pid (from driver_connected(ErlDrvPort port) ERL_DRV_STRING_CONS char *str, int len ERL_DRV_FLOAT double *dbl ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len +ERL_DRV_MAP int sz </pre> <p>The unsigned integer data type <c>ErlDrvUInt</c> and the signed integer data type <c>ErlDrvSInt</c> are 64 bits wide on a 64 bit runtime system and 32 bits wide on a 32 bit runtime system. They were introduced in erts version 5.6, - and replaced some of the <c>int</c> arguments in the list above. + and replaced some of the <c>int</c> arguments in the list above. </p> <p>The unsigned integer data type <c>ErlDrvUInt64</c> and the signed integer data type <c>ErlDrvSInt64</c> are always 64 bits - wide. They were introduced in erts version 5.7.4. + wide. They were introduced in erts version 5.7.4. </p> <p>To build the tuple <c>{tcp, Port, [100 | Binary]}</c>, the @@ -1856,6 +1903,24 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len }; erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]></code> + + <p>To build the map <c>#{key1 => 100, key2 => {200, 300}}</c>, the + following call could be made.</p> + <code type="none"><![CDATA[ + ErlDrvPort port = ... + ErlDrvTermData spec[] = { + ERL_DRV_ATOM, driver_mk_atom("key1"), + ERL_DRV_INT, 100, + ERL_DRV_ATOM, driver_mk_atom("key2"), + ERL_DRV_INT, 200, + ERL_DRV_INT, 300, + ERL_DRV_TUPLE, 2, + ERL_DRV_MAP, 2 + }; + erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); + ]]> + </code> + <p>If you want to pass a binary and don't already have the content of the binary in an <c>ErlDrvBinary</c>, you can benefit from using <c>ERL_DRV_BUF2BINARY</c> instead of creating an <c>ErlDrvBinary</c> @@ -1879,7 +1944,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <fsummary>Send term data from driver to port owner</fsummary> <desc> <marker id="driver_output_term"></marker> - <warning><p><c>driver_output_term()</c> is deferred and will + <warning><p><c>driver_output_term()</c> is deprecated and will be removed in the OTP-R17 release. Use <seealso marker="#erl_drv_send_term">erl_drv_output_term()</seealso> instead.</p> @@ -1937,7 +2002,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <fsummary>Send term data to other process than port owner process</fsummary> <desc> <marker id="driver_send_term"></marker> - <warning><p><c>driver_send_term()</c> is deferred and will + <warning><p><c>driver_send_term()</c> is deprecated and will be removed in the OTP-R17 release. Use <seealso marker="#erl_drv_send_term">erl_drv_send_term()</seealso> instead.</p> @@ -1981,7 +2046,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len thread, the following call can be used:</p> <p></p> <code type="none"><![CDATA[ - unsigned int myKey = (unsigned int) myPort; + unsigned int myKey = driver_async_port_key(myPort); r = driver_async(myPort, &myKey, myData, myFunc); ]]></code> @@ -1995,14 +2060,13 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <c>async_invoke</c> and <c>async_free</c>. It's typically a pointer to a structure that contains a pipe or event that can be used to signal that the async operation completed. - The data should be freed in <c>async_free</c>, because it's - called if <c>driver_async_cancel</c> is called.</p> + The data should be freed in <c>async_free</c>.</p> <p>When the async operation is done, <seealso marker="driver_entry#ready_async">ready_async</seealso> driver - entry function is called. If <c>async_ready</c> is null in + entry function is called. If <c>ready_async</c> is null in the driver entry, the <c>async_free</c> function is called instead.</p> - <p>The return value is a handle to the asynchronous task, which - can be used as argument to <c>driver_async_cancel</c>.</p> + <p>The return value is -1 if the <c>driver_async</c> call + fails.</p> <note> <p>As of erts version 5.5.4.3 the default stack size for threads in the async-thread pool is 16 kilowords, @@ -2022,23 +2086,21 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len </desc> </func> <func> - <name><ret>int</ret><nametext>driver_async_cancel(long id)</nametext></name> - <fsummary>Cancel an asynchronous call</fsummary> + <name><ret>unsigned int</ret><nametext>driver_async_port_key (ErlDrvPort port)</nametext></name> + <fsummary>Calculate an async key from an ErlDrvPort</fsummary> <desc> - <marker id="driver_async_cancel"></marker> - <p>This function used to cancel a scheduled asynchronous operation, - if it was still in the queue. It returned 1 if it succeeded, and - 0 if it failed.</p> - <p>Since it could not guarantee success, it was more or less useless. - The user had to implement synchronization of cancellation anyway. - It also unnecessarily complicated the implementation. Therefore, - as of OTP-R15B <c>driver_async_cancel()</c> is deprecated, and - scheduled for removal in OTP-R16. It will currently always fail, - and return 0.</p> - <warning><p><c>driver_async_cancel()</c> is deferred and will - be removed in the OTP-R16 release.</p> - </warning> - + <marker id="driver_async_port_key"></marker> + <p>This function calculates a key for later use in <seealso + marker="#driver_async">driver_async()</seealso>. The keys are + evenly distributed so that a fair mapping between port id's + and async thread id's is achieved.</p> + <note> + <p>Before OTP-R16, the actual port id could be used as a key + with proper casting, but after the rewrite of the port + subsystem, this is no longer the case. With this function, you + can achieve the same distribution based on port id's as before + OTP-R16.</p> + </note> </desc> </func> <func> @@ -2048,7 +2110,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <marker id="driver_lock_driver"></marker> <p>This function locks the driver used by the port <c>port</c> in memory for the rest of the emulator process' - lifetime. After this call, the driver behaves as one of Erlang's + lifetime. After this call, the driver behaves as one of Erlang's statically linked in drivers.</p> </desc> </func> @@ -2076,7 +2138,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <seealso marker="driver_entry">driver_entry</seealso>).</item> <tag><c>drv_data</c></tag> <item>The driver defined handle that will be passed in subsequent - calls to driver call-backs. Note, that the + calls to driver call-backs. Note, that the <seealso marker="driver_entry#start">driver start call-back</seealso> will not be called for this new driver instance. The driver defined handle is normally created in the @@ -2102,6 +2164,53 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len </func> <func> + <name><ret>void</ret><nametext>erl_drv_init_ack(ErlDrvPort port, ErlDrvData res)</nametext></name> + <fsummary>Acknowledge the start of the port</fsummary> + <desc> + <marker id="erl_drv_init_ack"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>port</c></tag> + <item>The port handle of the port (driver instance) creating + doing the acknowledgment. + </item> + <tag><c>res</c></tag> + <item>The result of the port initialization. This can be the same values + as the return value of <seealso marker="driver_entry#start">start</seealso>, + i.e any of the error codes or the ErlDrvData that is to be used for this + port. + </item> + </taglist> + <p> + When this function is called the initiating erlang:open_port call is + returned as if the <seealso marker="driver_entry#start">start</seealso> + function had just been called. It can only be used when the + <seealso marker="driver_entry#driver_flags">ERL_DRV_FLAG_USE_INIT_ACK</seealso> + flag has been set on the linked-in driver. + </p> + </desc> + </func> + + <func> + <name><ret>void</ret><nametext>erl_drv_set_os_pid(ErlDrvPort port, ErlDrvSInt pid)</nametext></name> + <fsummary>Set the os_pid for the port</fsummary> + <desc> + <marker id="erl_drv_set_os_pid"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>port</c></tag> + <item>The port handle of the port (driver instance) to set the pid on. + </item> + <tag><c>pid</c></tag> + <item>The pid to set.</item> + </taglist> + <p> + Set the os_pid seen when doing erlang:port_info/2 on this port. + </p> + </desc> + </func> + + <func> <name><ret>int</ret><nametext>erl_drv_thread_create(char *name, ErlDrvTid *tid, void * (*func)(void *), @@ -2284,7 +2393,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <item>A thread identifier.</item> </taglist> <p>This function compares two thread identifiers for equality, - and returns <c>0</c> it they aren't equal, and + and returns <c>0</c> it they aren't equal, and a value not equal to <c>0</c> if they are equal.</p> <note><p>A Thread identifier may be reused very quickly after a thread has terminated. Therefore, if a thread @@ -2469,7 +2578,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len </taglist> <p>This function broadcasts on a condition variable. That is, if other threads are waiting on the condition variable being - broadcasted on, <em>all</em> of them will be woken. + broadcast on, <em>all</em> of them will be woken. </p> <p>This function is thread-safe.</p> </desc> @@ -2498,7 +2607,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len the calling thread when calling this function. </p> <note><p><c>erl_drv_cond_wait()</c> might return even though - no-one has signaled or broadcasted on the condition + no-one has signaled or broadcast on the condition variable. Code calling <c>erl_drv_cond_wait()</c> should always be prepared for <c>erl_drv_cond_wait()</c> returning even though the condition that the thread was @@ -2780,7 +2889,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len </func> <func> - <name><ret>int</ret><nametext>erl_drv_putenv(char *key, char *value)</nametext></name> + <name><ret>int</ret><nametext>erl_drv_putenv(const char *key, char *value)</nametext></name> <fsummary>Set the value of an environment variable</fsummary> <desc> <marker id="erl_drv_putenv"></marker> @@ -2809,7 +2918,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_getenv(char *key, char *value, size_t *value_size)</nametext></name> + <name><ret>int</ret><nametext>erl_drv_getenv(const char *key, char *value, size_t *value_size)</nametext></name> <fsummary>Get the value of an environment variable</fsummary> <desc> <marker id="erl_drv_getenv"></marker> @@ -2822,7 +2931,7 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len <item>A pointer to an output buffer.</item> <tag><c>value_size</c></tag> <item>A pointer to an integer. The integer is both used for - passing input and output sizes (see below). + passing input and output sizes (see below). </item> </taglist> <p>This function retrieves the value of an environment variable. @@ -2889,8 +2998,164 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len beginning of this document.</p> </desc> </func> - </funcs> + <func> + <name><ret>char *</ret><nametext>erl_drv_cond_name(ErlDrvCond *cnd)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> + <desc> + <marker id="erl_drv_cnd_name"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>cnd</c></tag> + <item>A pointer to an initialized condition.</item> + </taglist> + <p> + Returns a pointer to the name of the condition. + </p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + <func> + <name><ret>char *</ret><nametext>erl_drv_mutex_name(ErlDrvMutex *mtx)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> + <desc> + <marker id="erl_drv_mutex_name"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>mtx</c></tag> + <item>A pointer to an initialized mutex.</item> + </taglist> + <p> + Returns a pointer to the name of the mutex. + </p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + <func> + <name><ret>char *</ret><nametext>erl_drv_rwlock_name(ErlDrvRWLock *rwlck)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> + <desc> + <marker id="erl_drv_rwlock_name"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>rwlck</c></tag> + <item>A pointer to an initialized r/w-lock.</item> + </taglist> + <p> + Returns a pointer to the name of the r/w-lock. + </p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + <func> + <name><ret>char *</ret><nametext>erl_drv_thread_name(ErlDrvTid tid)</nametext></name> + <fsummary>Get name of driver mutex.</fsummary> + <desc> + <marker id="erl_drv_rwlock_name"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>tid</c></tag> + <item>A thread identifier.</item> + </taglist> + <p> + Returns a pointer to the name of the thread. + </p> + <note> + <p>This function is intended for debugging purposes only.</p> + </note> + </desc> + </func> + + <func> + <name><ret>ErlDrvTime</ret><nametext>erl_drv_monotonic_time(ErlDrvTimeUnit time_unit)</nametext></name> + <fsummary>Get Erlang Monotonic Time</fsummary> + <desc> + <marker id="erl_drv_monotonic_time"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>time_unit</c></tag> + <item>Time unit of returned value.</item> + </taglist> + <p> + Returns + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso>. Note that it is not uncommon with + negative values. + </p> + <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.</p> + <p>See also:</p> + <list> + <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item> + <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item> + </list> + </desc> + </func> + + <func> + <name><ret>ErlDrvTime</ret><nametext>erl_drv_time_offset(ErlDrvTimeUnit time_unit)</nametext></name> + <fsummary>Get current Time Offset</fsummary> + <desc> + <marker id="erl_drv_time_offset"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>time_unit</c></tag> + <item>Time unit of returned value.</item> + </taglist> + <p>Returns the current time offset between + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang monotonic time</seealso> + and + <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso> + converted into the <c>time_unit</c> passed as argument.</p> + <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.</p> + <p>See also:</p> + <list> + <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item> + <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item> + </list> + </desc> + </func> + + <func> + <name><ret>ErlDrvTime</ret><nametext>erl_drv_convert_time_unit(ErlDrvTime val, ErlDrvTimeUnit from, ErlDrvTimeUnit to)</nametext></name> + <fsummary>Convert time unit of a time value</fsummary> + <desc> + <marker id="erl_drv_convert_time_unit"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>val</c></tag> + <item>Value to convert time unit for.</item> + <tag><c>from</c></tag> + <item>Time unit of <c>val</c>.</item> + <tag><c>to</c></tag> + <item>Time unit of returned value.</item> + </taglist> + <p>Converts the <c>val</c> value of time unit <c>from</c> to + the corresponding value of time unit <c>to</c>. The result is + rounded using the floor function.</p> + <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid + time unit argument.</p> + <p>See also:</p> + <list> + <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item> + <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item> + </list> + </desc> + </func> + + </funcs> <section> <title>SEE ALSO</title> <p><seealso marker="driver_entry">driver_entry(3)</seealso>, @@ -2900,4 +3165,3 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len Guide Ch. 3)</p> </section> </cref> - diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml index c6849f3326..2ac974f497 100644 --- a/erts/doc/src/erl_ext_dist.xml +++ b/erts/doc/src/erl_ext_dist.xml @@ -1,24 +1,25 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> <year>2007</year> - <year>2013</year> + <year>2015</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. The Initial Developer of the Original Code is Ericsson AB. </legalnotice> @@ -126,9 +127,8 @@ However, only characters that can be encoded using Latin1 (ISO-8859-1) are currently supported in atoms. The support for UTF-8 encoded atoms in the external format has been implemented in order to be able to support - all Unicode characters in atoms in <em>some future release</em>. Full - support for Unicode atoms will not happen before OTP-R18, and might - be introduced even later than that. Until full Unicode support for + all Unicode characters in atoms in <em>some future release</em>. + Until full Unicode support for atoms has been introduced, it is an <em>error</em> to pass atoms containing characters that cannot be encoded in Latin1, and <em>the behavior is undefined</em>.</p> @@ -150,10 +150,10 @@ </note> </section> - <marker id="distribution_header"/> <section> <title>Distribution header</title> <p> + <marker id="distribution_header"/> As of erts version 5.7.2 the old atom cache protocol was dropped and a new one was introduced. This atom cache protocol introduced the distribution header. Nodes with erts versions @@ -573,6 +573,33 @@ </section> <section> + <marker id="MAP_EXT"/> + <title>MAP_EXT</title> + + <table align="left"> + <row> + <cell align="center">1</cell> + <cell align="center">4</cell> + <cell align="center">N</cell> + </row> + <row> + <cell align="center">116</cell> + <cell align="center">Arity</cell> + <cell align="center">Pairs</cell> + </row> + <tcaption></tcaption></table> + <p> + <c>MAP_EXT</c> encodes a map. The <c>Arity</c> field is an unsigned + 4 byte integer in big endian format that determines the number of + key-value pairs in the map. Key and value pairs (<c>Ki => Vi</c>) + are encoded in the <c>Pairs</c> section in the following order: + <c>K1, V1, K2, V2,..., Kn, Vn</c>. + Duplicate keys are <em>not allowed</em> within the same map. + </p> + <p><em>Since: </em>OTP 17.0</p> + </section> + + <section> <marker id="NIL_EXT"/> <title>NIL_EXT</title> @@ -1014,10 +1041,10 @@ </row> <tcaption></tcaption></table> <p> - This term represents a bitstring whose length in bits is not a - multiple of 8 (created using the bit syntax in R12B and later). + This term represents a bitstring whose length in bits does + not have to be a multiple of 8. The <c>Len</c> field is an unsigned 4 byte integer (big endian). - The <c>Bits</c> field is the number of bits that are used + The <c>Bits</c> field is the number of bits (1-8) that are used in the last byte in the data field, counting from the most significant bit towards the least significant. diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 864b91946a..f3921f1922 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> <header> <copyright> - <year>2001</year><year>2013</year> + <year>2001</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -66,34 +67,6 @@ </list> </warning> - <p>The NIF concept is officially supported from R14B. NIF source code - written for earlier experimental versions might need adaption to run on R14B - or later versions:</p> - <list> - <item>No incompatible changes between <em>R14B</em> and R14A.</item> - <item>Incompatible changes between <em>R14A</em> and R13B04: - <list> - <item>Environment argument removed for <c>enif_alloc</c>, - <c>enif_realloc</c>, <c>enif_free</c>, <c>enif_alloc_binary</c>, - <c>enif_realloc_binary</c>, <c>enif_release_binary</c>, - <c>enif_alloc_resource</c>, <c>enif_release_resource</c>, - <c>enif_is_identical</c> and <c>enif_compare</c>.</item> - <item>Character encoding argument added to <c>enif_get_atom</c> - and <c>enif_make_existing_atom</c>.</item> - <item>Module argument added to <c>enif_open_resource_type</c> - while changing name spaces of resource types from global to module local.</item> - </list> - </item> - <item>Incompatible changes between <em>R13B04</em> and R13B03: - <list> - <item>The function prototypes of the NIFs have changed to expect <c>argc</c> and <c>argv</c> - arguments. The arity of a NIF is by that no longer limited to 3.</item> - <item><c>enif_get_data</c> renamed as <c>enif_priv_data</c>.</item> - <item><c>enif_make_string</c> got a third argument for character encoding.</item> - </list> - </item> - </list> - <p>A minimal example of a NIF library can look like this:</p> <p/> <code type="none"> @@ -165,23 +138,6 @@ ok automatically unloaded when the module code that it belongs to is purged by the code server.</p> - <p><marker id="lengthy_work"/> - As mentioned in the <seealso marker="#WARNING">warning</seealso> text at - the beginning of this document it is of vital importance that a native function - does return relatively fast. It is hard to give an exact maximum amount - of time that a native function is allowed to work, but as a rule of thumb - a well behaving native function should return to its caller before a - millisecond has passed. This can be achieved using different approaches. - If you have full control over the code that are to execute in the native - function, the best approach is to divide the work into multiple chunks of - work and call the native function multiple times. Function - <seealso marker="#enif_consume_timeslice">enif_consume_timeslice</seealso> can be - used this facilitate such work division. In some cases, however, this might not - be possible, e.g. when calling third party libraries. Then you typically want - to dispatch the work to another thread, return - from the native function, and wait for the result. The thread can send - the result back to the calling thread using message passing. Information - about thread primitives can be found below.</p> </description> <section> <title>FUNCTIONALITY</title> @@ -312,6 +268,220 @@ ok <p>The library initialization callbacks <c>load</c>, <c>reload</c> and <c>upgrade</c> are all thread-safe even for shared state data.</p> </item> + + <tag><marker id="version_management"/>Version Management</tag> + <item><p> + When a NIF library is built, information about NIF API version + is compiled into the library. When a NIF library is loaded the + runtime system verifies that the library is of a compatible version. + <c>erl_nif.h</c> defines <c>ERL_NIF_MAJOR_VERSION</c>, and + <c>ERL_NIF_MINOR_VERSION</c>. <c>ERL_NIF_MAJOR_VERSION</c> will be + incremented when NIF library incompatible changes are made to the + Erlang runtime system. Normally it will suffice to recompile the NIF + library when the <c>ERL_NIF_MAJOR_VERSION</c> has changed, but it + could, under rare circumstances, mean that NIF libraries have to + be slightly modified. If so, this will of course be documented. + <c>ERL_NIF_MINOR_VERSION</c> will be incremented when + new features are added. The runtime system uses the minor version + to determine what features to use. + </p><p> + The runtime system will normally refuse to load a NIF library if + the major versions differ, or if the major versions are equal and + the minor version used by the NIF library is greater than the one + used by the runtime system. Old NIF libraries with lower major + versions will however be allowed after a bump of the major version + during a transition period of two major releases. Such old NIF + libraries might however fail if deprecated features are used. + </p></item> + + <tag><marker id="time_measurement"/>Time Measurement</tag> + <item><p>Support for time measurement in NIF libraries:</p> + <list> + <item><seealso marker="#ErlNifTime"><c>ErlNifTime</c></seealso></item> + <item><seealso marker="#ErlNifTimeUnit"><c>ErlNifTimeUnit</c></seealso></item> + <item><seealso marker="#enif_monotonic_time"><c>enif_monotonic_time()</c></seealso></item> + <item><seealso marker="#enif_time_offset"><c>enif_time_offset()</c></seealso></item> + <item><seealso marker="#enif_convert_time_unit"><c>enif_convert_time_unit()</c></seealso></item> + </list> + </item> + + <tag><marker id="lengthy_work"/>Long-running NIFs</tag> + + <item><p> + As mentioned in the <seealso marker="#WARNING">warning</seealso> text at + the beginning of this document it is of <em>vital importance</em> that a + native function return relatively quickly. It is hard to give an exact + maximum amount of time that a native function is allowed to work, but as a + rule of thumb a well-behaving native function should return to its caller + before a millisecond has passed. This can be achieved using different + approaches. If you have full control over the code to execute in the + native function, the best approach is to divide the work into multiple + chunks of work and call the native function multiple times. In some + cases this might however not always be possible, e.g. when calling + third-party libraries.</p> + + <p>The + <seealso marker="#enif_consume_timeslice">enif_consume_timeslice()</seealso> + function can be used to inform the runtime system about the length of the + NIF call. It should typically always be used unless the NIF executes very + quickly.</p> + + <p>If the NIF call is too lengthy one needs to handle this in one of the + following ways in order to avoid degraded responsiveness, scheduler load + balancing problems, and other strange behaviors:</p> + + <taglist> + <tag>Yielding NIF</tag> + <item> + <p> + If the functionality of a long-running NIF can be split so that + its work can be achieved through a series of shorter NIF calls, + the application can either make that series of NIF calls from the + Erlang level, or it can call a NIF that first performs a chunk of + the work, then invokes the + <seealso marker="#enif_schedule_nif">enif_schedule_nif</seealso> + function to schedule another NIF call to perform the next chunk. + The final call scheduled in this manner can then return the + overall result. Breaking up a long-running function in + this manner enables the VM to regain control between calls to the + NIFs. + </p> + <p> + This approach is always preferred over the other alternatives + described below. This both from a performance perspective and + a system characteristics perspective. + </p> + </item> + + <tag>Threaded NIF</tag> + <item> + <p> + This is accomplished by dispatching the work to another thread + managed by the NIF library, return from the NIF, and wait for the + result. The thread can send the result back to the Erlang + process using <seealso marker="#enif_send">enif_send</seealso>. + Information about thread primitives can be found below. + </p> + </item> + + <tag><marker id="dirty_nifs"/>Dirty NIF</tag> + <item> + + <note> + <p> + <em>The dirty NIF functionality described here + is experimental</em>. Dirty NIF support is available only when + the emulator is configured with dirty schedulers enabled. This + feature is currently disabled by default. The Erlang runtime + without SMP support do not support dirty schedulers even when + the dirty scheduler support has been enabled. To check at + runtime for the presence of dirty scheduler threads, code can + use the + <seealso marker="#enif_system_info"><c>enif_system_info()</c></seealso> + API function. + </p> + </note> + + <p> + A NIF that cannot be split and cannot execute in a millisecond or + less is called a "dirty NIF" because it performs work that the + ordinary schedulers of the Erlang runtime system cannot handle cleanly. + Applications that make use of such functions must indicate to the + runtime that the functions are dirty so they can be handled + specially. This is handled by executing dirty jobs on a separate + set of schedulers called dirty schedulers. A dirty NIF executing + on a dirty scheduler does not have the same duration restriction + as a normal NIF. + </p> + + <p> + It is important to classify the dirty job correct. An I/O bound + job should be classified as such, and a CPU bound job should be + classified as such. If you should classify CPU bound jobs + as I/O bound jobs, dirty I/O schedulers might starve ordinary + schedulers. I/O bound jobs are expected to either block waiting + for I/O, and/or spend a limited amount of time moving data. + </p> + + <p> + To schedule a dirty NIF for execution, the appropriate + <c>flags</c> value can be set for the NIF in its + <seealso marker="#ErlNifFunc"><c>ErlNifFunc</c></seealso> + entry, or the application can call + <seealso marker="#enif_schedule_nif"><c>enif_schedule_nif</c></seealso>, + passing to it a pointer to the dirty NIF to be executed and + indicating with the <c>flags</c> argument whether it expects the + operation to be CPU-bound or I/O-bound. A job that alternates + between I/O bound and CPU bound can be reclassified and + rescheduled using <c>enif_schedule_nif</c> so that it executes on + the correct type of dirty scheduler at all times. For more + information see the documentation of the <c>erl</c> command line + arguments <seealso marker="erl#+SDcpu"><c>+SDcpu</c></seealso>, + and <seealso marker="erl#+SDio"><c>+SDio</c></seealso>. + </p> + + <p> + While a process is executing a dirty NIF some operations that + communicate with it may take a very long time to complete. + Suspend, or garbage collection of a process executing a dirty + NIF cannot be done until the dirty NIF has returned, so other + processes waiting for such operations to complete might have to + wait for a very long time. Blocking multi scheduling, i.e., + calling + <seealso marker="erlang#system_flag_multi_scheduling"><c>erlang:system_flag(multi_scheduling, + block)</c></seealso>, might also take a very long time to + complete. This since all ongoing dirty operations on all + dirty schedulers need to complete before the block + operation can complete. + </p> + + <p> + A lot of operations communicating with a process executing a + dirty NIF can, however, complete while it is executing the + dirty NIF. For example, retrieving information about it via + <c>process_info()</c>, setting its group leader, + register/unregister its name, etc. + </p> + + <p> + Termination of a process executing a dirty NIF can only be + completed up to a certain point while it is executing the + dirty NIF. All Erlang resources such as its registered name, + its ETS tables, etc will be released. All links and monitors + will be triggered. The actual execution of the NIF will + however <em>not</em> be stopped. The NIF can safely continue + execution, allocate heap memory, etc, but it is of course better + to stop executing as soon as possible. The NIF can check + whether current process is alive or not using + <seealso marker="#enif_is_current_process_alive"><c>enif_is_current_process_alive</c></seealso>. + Communication using + <seealso marker="#enif_send"><c>enif_send</c></seealso>, + and <seealso marker="#enif_port_command"><c>enif_port_command</c></seealso> + will also be dropped when the sending process is not alive. + Deallocation of certain internal resources such as process + heap, and process control block will be delayed until the + dirty NIF has completed. + </p> + + <p>Currently known issues that are planned to be fixed:</p> + <list> + <item> + <p> + Since purging of a module currently might need to garbage + collect a process in order to determine if it has + references to the module, a process executing a dirty + NIF might delay purging for a very long time. Delaying + a purge operation implies delaying <em>all</em> code + loading operations which might cause severe problems for + the system as a whole. + </p> + </item> + </list> + + </item> + </taglist> + + </item> </taglist> </section> <section> @@ -330,6 +500,8 @@ ok <c>upgrade</c> will be called to initialize the library. <c>unload</c> is called to release the library. They are all described individually below.</p> + <p>If compiling a nif for static inclusion via --enable-static-nifs you + have to define STATIC_ERLANG_NIF before the ERL_NIF_INIT declaration.</p> </item> <tag><marker id="load"/>int (*load)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)</tag> @@ -367,13 +539,15 @@ ok </item> <tag><marker id="reload"/>int (*reload)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)</tag> - <note><p>The reload mechanism is <em>deprecated</em>. It was only intended - as a development feature. Do not use it as an upgrade method for - live production systems. It might be removed in future releases. Be sure - to pass <c>reload</c> as <c>NULL</c> to <seealso marker="#ERL_NIF_INIT">ERL_NIF_INIT</seealso> - to disable it when not used.</p> - </note> - <item><p><c>reload</c> is called when the NIF library is loaded + + <item> + <note><p>The reload mechanism is <em>deprecated</em>. It was only intended + as a development feature. Do not use it as an upgrade method for + live production systems. It might be removed in future releases. Be sure + to pass <c>reload</c> as <c>NULL</c> to <seealso marker="#ERL_NIF_INIT">ERL_NIF_INIT</seealso> + to disable it when not used.</p> + </note> + <p><c>reload</c> is called when the NIF library is loaded and there is already a previously loaded library for this module code.</p> <p>Works the same as <c>load</c>. The only difference is that @@ -422,8 +596,9 @@ ok independent environment with all its terms is valid until you explicitly invalidates it with <seealso marker="#enif_free_env">enif_free_env</seealso> or <c>enif_send</c>.</p> - <p>All elements of a list/tuple must belong to the same environment as the - list/tuple itself. Terms can be copied between environments with + <p>All contained terms of a list/tuple/map must belong to the same + environment as the list/tuple/map itself. Terms can be copied between + environments with <seealso marker="#enif_make_copy">enif_make_copy</seealso>.</p> </item> <tag><marker id="ErlNifFunc"/>ErlNifFunc</tag> @@ -431,9 +606,10 @@ ok <p/> <code type="none"> typedef struct { - const char* <em>name</em>; - unsigned <em>arity</em>; - ERL_NIF_TERM (*<em>fptr</em>)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); + const char* name; + unsigned arity; + ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); + unsigned flags; } ErlNifFunc; </code> <p>Describes a NIF by its name, arity and implementation. @@ -444,15 +620,29 @@ typedef struct { will thus denote the Nth argument to the NIF. Note that the <c>argc</c> argument allows for the same C function to implement several Erlang functions with different arity (but - same name probably).</p> + same name probably). For a regular NIF, <c>flags</c> is 0 (and + so its value can be omitted for statically initialized <c>ErlNifFunc</c> + instances), or it can be used to indicate that the NIF is a <seealso + marker="#dirty_nifs">dirty NIF</seealso> that should be executed + on a dirty scheduler thread (<em>note that the dirty NIF functionality + described here is experimental</em> and that you have to enable + support for dirty schedulers when building OTP in order to try the + functionality out). If the dirty NIF is expected to be + CPU-bound, its <c>flags</c> field should be set to + <c>ERL_NIF_DIRTY_JOB_CPU_BOUND</c>, or for I/O-bound jobs, + <c>ERL_NIF_DIRTY_JOB_IO_BOUND</c>.</p> + <note><p>If one of the + <c>ERL_NIF_DIRTY_JOB_*_BOUND</c> flags is set, and the runtime + system has no support for dirty schedulers, the runtime system + will refuse to load the NIF library.</p></note> </item> <tag><marker id="ErlNifBinary"/>ErlNifBinary</tag> <item> <p/> <code type="none"> typedef struct { - unsigned <em>size</em>; - unsigned char* <em>data</em>; + unsigned size; + unsigned char* data; } ErlNifBinary; </code> <p><c>ErlNifBinary</c> contains transient information about an @@ -461,6 +651,18 @@ typedef struct { <p>Note that <c>ErlNifBinary</c> is a semi-opaque type and you are only allowed to read fields <c>size</c> and <c>data</c>.</p> </item> + + <tag><marker id="ErlNifBinaryToTerm"/>ErlNifBinaryToTerm</tag> + <item> + <p>An enumeration of the options that can be given to + <seealso marker="#enif_binary_to_term">enif_binary_to_term</seealso>. + For default behavior, use the value <c>0</c>.</p> + <taglist> + <tag><c>ERL_NIF_BIN2TERM_SAFE</c></tag> + <item><p>Use this option when receiving data from untrusted sources.</p></item> + </taglist> + </item> + <tag><marker id="ErlNifPid"/>ErlNifPid</tag> <item> <p><c>ErlNifPid</c> is a process identifier (pid). In contrast to @@ -469,6 +671,14 @@ typedef struct { <seealso marker="#ErlNifEnv">environment</seealso>. <c>ErlNifPid</c> is an opaque type.</p> </item> + <tag><marker id="ErlNifPort"/>ErlNifPort</tag> + <item> + <p><c>ErlNifPort</c> is a port identifier. In contrast to + port id terms (instances of <c>ERL_NIF_TERM</c>), <c>ErlNifPort</c>'s are self + contained and not bound to any + <seealso marker="#ErlNifEnv">environment</seealso>. <c>ErlNifPort</c> + is an opaque type.</p> + </item> <tag><marker id="ErlNifResourceType"/>ErlNifResourceType</tag> <item> @@ -483,8 +693,7 @@ typedef struct { <code type="none"> typedef void ErlNifResourceDtor(ErlNifEnv* env, void* obj); </code> - <p>The function prototype of a resource destructor function. - A destructor function is not allowed to call any term-making functions.</p> + <p>The function prototype of a resource destructor function.</p> </item> <tag><marker id="ErlNifCharEncoding"/>ErlNifCharEncoding</tag> <item> @@ -508,17 +717,51 @@ typedef enum { <item><p>A native signed 64-bit integer type.</p></item> <tag><marker id="ErlNifUInt64"/>ErlNifUInt64</tag> <item><p>A native unsigned 64-bit integer type.</p></item> + + <tag><marker id="ErlNifTime"/>ErlNifTime</tag> + <item> + <p>A signed 64-bit integer type for representation of time.</p> + </item> + <tag><marker id="ErlNifTimeUnit"/>ErlNifTimeUnit</tag> + <item> + <p>An enumeration of time units supported by the NIF API:</p> + <taglist> + <tag><c>ERL_NIF_SEC</c></tag> + <item><p>Seconds</p></item> + <tag><c>ERL_NIF_MSEC</c></tag> + <item><p>Milliseconds</p></item> + <tag><c>ERL_NIF_USEC</c></tag> + <item><p>Microseconds</p></item> + <tag><c>ERL_NIF_NSEC</c></tag> + <item><p>Nanoseconds</p></item> + </taglist> + </item> + + <tag><marker id="ErlNifUniqueInteger"/>ErlNifUniqueInteger</tag> + <item> + <p>An enumeration of the properties that can be requested from + <seealso marker="#enif_make_unique_integer">enif_unique_integer</seealso>. + For default properties, use the value <c>0</c>.</p> + <taglist> + <tag><c>ERL_NIF_UNIQUE_POSITIVE</c></tag> + <item><p>Return only positive integers</p></item> + <tag><c>ERL_NIF_UNIQUE_MONOTONIC</c></tag> + <item><p>Return only + <seealso marker="time_correction#Strictly_Monotonically_Increasing">strictly + monotonically increasing</seealso> integer corresponding to creation time</p></item> + </taglist> + </item> </taglist> </section> <funcs> <func><name><ret>void *</ret><nametext>enif_alloc(size_t size)</nametext></name> - <fsummary>Allocate dynamic memory.</fsummary> + <fsummary>Allocate dynamic memory</fsummary> <desc><p>Allocate memory of <c>size</c> bytes. Return NULL if allocation failed.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_alloc_binary(size_t size, ErlNifBinary* bin)</nametext></name> - <fsummary>Create a new binary.</fsummary> + <fsummary>Create a new binary</fsummary> <desc><p>Allocate a new binary of size <c>size</c> bytes. Initialize the structure pointed to by <c>bin</c> to refer to the allocated binary. The binary must either be released by @@ -545,11 +788,30 @@ typedef enum { <desc><p>Allocate a memory managed resource object of type <c>type</c> and size <c>size</c> bytes.</p></desc> </func> <func><name><ret>void</ret><nametext>enif_clear_env(ErlNifEnv* env)</nametext></name> - <fsummary>Clear an environment for reuse.</fsummary> + <fsummary>Clear an environment for reuse</fsummary> <desc><p>Free all terms in an environment and clear it for reuse. The environment must have been allocated with <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>. </p></desc> </func> + <func><name><ret>size_t</ret><nametext>enif_binary_to_term(ErlNifEnv *env, const unsigned char* data, size_t size, ERL_NIF_TERM *term, ErlNifBinaryToTerm opts)</nametext></name> + <fsummary>Create a term from the external format</fsummary> + <desc> + <p>Create a term that is the result of decoding the binary data + at <c>data</c>, which must be encoded according to the Erlang external term format. + No more than <c>size</c> bytes are read from <c>data</c>. Argument <c>opts</c> + correspond to the second argument to <seealso marker="erlang#binary_to_term-2"> + <c>erlang:binary_to_term/2</c></seealso>, and must be either <c>0</c> or + <c>ERL_NIF_BIN2TERM_SAFE</c>.</p> + <p>On success, store the resulting term at <c>*term</c> and return + the actual number of bytes read. Return zero if decoding fails or if <c>opts</c> + is invalid.</p> + <p>See also: + <seealso marker="#ErlNifBinaryToTerm"><c>ErlNifBinaryToTerm</c></seealso>, + <seealso marker="erlang#binary_to_term-2"><c>erlang:binary_to_term/2</c></seealso> and + <seealso marker="#enif_term_to_binary"><c>enif_term_to_binary</c></seealso>. + </p> + </desc> + </func> <func><name><ret>int</ret><nametext>enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name> <fsummary>Compare two terms</fsummary> <desc><p>Return an integer less than, equal to, or greater than @@ -607,7 +869,48 @@ typedef enum { a number of repeated NIF-calls without the need to create threads. See also the <seealso marker="#WARNING">warning</seealso> text at the beginning of this document.</p> </desc> + + </func> + + <func> + <name><ret>ErlNifTime</ret><nametext>enif_convert_time_unit(ErlNifTime val, ErlNifTimeUnit from, ErlNifTimeUnit to)</nametext></name> + <fsummary>Convert time unit of a time value</fsummary> + <desc> + <marker id="enif_convert_time_unit"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>val</c></tag> + <item>Value to convert time unit for.</item> + <tag><c>from</c></tag> + <item>Time unit of <c>val</c>.</item> + <tag><c>to</c></tag> + <item>Time unit of returned value.</item> + </taglist> + <p>Converts the <c>val</c> value of time unit <c>from</c> to + the corresponding value of time unit <c>to</c>. The result is + rounded using the floor function.</p> + <p>Returns <c>ERL_NIF_TIME_ERROR</c> if called with an invalid + time unit argument.</p> + <p>See also: + <seealso marker="#ErlNifTime"><c>ErlNifTime</c></seealso> and + <seealso marker="#ErlNifTimeUnit"><c>ErlNifTimeUnit</c></seealso>. + </p> + </desc> + </func> + + <func> + <name><ret>ERL_NIF_TERM</ret><nametext>enif_cpu_time(ErlNifEnv *)</nametext></name> + <fsummary></fsummary> + <desc> + <p>Returns the CPU time in the same format as <seealso marker="erlang#timestamp-0">erlang:timestamp()</seealso>. + The CPU time is the time the current logical cpu has spent executing since + some arbitrary point in the past. + If the OS does not support fetching of this value <c>enif_cpu_time</c> + invokes <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>. + </p> + </desc> </func> + <func><name><ret>int</ret><nametext>enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)</nametext></name> <fsummary></fsummary> <desc><p>Same as <seealso marker="erl_driver#erl_drv_equal_tids">erl_drv_equal_tids</seealso>. @@ -633,14 +936,14 @@ typedef enum { <c>size-1</c>.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_atom_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)</nametext></name> - <fsummary>Get the length of atom <c>term</c>.</fsummary> + <fsummary>Get the length of atom <c>term</c></fsummary> <desc><p>Set <c>*len</c> to the length (number of bytes excluding terminating null character) of the atom <c>term</c> with encoding <c>encode</c>. Return true on success or false if <c>term</c> is not an atom.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_double(ErlNifEnv* env, ERL_NIF_TERM term, double* dp)</nametext></name> - <fsummary>Read a floating-point number term.</fsummary> + <fsummary>Read a floating-point number term</fsummary> <desc><p>Set <c>*dp</c> to the floating point value of <c>term</c>. Return true on success or false if <c>term</c> is not a float.</p></desc> </func> @@ -662,6 +965,12 @@ typedef enum { pid variable <c>*pid</c> from it and return true. Otherwise return false. No check if the process is alive is done.</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_get_local_port(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPort* port_id)</nametext></name> + <fsummary>Read an local port term</fsummary> + <desc><p>If <c>term</c> identifies a node local port, initialize the + port variable <c>*port_id</c> from it and return true. Otherwise return false. + No check if the port is alive is done.</p></desc> + </func> <func><name><ret>int</ret><nametext>enif_get_list_cell(ErlNifEnv* env, ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)</nametext></name> <fsummary>Get head and tail from a list</fsummary> <desc><p>Set <c>*head</c> and <c>*tail</c> from @@ -669,17 +978,28 @@ typedef enum { non-empty list.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_list_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len)</nametext></name> - <fsummary>Get the length of list <c>term</c>.</fsummary> + <fsummary>Get the length of list <c>term</c></fsummary> <desc><p>Set <c>*len</c> to the length of list <c>term</c> and return true, - or return false if <c>term</c> is not a list.</p></desc> + or return false if <c>term</c> is not a proper list.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip)</nametext></name> - <fsummary>Read an long integer term.</fsummary> + <fsummary>Read an long integer term</fsummary> <desc><p>Set <c>*ip</c> to the long integer value of <c>term</c> and return true, or return false if <c>term</c> is not an integer or is outside the bounds of type <c>long int</c>.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)</nametext></name> + <func><name><ret>int</ret><nametext>enif_get_map_size(ErlNifEnv* env, ERL_NIF_TERM term, size_t *size)</nametext></name> + <fsummary>Read the size of a map term</fsummary> + <desc><p>Set <c>*size</c> to the number of key-value pairs in the map <c>term</c> and + return true, or return false if <c>term</c> is not a map.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_get_map_value(ErlNifEnv* env, ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value)</nametext></name> + <fsummary>Get the value of a key in a map</fsummary> + <desc><p>Set <c>*value</c> to the value associated with <c>key</c> in the + map <c>map</c> and return true. Return false if <c>map</c> is not a map + or if <c>map</c> does not contain <c>key</c>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)</nametext></name> <fsummary>Get the pointer to a resource object</fsummary> <desc><p>Set <c>*objp</c> to point to the resource object referred to by <c>term</c>.</p> <p>Return true on success or false if <c>term</c> is not a handle to a resource object @@ -688,7 +1008,7 @@ typedef enum { <func><name><ret>int</ret><nametext>enif_get_string(ErlNifEnv* env, ERL_NIF_TERM list, char* buf, unsigned size, ErlNifCharEncoding encode)</nametext></name> - <fsummary>Get a C-string from a list.</fsummary> + <fsummary>Get a C-string from a list</fsummary> <desc><p>Write a null-terminated string, in the buffer pointed to by <c>buf</c> with size <c>size</c>, consisting of the characters in the string <c>list</c>. The characters are written using encoding @@ -701,7 +1021,7 @@ typedef enum { <c>size</c> is less than 1.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM term, int* arity, const ERL_NIF_TERM** array)</nametext></name> - <fsummary>Inspect the elements of a tuple.</fsummary> + <fsummary>Inspect the elements of a tuple</fsummary> <desc><p>If <c>term</c> is a tuple, set <c>*array</c> to point to an array containing the elements of the tuple and set <c>*arity</c> to the number of elements. Note that the array @@ -711,23 +1031,40 @@ typedef enum { tuple.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM term, unsigned int* ip)</nametext></name> - <fsummary>Read an unsigned integer term.</fsummary> + <fsummary>Read an unsigned integer term</fsummary> <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and return true, or return false if <c>term</c> is not an unsigned integer or is outside the bounds of type <c>unsigned int</c>.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip)</nametext></name> - <fsummary>Read an unsigned 64-bit integer term.</fsummary> + <fsummary>Read an unsigned 64-bit integer term</fsummary> <desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and return true, or return false if <c>term</c> is not an unsigned integer or is outside the bounds of an unsigned 64-bit integer.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip)</nametext></name> - <fsummary>Read an unsigned integer term.</fsummary> + <fsummary>Read an unsigned integer term</fsummary> <desc><p>Set <c>*ip</c> to the unsigned long integer value of <c>term</c> and return true, or return false if <c>term</c> is not an unsigned integer or is outside the bounds of type <c>unsigned long</c>.</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_getenv(const char* key, char* value, size_t *value_size)</nametext></name> + <fsummary>Get the value of an environment variable</fsummary> + <desc><p>Same as <seealso marker="erl_driver#erl_drv_getenv">erl_drv_getenv</seealso>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_has_pending_exception(ErlNifEnv* env, ERL_NIF_TERM* reason)</nametext></name> + <fsummary>Check if an exception has been raised</fsummary> + <desc><p>Return true if a pending exception is associated + with the environment <c>env</c>. If <c>reason</c> is a null pointer, ignore it. + Otherwise, if there's a pending exception associated with <c>env</c>, set the ERL_NIF_TERM + to which <c>reason</c> points to the value of the exception's term. For example, if + <seealso marker="#enif_make_badarg">enif_make_badarg</seealso> is called to set a + pending <c>badarg</c> exception, a subsequent call to <c>enif_has_pending_exception(env, &reason)</c> + will set <c>reason</c> to the atom <c>badarg</c>, then return true.</p> + <p>See also: <seealso marker="#enif_make_badarg">enif_make_badarg</seealso> + and <seealso marker="#enif_raise_exception">enif_raise_exception</seealso>.</p> + </desc> + </func> <func><name><ret>int</ret><nametext>enif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin)</nametext></name> <fsummary>Inspect the content of a binary</fsummary> <desc><p>Initialize the structure pointed to by <c>bin</c> with @@ -753,13 +1090,25 @@ typedef enum { <fsummary>Determine if a term is a binary</fsummary> <desc><p>Return true if <c>term</c> is a binary</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_is_current_process_alive(ErlNifEnv* env)</nametext></name> + <fsummary>Determine if currently executing process is alive or not.</fsummary> + <desc><p>Return true if currently executing process is currently alive; otherwise + false.</p> + <p>This function can only be used from a NIF-calling thread, and with an + environment corresponding to currently executing processes.</p></desc> + </func> <func><name><ret>int</ret><nametext>enif_is_empty_list(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> <fsummary>Determine if a term is an empty list</fsummary> <desc><p>Return true if <c>term</c> is an empty list.</p></desc> </func> - <marker id="enif_is_exception"/><func><name><ret>int</ret><nametext>enif_is_exception(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> + <func><name><ret>int</ret><nametext>enif_is_exception(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> <fsummary>Determine if a term is an exception</fsummary> - <desc><p>Return true if <c>term</c> is an exception.</p></desc> + <desc><marker id="enif_is_exception"/> + <p>Return true if <c>term</c> is an exception.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_is_map(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> + <fsummary>Determine if a term is a map</fsummary> + <desc><p>Return true if <c>term</c> is a map, false otherwise.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_is_number(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> <fsummary>Determine if a term is a number (integer or float)</fsummary> @@ -783,6 +1132,18 @@ typedef enum { <fsummary>Determine if a term is a port</fsummary> <desc><p>Return true if <c>term</c> is a port.</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_is_port_alive(ErlNifEnv* env, ErlNifPort *port_id)</nametext></name> + <fsummary>Determine if a local port is alive or not.</fsummary> + <desc><p>Return true if <c>port_id</c> is currently alive.</p> + <p>This function is only thread-safe when the emulator with SMP support is used. + It can only be used in a non-SMP emulator from a NIF-calling thread.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_is_process_alive(ErlNifEnv* env, ErlNifPid *pid)</nametext></name> + <fsummary>Determine if a local process is alive or not.</fsummary> + <desc><p>Return true if <c>pid</c> is currently alive.</p> + <p>This function is only thread-safe when the emulator with SMP support is used. + It can only be used in a non-SMP emulator from a NIF-calling thread.</p></desc> + </func> <func><name><ret>int</ret><nametext>enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name> <fsummary>Determine if a term is a reference</fsummary> <desc><p>Return true if <c>term</c> is a reference.</p></desc> @@ -806,40 +1167,58 @@ typedef enum { <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom(ErlNifEnv* env, const char* name)</nametext></name> <fsummary>Create an atom term</fsummary> <desc><p>Create an atom term from the null-terminated C-string <c>name</c> - with iso-latin-1 encoding.</p></desc> + with iso-latin-1 encoding. If the length of <c>name</c> exceeds the maximum length + allowed for an atom (255 characters), <c>enif_make_atom</c> invokes + <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>. + </p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom_len(ErlNifEnv* env, const char* name, size_t len)</nametext></name> <fsummary>Create an atom term</fsummary> <desc><p>Create an atom term from the string <c>name</c> with length <c>len</c>. - Null-characters are treated as any other characters.</p></desc> + Null-characters are treated as any other characters. If <c>len</c> is greater than the maximum length + allowed for an atom (255 characters), <c>enif_make_atom</c> invokes + <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>. + </p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_badarg(ErlNifEnv* env)</nametext></name> - <fsummary>Make a badarg exception.</fsummary> - <desc><p>Make a badarg exception to be returned from a NIF, and set - an associated exception reason in <c>env</c>. If - <c>enif_make_badarg</c> is called, the term it returns <em>must</em> - be returned from the function that called it. No other return value - is allowed. Also, the term returned from <c>enif_make_badarg</c> may - be passed only to - <seealso marker="#enif_is_exception">enif_is_exception</seealso> and - not to any other NIF API function.</p></desc> + <fsummary>Make a badarg exception</fsummary> + <desc><p>Make a badarg exception to be returned from a NIF, and associate + it with the environment <c>env</c>. Once a NIF or any function + it calls invokes <c>enif_make_badarg</c>, the runtime ensures that a + <c>badarg</c> exception is raised when the NIF returns, even if the NIF + attempts to return a non-exception term instead. + The return value from <c>enif_make_badarg</c> may be used only as the + return value from the NIF that invoked it (directly or indirectly) + or be passed to + <seealso marker="#enif_is_exception">enif_is_exception</seealso>, but + not to any other NIF API function.</p> + <p>See also: <seealso marker="#enif_has_pending_exception">enif_has_pending_exception</seealso> + and <seealso marker="#enif_raise_exception">enif_raise_exception</seealso>. + </p> + <note><p>In earlier versions (older than erts-7.0, OTP 18) the return value + from <c>enif_make_badarg</c> had to be returned from the NIF. This + requirement is now lifted as the return value from the NIF is ignored + if <c>enif_make_badarg</c> has been invoked.</p></note></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name> - <fsummary>Make a binary term.</fsummary> + <fsummary>Make a binary term</fsummary> <desc><p>Make a binary term from <c>bin</c>. Any ownership of the binary data will be transferred to the created term and <c>bin</c> should be considered read-only for the rest of the NIF call and then as released.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_copy(ErlNifEnv* dst_env, ERL_NIF_TERM src_term)</nametext></name> - <fsummary>Make a copy of a term.</fsummary> + <fsummary>Make a copy of a term</fsummary> <desc><p>Make a copy of term <c>src_term</c>. The copy will be created in environment <c>dst_env</c>. The source term may be located in any environment.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_double(ErlNifEnv* env, double d)</nametext></name> <fsummary>Create a floating-point term</fsummary> - <desc><p>Create a floating-point term from a <c>double</c>.</p></desc> + <desc><p>Create a floating-point term from a <c>double</c>. If the <c>double</c> argument is + not finite or is NaN, <c>enif_make_double</c> invokes + <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>. + </p></desc> </func> <func><name><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding encode)</nametext></name> <fsummary>Create an existing atom term</fsummary> @@ -847,7 +1226,9 @@ typedef enum { the null-terminated C-string <c>name</c> with encoding <seealso marker="#ErlNifCharEncoding">encode</seealso>. If the atom already exists store the term in <c>*atom</c> and return true, otherwise - return false.</p></desc> + return false. If the length of <c>name</c> exceeds the maximum length + allowed for an atom (255 characters), <c>enif_make_existing_atom</c> + returns false.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_make_existing_atom_len(ErlNifEnv* env, const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEncoding encoding)</nametext></name> <fsummary>Create an existing atom term</fsummary> @@ -855,7 +1236,9 @@ typedef enum { string <c>name</c> with length <c>len</c> and encoding <seealso marker="#ErlNifCharEncoding">encode</seealso>. Null-characters are treated as any other characters. If the atom already exists store the term - in <c>*atom</c> and return true, otherwise return false.</p></desc> + in <c>*atom</c> and return true, otherwise return false. If <c>len</c> is greater + than the maximum length allowed for an atom (255 characters), + <c>enif_make_existing_atom_len</c> returns false.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_int(ErlNifEnv* env, int i)</nametext></name> <fsummary>Create an integer term</fsummary> @@ -866,7 +1249,7 @@ typedef enum { <desc><p>Create an integer term from a signed 64-bit integer.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list(ErlNifEnv* env, unsigned cnt, ...)</nametext></name> - <fsummary>Create a list term.</fsummary> + <fsummary>Create a list term</fsummary> <desc><p>Create an ordinary list term of length <c>cnt</c>. Expects <c>cnt</c> number of arguments (after <c>cnt</c>) of type ERL_NIF_TERM as the elements of the list. An empty list is returned if <c>cnt</c> is 0.</p></desc> @@ -880,28 +1263,21 @@ typedef enum { <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)</nametext></name> <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)</nametext></name> <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)</nametext></name> - <fsummary>Create a list term.</fsummary> + <fsummary>Create a list term</fsummary> <desc><p>Create an ordinary list term with length indicated by the function name. Prefer these functions (macros) over the variadic <c>enif_make_list</c> to get a compile time error if the number of arguments does not match.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail)</nametext></name> - <fsummary>Create a list cell.</fsummary> + <fsummary>Create a list cell</fsummary> <desc><p>Create a list cell <c>[head | tail]</c>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name> - <fsummary>Create a list term from an array.</fsummary> + <fsummary>Create a list term from an array</fsummary> <desc><p>Create an ordinary list containing the elements of array <c>arr</c> of length <c>cnt</c>. An empty list is returned if <c>cnt</c> is 0.</p></desc> </func> - <func><name><ret>int</ret><nametext>enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM term, ERL_NIF_TERM *list)</nametext></name> - <fsummary>Create the reverse list of the list <c>term</c>.</fsummary> - <desc><p>Set <c>*list</c> to the reverse list of the list <c>term</c> and return true, - or return false if <c>term</c> is not a list. This function should only be used on - short lists as a copy will be created of the list which will not be released until after the - nif returns.</p></desc> - </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_long(ErlNifEnv* env, long int i)</nametext></name> <fsummary>Create an integer term from a long int</fsummary> <desc><p>Create an integer term from a <c>long int</c>.</p></desc> @@ -916,12 +1292,42 @@ typedef enum { reallocated.</p><p>Return a pointer to the raw binary data and set <c>*termp</c> to the binary term.</p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_new_map(ErlNifEnv* env)</nametext></name> + <fsummary>Make an empty map term</fsummary> + <desc><p>Make an empty map term.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_make_map_put(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value, ERL_NIF_TERM* map_out)</nametext></name> + <fsummary>Insert key-value pair in map</fsummary> + <desc><p>Make a copy of map <c>map_in</c> and insert <c>key</c> with + <c>value</c>. If <c>key</c> already exists in <c>map_in</c>, the old + associated value is replaced by <c>value</c>. If successful set + <c>*map_out</c> to the new map and return true. Return false if + <c>map_in</c> is not a map.</p> + <p>The <c>map_in</c> term must belong to the environment <c>env</c>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_make_map_update(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value, ERL_NIF_TERM* map_out)</nametext></name> + <fsummary>Replace value for key in map</fsummary> + <desc><p>Make a copy of map <c>map_in</c> and replace the old associated + value for <c>key</c> with <c>new_value</c>. If successful set + <c>*map_out</c> to the new map and return true. Return false if + <c>map_in</c> is not a map or if it does no contain <c>key</c>.</p> + <p>The <c>map_in</c> term must belong to the environment <c>env</c>.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_make_map_remove(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out)</nametext></name> + <fsummary>Remove key from map</fsummary> + <desc><p>If map <c>map_in</c> contains <c>key</c>, make a copy of + <c>map_in</c> in <c>*map_out</c> and remove <c>key</c> and associated + value. If map <c>map_in</c> does not contain <c>key</c>, set + <c>*map_out</c> to <c>map_in</c>. Return true for success or false if + <c>map_in</c> is not a map.</p> + <p>The <c>map_in</c> term must belong to the environment <c>env</c>.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)</nametext></name> <fsummary>Make a pid term</fsummary> <desc><p>Make a pid term from <c>*pid</c>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ref(ErlNifEnv* env)</nametext></name> - <fsummary>Create a reference.</fsummary> + <fsummary>Create a reference</fsummary> <desc><p>Create a reference like <seealso marker="erlang#make_ref-0">erlang:make_ref/0</seealso>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_resource(ErlNifEnv* env, void* obj)</nametext></name> @@ -959,20 +1365,28 @@ typedef enum { <seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p> </desc> </func> + <func><name><ret>int</ret><nametext>enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in, ERL_NIF_TERM *list_out)</nametext></name> + <fsummary>Create the reverse of a list</fsummary> + <desc><p>Set <c>*list_out</c> to the reverse list of the list <c>list_in</c> and return true, + or return false if <c>list_in</c> is not a list. This function should only be used on + short lists as a copy will be created of the list which will not be released until after the + nif returns.</p> + <p>The <c>list_in</c> term must belong to the environment <c>env</c>.</p></desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding)</nametext></name> - <fsummary>Create a string.</fsummary> + <fsummary>Create a string</fsummary> <desc><p>Create a list containing the characters of the null-terminated string <c>string</c> with encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string_len(ErlNifEnv* env, const char* string, size_t len, ErlNifCharEncoding encoding)</nametext></name> - <fsummary>Create a string.</fsummary> + <fsummary>Create a string</fsummary> <desc><p>Create a list containing the characters of the string <c>string</c> with length <c>len</c> and encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>. Null-characters are treated as any other characters.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_sub_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, size_t pos, size_t size)</nametext></name> - <fsummary>Make a subbinary term.</fsummary> + <fsummary>Make a subbinary term</fsummary> <desc><p>Make a subbinary of binary <c>bin_term</c>, starting at zero-based position <c>pos</c> with a length of <c>size</c> bytes. <c>bin_term</c> must be a binary or bitstring and @@ -980,7 +1394,7 @@ typedef enum { bytes in <c>bin_term</c>.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple(ErlNifEnv* env, unsigned cnt, ...)</nametext></name> - <fsummary>Create a tuple term.</fsummary> + <fsummary>Create a tuple term</fsummary> <desc><p>Create a tuple term of arity <c>cnt</c>. Expects <c>cnt</c> number of arguments (after <c>cnt</c>) of type ERL_NIF_TERM as the elements of the tuple.</p></desc> @@ -994,14 +1408,14 @@ typedef enum { <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)</nametext></name> <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)</nametext></name> <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)</nametext></name> - <fsummary>Create a tuple term.</fsummary> + <fsummary>Create a tuple term</fsummary> <desc><p>Create a tuple term with length indicated by the function name. Prefer these functions (macros) over the variadic <c>enif_make_tuple</c> to get a compile time error if the number of arguments does not match.</p></desc> </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name> - <fsummary>Create a tuple term from an array.</fsummary> + <fsummary>Create a tuple term from an array</fsummary> <desc><p>Create a tuple containing the elements of array <c>arr</c> of length <c>cnt</c>.</p></desc> </func> @@ -1013,10 +1427,120 @@ typedef enum { <fsummary>Create an unsigned integer term</fsummary> <desc><p>Create an integer term from an unsigned 64-bit integer.</p></desc> </func> + <func> + <name><ret>ERL_NIF_TERM</ret><nametext>enif_make_unique_integer(ErlNifEnv *env, ErlNifUniqueInteger properties)</nametext></name> + <fsummary></fsummary> + <desc> + <p>Returns a unique integer with the same properties as given by <seealso marker="erlang#unique_integer-1">erlang:unique_integer/1</seealso>.</p> + <p><c>env</c> is the environment to create the integer in.</p> + <p> + <c>ERL_NIF_UNIQUE_POSITIVE</c> and <c>ERL_NIF_UNIQUE_MONOTONIC</c> can + be passed as the second argument to change the properties of the + integer returned. It is possible to combine them by or:ing the + two values together. + </p> + <p>See also: + <seealso marker="#ErlNifUniqueInteger"><c>ErlNifUniqueInteger</c></seealso>. + </p> + </desc> + </func> <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ulong(ErlNifEnv* env, unsigned long i)</nametext></name> <fsummary>Create an integer term from an unsigned long int</fsummary> <desc><p>Create an integer term from an <c>unsigned long int</c>.</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_create(ErlNifEnv *env, ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEntry entry)</nametext></name> + <fsummary>Create a map iterator</fsummary> + <desc><p>Create an iterator for the map <c>map</c> by initializing the + structure pointed to by <c>iter</c>. The <c>entry</c> argument determines + the start position of the iterator: <c>ERL_NIF_MAP_ITERATOR_FIRST</c> or + <c>ERL_NIF_MAP_ITERATOR_LAST</c>. Return true on success or false if + <c>map</c> is not a map.</p> + <p>A map iterator is only useful during the lifetime of the environment + <c>env</c> that the <c>map</c> belongs to. The iterator must be destroyed by + calling <seealso marker="#enif_map_iterator_destroy"> + enif_map_iterator_destroy</seealso>.</p> + <code type="none"> +ERL_NIF_TERM key, value; +ErlNifMapIterator iter; +enif_map_iterator_create(env, my_map, &iter, ERL_NIF_MAP_ITERATOR_FIRST); + +while (enif_map_iterator_get_pair(env, &iter, &key, &value)) { + do_something(key,value); + enif_map_iterator_next(env, &iter); +} +enif_map_iterator_destroy(env, &iter); + </code> + <note><p>The key-value pairs of a map have no defined iteration + order. The only guarantee is that the iteration order of a single map + instance is preserved during the lifetime of the environment that the map + belongs to.</p> + </note> + </desc> + </func> + <func><name><ret>void</ret><nametext>enif_map_iterator_destroy(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Destroy a map iterator</fsummary> + <desc><p>Destroy a map iterator created by + <seealso marker="#enif_map_iterator_create">enif_map_iterator_create</seealso>. + </p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_get_pair(ErlNifEnv *env, ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM *value)</nametext></name> + <fsummary>Get key and value at current map iterator position</fsummary> + <desc><p>Get key and value terms at current map iterator position. + On success set <c>*key</c> and <c>*value</c> and return true. + Return false if the iterator is positioned at head (before first entry) + or tail (beyond last entry).</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_is_head(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Check if map iterator is positioned before first</fsummary> + <desc><p>Return true if map iterator <c>iter</c> is positioned + before first entry.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_is_tail(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Check if map iterator is positioned after last</fsummary> + <desc><p>Return true if map iterator <c>iter</c> is positioned + after last entry.</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_next(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Increment map iterator to point to next entry</fsummary> + <desc><p>Increment map iterator to point to next key-value entry. + Return true if the iterator is now positioned at a valid key-value entry, + or false if the iterator is positioned at the tail (beyond the last + entry).</p></desc> + </func> + <func><name><ret>int</ret><nametext>enif_map_iterator_prev(ErlNifEnv *env, ErlNifMapIterator *iter)</nametext></name> + <fsummary>Decrement map iterator to point to previous entry</fsummary> + <desc><p>Decrement map iterator to point to previous key-value entry. + Return true if the iterator is now positioned at a valid key-value entry, + or false if the iterator is positioned at the head (before the first + entry).</p></desc> + </func> + + <func> + <name><ret>ErlNifTime</ret><nametext>enif_monotonic_time(ErlNifTimeUnit time_unit)</nametext></name> + <fsummary>Get Erlang Monotonic Time</fsummary> + <desc> + <marker id="enif_monotonic_time"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>time_unit</c></tag> + <item>Time unit of returned value.</item> + </taglist> + <p> + Returns the current + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso>. Note that it is not uncommon with + negative values. + </p> + <p>Returns <c>ERL_NIF_TIME_ERROR</c> if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.</p> + <p>See also: + <seealso marker="#ErlNifTime"><c>ErlNifTime</c></seealso> and + <seealso marker="#ErlNifTimeUnit"><c>ErlNifTimeUnit</c></seealso>. + </p> + </desc> + </func> + <func><name><ret>ErlNifMutex *</ret><nametext>enif_mutex_create(char *name)</nametext></name> <fsummary></fsummary> <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_create">erl_drv_mutex_create</seealso>. @@ -1042,6 +1566,11 @@ typedef enum { <desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_unlock">erl_drv_mutex_unlock</seealso>. </p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_now_time(ErlNifEnv *env)</nametext></name> + <fsummary></fsummary> + <desc><p>Retuns an <seealso marker="erlang#now-0">erlang:now()</seealso> timestamp. + The enif_now_time function is <em>deprecated</em>.</p></desc> + </func> <func><name><ret>ErlNifResourceType *</ret><nametext>enif_open_resource_type(ErlNifEnv* env, const char* module_str, const char* name, ErlNifResourceDtor* dtor, ErlNifResourceFlags flags, ErlNifResourceFlags* tried)</nametext></name> @@ -1071,25 +1600,68 @@ typedef enum { and <seealso marker="#upgrade">upgrade</seealso>.</p> </desc> </func> + <func><name><ret>int</ret><nametext>enif_port_command(ErlNifEnv* env, const ErlNifPort* to_port, ErlNifEnv *msg_env, ERL_NIF_TERM msg)</nametext></name> + <fsummary>Send a port_command to to_port</fsummary> + <desc> + <p>This function works the same as <seealso marker="erlang#port_command-2">erlang:port_command/2</seealso> + except that it is always completely asynchronous.</p> + <taglist> + <tag><c>env</c></tag> + <item>The environment of the calling process. May not be NULL.</item> + <tag><c>*to_port</c></tag> + <item>The port id of the receiving port. The port id should refer to a + port on the local node.</item> + <tag><c>msg_env</c></tag> + <item>The environment of the message term. Can be a process + independent environment allocated with + <seealso marker="#enif_alloc_env">enif_alloc_env</seealso> or NULL.</item> + <tag><c>msg</c></tag> + <item>The message term to send. The same limitations apply as on the + payload to <seealso marker="erlang#port_command-2">erlang:port_command/2</seealso>.</item> + </taglist> + <p>Using a <c>msg_env</c> of NULL is an optimization which groups together + calls to <c>enif_alloc_env</c>, <c>enif_make_copy</c>, <c>enif_port_command</c> + and <c>enif_free_env</c> into one call. This optimization is only usefull + when a majority of the terms are to be copied from <c>env</c> to the <c>msg_env</c>.</p> + <p>This function return true if the command was successfully sent; otherwise, + false. The call may return false if it detects that the command failed for some + reason. For example, <c>*to_port</c> does not refer to a local port, if currently + executing process, i.e. the sender, is not alive, or if <c>msg</c> is invalid.</p> + <p>See also: <seealso marker="#enif_get_local_port"><c>enif_get_local_port</c></seealso>.</p> + </desc> + </func> <func><name><ret>void *</ret><nametext>enif_priv_data(ErlNifEnv* env)</nametext></name> <fsummary>Get the private data of a NIF library</fsummary> <desc><p>Return the pointer to the private data that was set by <c>load</c>, <c>reload</c> or <c>upgrade</c>.</p> <p>Was previously named <c>enif_get_data</c>.</p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_raise_exception(ErlNifEnv* env, ERL_NIF_TERM reason)</nametext></name> + <fsummary>Raise a NIF error exception</fsummary> + <desc><p>Create an error exception with the term <c>reason</c> to be returned from a NIF, + and associate it with the environment <c>env</c>. Once a NIF or any function it calls + invokes <c>enif_raise_exception</c>, the runtime ensures that the exception it creates + is raised when the NIF returns, even if the NIF attempts to return a non-exception + term instead. The return value from <c>enif_raise_exception</c> may be used only as + the return value from the NIF that invoked it (directly or indirectly) or be passed + to <seealso marker="#enif_is_exception">enif_is_exception</seealso>, but + not to any other NIF API function.</p> + <p>See also: <seealso marker="#enif_has_pending_exception">enif_has_pending_exception</seealso> + and <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>.</p></desc> + </func> <func><name><ret>int</ret><nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext></name> - <fsummary>Change the size of a binary.</fsummary> + <fsummary>Change the size of a binary</fsummary> <desc><p>Change the size of a binary <c>bin</c>. The source binary may be read-only, in which case it will be left untouched and a mutable copy is allocated and assigned to <c>*bin</c>. Return true on success, false if memory allocation failed.</p></desc> </func> <func><name><ret>void</ret><nametext>enif_release_binary(ErlNifBinary* bin)</nametext></name> - <fsummary>Release a binary.</fsummary> + <fsummary>Release a binary</fsummary> <desc><p>Release a binary obtained from <c>enif_alloc_binary</c>.</p></desc> </func> <func><name><ret>void</ret><nametext>enif_release_resource(void* obj)</nametext></name> - <fsummary>Release a resource object.</fsummary> + <fsummary>Release a resource object</fsummary> <desc><p>Remove a reference to resource object <c>obj</c>obtained from <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>. The resource object will be destructed when the last reference is removed. @@ -1139,13 +1711,38 @@ typedef enum { <desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock</seealso>. </p></desc> </func> + <func><name><ret>ERL_NIF_TERM</ret><nametext>enif_schedule_nif(ErlNifEnv* env, const char* fun_name, int flags, ERL_NIF_TERM (*fp)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]), int argc, const ERL_NIF_TERM argv[])</nametext></name> + <fsummary>Schedule a NIF for execution</fsummary> + <desc> + <p>Schedule NIF <c>fp</c> to execute. This function allows an application to break up long-running + work into multiple regular NIF calls or to schedule a <seealso marker="#dirty_nifs">dirty NIF</seealso> + to execute on a dirty scheduler thread (<em>note that the dirty NIF functionality described here is + experimental</em> and that you have to enable support for dirty schedulers when building OTP in + order to try the functionality out).</p> + <p>The <c>fun_name</c> argument provides a name for the NIF being scheduled for execution. If it cannot + be converted to an atom, <c>enif_schedule_nif</c> returns a <c>badarg</c> exception.</p> + <p>The <c>flags</c> argument must be set to 0 for a regular NIF, or if the emulator was built the + experimental dirty scheduler support enabled, <c>flags</c> can be set to either <c>ERL_NIF_DIRTY_JOB_CPU_BOUND</c> + if the job is expected to be CPU-bound, or <c>ERL_NIF_DIRTY_JOB_IO_BOUND</c> for jobs that will + be I/O-bound. If dirty scheduler threads are not available in the emulator, a try to schedule such a job + will result in a <c>badarg</c> exception.</p> + + <p>The <c>argc</c> and <c>argv</c> arguments can either be the originals passed into the calling NIF, or + they can be values created by the calling NIF.</p> + <p>The calling NIF must use the return value of <c>enif_schedule_nif</c> as its own return value.</p> + <p>Be aware that <c>enif_schedule_nif</c>, as its name implies, only schedules the + NIF for future execution. The calling NIF does not block waiting for the scheduled NIF to + execute and return, which means that the calling NIF can't expect to receive the scheduled NIF + return value and use it for further operations.</p> + </desc> + </func> <func><name><ret>ErlNifPid *</ret><nametext>enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)</nametext></name> - <fsummary>Get the pid of the calling process.</fsummary> + <fsummary>Get the pid of the calling process</fsummary> <desc><p>Initialize the pid variable <c>*pid</c> to represent the calling process. Return <c>pid</c>.</p></desc> </func> <func><name><ret>int</ret><nametext>enif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)</nametext></name> - <fsummary>Send a message to a process.</fsummary> + <fsummary>Send a message to a process</fsummary> <desc><p>Send a message to a process.</p> <taglist> <tag><c>env</c></tag> @@ -1156,17 +1753,23 @@ typedef enum { <tag><c>msg_env</c></tag> <item>The environment of the message term. Must be a process independent environment allocated with - <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>.</item> + <seealso marker="#enif_alloc_env">enif_alloc_env</seealso> or NULL.</item> <tag><c>msg</c></tag> <item>The message term to send.</item> </taglist> - <p>Return true on success, or false if <c>*to_pid</c> does not refer to an alive local process.</p> + <p>Return true if the message was successfully sent; otherwise, false. The send + operation will fail if <c>*to_pid</c> does not refer to an alive local process, + or if currently executing process, i.e. the sender, is not alive.</p> <p>The message environment <c>msg_env</c> with all its terms (including <c>msg</c>) will be invalidated by a successful call to <c>enif_send</c>. The environment should either be freed with <seealso marker="#enif_free_env">enif_free_env</seealso> of cleared for reuse with <seealso marker="#enif_clear_env">enif_clear_env</seealso>.</p> + <p>If <c>msg_env</c> is set to NULL the <c>msg</c> term is copied and + the original term and its environemt is still valid after the call.</p> <p>This function is only thread-safe when the emulator with SMP support is used. It can only be used in a non-SMP emulator from a NIF-calling thread.</p> + <note><p>Passing <c>msg_env</c> as <c>NULL</c> is only supported since + erts-8.0 (OTP 19).</p></note> </desc> </func> <func><name><ret>unsigned</ret><nametext>enif_sizeof_resource(void* obj)</nametext></name> @@ -1174,12 +1777,33 @@ typedef enum { <desc><p>Get the byte size of a resource object <c>obj</c> obtained by <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.</p></desc> </func> + + <func><name><ret>int</ret><nametext>enif_snprintf(char *str, size_t size, const char *format, ...)</nametext></name> + <fsummary>Format strings and Erlang terms</fsummary> + <desc> + <p>Similar to <c>snprintf</c> but this format string also accepts <c>"%T"</c> which formats Erlang terms. + </p> + </desc> + </func> + <func> <name><ret>void</ret><nametext>enif_system_info(ErlNifSysInfo *sys_info_ptr, size_t size)</nametext></name> <fsummary>Get information about the Erlang runtime system</fsummary> <desc><p>Same as <seealso marker="erl_driver#driver_system_info">driver_system_info</seealso>. </p></desc> </func> + <func><name><ret>int</ret><nametext>enif_term_to_binary(ErlNifEnv *env, ERL_NIF_TERM term, ErlNifBinary *bin)</nametext></name> + <fsummary>Convert a term to the external format</fsummary> + <desc> + <p>Allocates a new binary with <seealso marker="#enif_alloc_binary">enif_alloc_binary</seealso> + and stores the result of encoding <c>term</c> according to the Erlang external term format.</p> + <p>Returns true on success or false if allocation failed.</p> + <p>See also: + <seealso marker="erlang#term_to_binary-1"><c>erlang:term_to_binary/1</c></seealso> and + <seealso marker="#enif_binary_to_term"><c>enif_binary_to_term</c></seealso>. + </p> + </desc> + </func> <func><name><ret>int</ret><nametext>enif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts *opts)</nametext></name> <fsummary></fsummary> <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_create">erl_drv_thread_create</seealso>. @@ -1210,6 +1834,50 @@ typedef enum { <desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_self">erl_drv_thread_self</seealso>. </p></desc> </func> + <func><name><ret>int</ret><nametext>enif_thread_type(void)</nametext></name> + <fsummary>Determine type of current thread</fsummary> + <desc> + <p>Determine the type of currently executing thread. A positive value + indicates a scheduler thread while a negative value or zero indicates + another type of thread. Currently the following specific types exist + (which may be extended in the future):</p> + <taglist> + <tag><c>ERL_NIF_THR_UNDEFINED</c></tag> + <item><p>Undefined thread that is not a scheduler thread.</p></item> + <tag><c>ERL_NIF_THR_NORMAL_SCHEDULER</c></tag> + <item><p>A normal scheduler thread.</p></item> + <tag><c>ERL_NIF_THR_DIRTY_CPU_SCHEDULER</c></tag> + <item><p>A dirty CPU scheduler thread.</p></item> + <tag><c>ERL_NIF_THR_DIRTY_IO_SCHEDULER</c></tag> + <item><p>A dirty I/O scheduler thread.</p></item> + </taglist> + </desc> + </func> + <func> + <name><ret>ErlNifTime</ret><nametext>enif_time_offset(ErlNifTimeUnit time_unit)</nametext></name> + <fsummary>Get current Time Offset</fsummary> + <desc> + <marker id="enif_time_offset"></marker> + <p>Arguments:</p> + <taglist> + <tag><c>time_unit</c></tag> + <item>Time unit of returned value.</item> + </taglist> + <p>Returns the current time offset between + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang monotonic time</seealso> + and + <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso> + converted into the <c>time_unit</c> passed as argument.</p> + <p>Returns <c>ERL_NIF_TIME_ERROR</c> if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.</p> + <p>See also: + <seealso marker="#ErlNifTime"><c>ErlNifTime</c></seealso> and + <seealso marker="#ErlNifTimeUnit"><c>ErlNifTimeUnit</c></seealso>. + </p> + </desc> + </func> + <func><name><ret>int</ret><nametext>enif_tsd_key_create(char *name, ErlNifTSDKey *key)</nametext></name> <fsummary></fsummary> <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_create">erl_drv_tsd_key_create</seealso>. @@ -1236,4 +1904,3 @@ typedef enum { <p><seealso marker="erlang#load_nif-2">erlang:load_nif/2</seealso></p> </section> </cref> - diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml index 9f5b3f385b..d3ece37cc5 100644 --- a/erts/doc/src/erl_prim_loader.xml +++ b/erts/doc/src/erl_prim_loader.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -35,17 +36,11 @@ the system. The start script is also fetched with this low level loader.</p> <p><c>erl_prim_loader</c> knows about the environment and how to - fetch modules. The loader could, for example, fetch files using - the file system (with absolute file names as input), or a - database (where the binary format of a module is stored).</p> + fetch modules.</p> <p>The <c>-loader Loader</c> command line flag can be used to choose the method used by the <c>erl_prim_loader</c>. Two <c>Loader</c> methods are supported by the Erlang runtime system: - <c>efile</c> and <c>inet</c>. If another loader is required, then - it has to be implemented by the user. The <c>Loader</c> provided - by the user must fulfill the protocol defined below, and it is - started with the <c>erl_prim_loader</c> by evaluating - <c>open_port({spawn,Loader},[binary])</c>.</p> + <c>efile</c> and <c>inet</c>.</p> <warning><p>The support for loading of code from archive files is experimental. The sole purpose of releasing it before it is ready @@ -55,39 +50,9 @@ <c>-loader_debug</c> are also experimental</p></warning> </description> - <datatypes> - <datatype> - <name name="host"/> - </datatype> - </datatypes> <funcs> <func> - <name name="start" arity="3"/> - <fsummary>Start the Erlang low level loader</fsummary> - <desc> - <p>Starts the Erlang low level loader. This function is called - by the <c>init</c> process (and module). The <c>init</c> - process reads the command line flags <c>-id <anno>Id</anno></c>, - <c>-loader <anno>Loader</anno></c>, and <c>-hosts <anno>Hosts</anno></c>. These are - the arguments supplied to the <c>start/3</c> function.</p> - <p>If <c>-loader</c> is not given, the default loader is - <c>efile</c> which tells the system to read from the file - system.</p> - <p>If <c>-loader</c> is <c>inet</c>, the <c>-id <anno>Id</anno></c>, - <c>-hosts <anno>Hosts</anno></c>, and <c>-setcookie Cookie</c> flags must - also be supplied. <c><anno>Hosts</anno></c> identifies hosts which this - node can contact in order to load modules. One Erlang - runtime system with a <c>erl_boot_server</c> process must be - started on each of hosts given in <c><anno>Hosts</anno></c> in order to - answer the requests. See <seealso - marker="kernel:erl_boot_server">erl_boot_server(3)</seealso>.</p> - <p>If <c>-loader</c> is something else, the given port program - is started. The port program is supposed to follow - the protocol specified below.</p> - </desc> - </func> - <func> <name name="get_file" arity="1"/> <fsummary>Get a file</fsummary> <desc> @@ -95,8 +60,6 @@ <c><anno>Filename</anno></c> is either an absolute file name or just the name of the file, for example <c>"lists.beam"</c>. If an internal path is set to the loader, this path is used to find the file. - If a user supplied loader is used, the path can be stripped - off if it is obsolete, and the loader does not use a path. <c><anno>FullName</anno></c> is the complete name of the fetched file. <c><anno>Bin</anno></c> is the contents of the file as a binary.</p> @@ -148,6 +111,22 @@ </desc> </func> <func> + <name name="read_link_info" arity="1"/> + <fsummary>Get information about a link or file</fsummary> + <desc> + <p>This function works like + <seealso marker="#read_file_info/1">read_file_info/1</seealso> + except that if <c><anno>Filename</anno></c> is a symbolic link, + information about the link will be returned in the <c>file_info</c> + record and the <c>type</c> field of the record will be set to + <c>symlink</c>.</p> + <p>If <c><anno>Filename</anno></c> is not a symbolic link, this function + returns exactly the same result as <c>read_file_info/1</c>. + On platforms that do not support symbolic links, this function + is always equivalent to <c>read_file_info/1</c>.</p> + </desc> + </func> + <func> <name name="set_path" arity="1"/> <fsummary>Set the path of the loader</fsummary> <desc> @@ -158,22 +137,6 @@ </funcs> <section> - <title>Protocol</title> - <p>The following protocol must be followed if a user provided - loader port program is used. The <c>Loader</c> port program is - started with the command - <c>open_port({spawn,Loader},[binary])</c>. The protocol is as - follows:</p> - <pre> -Function Send Receive -------------------------------------------------------------- -get_file [102 | FileName] [121 | BinaryFile] (on success) - [122] (failure) - -stop eof terminate</pre> - </section> - - <section> <title>Command Line Flags</title> <p>The <c>erl_prim_loader</c> module interprets the following command line flags:</p> @@ -182,10 +145,8 @@ stop eof terminate</pre> <item> <p>Specifies the name of the loader used by <c>erl_prim_loader</c>. <c>Loader</c> can be <c>efile</c> - (use the local file system), or <c>inet</c> (load using - the <c>boot_server</c> on another Erlang node). If - <c>Loader</c> is user defined, the defined <c>Loader</c> port - program is started.</p> + (use the local file system) or <c>inet</c> (load using + the <c>boot_server</c> on another Erlang node).</p> <p>If the <c>-loader</c> flag is omitted, it defaults to <c>efile</c>.</p> </item> @@ -199,17 +160,12 @@ stop eof terminate</pre> <p>Specifies which other Erlang nodes the <c>inet</c> loader can use. This flag is mandatory if the <c>-loader inet</c> flag is present. On each host, there must be on Erlang node - with the <c>erl_boot_server</c> which handles the load - requests. <c>Hosts</c> is a list of IP addresses (hostnames + with the <seealso + marker="kernel:erl_boot_server">erl_boot_server(3)</seealso> + which handles the load requests. + <c>Hosts</c> is a list of IP addresses (hostnames are not acceptable).</p> </item> - <tag><c>-id Id</c></tag> - <item> - <p>Specifies the identity of the Erlang runtime system. If - the system runs as a distributed node, <c>Id</c> must be - identical to the name supplied with the <c>-sname</c> or - <c>-name</c> distribution flags.</p> - </item> <tag><c>-setcookie Cookie</c></tag> <item> <p>Specifies the cookie of the Erlang runtime system. This flag diff --git a/erts/doc/src/erl_tracer.xml b/erts/doc/src/erl_tracer.xml new file mode 100644 index 0000000000..7841fdfd63 --- /dev/null +++ b/erts/doc/src/erl_tracer.xml @@ -0,0 +1,646 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2016</year><year>2016</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>erl_tracer</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>erl_tracer</module> + <modulesummary>Erlang Tracer Behaviour</modulesummary> + <description> + <p>A behaviour module for implementing the back end of the erlang + tracing system. The functions in this module will be called whenever + a trace probe is triggered. Both the <c>enabled</c> and <c>trace</c> + functions are called in the context of the entity that triggered the + trace probe. + This means that the overhead by having the tracing enabled will be + greatly effected by how much time is spent in these functions. So do as + little work as possible in these functions.</p> + <note> + <p>All functions in this behaviour have to be implemented as NIF's. + This is a limitation that may the lifted in the future. + There is an <seealso marker="#example">example tracer module nif</seealso> + implementation at the end of this page.</p> + </note> + <warning> + <p>Do not send messages or issue port commands to the <c>Tracee</c> + in any of the callbacks. Doing so is not allowed and can cause all + sorts of strange behaviour, including but not limited to infinite + recursions.</p> + </warning> + </description> + + <datatypes> + <datatype> <name name="trace_tag_send" /> </datatype> + <datatype> <name name="trace_tag_receive" /> </datatype> + <datatype> <name name="trace_tag_call" /> </datatype> + <datatype> <name name="trace_tag_procs" /> </datatype> + <datatype> <name name="trace_tag_ports" /> </datatype> + <datatype> <name name="trace_tag_running_procs" /> </datatype> + <datatype> <name name="trace_tag_running_ports" /> </datatype> + <datatype> <name name="trace_tag_gc" /> </datatype> + <datatype> + <name name="trace_tag" /> + <desc> + <p>The different trace tags that the tracer will be called with. + Each trace tag is described in greater detail in + <seealso marker="#Module:trace/5">Module:trace/5</seealso> + </p> + </desc> + </datatype> + <datatype> + <name name="tracee" /> + <desc> + <p>The process or port that the trace belongs to. + </p> + </desc> + </datatype> + <datatype> + <name name="trace_opts" /> + <desc> + <p>The options for the tracee.</p> + <taglist> + <tag><c>timestamp</c></tag> + <item>If set the tracer has been requested to include a timestamp.</item> + <tag><c>extra</c></tag> + <item>If set the tracepoint has included additonal data about + the trace event. What the additional data is depends on which + <c>TraceTag</c> has been triggered. The <c>extra</c> trace data + corresponds to the fifth elemnt in the trace tuples described in + <seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>.</item> + <tag><c>match_spec_result</c></tag> + <item>If set the tracer has been requested to include the output + of a match specification that was run.</item> + <tag><c>scheduler_id</c></tag> + <item>Set the scheduler id is to be included by the tracer.</item> + </taglist> + </desc> + </datatype> + <datatype> + <name name="tracer_state" /> + <desc> + <p> + The state which is given when calling + <seealso marker="erlang#trace-3"><c>erlang:trace(PidPortSpec,true,[{tracer,Module,TracerState}])</c></seealso>. + The tracer state is an immutable value that is passed to erl_tracer callbacks and should + contain all the data that is needed to generate the trace event. + </p> + </desc> + </datatype> + </datatypes> + + <section> + <title>CALLBACK FUNCTIONS</title> + <p>The following functions + should be exported from a <c>erl_tracer</c> callback module.</p> + <taglist> + <tag><seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso></tag> + <item>Mandatory</item> + <tag><seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso></tag> + <item>Mandatory</item> + <tag><seealso marker="#Module:enabled_procs/3"><c>Module:enabled_procs/3</c></seealso></tag> + <item>Optional</item> + <tag><seealso marker="#Module:trace_procs/5"><c>Module:trace_procs/5</c></seealso></tag> + <item>Optional</item> + <tag><seealso marker="#Module:enabled_ports/3"><c>Module:enabled_ports/3</c></seealso></tag> + <item>Optional</item> + <tag><seealso marker="#Module:trace_ports/5"><c>Module:trace_ports/5</c></seealso></tag> + <item>Optional</item> + <tag><seealso marker="#Module:enabled_running_ports/3"><c>Module:enabled_running_ports/3</c></seealso></tag> + <item>Optional</item> + <tag><seealso marker="#Module:trace_running_ports/5"><c>Module:trace_running_ports/5</c></seealso></tag> + <item>Optional</item> + <tag><seealso marker="#Module:enabled_running_procs/3"><c>Module:enabled_running_procs/3</c></seealso></tag> + <item>Optional</item> + <tag><seealso marker="#Module:trace_running_procs/5"><c>Module:trace_running_procs/5</c></seealso></tag> + <item>Optional</item> + </taglist> + + </section> + + <funcs> + <func> + <name>Module:enabled(TraceTag, TracerState, Tracee) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso> | trace_status</v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>Result = trace | discard | remove</v> + </type> + <desc> + <p>This callback will be called whenever a tracepoint is triggered. It + allows the tracer to decide whether a trace should be generated or not. + This check is made as early as possible in order to limit the amount of + overhead associated with tracing. If <c>trace</c> is returned the + necessary trace data will be created and the trace call-back of the tracer + will be called. If <c>discard</c> is returned, this trace call + will be discarded and no call to trace will be done. + </p> + <p><c>trace_status</c> is a special type of <c>TraceTag</c> which is used + to check if the tracer should still be active. It is called in multiple + scenarios, but most significantly it is used when tracing is started + using this tracer. If <c>remove</c> is returned when the <c>trace_status</c> + is checked, the tracer will be removed from the tracee.</p> + <p>This function may be called multiple times per tracepoint, so it + is important that it is both fast and side effect free.</p> + </desc> + </func> + <func> + <name>Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>FirstTraceTerm = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>This callback will be called when a tracepoint is triggered and + the <seealso marker="#Module:enabled/3">Module:enabled/3</seealso> + callback returned <c>trace</c>. In it any side effects needed by + the tracer should be done. The tracepoint payload is located in + the <c>TraceTerm</c>. The content of the TraceTerm depends on which + <c>TraceTag</c> has been triggered. + The <c>TraceTerm</c> corresponds to the + fourth element in the trace tuples described in + <seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>. + If the trace tuple has five elements, the fifth element will be sent as + the <c>extra</c> value in the <c>Opts</c> maps.</p> + </desc> + </func> + <func> + <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result</name> + <fsummary>Check if a sequence trace event should be generated.</fsummary> + <type> + <v>TracerState = term()</v> + <v>Label = term()</v> + <v>SeqTraceInfo = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>The <c>TraceTag</c> <c>seq_trace</c> is handled a little bit + differently. There is not <c>Tracee</c> for seq_trace, instead the + <c>Label</c> associated with the seq_trace event is given. + For more info on what <c>Label</c> and <c>SeqTraceInfo</c> can be + see the <seealso marker="kernel:seq_trace">seq_trace</seealso> manual.</p> + </desc> + </func> + + <func> + <name>Module:enabled_procs(TraceTag, TracerState, Tracee) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_procs">trace_tag_procs()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>Result = trace | discard | remove</v> + </type> + <desc> + <p>This callback will be called whenever a tracepoint with trace flag + <seealso marker="erlang#trace-3"><c>procs</c></seealso> + is triggered.</p> + <p>If <c>enabled_procs/3</c> is not defined <c>enabled/3</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_procs">trace_tag()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>FirstTraceTerm = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>This callback will be called when a tracepoint is triggered and + the <seealso marker="#Module:enabled_procs/3">Module:enabled_procs/3</seealso> + callback returned <c>trace</c>.</p> + <p>If <c>trace_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:enabled_ports(TraceTag, TracerState, Tracee) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_ports">trace_tag_ports()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>Result = trace | discard | remove</v> + </type> + <desc> + <p>This callback will be called whenever a tracepoint with trace flag + <seealso marker="erlang#trace-3"><c>ports</c></seealso> + is triggered.</p> + <p>If <c>enabled_ports/3</c> is not defined <c>enabled/3</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_ports">trace_tag()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>FirstTraceTerm = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>This callback will be called when a tracepoint is triggered and + the <seealso marker="#Module:enabled_ports/3">Module:enabled_ports/3</seealso> + callback returned <c>trace</c>.</p> + <p>If <c>trace_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:enabled_running_procs(TraceTag, TracerState, Tracee) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_running_procs">trace_tag_running_procs()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>Result = trace | discard | remove</v> + </type> + <desc> + <p>This callback will be called whenever a tracepoint with trace flag + <seealso marker="erlang#trace-3"><c>running_procs | running</c></seealso> + is triggered.</p> + <p>If <c>enabled_running_procs/3</c> is not defined <c>enabled/3</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_running_procs">trace_tag_running_procs()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>FirstTraceTerm = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>This callback will be called when a tracepoint is triggered and + the <seealso marker="#Module:enabled_running_procs/3">Module:enabled_running_procs/3</seealso> + callback returned <c>trace</c>.</p> + <p>If <c>trace_running_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:enabled_running_ports(TraceTag, TracerState, Tracee) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_running_ports">trace_tag_running_ports()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>Result = trace | discard | remove</v> + </type> + <desc> + <p>This callback will be called whenever a tracepoint with trace flag + <seealso marker="erlang#trace-3"><c>running_ports</c></seealso> + is triggered.</p> + <p>If <c>enabled_running_ports/3</c> is not defined <c>enabled/3</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_running_ports">trace_tag_running_ports()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>FirstTraceTerm = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>This callback will be called when a tracepoint is triggered and + the <seealso marker="#Module:enabled_running_ports/3">Module:enabled_running_ports/3</seealso> + callback returned <c>trace</c>.</p> + <p>If <c>trace_running_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:enabled_call(TraceTag, TracerState, Tracee) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_call">trace_tag_call()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>Result = trace | discard | remove</v> + </type> + <desc> + <p>This callback will be called whenever a tracepoint with trace flag + <seealso marker="erlang#trace-3"><c>call | return_to</c></seealso> + is triggered.</p> + <p>If <c>enabled_call/3</c> is not defined <c>enabled/3</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_call">trace_tag_call()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>FirstTraceTerm = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>This callback will be called when a tracepoint is triggered and + the <seealso marker="#Module:enabled_call/3">Module:enabled_call/3</seealso> + callback returned <c>trace</c>.</p> + <p>If <c>trace_call/5</c> is not defined <c>trace/5</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:enabled_send(TraceTag, TracerState, Tracee) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_send">trace_tag_send()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>Result = trace | discard | remove</v> + </type> + <desc> + <p>This callback will be called whenever a tracepoint with trace flag + <seealso marker="erlang#trace-3"><c>send</c></seealso> + is triggered.</p> + <p>If <c>enabled_send/3</c> is not defined <c>enabled/3</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_send">trace_tag_send()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>FirstTraceTerm = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>This callback will be called when a tracepoint is triggered and + the <seealso marker="#Module:enabled_send/3">Module:enabled_send/3</seealso> + callback returned <c>trace</c>.</p> + <p>If <c>trace_send/5</c> is not defined <c>trace/5</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:enabled_receive(TraceTag, TracerState, Tracee) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_receive">trace_tag_receive()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>Result = trace | discard | remove</v> + </type> + <desc> + <p>This callback will be called whenever a tracepoint with trace flag + <seealso marker="erlang#trace-3"><c>'receive'</c></seealso> + is triggered.</p> + <p>If <c>enabled_receive/3</c> is not defined <c>enabled/3</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:trace_receive(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_receive">trace_tag_receive()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>FirstTraceTerm = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>This callback will be called when a tracepoint is triggered and + the <seealso marker="#Module:enabled_receive/3">Module:enabled_receive/3</seealso> + callback returned <c>trace</c>.</p> + <p>If <c>trace_receive/5</c> is not defined <c>trace/5</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:enabled_garbage_collection(TraceTag, TracerState, Tracee) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_gc">trace_tag_gc()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>Result = trace | discard | remove</v> + </type> + <desc> + <p>This callback will be called whenever a tracepoint with trace flag + <seealso marker="erlang#trace-3"><c>garbage_collection</c></seealso> + is triggered.</p> + <p>If <c>enabled_garbage_collection/3</c> is not defined <c>enabled/3</c> will be called instead.</p> + </desc> + </func> + + <func> + <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name> + <fsummary>Check if a trace event should be generated.</fsummary> + <type> + <v>TraceTag = <seealso marker="#type-trace_tag_gc">trace_tag_gc()</seealso></v> + <v>TracerState = term()</v> + <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v> + <v>FirstTraceTerm = term()</v> + <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v> + <v>Result = ok</v> + </type> + <desc> + <p>This callback will be called when a tracepoint is triggered and + the <seealso marker="#Module:enabled_garbage_collection/3">Module:enabled_garbage_collection/3</seealso> + callback returned <c>trace</c>.</p> + <p>If <c>trace_garbage_collection/5</c> is not defined <c>trace/5</c> will be called instead.</p> + </desc> + </func> + + </funcs> + <section> + <marker id="example"></marker> + <title>Erl Tracer Module example</title> + <p>In the example below a tracer module with a nif backend sends a message + for each <c>send</c> trace tag containing only the sender and receiver. + Using this tracer module, a much more lightweight message tracer is + used that only records who sent messages to who.</p> + <p>Here is an example session using it on Linux.</p> + <pre> +$ gcc -I erts-8.0/include/ -fPIC -shared -o erl_msg_tracer.so erl_msg_tracer.c +$ erl +Erlang/OTP 19 [DEVELOPMENT] [erts-8.0] [source-ed2b56b] [64-bit] [smp:8:8] [async-threads:10] [hipe] [kernel-poll:false] + +Eshell V8.0 (abort with ^G) +1> c(erl_msg_tracer), erl_msg_tracer:load(). +ok +2> Tracer = spawn(fun F() -> receive M -> io:format("~p~n",[M]), F() end end). +<0.37.0> +3> erlang:trace(new, true, [send,{tracer, erl_msg_tracer, Tracer}]). +0 +{<0.39.0>,<0.27.0>} +4> {ok, D} = file:open("/tmp/tmp.data",[write]). +{trace,#Port<0.486>,<0.40.0>} +{trace,<0.40.0>,<0.21.0>} +{trace,#Port<0.487>,<0.4.0>} +{trace,#Port<0.488>,<0.4.0>} +{trace,#Port<0.489>,<0.4.0>} +{trace,#Port<0.490>,<0.4.0>} +{ok,<0.40.0>} +{trace,<0.41.0>,<0.27.0>} +5> + </pre> + <p>erl_msg_tracer.erl</p> + <pre> +-module(erl_msg_tracer). + +-export([enabled/3, trace/5, load/0]). + +load() -> + erlang:load_nif("erl_msg_tracer", []). + +enabled(_, _, _) -> + error. + +trace(_, _, _,_, _) -> + error. + </pre> + <p>erl_msg_tracer.c</p> + <pre> +#include "erl_nif.h" + +/* NIF interface declarations */ +static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info); +static int upgrade(ErlNifEnv* env, void** priv_data, void** old_priv_data, ERL_NIF_TERM load_info); +static void unload(ErlNifEnv* env, void* priv_data); + +/* The NIFs: */ +static ERL_NIF_TERM enabled(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); +static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); + +static ErlNifFunc nif_funcs[] = { + {"enabled", 3, enabled}, + {"trace", 5, trace} +}; + +ERL_NIF_INIT(erl_msg_tracer, nif_funcs, load, NULL, upgrade, unload) + +static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info) +{ + *priv_data = NULL; + return 0; +} + +static void unload(ErlNifEnv* env, void* priv_data) +{ + +} + +static int upgrade(ErlNifEnv* env, void** priv_data, void** old_priv_data, + ERL_NIF_TERM load_info) +{ + if (*old_priv_data != NULL || *priv_data != NULL) { + return -1; /* Don't know how to do that */ + } + if (load(env, priv_data, load_info)) { + return -1; + } + return 0; +} + +/* + * argv[0]: TraceTag + * argv[1]: TracerState + * argv[2]: Tracee + */ +static ERL_NIF_TERM enabled(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) +{ + ErlNifPid to_pid; + if (enif_get_local_pid(env, argv[1], &to_pid)) + if (!enif_is_process_alive(env, &to_pid)) + if (enif_is_identical(enif_make_atom(env, "trace_status"), argv[0])) + /* tracer is dead so we should remove this tracepoint */ + return enif_make_atom(env, "remove"); + else + return enif_make_atom(env, "discard"); + + /* Only generate trace for when tracer != tracee */ + if (enif_is_identical(argv[1], argv[2])) + return enif_make_atom(env, "discard"); + + /* Only trigger trace messages on 'send' */ + if (enif_is_identical(enif_make_atom(env, "send"), argv[0])) + return enif_make_atom(env, "trace"); + + /* Have to answer trace_status */ + if (enif_is_identical(enif_make_atom(env, "trace_status"), argv[0])) + return enif_make_atom(env, "trace"); + + return enif_make_atom(env, "discard"); +} + +/* + * argv[0]: TraceTag, should only be 'send' + * argv[1]: TracerState, process to send {argv[2], argv[4]} to + * argv[2]: Tracee + * argv[3]: Recipient + * argv[4]: Options, ignored + */ +static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) +{ + ErlNifPid to_pid; + + if (enif_get_local_pid(env, argv[1], &to_pid)) { + ERL_NIF_TERM msg = enif_make_tuple3(env, enif_make_atom(env, "trace"), argv[2], argv[4]); + enif_send(env, &to_pid, NULL, msg); + } + + return enif_make_atom(env, "ok"); +} + </pre> + </section> +</erlref> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 767edc1cc0..6289f033b2 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -29,36 +30,123 @@ <file>erlang.xml</file> </header> <module>erlang</module> - <modulesummary>The Erlang BIFs</modulesummary> + <modulesummary>The Erlang BIFs.</modulesummary> <description> - <p>By convention, most built-in functions (BIFs) are seen as being - in the module <c>erlang</c>. A number of the BIFs are viewed more + <p>By convention, most Built-In Functions (BIFs) are seen as being + in this module. Some of the BIFs are viewed more or less as part of the Erlang programming language and are - <em>auto-imported</em>. Thus, it is not necessary to specify - the module name and both the calls <c>atom_to_list(Erlang)</c> and - <c>erlang:atom_to_list(Erlang)</c> are identical.</p> - <p>In the text, auto-imported BIFs are listed without module prefix. + <em>auto-imported</em>. Thus, it is not necessary to specify the + module name. For example, the calls <c>atom_to_list(Erlang)</c> + and <c>erlang:atom_to_list(Erlang)</c> are identical.</p> + <p>Auto-imported BIFs are listed without module prefix. BIFs listed with module prefix are not auto-imported.</p> - <p>BIFs may fail for a variety of reasons. All BIFs fail with + <p>BIFs can fail for various reasons. All BIFs fail with reason <c>badarg</c> if they are called with arguments of an - incorrect type. The other reasons that may make BIFs fail are - described in connection with the description of each individual - BIF.</p> - <p>Some BIFs may be used in guard tests, these are marked with + incorrect type. The other reasons are described in the + description of each individual BIF.</p> + <p>Some BIFs can be used in guard tests and are marked with "Allowed in guard tests".</p> </description> <datatypes> <datatype> - <name><marker id="type-ext_binary">ext_binary()</marker></name> + <name>ext_binary()</name> <desc> <p>A binary data object, structured according to the Erlang external term format.</p> </desc> </datatype> + + <datatype> + <name name="message_queue_data"></name> + <desc><p>See <seealso marker="#process_flag_message_queue_data"><c>erlang:process_flag(message_queue_data, MQD)</c></seealso>.</p> + </desc> + </datatype> + <datatype> <name name="timestamp"></name> - <desc><p>See <seealso marker="#now/0">now/0</seealso>.</p> + <desc><p>See <seealso marker="#timestamp/0">erlang:timestamp/0</seealso>.</p> + </desc> + </datatype> + <datatype> + <name name="time_unit"></name> + <desc><p><marker id="type_time_unit"/> + Supported time unit representations:</p> + <taglist> + <tag><c>PartsPerSecond :: integer() >= 1</c></tag> + <item><p>Time unit expressed in parts per second. That is, + the time unit equals <c>1/PartsPerSecond</c> second.</p></item> + + <tag><c>seconds</c></tag> + <item><p>Symbolic representation of the time unit + represented by the integer <c>1</c>.</p></item> + + <tag><c>milli_seconds</c></tag> + <item><p>Symbolic representation of the time unit + represented by the integer <c>1000</c>.</p></item> + + <tag><c>micro_seconds</c></tag> + <item><p>Symbolic representation of the time unit + represented by the integer <c>1000000</c>.</p></item> + + <tag><c>nano_seconds</c></tag> + <item><p>Symbolic representation of the time unit + represented by the integer <c>1000000000</c>.</p></item> + + <tag><c>native</c></tag> + <item><p>Symbolic representation of the native time unit + used by the Erlang runtime system.</p> + + <p>The <c>native</c> time unit is determined at + runtime system start, and remains the same until + the runtime system terminates. If a runtime system + is stopped and then started again (even on the same + machine), the <c>native</c> time unit of the new + runtime system instance can differ from the + <c>native</c> time unit of the old runtime system + instance.</p> + + <p>One can get an approximation of the <c>native</c> + time unit by calling <c>erlang:convert_time_unit(1, + seconds, native)</c>. The result equals the number + of whole <c>native</c> time units per second. In case + the number of <c>native</c> time units per second does + not add up to a whole number, the result is rounded downwards.</p> + + <note> + <p>The value of the <c>native</c> time unit gives + you more or less no information at all about the + quality of time values. It sets a limit for + the + <seealso marker="time_correction#Time_Resolution">resolution</seealso> + as well as for the + <seealso marker="time_correction#Time_Precision">precision</seealso> + of time values, + but it gives absolutely no information at all about the + <seealso marker="time_correction#Time_Accuracy">accuracy</seealso> + of time values. The resolution of the <c>native</c> time + unit and the resolution of time values can differ + significantly.</p> + </note> + </item> + + <tag><c>perf_counter</c></tag> + <item><p>Symbolic representation of the performance counter + time unit used by the Erlang runtime system.</p> + + <p>The <c>perf_counter</c> time unit behaves much in the same way + as the <c>native</c> time unit. That is it might differ inbetween + run-time restarts. You get values of this type by calling + <seealso marker="kernel:os#perf_counter/0"><c>os:perf_counter()</c></seealso> + </p> + </item> + + </taglist> + + <p>The <c>time_unit/0</c> type may be extended. Use + <seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit/3</c></seealso> + in order to convert time values between time units.</p> + </desc> </datatype> </datatypes> @@ -67,12 +155,15 @@ <func> <name name="abs" arity="1" clause_i="1"/> <name name="abs" arity="1" clause_i="2"/> - <type variable="Float" name_i="1"/> - <type variable="Int" name_i="2"/> - <fsummary>Arithmetical absolute value</fsummary> - <desc> - <p>Returns an integer or float which is the arithmetical - absolute value of <c><anno>Float</anno></c> or <c><anno>Int</anno></c>.</p> + <fsummary>Arithmetical absolute value.</fsummary> + <type> + <v>Float = float()</v> + <v>Int = integer()</v> + </type> + <desc> + <p>Returns an integer or float that is the arithmetical + absolute value of <c><anno>Float</anno></c> or + <c><anno>Int</anno></c>, for example:</p> <pre> > <input>abs(-3.33).</input> 3.33 @@ -81,206 +172,214 @@ <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="adler32" arity="1"/> - <fsummary>Compute adler32 checksum</fsummary> + <fsummary>Computes adler32 checksum.</fsummary> <desc> - <p>Computes and returns the adler32 checksum for <c><anno>Data</anno></c>.</p> + <p>Computes and returns the adler32 checksum for + <c><anno>Data</anno></c>.</p> </desc> </func> + <func> <name name="adler32" arity="2"/> - <fsummary>Compute adler32 checksum</fsummary> + <fsummary>Computes adler32 checksum.</fsummary> <desc> - <p>Continue computing the adler32 checksum by combining - the previous checksum, <c><anno>OldAdler</anno></c>, with the checksum of - <c><anno>Data</anno></c>.</p> - <p>The following code:</p> - <code> - X = erlang:adler32(Data1), - Y = erlang:adler32(X,Data2). - </code> - <p>- would assign the same value to <c>Y</c> as this would:</p> - <code> - Y = erlang:adler32([Data1,Data2]). - </code> + <p>Continues computing the adler32 checksum by combining + the previous checksum, <c><anno>OldAdler</anno></c>, with + the checksum of <c><anno>Data</anno></c>.</p> + <p>The following code:</p> + <code> + X = erlang:adler32(Data1), + Y = erlang:adler32(X,Data2).</code> + <p>assigns the same value to <c>Y</c> as this:</p> + <code> + Y = erlang:adler32([Data1,Data2]).</code> </desc> </func> + <func> <name name="adler32_combine" arity="3"/> - <fsummary>Combine two adler32 checksums</fsummary> - <desc> - <p>Combines two previously computed adler32 checksums. - This computation requires the size of the data object for - the second checksum to be known.</p> - <p>The following code:</p> - <code> - Y = erlang:adler32(Data1), - Z = erlang:adler32(Y,Data2). - </code> - <p>- would assign the same value to <c>Z</c> as this would:</p> - <code> - X = erlang:adler32(Data1), - Y = erlang:adler32(Data2), - Z = erlang:adler32_combine(X,Y,iolist_size(Data2)). - </code> + <fsummary>Combines two adler32 checksums.</fsummary> + <desc> + <p>Combines two previously computed adler32 checksums. + This computation requires the size of the data object for + the second checksum to be known.</p> + <p>The following code:</p> + <code> + Y = erlang:adler32(Data1), + Z = erlang:adler32(Y,Data2).</code> + <p>assigns the same value to <c>Z</c> as this:</p> + <code> + X = erlang:adler32(Data1), + Y = erlang:adler32(Data2), + Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code> </desc> </func> + <func> <name name="append_element" arity="2"/> - <fsummary>Append an extra element to a tuple</fsummary> - <desc> - <p>Returns a new tuple which has one element more than - <c><anno>Tuple1</anno></c>, and contains the elements in <c><anno>Tuple1</anno></c> - followed by <c><anno>Term</anno></c> as the last element. Semantically - equivalent to - <c>list_to_tuple(tuple_to_list(<anno>Tuple1</anno>) ++ [<anno>Term</anno>])</c>, but much - faster.</p> + <fsummary>Appends an extra element to a tuple.</fsummary> + <desc> + <p>Returns a new tuple that has one element more than + <c><anno>Tuple1</anno></c>, and contains the elements in + <c><anno>Tuple1</anno></c> + followed by <c><anno>Term</anno></c> as the last element. + Semantically equivalent to + <c>list_to_tuple(tuple_to_list(<anno>Tuple1</anno>) ++ + [<anno>Term</anno>])</c>, but much faster.</p> + <p>Example:</p> <pre> > <input>erlang:append_element({one, two}, three).</input> {one,two,three}</pre> </desc> </func> + <func> <name name="apply" arity="2"/> - <fsummary>Apply a function to an argument list</fsummary> + <fsummary>Applies a function to an argument list.</fsummary> <desc> - <p>Call a fun, passing the elements in <c><anno>Args</anno></c> as - arguments.</p> - <p>Note: If the number of elements in the arguments are known at - compile-time, the call is better written as + <p>Calls a fun, passing the elements in <c><anno>Args</anno></c> + as arguments.</p> + <p>If the number of elements in the arguments are known at + compile time, the call is better written as <c><anno>Fun</anno>(Arg1, Arg2, ... ArgN)</c>.</p> <warning> <p>Earlier, <c><anno>Fun</anno></c> could also be given as <c>{Module, Function}</c>, equivalent to - <c>apply(Module, Function, Args)</c>. This usage is - deprecated and will stop working in a future release of - Erlang/OTP.</p> + <c>apply(Module, Function, Args)</c>. This use is + deprecated and will stop working in a future release.</p> </warning> </desc> </func> + <func> <name name="apply" arity="3"/> - <fsummary>Apply a function to an argument list</fsummary> + <fsummary>Applies a function to an argument list.</fsummary> <desc> <p>Returns the result of applying <c>Function</c> in - <c><anno>Module</anno></c> to <c><anno>Args</anno></c>. The applied function must + <c><anno>Module</anno></c> to <c><anno>Args</anno></c>. + The applied function must be exported from <c>Module</c>. The arity of the function is the length of <c>Args</c>.</p> + <p>Example:</p> <pre> > <input>apply(lists, reverse, [[a, b, c]]).</input> -[c,b,a]</pre> - <p><c>apply</c> can be used to evaluate BIFs by using - the module name <c>erlang</c>.</p> - <pre> +[c,b,a] > <input>apply(erlang, atom_to_list, ['Erlang']).</input> "Erlang"</pre> - <p>Note: If the number of arguments are known at compile-time, + <p>If the number of arguments are known at compile time, the call is better written as <c><anno>Module</anno>:<anno>Function</anno>(Arg1, Arg2, ..., ArgN)</c>.</p> <p>Failure: <c>error_handler:undefined_function/3</c> is called if the applied function is not exported. The error handler can be redefined (see <seealso marker="#process_flag/2">process_flag/2</seealso>). - If the <c>error_handler</c> is undefined, or if the user has + If <c>error_handler</c> is undefined, or if the user has redefined the default <c>error_handler</c> so the replacement module is undefined, an error with the reason <c>undef</c> is generated.</p> </desc> </func> + <func> <name name="atom_to_binary" arity="2"/> - <fsummary>Return the binary representation of an atom</fsummary> - <desc> - <p>Returns a binary which corresponds to the text - representation of <c><anno>Atom</anno></c>. If <c><anno>Encoding</anno></c> - is <c>latin1</c>, there will be one byte for each character - in the text representation. If <c><anno>Encoding</anno></c> is - <c>utf8</c> or - <c>unicode</c>, the characters will be encoded using UTF-8 - (meaning that characters from 16#80 up to 0xFF will be - encoded in two bytes).</p> - - <note><p>Currently, <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> can - never fail because the text representation of an atom can only contain - characters from 0 to 16#FF. In a future release, the text representation - of atoms might be allowed to contain any Unicode character - and <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> will fail if the - text representation for the <c><anno>Atom</anno></c> contains a Unicode - character greater than 16#FF.</p></note> - + <fsummary>Returns the binary representation of an atom.</fsummary> + <desc> + <p>Returns a binary corresponding to the text + representation of <c><anno>Atom</anno></c>. + If <c><anno>Encoding</anno></c> + is <c>latin1</c>, there is one byte for each character + in the text representation. If <c><anno>Encoding</anno></c> is + <c>utf8</c> or + <c>unicode</c>, the characters are encoded using UTF-8 + (that is, characters from 128 through 255 are + encoded in two bytes).</p> + <note><p><c>atom_to_binary(<anno>Atom</anno>, latin1)</c> never + fails because the text representation of an atom can only + contain characters from 0 through 255. In a future release, + the text representation + of atoms can be allowed to contain any Unicode character and + <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> will then fail if the + text representation for <c><anno>Atom</anno></c> contains a Unicode + character greater than 255.</p></note> + <p>Example:</p> <pre> > <input>atom_to_binary('Erlang', latin1).</input> <<"Erlang">></pre> </desc> </func> + <func> <name name="atom_to_list" arity="1"/> - <fsummary>Text representation of an atom</fsummary> + <fsummary>Text representation of an atom.</fsummary> <desc> - <p>Returns a string which corresponds to the text - representation of <c><anno>Atom</anno></c>.</p> + <p>Returns a string corresponding to the text + representation of <c><anno>Atom</anno></c>, for example:</p> <pre> > <input>atom_to_list('Erlang').</input> "Erlang"</pre> </desc> </func> + <func> <name name="binary_part" arity="2"/> - <fsummary>Extracts a part of a binary</fsummary> + <fsummary>Extracts a part of a binary.</fsummary> <desc> - <p>Extracts the part of the binary described by <c><anno>PosLen</anno></c>.</p> - - <p>Negative length can be used to extract bytes at the end of a binary:</p> - + <p>Extracts the part of the binary described by + <c><anno>PosLen</anno></c>.</p> + <p>Negative length can be used to extract bytes at the end + of a binary, for example:</p> <code> 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>. -2> binary_part(Bin,{byte_size(Bin), -5)). -<<6,7,8,9,10>> -</code> - - <p>If <c><anno>PosLen</anno></c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> - - <p><c><anno>Start</anno></c> is zero-based, i.e.:</p> +2> binary_part(Bin,{byte_size(Bin), -5}). +<<6,7,8,9,10>></code> + <p>Failure: <c>badarg</c> if <c><anno>PosLen</anno></c> in any way + references outside the binary.</p> + <p><c><anno>Start</anno></c> is zero-based, that is:</p> <code> 1> Bin = <<1,2,3>> 2> binary_part(Bin,{0,2}). -<<1,2>> -</code> - - <p>See the STDLIB module <c>binary</c> for details about the <c><anno>PosLen</anno></c> semantics.</p> - +<<1,2>></code> + <p>For details about the <c><anno>PosLen</anno></c> semantics, see the + <seealso marker="stdlib:binary">binary</seealso> + manual page in <c>STDLIB</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="binary_part" arity="3"/> - <fsummary>Extracts a part of a binary</fsummary> + <fsummary>Extracts a part of a binary.</fsummary> <desc> - <p>The same as <c>binary_part(<anno>Subject</anno>, {<anno>Start</anno>, <anno>Length</anno>})</c>.</p> - + <p>The same as <c>binary_part(<anno>Subject</anno>, + {<anno>Start</anno>, <anno>Length</anno>})</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="binary_to_atom" arity="2"/> - <fsummary>Convert from text representation to an atom</fsummary> + <fsummary>Converts from text representation to an atom.</fsummary> <desc> <p>Returns the atom whose text representation is - <c><anno>Binary</anno></c>. If <c><anno>Encoding</anno></c> is <c>latin1</c>, no - translation of bytes in the binary is done. If <c><anno>Encoding</anno></c> - is <c>utf8</c> or <c>unicode</c>, the binary must contain - valid UTF-8 sequences; furthermore, only Unicode characters up - to 0xFF are allowed.</p> - - <note><p><c>binary_to_atom(<anno>Binary</anno>, utf8)</c> will fail if - the binary contains Unicode characters greater than 16#FF. - In a future release, such Unicode characters might be allowed - and <c>binary_to_atom(<anno>Binary</anno>, utf8)</c> - will not fail in that case. For more information on Unicode support in atoms - see <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8 encoded atoms</seealso> - in the chapter about the external term format in the ERTS User's Guide.</p></note> - + <c><anno>Binary</anno></c>. + If <c><anno>Encoding</anno></c> is <c>latin1</c>, no + translation of bytes in the binary is done. + If <c><anno>Encoding</anno></c> + is <c>utf8</c> or <c>unicode</c>, the binary must contain + valid UTF-8 sequences. Only Unicode characters up + to 255 are allowed.</p> + <note><p><c>binary_to_atom(<anno>Binary</anno>, utf8)</c> fails if + the binary contains Unicode characters greater than 255. + In a future release, such Unicode characters can be allowed + and <c>binary_to_atom(<anno>Binary</anno>, utf8)</c> does then not fail. + For more information on Unicode support in atoms, see the + <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8 + encoded atoms</seealso> + in Section "External Term Format" in the User's Guide.</p></note> + <p>Examples:</p> <pre> > <input>binary_to_atom(<<"Erlang">>, latin1).</input> 'Erlang' @@ -290,20 +389,24 @@ called as binary_to_atom(<<208,128>>,utf8)</pre> </desc> </func> + <func> <name name="binary_to_existing_atom" arity="2"/> - <fsummary>Convert from text representation to an atom</fsummary> + <fsummary>Converts from text representation to an atom.</fsummary> <desc> - <p>Works like <seealso marker="#binary_to_atom/2">binary_to_atom/2</seealso>, - but the atom must already exist.</p> - <p>Failure: <c>badarg</c> if the atom does not already exist.</p> + <p>As + <seealso marker="#binary_to_atom/2">binary_to_atom/2</seealso>, + but the atom must exist.</p> + <p>Failure: <c>badarg</c> if the atom does not exist.</p> </desc> </func> + <func> <name name="binary_to_float" arity="1"/> - <fsummary>Convert from text representation to a float</fsummary> + <fsummary>Converts from text representation to a float.</fsummary> <desc> - <p>Returns the float whose text representation is <c><anno>Binary</anno></c>.</p> + <p>Returns the float whose text representation is + <c><anno>Binary</anno></c>, for example:</p> <pre> > <input>binary_to_float(<<"2.2017764e+0">>).</input> 2.2017764</pre> @@ -311,12 +414,13 @@ representation of a float.</p> </desc> </func> + <func> <name name="binary_to_integer" arity="1"/> - <fsummary>Convert from text representation to an integer</fsummary> + <fsummary>Converts from text representation to an integer.</fsummary> <desc> <p>Returns an integer whose text representation is - <c><anno>Binary</anno></c>.</p> + <c><anno>Binary</anno></c>, for example:</p> <pre> > <input>binary_to_integer(<<"123">>).</input> 123</pre> @@ -324,12 +428,13 @@ representation of an integer.</p> </desc> </func> + <func> <name name="binary_to_integer" arity="2"/> - <fsummary>Convert from text representation to an integer</fsummary> + <fsummary>Converts from text representation to an integer.</fsummary> <desc> <p>Returns an integer whose text representation in base - <c><anno>Base</anno></c> is <c><anno>Binary</anno></c>.</p> + <c><anno>Base</anno></c> is <c><anno>Binary</anno></c>, for example:</p> <pre> > <input>binary_to_integer(<<"3FF">>, 16).</input> 1023</pre> @@ -337,93 +442,101 @@ representation of an integer.</p> </desc> </func> + <func> <name name="binary_to_list" arity="1"/> - <fsummary>Convert a binary to a list</fsummary> + <fsummary>Converts a binary to a list.</fsummary> <desc> - <p>Returns a list of integers which correspond to the bytes of + <p>Returns a list of integers corresponding to the bytes of <c><anno>Binary</anno></c>.</p> </desc> </func> + <func> <name name="binary_to_list" arity="3"/> - <fsummary>Convert part of a binary to a list</fsummary> - <type_desc variable="Start">1..byte_size(<anno>Binary</anno>)</type_desc> + <fsummary>Converts part of a binary to a list.</fsummary> + <type_desc variable="Start">1..byte_size(<c><anno>Binary</anno></c>)</type_desc> <desc> <p>As <c>binary_to_list/1</c>, but returns a list of integers corresponding to the bytes from position <c><anno>Start</anno></c> to - position <c><anno>Stop</anno></c> in <c><anno>Binary</anno></c>. Positions in the + position <c><anno>Stop</anno></c> in <c><anno>Binary</anno></c>. + The positions in the binary are numbered starting from 1.</p> - - <note><p>This function's indexing style of using one-based indices for - binaries is deprecated. New code should use the functions in - the STDLIB module <c>binary</c> instead. They consequently - use the same (zero-based) style of indexing.</p></note> + <note><p>The one-based indexing for binaries used by + this function is deprecated. New code is to use + <seealso marker="stdlib:binary#bin_to_list/3">binary:bin_to_list/3</seealso> + in <c>STDLIB</c> instead. All functions in module + <c>binary</c> consistently use zero-based indexing.</p></note> </desc> </func> + <func> <name name="bitstring_to_list" arity="1"/> - <fsummary>Convert a bitstring to a list</fsummary> + <fsummary>Converts a bitstring to a list.</fsummary> <desc> - <p>Returns a list of integers which correspond to the bytes of - <c><anno>Bitstring</anno></c>. If the number of bits in the binary is not - divisible by 8, the last element of the list will be a bitstring - containing the remaining bits (1 up to 7 bits).</p> + <p>Returns a list of integers corresponding to the bytes of + <c><anno>Bitstring</anno></c>. If the number of bits in the binary + is not divisible by 8, the last element of the list is a bitstring + containing the remaining 1-7 bits.</p> </desc> </func> + <func> <name name="binary_to_term" arity="1"/> - <fsummary>Decode an Erlang external term format binary</fsummary> + <fsummary>Decodes an Erlang external term format binary.</fsummary> <desc> - <p>Returns an Erlang term which is the result of decoding - the binary object <c><anno>Binary</anno></c>, which must be encoded + <p>Returns an Erlang term that is the result of decoding + binary object <c><anno>Binary</anno></c>, which must be encoded according to the Erlang external term format.</p> - <warning> - <p>When decoding binaries from untrusted sources, consider using - <c>binary_to_term/2</c> to prevent denial of service attacks.</p> - </warning> - <p>See also - <seealso marker="#term_to_binary/1">term_to_binary/1</seealso> - and - <seealso marker="#binary_to_term/2">binary_to_term/2</seealso>.</p> + <warning><p>When decoding binaries from untrusted sources, + consider using <c>binary_to_term/2</c> to prevent Denial + of Service attacks.</p></warning> + <p>See also + <seealso marker="#term_to_binary/1">term_to_binary/1</seealso> + and + <seealso marker="#binary_to_term/2">binary_to_term/2</seealso>.</p> </desc> </func> + <func> <name name="binary_to_term" arity="2"/> - <fsummary>Decode an Erlang external term format binary</fsummary> + <fsummary>Decodes an Erlang external term format binary.</fsummary> <desc> <p>As <c>binary_to_term/1</c>, but takes options that affect decoding of the binary.</p> <taglist> <tag><c>safe</c></tag> <item> - <p>Use this option when receiving binaries from an untrusted + <p>Use this option when receiving binaries from an untrusted source.</p> - <p>When enabled, it prevents decoding data that may be used to - attack the Erlang system. In the event of receiving unsafe - data, decoding fails with a badarg error.</p> - <p>Currently, this prevents creation of new atoms directly, - creation of new atoms indirectly (as they are embedded in - certain structures like pids, refs, funs, etc.), and creation of - new external function references. None of those resources are - currently garbage collected, so unchecked creation of them can - exhaust available memory.</p> + <p>When enabled, it prevents decoding data that can be used to + attack the Erlang system. In the event of receiving unsafe + data, decoding fails with a <c>badarg</c> error.</p> + <p>This prevents creation of new atoms directly, + creation of new atoms indirectly (as they are embedded in + certain structures, such as process identifiers, + refs, and funs), and + creation of new external function references. + None of those resources are garbage collected, so unchecked + creation of them can exhaust available memory.</p> </item> </taglist> - <p>Failure: <c>badarg</c> if <c>safe</c> is specified and unsafe data - is decoded.</p> + <p>Failure: <c>badarg</c> if <c>safe</c> is specified and unsafe + data is decoded.</p> <p>See also <seealso marker="#term_to_binary/1">term_to_binary/1</seealso>, <seealso marker="#binary_to_term/1">binary_to_term/1</seealso>, - and <seealso marker="#list_to_existing_atom/1"> - list_to_existing_atom/1</seealso>.</p> + and + <seealso marker="#list_to_existing_atom/1">list_to_existing_atom/1</seealso>.</p> </desc> </func> + <func> <name name="bit_size" arity="1"/> - <fsummary>Return the size of a bitstring</fsummary> + <fsummary>Returns the size of a bitstring.</fsummary> <desc> - <p>Returns an integer which is the size in bits of <c><anno>Bitstring</anno></c>.</p> + <p>Returns an integer that is the size in bits of + <c><anno>Bitstring</anno></c>, for example:</p> <pre> > <input>bit_size(<<433:16,3:3>>).</input> 19 @@ -432,30 +545,34 @@ <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="bump_reductions" arity="1"/> - <fsummary>Increment the reduction counter</fsummary> + <fsummary>Increments the reduction counter.</fsummary> <desc> <p>This implementation-dependent function increments the reduction counter for the calling process. In the Beam emulator, the reduction counter is normally incremented by - one for each function and BIF call, and a context switch is - forced when the counter reaches the maximum number of reductions - for a process (2000 reductions in R12B).</p> + one for each function and BIF call. A context switch is + forced when the counter reaches the maximum number of + reductions for a process (2000 reductions in OTP R12B).</p> <warning> - <p>This BIF might be removed in a future version of the Beam + <p>This BIF can be removed in a future version of the Beam machine without prior warning. It is unlikely to be implemented in other Erlang implementations.</p> </warning> </desc> </func> + <func> <name name="byte_size" arity="1"/> - <fsummary>Return the size of a bitstring (or binary)</fsummary> + <fsummary>Returns the size of a bitstring (or binary).</fsummary> <desc> - <p>Returns an integer which is the number of bytes needed to contain - <c><anno>Bitstring</anno></c>. (That is, if the number of bits in <c><anno>Bitstring</anno></c> is not - divisible by 8, the resulting number of bytes will be rounded <em>up</em>.)</p> + <p>Returns an integer that is the number of bytes needed to + contain <c><anno>Bitstring</anno></c>. That is, if the number of bits + in <c><anno>Bitstring</anno></c> is not divisible by 8, the resulting + number of bytes is rounded <em>up</em>.</p> + <p>Examples:</p> <pre> > <input>byte_size(<<433:16,3:3>>).</input> 3 @@ -464,151 +581,319 @@ <p>Allowed in guard tests.</p> </desc> </func> + <func> - <name name="cancel_timer" arity="1"/> - <fsummary>Cancel a timer</fsummary> - <desc> - <p>Cancels a timer, where <c><anno>TimerRef</anno></c> was returned by - either - <seealso marker="#send_after/3">erlang:send_after/3</seealso> - or - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>. - If the timer is there to be removed, the function returns - the time in milliseconds left until the timer would have expired, - otherwise <c>false</c> (which means that <c><anno>TimerRef</anno></c> was - never a timer, that it has already been cancelled, or that it - has already delivered its message).</p> + <name name="cancel_timer" arity="2"/> + <fsummary>Cancels a timer.</fsummary> + <desc> + <p> + Cancels a timer that has been created by + <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>, + or <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>. + <c><anno>TimerRef</anno></c> identifies the timer, and + was returned by the BIF that created the timer. + </p> + <p>Available <c><anno>Option</anno></c>s:</p> + <taglist> + <tag><c>{async, Async}</c></tag> + <item> + <p> + Asynchronous request for cancellation. <c>Async</c> + defaults to <c>false</c> which will cause the + cancellation to be performed synchronously. When + <c>Async</c> is set to <c>true</c>, the cancel + operation is performed asynchronously. That is, + <c>erlang:cancel_timer()</c> will send an asynchronous + request for cancellation to the timer service that + manages the timer, and then return <c>ok</c>. + </p> + </item> + <tag><c>{info, Info}</c></tag> + <item> + <p> + Request information about the <c><anno>Result</anno></c> + of the cancellation. <c>Info</c> defaults to <c>true</c> + which means the <c><anno>Result</anno></c> is + given. When <c>Info</c> is set to <c>false</c>, no + information about the result of the cancellation + is given. When the operation is performed</p> + <taglist> + <tag>synchronously</tag> + <item> + <p> + If <c>Info</c> is <c>true</c>, the <c>Result</c> is + returned by <c>erlang:cancel_timer()</c>; otherwise, + <c>ok</c> is returned. + </p> + </item> + <tag>asynchronously</tag> + <item> + <p> + If <c>Info</c> is <c>true</c>, a message on the form + <c>{cancel_timer, <anno>TimerRef</anno>, + <anno>Result</anno>}</c> is sent to the + caller of <c>erlang:cancel_timer()</c> when the + cancellation operation has been performed; otherwise, + no message is sent. + </p> + </item> + </taglist> + </item> + </taglist> + <p> + More <c><anno>Option</anno></c>s may be added in the future. + </p> + <p>If <c><anno>Result</anno></c> is an integer, it represents + the time in milli-seconds left until the canceled timer would + have expired.</p> + <p> + If <c><anno>Result</anno></c> is <c>false</c>, a + timer corresponding to <c><anno>TimerRef</anno></c> could not + be found. This can be either because the timer had expired, + already had been canceled, or because <c><anno>TimerRef</anno></c> + never corresponded to a timer. Even if the timer had expired, + it does not tell you whether or not the timeout message has + arrived at its destination yet. + </p> + <note> + <p> + The timer service that manages the timer may be co-located + with another scheduler than the scheduler that the calling + process is executing on. If this is the case, communication + with the timer service takes much longer time than if it + is located locally. If the calling process is in critical + path, and can do other things while waiting for the result + of this operation, or is not interested in the result of + the operation, you want to use option <c>{async, true}</c>. + If using option <c>{async, false}</c>, the calling + process blocks until the operation has been performed. + </p> + </note> <p>See also - <seealso marker="#send_after/3">erlang:send_after/3</seealso>, - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>, + <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>, + <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>, and - <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p> - <p>Note: Cancelling a timer does not guarantee that the message - has not already been delivered to the message queue.</p> + <seealso marker="#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p> + </desc> + </func> + <func> + <name name="cancel_timer" arity="1"/> + <fsummary>Cancels a timer.</fsummary> + <desc> + <p>Cancels a timer. The same as calling + <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer(TimerRef, + [])</c></seealso>.</p> </desc> </func> - <func> <name name="check_old_code" arity="1"/> - <fsummary>Check if a module has old code</fsummary> + <fsummary>Checks if a module has old code.</fsummary> <desc> - <p>Returns <c>true</c> if the <c><anno>Module</anno></c> has old code, - and <c>false</c> otherwise.</p> + <p>Returns <c>true</c> if <c><anno>Module</anno></c> has old code, + otherwise <c>false</c>.</p> <p>See also <seealso marker="kernel:code">code(3)</seealso>.</p> </desc> </func> + <func> <name name="check_process_code" arity="2"/> - <fsummary>Check if a process is executing old code for a module</fsummary> - <desc> - <p>Returns <c>true</c> if the process <c><anno>Pid</anno></c> is executing - old code for <c><anno>Module</anno></c>. That is, if the current call of - the process executes old code for this module, or if the - process has references to old code for this module, or if the - process contains funs that references old code for this - module. Otherwise, it returns <c>false</c>.</p> - <pre> -> <input>check_process_code(Pid, lists).</input> -false</pre> + <fsummary>Checks if a process executes old code for a module.</fsummary> + <desc> + <p>The same as + <seealso marker="#check_process_code/3"><c>erlang:check_process_code(<anno>Pid</anno>, <anno>Module</anno>, [])</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="check_process_code" arity="3"/> + <fsummary>Checks if a process executes old code for a module.</fsummary> + <desc> + <p>Checks if the node local process identified by <c><anno>Pid</anno></c> + executes old code for <c><anno>Module</anno></c>.</p> + <p>The available <c><anno>Option</anno></c>s are as follows:</p> + <taglist> + <tag><c>{allow_gc, boolean()}</c></tag> + <item> + <p>Determines if garbage collection is allowed when performing + the operation. If <c>{allow_gc, false}</c> is passed, and + a garbage collection is needed to determine the + result of the operation, the operation is aborted (see + information on <c><anno>CheckResult</anno></c> in the following). + The default is to allow garbage collection, that is, + <c>{allow_gc, true}</c>.</p> + </item> + <tag><c>{async, RequestId}</c></tag> + <item> + <p>The function <c>check_process_code/3</c> returns + the value <c>async</c> immediately after the request + has been sent. When the request has been processed, the + process that called this function is passed a + message on the form + <c>{check_process_code, <anno>RequestId</anno>, <anno>CheckResult</anno>}</c>.</p> + </item> + </taglist> + <p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and + no <c>async</c> option has been passed, the operation + is performed at once. Otherwise a request for + the operation is sent to the process identified by + <c><anno>Pid</anno></c>, and is handled when + appropriate. If no <c>async</c> option has been passed, + the caller blocks until <c><anno>CheckResult</anno></c> + is available and can be returned.</p> + <p><c><anno>CheckResult</anno></c> informs about the result of + the request as follows:</p> + <taglist> + <tag><c>true</c></tag> + <item> + <p>The process identified by <c><anno>Pid</anno></c> + executes old code for <c><anno>Module</anno></c>. + That is, the current call of the process executes old + code for this module, or the process has references + to old code for this module, or the process contains + funs that references old code for this module.</p> + </item> + <tag><c>false</c></tag> + <item> + <p>The process identified by <c><anno>Pid</anno></c> does + not execute old code for <c><anno>Module</anno></c>.</p> + </item> + <tag><c>aborted</c></tag> + <item> + <p>The operation was aborted, as the process needed to + be garbage collected to determine the operation result, + and the operation was requested + by passing option <c>{allow_gc, false}</c>.</p></item> + </taglist> <p>See also <seealso marker="kernel:code">code(3)</seealso>.</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item>If <c><anno>Pid</anno></c> is not a node local process identifier. + </item> + <tag><c>badarg</c></tag> + <item>If <c><anno>Module</anno></c> is not an atom. + </item> + <tag><c>badarg</c></tag> + <item>If <c><anno>OptionList</anno></c> is an invalid list of options. + </item> + </taglist> + </desc> + </func> + + <func> + <name name="convert_time_unit" arity="3"/> + <fsummary>Converts time unit of a time value.</fsummary> + <desc> + <p>Converts the <c><anno>Time</anno></c> value of time unit + <c><anno>FromUnit</anno></c> to the corresponding + <c><anno>ConvertedTime</anno></c> value of time unit + <c><anno>ToUnit</anno></c>. The result is rounded + using the floor function.</p> + + <warning><p>You may lose accuracy and precision when converting + between time units. In order to minimize such loss, collect all + data at <c>native</c> time unit and do the conversion on the end + result.</p></warning> </desc> </func> <func> <name name="crc32" arity="1"/> - <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary> + <fsummary>Computes crc32 (IEEE 802.3) checksum.</fsummary> <desc> - <p>Computes and returns the crc32 (IEEE 802.3 style) checksum for <c><anno>Data</anno></c>.</p> + <p>Computes and returns the crc32 (IEEE 802.3 style) checksum + for <c><anno>Data</anno></c>.</p> </desc> </func> + <func> <name name="crc32" arity="2"/> - <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary> + <fsummary>Computes crc32 (IEEE 802.3) checksum.</fsummary> <desc> - <p>Continue computing the crc32 checksum by combining - the previous checksum, <c><anno>OldCrc</anno></c>, with the checksum of - <c><anno>Data</anno></c>.</p> - <p>The following code:</p> - <code> - X = erlang:crc32(Data1), - Y = erlang:crc32(X,Data2). - </code> - <p>- would assign the same value to <c>Y</c> as this would:</p> - <code> - Y = erlang:crc32([Data1,Data2]). - </code> + <p>Continues computing the crc32 checksum by combining + the previous checksum, <c><anno>OldCrc</anno></c>, with the checksum of + <c><anno>Data</anno></c>.</p> + <p>The following code:</p> + <code> + X = erlang:crc32(Data1), + Y = erlang:crc32(X,Data2).</code> + <p>assigns the same value to <c>Y</c> as this:</p> + <code> + Y = erlang:crc32([Data1,Data2]).</code> </desc> </func> + <func> <name name="crc32_combine" arity="3"/> - <fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary> - <desc> - <p>Combines two previously computed crc32 checksums. - This computation requires the size of the data object for - the second checksum to be known.</p> - <p>The following code:</p> - <code> - Y = erlang:crc32(Data1), - Z = erlang:crc32(Y,Data2). - </code> - <p>- would assign the same value to <c>Z</c> as this would:</p> + <fsummary>Combines two crc32 (IEEE 802.3) checksums.</fsummary> + <desc> + <p>Combines two previously computed crc32 checksums. + This computation requires the size of the data object for + the second checksum to be known.</p> + <p>The following code:</p> + <code> + Y = erlang:crc32(Data1), + Z = erlang:crc32(Y,Data2).</code> + <p>assigns the same value to <c>Z</c> as this:</p> <code> - X = erlang:crc32(Data1), - Y = erlang:crc32(Data2), - Z = erlang:crc32_combine(X,Y,iolist_size(Data2)). - </code> + X = erlang:crc32(Data1), + Y = erlang:crc32(Data2), + Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).</code> </desc> </func> + <func> <name name="date" arity="0"/> - <fsummary>Current date</fsummary> + <fsummary>Current date.</fsummary> <desc> <p>Returns the current date as <c>{Year, Month, Day}</c>.</p> - <p>The time zone and daylight saving time correction depend on + <p>The time zone and Daylight Saving Time correction depend on the underlying OS.</p> + <p>Example:</p> <pre> > <input>date().</input> {1995,2,19}</pre> </desc> </func> + <func> <name name="decode_packet" arity="3"/> - <fsummary>Extracts a protocol packet from a binary</fsummary> + <fsummary>Extracts a protocol packet from a binary.</fsummary> <desc> - <p>Decodes the binary <c><anno>Bin</anno></c> according to the packet - protocol specified by <c><anno>Type</anno></c>. Very similar to the packet - handling done by sockets with the option {packet,<anno>Type</anno>}.</p> - <p>If an entire packet is contained in <c><anno>Bin</anno></c> it is + protocol specified by <c><anno>Type</anno></c>. Similar to the packet + handling done by sockets with option {packet,<anno>Type</anno>}.</p> + <p>If an entire packet is contained in <c><anno>Bin</anno></c>, it is returned together with the remainder of the binary as <c>{ok,<anno>Packet</anno>,<anno>Rest</anno>}</c>.</p> <p>If <c><anno>Bin</anno></c> does not contain the entire packet, - <c>{more,<anno>Length</anno>}</c> is returned. <c><anno>Length</anno></c> is either the - expected <em>total size</em> of the packet or <c>undefined</c> - if the expected packet size is not known. <c>decode_packet</c> + <c>{more,<anno>Length</anno>}</c> is returned. + <c><anno>Length</anno></c> is either the + expected <em>total size</em> of the packet, or <c>undefined</c> + if the expected packet size is unknown. <c>decode_packet</c> can then be called again with more data added.</p> - <p>If the packet does not conform to the protocol format + <p>If the packet does not conform to the protocol format, <c>{error,<anno>Reason</anno>}</c> is returned.</p> - <p>The following values of <c><anno>Type</anno></c> are valid:</p> + <p>The following <c>Type</c>s are valid:</p> <taglist> <tag><c>raw | 0</c></tag> <item> - <p>No packet handling is done. Entire binary is + <p>No packet handling is done. The entire binary is returned unless it is empty.</p> </item> <tag><c>1 | 2 | 4</c></tag> <item> <p>Packets consist of a header specifying the number of bytes in the packet, followed by that number of bytes. - The length of header can be one, two, or four bytes; + The length of the header can be one, two, or four bytes; the order of the bytes is big-endian. The header - will be stripped off when the packet is returned.</p> + is stripped off when the packet is returned.</p> </item> <tag><c>line</c></tag> <item> - <p>A packet is a line terminated with newline. The - newline character is included in the returned packet - unless the line was truncated according to the option - <c>line_length</c>.</p> + <p>A packet is a line terminated by a delimiter byte, + default is the latin1 newline character. The delimiter + byte is included in the returned packet unless the line + was truncated according to option <c>line_length</c>.</p> </item> <tag><c>asn1 | cdr | sunrm | fcgi | tpkt</c></tag> <item> @@ -626,41 +911,50 @@ false</pre> <item> <p>The Hypertext Transfer Protocol. The packets are returned with the format according to - <c><anno>HttpPacket</anno></c> described above. A packet is either a - request, a response, a header or an end of header - mark. Invalid lines are returned as <c><anno>HttpError</anno></c>.</p> - <p>Recognized request methods and header fields are returned as atoms. - Others are returned as strings. Strings of unrecognized header fields - are formatted with only capital letters first and after hyphen characters - (like <c>"Sec-Websocket-Key"</c>).</p> - <p>The protocol type <c>http</c> should only be used for - the first line when a <c><anno>HttpRequest</anno></c> or a - <c><anno>HttpResponse</anno></c> is expected. The following calls - should use <c>httph</c> to get <c><anno>HttpHeader</anno></c>'s until - <c>http_eoh</c> is returned that marks the end of the + <c><anno>HttpPacket</anno></c> described earlier. + A packet is either a + request, a response, a header, or an end of header + mark. Invalid lines are returned as + <c><anno>HttpError</anno></c>.</p> + <p>Recognized request methods and header fields are returned + as atoms. Others are returned as strings. Strings of + unrecognized header fields are formatted with only + capital letters first and after hyphen characters, for + example, <c>"Sec-Websocket-Key"</c>.</p> + <p>The protocol type <c>http</c> is only to be used for + the first line when an <c><anno>HttpRequest</anno></c> or an + <c><anno>HttpResponse</anno></c> is expected. + The following calls are to use <c>httph</c> to get + <c><anno>HttpHeader</anno></c>s until + <c>http_eoh</c> is returned, which marks the end of the headers and the beginning of any following message body.</p> - <p>The variants <c>http_bin</c> and <c>httph_bin</c> will return + <p>The variants <c>http_bin</c> and <c>httph_bin</c> return strings (<c>HttpString</c>) as binaries instead of lists.</p> </item> </taglist> <p>The following options are available:</p> <taglist> <tag><c>{packet_size, integer() >= 0}</c></tag> - <item><p>Sets the max allowed size of the packet body. If - the packet header indicates that the length of the - packet is longer than the max allowed length, the packet - is considered invalid. Default is 0 which means no - size limit.</p> + <item><p>Sets the maximum allowed size of the packet body. + If the packet header indicates that the length of the + packet is longer than the maximum allowed length, the + packet is considered invalid. Default is 0, which means + no size limit.</p> </item> <tag><c>{line_length, integer() >= 0}</c></tag> - <item><p>For packet type <c>line</c>, truncate lines longer - than the indicated length.</p> - <p>Option <c>line_length</c> also applies to <c>http*</c> - packet types as an alias for option <c>packet_size</c> in the - case when <c>packet_size</c> itself is not set. This usage is - only intended for backward compatibility.</p> + <item><p>For packet type <c>line</c>, lines longer than + the indicated length are truncated.</p> + <p>Option <c>line_length</c> also applies to <c>http*</c> + packet types as an alias for option <c>packet_size</c> + if <c>packet_size</c> itself is not set. This use is + only intended for backward compatibility.</p> + </item> + <tag><c>{line_delimiter, 0 =< byte() =< 255}</c></tag> + <item><p>For packet type <c>line</c>, sets the delimiting byte. + Default is the latin1 character <c>$\n</c>.</p> </item> </taglist> + <p>Examples:</p> <pre> > <input>erlang:decode_packet(1,<<3,"abcd">>,[]).</input> {ok,<<"abc">>,<<"d">>} @@ -671,13 +965,11 @@ false</pre> <func> <name name="delete_element" arity="2"/> - <fsummary>Delete element at index in a tuple</fsummary> + <fsummary>Deletes element at index in a tuple.</fsummary> <type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno>)</type_desc> <desc> - <p> - Returns a new tuple with element at <c><anno>Index</anno></c> removed from - tuple <c><anno>Tuple1</anno></c>. - </p> + <p>Returns a new tuple with element at <c><anno>Index</anno></c> + removed from tuple <c><anno>Tuple1</anno></c>, for example:</p> <pre> > <input>erlang:delete_element(2, {one, two, three}).</input> {one,three}</pre> @@ -686,45 +978,49 @@ false</pre> <func> <name name="delete_module" arity="1"/> - <fsummary>Make the current code for a module old</fsummary> + <fsummary>Makes the current code for a module old.</fsummary> <desc> - <p>Makes the current code for <c><anno>Module</anno></c> become old code, and - deletes all references for this module from the export table. + <p>Makes the current code for <c><anno>Module</anno></c> become old code, + and deletes all references for this module from the export table. Returns <c>undefined</c> if the module does not exist, otherwise <c>true</c>.</p> <warning> <p>This BIF is intended for the code server (see - <seealso marker="kernel:code">code(3)</seealso>) and should not be - used elsewhere.</p> + <seealso marker="kernel:code">code(3)</seealso>) and is not + to be used elsewhere.</p> </warning> - <p>Failure: <c>badarg</c> if there is already an old version of + <p>Failure: <c>badarg</c> if there already is an old version of <c>Module</c>.</p> </desc> </func> + <func> <name name="demonitor" arity="1"/> - <fsummary>Stop monitoring</fsummary> + <fsummary>Stops monitoring.</fsummary> <desc> - <p>If <c><anno>MonitorRef</anno></c> is a reference which the calling process - obtained by calling + <p>If <c><anno>MonitorRef</anno></c> is a reference that the + calling process obtained by calling <seealso marker="#monitor/2">monitor/2</seealso>, this monitoring is turned off. If the monitoring is already turned off, nothing happens.</p> - <p>Once <c>demonitor(<anno>MonitorRef</anno>)</c> has returned it is - guaranteed that no <c>{'DOWN', <anno>MonitorRef</anno>, _, _, _}</c> message - due to the monitor will be placed in the caller's message queue - in the future. A <c>{'DOWN', <anno>MonitorRef</anno>, _, _, _}</c> message - might have been placed in the caller's message queue prior to - the call, though. Therefore, in most cases, it is advisable + <p>Once <c>demonitor(<anno>MonitorRef</anno>)</c> has returned, it is + guaranteed that no <c>{'DOWN', + <anno>MonitorRef</anno>, _, _, _}</c> message, + because of the monitor, will be placed in the caller message queue + in the future. A <c>{'DOWN', + <anno>MonitorRef</anno>, _, _, _}</c> message + can have been placed in the caller message queue before + the call, though. It is therefore usually advisable to remove such a <c>'DOWN'</c> message from the message queue - after monitoring has been stopped. - <seealso marker="#demonitor/2">demonitor(<anno>MonitorRef</anno>, [flush])</seealso> can be used instead of + after monitoring has been stopped. + <seealso marker="#demonitor/2"><c>demonitor(<anno>MonitorRef</anno>, [flush])</c></seealso> + can be used instead of <c>demonitor(<anno>MonitorRef</anno>)</c> if this cleanup is wanted.</p> <note> - <p>Prior to OTP release R11B (erts version 5.5) <c>demonitor/1</c> - behaved completely asynchronous, i.e., the monitor was active + <p>Prior to OTP release R11B (ERTS version 5.5) <c>demonitor/1</c> + behaved completely asynchronously, i.e., the monitor was active until the "demonitor signal" reached the monitored entity. This - had one undesirable effect, though. You could never know when + had one undesirable effect. You could never know when you were guaranteed <em>not</em> to receive a <c>DOWN</c> message due to the monitor.</p> <p>Current behavior can be viewed as two combined operations: @@ -733,31 +1029,31 @@ false</pre> </note> <p>Failure: It is an error if <c><anno>MonitorRef</anno></c> refers to a monitoring started by another process. Not all such cases are - cheap to check; if checking is cheap, the call fails with - <c>badarg</c> (for example if <c><anno>MonitorRef</anno></c> is a remote - reference).</p> + cheap to check. If checking is cheap, the call fails with + <c>badarg</c> for example, if <c><anno>MonitorRef</anno></c> is a + remote reference.</p> </desc> </func> + <func> <name name="demonitor" arity="2"/> - <fsummary>Stop monitoring</fsummary> + <fsummary>Stops monitoring.</fsummary> <desc> <p>The returned value is <c>true</c> unless <c>info</c> is part - of <c><anno>OptionList</anno></c>. - </p> + of <c><anno>OptionList</anno></c>.</p> <p><c>demonitor(<anno>MonitorRef</anno>, [])</c> is equivalent to - <seealso marker="#demonitor/1">demonitor(<anno>MonitorRef</anno>)</seealso>.</p> - <p>Currently the following <c><anno>Option</anno></c>s are valid:</p> + <seealso marker="#demonitor/1"><c>demonitor(<anno>MonitorRef</anno>)</c></seealso>.</p> + <p>The available <c><anno>Option</anno></c>s are as follows:</p> <taglist> <tag><c>flush</c></tag> <item> - <p>Remove (one) <c>{_, <anno>MonitorRef</anno>, _, _, _}</c> message, - if there is one, from the caller's message queue after + <p>Removes (one) <c>{_, + <anno>MonitorRef</anno>, _, _, _}</c> message, + if there is one, from the caller message queue after monitoring has been stopped.</p> <p>Calling <c>demonitor(<anno>MonitorRef</anno>, [flush])</c> is equivalent to the following, but more efficient:</p> <code type="none"> - demonitor(MonitorRef), receive {_, MonitorRef, _, _, _} -> @@ -768,78 +1064,90 @@ false</pre> </item> <tag><c>info</c></tag> <item> - <p>The returned value is one of the following:</p> - <taglist> - <tag><c>true</c></tag> - <item><p>The monitor was found and removed. In this case - no <c>'DOWN'</c> message due to this monitor have - been nor will be placed in the message queue - of the caller. - </p> - </item> - <tag><c>false</c></tag> - <item><p>The monitor was not found and could not be removed. - This probably because someone already has placed a - <c>'DOWN'</c> message corresponding to this monitor - in the caller's message queue. - </p> - </item> - </taglist> - <p>If the <c>info</c> option is combined with the <c>flush</c> - option, <c>false</c> will be returned if a flush was needed; - otherwise, <c>true</c>. - </p> + <p>The returned value is one of the following:</p> + <taglist> + <tag><c>true</c></tag> + <item>The monitor was found and removed. In this case, + no <c>'DOWN'</c> message corresponding to this + monitor has been delivered and will not be delivered. + </item> + <tag><c>false</c></tag> + <item>The monitor was not found and could not be removed. + This probably because someone already has placed a + <c>'DOWN'</c> message corresponding to this monitor + in the caller message queue. + </item> + </taglist> + <p>If option <c>info</c> is combined with option <c>flush</c>, + <c>false</c> is returned if a flush was needed, + otherwise <c>true</c>.</p> </item> </taglist> <note> - <p>More options may be added in the future.</p> + <p>More options can be added in a future release.</p> </note> - <p>Failure: <c>badarg</c> if <c><anno>OptionList</anno></c> is not a list, or - if <c><anno>Option</anno></c> is not a valid option, or the same failure as for - <seealso marker="#demonitor/1">demonitor/1</seealso></p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item>If <c><anno>OptionList</anno></c> is not a list. + </item> + <tag><c>badarg</c></tag> + <item>If <c><anno>Option</anno></c> is an invalid option. + </item> + <tag><c>badarg</c></tag> + <item>The same failure as for + <seealso marker="#demonitor/1">demonitor/1</seealso>. + </item> + </taglist> </desc> </func> + <func> <name name="disconnect_node" arity="1"/> - <fsummary>Force the disconnection of a node</fsummary> + <fsummary>Forces the disconnection of a node.</fsummary> <desc> - <p>Forces the disconnection of a node. This will appear to - the node <c><anno>Node</anno></c> as if the local node has crashed. This - BIF is mainly used in the Erlang network authentication - protocols. Returns <c>true</c> if disconnection succeeds, + <p>Forces the disconnection of a node. This appears to + the node <c><anno>Node</anno></c> as if the local node has crashed. + This BIF is mainly used in the Erlang network authentication + protocols.</p> + <p>Returns <c>true</c> if disconnection succeeds, otherwise <c>false</c>. If the local node is not alive, - the function returns <c>ignored</c>.</p> + <c>ignored</c> is returned.</p> </desc> </func> + <func> <name name="display" arity="1"/> - <fsummary>Print a term on standard output</fsummary> + <fsummary>Prints a term on standard output.</fsummary> <desc> - <p>Prints a text representation of <c><anno>Term</anno></c> on the standard - output.</p> + <p>Prints a text representation of <c><anno>Term</anno></c> on the + standard output.</p> <warning> <p>This BIF is intended for debugging only.</p> </warning> </desc> </func> + <func> <name name="element" arity="2"/> + <fsummary>Returns the Nth element of a tuple.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> - <fsummary>Get Nth element of a tuple</fsummary> <desc> <p>Returns the <c><anno>N</anno></c>th element (numbering from 1) of - <c><anno>Tuple</anno></c>.</p> + <c><anno>Tuple</anno></c>, for example:</p> <pre> > <input>element(2, {a, b, c}).</input> b</pre> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="erase" arity="0"/> - <fsummary>Return and delete the process dictionary</fsummary> + <fsummary>Returns and deletes the process dictionary.</fsummary> <desc> - <p>Returns the process dictionary and deletes it.</p> + <p>Returns the process dictionary and deletes it, for + example:</p> <pre> > <input>put(key1, {1, 2, 3}),</input> <input>put(key2, [a, b, c]),</input> @@ -847,13 +1155,16 @@ b</pre> [{key1,{1,2,3}},{key2,[a,b,c]}]</pre> </desc> </func> + <func> <name name="erase" arity="1"/> - <fsummary>Return and delete a value from the process dictionary</fsummary> + <fsummary>Returns and deletes a value from the process dictionary.</fsummary> <desc> - <p>Returns the value <c><anno>Val</anno></c> associated with <c><anno>Key</anno></c> and - deletes it from the process dictionary. Returns - <c>undefined</c> if no value is associated with <c><anno>Key</anno></c>.</p> + <p>Returns the value <c><anno>Val</anno></c> associated with + <c><anno>Key</anno></c> and deletes it from the process dictionary. + Returns <c>undefined</c> if no value is associated with + <c><anno>Key</anno></c>.</p> + <p>Example:</p> <pre> > <input>put(key1, {merry, lambs, are, playing}),</input> <input>X = erase(key1),</input> @@ -861,16 +1172,19 @@ b</pre> {{merry,lambs,are,playing},undefined}</pre> </desc> </func> + <func> <name name="error" arity="1"/> - <fsummary>Stop execution with a given reason</fsummary> + <fsummary>Stops execution with a given reason.</fsummary> <desc> <p>Stops the execution of the calling process with the reason - <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> is any term. The actual - exit reason will be <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c> + <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> + is any term. The exit reason is + <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c> is a list of the functions most recently called (the current function first). Since evaluating this function causes the process to terminate, it has no return value.</p> + <p>Example:</p> <pre> > <input>catch error(foobar).</input> {'EXIT',{foobar,[{erl_eval,do_apply,5}, @@ -880,29 +1194,34 @@ b</pre> {shell,eval_loop,3}]}}</pre> </desc> </func> + <func> <name name="error" arity="2"/> - <fsummary>Stop execution with a given reason</fsummary> + <fsummary>Stops execution with a given reason.</fsummary> <desc> <p>Stops the execution of the calling process with the reason - <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> is any term. The actual - exit reason will be <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c> + <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> + is any term. The exit reason is + <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c> is a list of the functions most recently called (the current - function first). <c><anno>Args</anno></c> is expected to be the list of - arguments for the current function; in Beam it will be used - to provide the actual arguments for the current function in - the <c>Where</c> term. Since evaluating this function causes + function first). <c><anno>Args</anno></c> is expected to be the + list of arguments for the current function; in Beam it is used + to provide the arguments for the current function in + the term <c>Where</c>. Since evaluating this function causes the process to terminate, it has no return value.</p> </desc> </func> + <func> <name name="exit" arity="1"/> - <fsummary>Stop execution with a given reason</fsummary> + <fsummary>Stops execution with a given reason.</fsummary> <desc> - <p>Stops the execution of the calling process with the exit - reason <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> is any term. Since + <p>Stops the execution of the calling process with exit reason + <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> + is any term. Since evaluating this function causes the process to terminate, it has no return value.</p> + <p>Example:</p> <pre> > <input>exit(foobar).</input> ** exception exit: foobar @@ -910,110 +1229,117 @@ b</pre> {'EXIT',foobar}</pre> </desc> </func> + <func> <name name="exit" arity="2"/> - <fsummary>Send an exit signal to a process or a port</fsummary> + <fsummary>Sends an exit signal to a process or a port.</fsummary> <desc> <p>Sends an exit signal with exit reason <c><anno>Reason</anno></c> to the process or port identified by <c><anno>Pid</anno></c>.</p> - <p>The following behavior apply if <c><anno>Reason</anno></c> is any term - except <c>normal</c> or <c>kill</c>:</p> - <p>If <c><anno>Pid</anno></c> is not trapping exits, <c><anno>Pid</anno></c> itself will - exit with exit reason <c><anno>Reason</anno></c>. If <c><anno>Pid</anno></c> is trapping - exits, the exit signal is transformed into a message - <c>{'EXIT', From, <anno>Reason</anno>}</c> and delivered to the message - queue of <c><anno>Pid</anno></c>. <c>From</c> is the pid of the process - which sent the exit signal. See also - <seealso marker="#process_flag/2">process_flag/2</seealso>.</p> - <p>If <c><anno>Reason</anno></c> is the atom <c>normal</c>, <c><anno>Pid</anno></c> will - not exit. If it is trapping exits, the exit signal is - transformed into a message <c>{'EXIT', From, normal}</c> - and delivered to its message queue.</p> - <p>If <c><anno>Reason</anno></c> is the atom <c>kill</c>, that is if - <c>exit(<anno>Pid</anno>, kill)</c> is called, an untrappable exit signal - is sent to <c><anno>Pid</anno></c> which will unconditionally exit with - exit reason <c>killed</c>.</p> + <p>The following behavior applies if <c><anno>Reason</anno></c> + is any term, except <c>normal</c> or <c>kill</c>:</p> + <list type="bulleted"> + <item>If <c><anno>Pid</anno></c> is not trapping exits, + <c><anno>Pid</anno></c> + itself exits with exit reason <c><anno>Reason</anno></c>. + </item> + <item>If <c><anno>Pid</anno></c> is trapping exits, the exit + signal is transformed into a message + <c>{'EXIT', From, <anno>Reason</anno>}</c> + and delivered to the message queue of <c><anno>Pid</anno></c>. + </item> + <item><c>From</c> is the process identifier of the process + that sent the exit signal. See also + <seealso marker="#process_flag/2">process_flag/2</seealso>. + </item> + </list> + <p>If <c><anno>Reason</anno></c> is the atom <c>normal</c>, + <c><anno>Pid</anno></c> + does not exit. If it is trapping exits, the exit signal is + transformed into a message <c>{'EXIT', From, normal}</c> + and delivered to its message queue.</p> + <p>If <c><anno>Reason</anno></c> is the atom <c>kill</c>, + that is, if <c>exit(<anno>Pid</anno>, kill)</c> is called, + an untrappable exit signal is sent to <c><anno>Pid</anno></c>, + which unconditionally exits with exit reason <c>killed</c>. + </p> </desc> </func> + <func> <name name="external_size" arity="1"/> - <fsummary>Calculate the maximum size for a term encoded in the Erlang - external term format</fsummary> + <fsummary>Calculates the maximum size for a term encoded in the Erlang external term format.</fsummary> <desc> <p>Calculates, without doing the encoding, the maximum byte size for a term encoded in the Erlang external term format. The following condition applies always:</p> - <p> <pre> > <input>Size1 = byte_size(term_to_binary(<anno>Term</anno>)),</input> > <input>Size2 = erlang:external_size(<anno>Term</anno>),</input> > <input>true = Size1 =< Size2.</input> -true - </pre> - </p> - <p>This is equivalent to a call to: <code>erlang:external_size(<anno>Term</anno>, []) - </code></p> +true</pre> + <p>This is equivalent to a call to:</p> +<code>erlang:external_size(<anno>Term</anno>, [])</code> </desc> </func> + <func> <name name="external_size" arity="2"/> - <fsummary>Calculate the maximum size for a term encoded in the Erlang - external term format</fsummary> + <fsummary>Calculates the maximum size for a term encoded in the Erlang external term format.</fsummary> <desc> <p>Calculates, without doing the encoding, the maximum byte size for a term encoded in the Erlang external term format. The following condition applies always:</p> - <p> <pre> > <input>Size1 = byte_size(term_to_binary(<anno>Term</anno>, <anno>Options</anno>)),</input> > <input>Size2 = erlang:external_size(<anno>Term</anno>, <anno>Options</anno>),</input> > <input>true = Size1 =< Size2.</input> -true - </pre> - </p> - <p>The option <c>{minor_version, <anno>Version</anno>}</c> specifies how floats - are encoded. See - <seealso marker="#term_to_binary/2">term_to_binary/2</seealso> for - a more detailed description. - </p> +true</pre> + <p>Option <c>{minor_version, <anno>Version</anno>}</c> specifies how + floats are encoded. For a detailed description, see + <seealso marker="#term_to_binary/2">term_to_binary/2</seealso>.</p> </desc> </func> + <func> <name name="float" arity="1"/> - <fsummary>Convert a number to a float</fsummary> + <fsummary>Converts a number to a float.</fsummary> <desc> - <p>Returns a float by converting <c><anno>Number</anno></c> to a float.</p> + <p>Returns a float by converting <c><anno>Number</anno></c> to a float, + for example:</p> <pre> > <input>float(55).</input> 55.0</pre> <p>Allowed in guard tests.</p> <note> - <p>Note that if used on the top-level in a guard, it will - test whether the argument is a floating point number; for - clarity, use + <p>If used on the top level in a guard, it tests whether the + argument is a floating point number; for clarity, use <seealso marker="#is_float/1">is_float/1</seealso> instead.</p> <p>When <c>float/1</c> is used in an expression in a guard, such as '<c>float(A) == 4.0</c>', it converts a number as - described above.</p> + described earlier.</p> </note> </desc> </func> + <func> <name name="float_to_binary" arity="1"/> - <fsummary>Text representation of a float</fsummary> + <fsummary>Text representation of a float.</fsummary> <desc> - <p>The same as <c>float_to_binary(<anno>Float</anno>,[{scientific,20}])</c>.</p> + <p>The same as + <c>float_to_binary(<anno>Float</anno>,[{scientific,20}])</c>.</p> </desc> </func> + <func> <name name="float_to_binary" arity="2"/> - <fsummary>Text representation of a float formatted using given options</fsummary> + <fsummary>Text representation of a float formatted using given options.</fsummary> <desc> - <p>Returns a binary which corresponds to the text + <p>Returns a binary corresponding to the text representation of <c><anno>Float</anno></c> using fixed decimal - point formatting. The <c><anno>Options</anno></c> behave in the same - way as <seealso marker="#float_to_list/2">float_to_list/2</seealso>. - </p> + point formatting. <c><anno>Options</anno></c> behaves in the same + way as <seealso marker="#float_to_list/2">float_to_list/2</seealso>.</p> + <p>Examples:</p> <pre> > <input>float_to_binary(7.12, [{decimals, 4}]).</input> <<"7.1200">> @@ -1021,31 +1347,42 @@ true <<"7.12">></pre> </desc> </func> + <func> <name name="float_to_list" arity="1"/> - <fsummary>Text representation of a float</fsummary> + <fsummary>Text representation of a float.</fsummary> <desc> - <p>The same as <c>float_to_list(<anno>Float</anno>,[{scientific,20}])</c>.</p> + <p>The same as + <c>float_to_list(<anno>Float</anno>,[{scientific,20}])</c>.</p> </desc> </func> + <func> <name name="float_to_list" arity="2"/> - <fsummary>Text representation of a float formatted using given options</fsummary> - <desc> - <p>Returns a string which corresponds to the text - representation of <c>Float</c> using fixed decimal point formatting. - When <c>decimals</c> option is specified - the returned value will contain at most <c>Decimals</c> number of - digits past the decimal point. If the number doesn't fit in the - internal static buffer of 256 bytes, the function throws <c>badarg</c>. - When <c>compact</c> option is provided - the trailing zeros at the end of the list are truncated (this option is - only meaningful together with the <c>decimals</c> option). When - <c>scientific</c> option is provided, the float will be formatted using - scientific notation with <c>Decimals</c> digits of precision. If - <c>Options</c> is <c>[]</c> the function behaves like - <c><seealso marker="#float_to_list/1">float_to_list/1</seealso></c>. - </p> + <fsummary>Text representation of a float formatted using given options.</fsummary> + <desc> + <p>Returns a string corresponding to the text representation + of <c>Float</c> using fixed decimal point formatting. The + options are as follows:</p> + <list type="bulleted"> + <item>If option <c>decimals</c> is specified, the returned value + contains at most <c>Decimals</c> number of digits past the + decimal point. If the number does not fit in the internal + static buffer of 256 bytes, the function throws <c>badarg</c>. + </item> + <item>If option <c>compact</c> is provided, the trailing zeros + at the end of the list are truncated. This option is only + meaningful together with option <c>decimals</c>. + </item> + <item>If option <c>scientific</c> is provided, the float is + formatted using scientific notation with <c>Decimals</c> + digits of precision. + </item> + <item>If <c>Options</c> is <c>[]</c>, the function behaves as + <seealso marker="#float_to_list/1">float_to_list/1</seealso>. + </item> + </list> + <p>Examples:</p> <pre> > <input>float_to_list(7.12, [{decimals, 4}]).</input> "7.1200" @@ -1053,36 +1390,40 @@ true "7.12"</pre> </desc> </func> + <func> <name name="fun_info" arity="1"/> - <fsummary>Information about a fun</fsummary> + <fsummary>Information about a fun.</fsummary> <desc> - <p>Returns a list containing information about the fun - <c><anno>Fun</anno></c>. Each element of the list is a tuple. The order of - the tuples is not defined, and more tuples may be added in a + <p>Returns a list with information about the fun + <c><anno>Fun</anno></c>. Each list element is a tuple. The order + of the tuples is undefined, and more tuples can be added in a future release.</p> <warning> <p>This BIF is mainly intended for debugging, but it can - occasionally be useful in library functions that might need - to verify, for instance, the arity of a fun.</p> + sometimes be useful in library functions that need + to verify, for example, the arity of a fun.</p> </warning> - <p>There are two types of funs with slightly different - semantics:</p> - <p>A fun created by <c>fun M:F/A</c> is called an - <em>external</em> fun. Calling it will always call the - function <c>F</c> with arity <c>A</c> in the latest code for - module <c>M</c>. Note that module <c>M</c> does not even need - to be loaded when the fun <c>fun M:F/A</c> is created.</p> - <p>All other funs are called <em>local</em>. When a local fun - is called, the same version of the code that created the fun - will be called (even if newer version of the module has been - loaded).</p> - <p>The following elements will always be present in the list + <p>Two types of funs have slightly different semantics:</p> + <list type="bulleted"> + <item>A fun created by <c>fun M:F/A</c> is called an + <em>external</em> fun. Calling it will always call the + function <c>F</c> with arity <c>A</c> in the latest code for + module <c>M</c>. Notice that module <c>M</c> does not even + need to be loaded when the fun <c>fun M:F/A</c> is created. + </item> + <item>All other funs are called <em>local</em>. When a local fun + is called, the same version of the code that created the fun + is called (even if a newer version of the module has been + loaded). + </item> + </list> + <p>The following elements are always present in the list for both local and external funs:</p> <taglist> <tag><c>{type, Type}</c></tag> <item> - <p><c>Type</c> is either <c>local</c> or <c>external</c>.</p> + <p><c>Type</c> is <c>local</c> or <c>external</c>.</p> </item> <tag><c>{module, Module}</c></tag> <item> @@ -1097,128 +1438,189 @@ true <p><c>Name</c> (an atom) is a function name.</p> <p>If <c>Fun</c> is a local fun, <c>Name</c> is the name of the local function that implements the fun. - (This name was generated by the compiler, and is generally + (This name was generated by the compiler, and is only of informational use. As it is a local function, it - is not possible to call it directly.) + cannot be called directly.) If no code is currently loaded for the fun, <c>[]</c> - will be returned instead of an atom.</p> + is returned instead of an atom.</p> <p>If <c>Fun</c> is an external fun, <c>Name</c> is the name of the exported function that the fun refers to.</p> </item> <tag><c>{arity, Arity}</c></tag> <item> <p><c>Arity</c> is the number of arguments that the fun - should be called with.</p> + is to be called with.</p> </item> <tag><c>{env, Env}</c></tag> <item> <p><c>Env</c> (a list) is the environment or free variables - for the fun. (For external funs, the returned list is - always empty.)</p> + for the fun. For external funs, the returned list is + always empty.</p> </item> </taglist> - <p>The following elements will only be present in the list if + <p>The following elements are only present in the list if <c>Fun</c> is local:</p> <taglist> <tag><c>{pid, Pid}</c></tag> <item> - <p><c>Pid</c> is the pid of the process that originally - created the fun.</p> + <p><c>Pid</c> is the process identifier of the process + that originally created the fun.</p> </item> <tag><c>{index, Index}</c></tag> <item> - <p><c>Index</c> (an integer) is an index into the module's + <p><c>Index</c> (an integer) is an index into the module fun table.</p> </item> <tag><c>{new_index, Index}</c></tag> <item> - <p><c>Index</c> (an integer) is an index into the module's + <p><c>Index</c> (an integer) is an index into the module fun table.</p> </item> <tag><c>{new_uniq, Uniq}</c></tag> <item> - <p><c>Uniq</c> (a binary) is a unique value for this fun. - It is calculated from the compiled code for the entire module.</p> + <p><c>Uniq</c> (a binary) is a unique value for this fun. It + is calculated from the compiled code for the entire module.</p> </item> <tag><c>{uniq, Uniq}</c></tag> <item> <p><c>Uniq</c> (an integer) is a unique value for this fun. - Starting in the R15 release, this integer is calculated from - the compiled code for the entire module. Before R15, this - integer was based on only the body of the fun. - </p> + As from OTP R15, this integer is calculated from the + compiled code for the entire module. Before OTP R15, this + integer was based on only the body of the fun.</p> </item> </taglist> </desc> </func> + <func> <name name="fun_info" arity="2"/> + <fsummary>Information about a fun.</fsummary> <type name="fun_info_item"/> - <fsummary>Information about a fun</fsummary> <desc> <p>Returns information about <c><anno>Fun</anno></c> as specified by - <c><anno>Item</anno></c>, in the form <c>{<anno>Item</anno>,<anno>Info</anno>}</c>.</p> + <c><anno>Item</anno></c>, in the form + <c>{<anno>Item</anno>,<anno>Info</anno>}</c>.</p> <p>For any fun, <c><anno>Item</anno></c> can be any of the atoms - <c>module</c>, <c>name</c>, <c>arity</c>, <c>env</c>, or <c>type</c>.</p> - <p>For a local fun, <c><anno>Item</anno></c> can also be any of the atoms - <c>index</c>, <c>new_index</c>, <c>new_uniq</c>, + <c>module</c>, <c>name</c>, <c>arity</c>, <c>env</c>, or + <c>type</c>.</p> + <p>For a local fun, <c><anno>Item</anno></c> can also be any of the + atoms <c>index</c>, <c>new_index</c>, <c>new_uniq</c>, <c>uniq</c>, and <c>pid</c>. For an external fun, the value of any of these items is always the atom <c>undefined</c>.</p> <p>See <seealso marker="#fun_info/1">erlang:fun_info/1</seealso>.</p> </desc> </func> + <func> <name name="fun_to_list" arity="1"/> - <fsummary>Text representation of a fun</fsummary> + <fsummary>Text representation of a fun.</fsummary> <desc> - <p>Returns a string which corresponds to the text + <p>Returns a string corresponding to the text representation of <c><anno>Fun</anno></c>.</p> </desc> </func> + <func> <name name="function_exported" arity="3"/> - <fsummary>Check if a function is exported and loaded</fsummary> + <fsummary>Checks if a function is exported and loaded.</fsummary> <desc> <p>Returns <c>true</c> if the module <c><anno>Module</anno></c> is loaded - and contains an exported function <c><anno>Function</anno>/<anno>Arity</anno></c>; - otherwise <c>false</c>.</p> - <p>Returns <c>false</c> for any BIF (functions implemented in C - rather than in Erlang).</p> + and contains an exported function <c><anno>Function</anno>/<anno>Arity</anno></c>, + or if there is a BIF (a built-in function implemented in C) + with the given name, otherwise returns <c>false</c>.</p> + <note><p>This function used to return false for built-in + functions before the 18.0 release.</p></note> </desc> </func> + <func> <name name="garbage_collect" arity="0"/> - <fsummary>Force an immediate garbage collection of the calling process</fsummary> + <fsummary>Forces an immediate garbage collection of the calling process.</fsummary> <desc> - <p>Forces an immediate garbage collection of the currently - executing process. The function should not be used, unless - it has been noticed -- or there are good reasons to suspect -- + <p>Forces an immediate garbage collection of the + executing process. The function is not to be used unless + it has been noticed (or there are good reasons to suspect) that the spontaneous garbage collection will occur too late - or not at all. Improper use may seriously degrade system - performance.</p> - <p>Compatibility note: In versions of OTP prior to R7, - the garbage collection took place at the next context switch, - not immediately. To force a context switch after a call to - <c>erlang:garbage_collect()</c>, it was sufficient to make - any function call.</p> + or not at all.</p> + <warning> + <p>Improper use can seriously degrade system performance.</p> + </warning> </desc> </func> + <func> <name name="garbage_collect" arity="1"/> - <fsummary>Force an immediate garbage collection of a process</fsummary> + <fsummary>Garbage collects a process.</fsummary> + <desc> + <p>The same as + <seealso marker="#garbage_collect/2"><c>garbage_collect(<anno>Pid</anno>, [])</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="garbage_collect" arity="2"/> + <fsummary>Garbage collects a process.</fsummary> <desc> - <p>Works like <c>erlang:garbage_collect()</c> but on any - process. The same caveats apply. Returns <c>false</c> if - <c><anno>Pid</anno></c> refers to a dead process; <c>true</c> otherwise.</p> + <p>Garbage collects the node local process identified by + <c><anno>Pid</anno></c>.</p> + <p>The available <c><anno>Option</anno></c>s are as follows:</p> + <taglist> + <tag><c>{async, RequestId}</c></tag> + <item>The function <c>garbage_collect/2</c> returns + the value <c>async</c> immediately after the request + has been sent. When the request has been processed, the + process that called this function is passed a message on + the form <c>{garbage_collect, + <anno>RequestId</anno>, <anno>GCResult</anno>}</c>. + </item> + </taglist> + <p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and + no <c>async</c> option has been passed, the garbage + collection is performed at once, that is, the same as calling + <seealso marker="#garbage_collect/0">garbage_collect/0</seealso>. + Otherwise a request for garbage collection + is sent to the process identified by <c><anno>Pid</anno></c>, + and will be handled when appropriate. If no <c>async</c> + option has been passed, the caller blocks until + <c><anno>GCResult</anno></c> is available and can be returned.</p> + <p><c><anno>GCResult</anno></c> informs about the result of + the garbage collection request as follows:</p> + <taglist> + <tag><c>true</c></tag> + <item> + The process identified by <c><anno>Pid</anno></c> has + been garbage collected. + </item> + <tag><c>false</c></tag> + <item> + No garbage collection was performed, as + the process identified by <c><anno>Pid</anno></c> + terminated before the request could be satisfied. + </item> + </taglist> + <p>Notice that the same caveats apply as for + <seealso marker="#garbage_collect/0">garbage_collect/0</seealso>.</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Pid</anno></c> is not a node local process identifier. + </item> + <tag><c>badarg</c></tag> + <item> + If <c><anno>OptionList</anno></c> is an invalid list of options. + </item> + </taglist> </desc> </func> + <func> <name name="get" arity="0"/> - <fsummary>Return the process dictionary</fsummary> + <fsummary>Returns the process dictionary.</fsummary> <desc> <p>Returns the process dictionary as a list of - <c>{<anno>Key</anno>, <anno>Val</anno>}</c> tuples.</p> + <c>{<anno>Key</anno>, <anno>Val</anno>}</c> tuples, for example:</p> <pre> > <input>put(key1, merry),</input> <input>put(key2, lambs),</input> @@ -1227,13 +1629,15 @@ true [{key1,merry},{key2,lambs},{key3,{are,playing}}]</pre> </desc> </func> + <func> <name name="get" arity="1"/> - <fsummary>Return a value from the process dictionary</fsummary> + <fsummary>Returns a value from the process dictionary.</fsummary> <desc> - <p>Returns the value <c><anno>Val</anno></c>associated with <c><anno>Key</anno></c> in + <p>Returns the value <c><anno>Val</anno></c> associated with <c><anno>Key</anno></c> in the process dictionary, or <c>undefined</c> if <c><anno>Key</anno></c> does not exist.</p> + <p>Example:</p> <pre> > <input>put(key1, merry),</input> <input>put(key2, lambs),</input> @@ -1242,20 +1646,35 @@ true {are,playing}</pre> </desc> </func> + <func> <name name="get_cookie" arity="0"/> - <fsummary>Get the magic cookie of the local node</fsummary> + <fsummary>Gets the magic cookie of the local node.</fsummary> + <desc> + <p>Returns the magic cookie of the local node if the node is + alive, otherwise the atom <c>nocookie</c>.</p> + </desc> + </func> + + <func> + <name name="get_keys" arity="0"/> + <fsummary>Return a list of all keys from the process dictionary</fsummary> <desc> - <p>Returns the magic cookie of the local node, if the node is - alive; otherwise the atom <c>nocookie</c>.</p> + <p>Returns a list of keys all keys present in the process dictionary.</p> + <pre> +> <input>put(dog, {animal,1}),</input> +<input>put(cow, {animal,2}),</input> +<input>put(lamb, {animal,3}),</input> +<input>get_keys().</input> +[dog,cow,lamb]</pre> </desc> </func> <func> <name name="get_keys" arity="1"/> - <fsummary>Return a list of keys from the process dictionary</fsummary> + <fsummary>Returns a list of keys from the process dictionary.</fsummary> <desc> - <p>Returns a list of keys which are associated with the value - <c><anno>Val</anno></c> in the process dictionary.</p> + <p>Returns a list of keys that are associated with the value + <c><anno>Val</anno></c> in the process dictionary, for example:</p> <pre> > <input>put(mary, {1, 2}),</input> <input>put(had, {1, 2}),</input> @@ -1267,40 +1686,40 @@ true [mary,had,a,little,lamb]</pre> </desc> </func> + <func> <name name="get_stacktrace" arity="0"/> - <fsummary>Get the call stack back-trace of the last exception</fsummary> + <fsummary>Gets the call stack back-trace of the last exception.</fsummary> <type name="stack_item"/> <desc> - <p>Get the call stack back-trace (<em>stacktrace</em>) of the last - exception in the calling process as a list of + <p>Gets the call stack back-trace (<em>stacktrace</em>) of the + last exception in the calling process as a list of <c>{<anno>Module</anno>,<anno>Function</anno>,<anno>Arity</anno>,<anno>Location</anno>}</c> tuples. - The <c><anno>Arity</anno></c> field in the first tuple may be the argument - list of that function call instead of an arity integer, + Field <c><anno>Arity</anno></c> in the first tuple can be the + argument list of that function call instead of an arity integer, depending on the exception.</p> <p>If there has not been any exceptions in a process, the stacktrace is <c>[]</c>. After a code change for the process, - the stacktrace may also be reset to [].</p> + the stacktrace can also be reset to <c>[]</c>.</p> <p>The stacktrace is the same data as the <c>catch</c> operator returns, for example:</p> <p><c>{'EXIT',{badarg,Stacktrace}} = catch abs(x)</c></p> - <p><c><anno>Location</anno></c> is a (possibly empty) list of two-tuples that - may indicate the location in the source code of the function. - The first element is an atom that describes the type of - information in the second element. Currently the following - items may occur:</p> + <p><c><anno>Location</anno></c> is a (possibly empty) list + of two-tuples that + can indicate the location in the source code of the function. + The first element is an atom describing the type of + information in the second element. The following + items can occur:</p> <taglist> <tag><c>file</c></tag> - <item> - <p>The second element of the tuple is a string (list of - characters) representing the filename of the source file - of the function.</p> + <item>The second element of the tuple is a string (list of + characters) representing the file name of the source file + of the function. </item> <tag><c>line</c></tag> - <item> - <p>The second element of the tuple is the line number + <item>The second element of the tuple is the line number (an integer greater than zero) in the source file - where the exception occurred or the function was called.</p> + where the exception occurred or the function was called. </item> </taglist> <p>See also @@ -1308,49 +1727,56 @@ true <seealso marker="#error/2">erlang:error/2</seealso>.</p> </desc> </func> + <func> <name name="group_leader" arity="0"/> - <fsummary>Get the group leader for the calling process</fsummary> + <fsummary>Gets the group leader for the calling process.</fsummary> <desc> - <p>Returns the pid of the group leader for the process which - evaluates the function.</p> + <p>Returns the process identifier of the group leader for the + process evaluating the function.</p> <p>Every process is a member of some process group and all - groups have a <em>group leader</em>. All IO from the group + groups have a <em>group leader</em>. All I/O from the group is channeled to the group leader. When a new process is spawned, it gets the same group leader as the spawning process. Initially, at system start-up, <c>init</c> is both its own group leader and the group leader of all processes.</p> </desc> </func> + <func> <name name="group_leader" arity="2"/> - <fsummary>Set the group leader for a process</fsummary> + <fsummary>Sets the group leader for a process.</fsummary> <desc> - <p>Sets the group leader of <c><anno>Pid</anno></c> to <c><anno>GroupLeader</anno></c>. - Typically, this is used when a processes started from a - certain shell should have another group leader than + <p>Sets the group leader of <c><anno>Pid</anno></c> + to <c><anno>GroupLeader</anno></c>. + Typically, this is used when a process started from a + certain shell is to have another group leader than <c>init</c>.</p> <p>See also <seealso marker="#group_leader/0">group_leader/0</seealso>.</p> </desc> </func> + <func> <name name="halt" arity="0"/> - <fsummary>Halt the Erlang runtime system and indicate normal exit to the calling environment</fsummary> + <fsummary>Halts the Erlang runtime system and indicates normal exit to the calling environment.</fsummary> <desc> <p>The same as <seealso marker="#halt/2"><c>halt(0, [])</c></seealso>.</p> + <p>Example:</p> <pre> > <input>halt().</input> os_prompt% </pre> </desc> </func> + <func> <name name="halt" arity="1"/> - <fsummary>Halt the Erlang runtime system</fsummary> + <fsummary>Halts the Erlang runtime system.</fsummary> <desc> <p>The same as <seealso marker="#halt/2"><c>halt(<anno>Status</anno>, [])</c></seealso>.</p> + <p>Example:</p> <pre> > <input>halt(17).</input> os_prompt% <input>echo $?</input> @@ -1358,178 +1784,191 @@ os_prompt% <input>echo $?</input> os_prompt% </pre> </desc> </func> + <func> <name name="halt" arity="2"/> - <fsummary>Halt the Erlang runtime system</fsummary> + <fsummary>Halts the Erlang runtime system.</fsummary> <desc> <p><c><anno>Status</anno></c> must be a non-negative integer, a string, or the atom <c>abort</c>. Halts the Erlang runtime system. Has no return value. - Depending on <c><anno>Status</anno></c>: - </p> + Depending on <c><anno>Status</anno></c>, the following occurs:</p> <taglist> <tag>integer()</tag> - <item>The runtime system exits with the integer value <c><anno>Status</anno></c> - as status code to the calling environment (operating system). + <item>The runtime system exits with integer value + <c><anno>Status</anno></c> + as status code to the calling environment (OS). </item> <tag>string()</tag> - <item>An erlang crash dump is produced with <c><anno>Status</anno></c> as slogan, - and then the runtime system exits with status code <c>1</c>. + <item>An Erlang crash dump is produced with <c><anno>Status</anno></c> + as slogan. Then the runtime system exits with status code <c>1</c>. + Note that only code points in the range 0-255 may be used + and the string will be truncated if longer than 200 characters. </item> <tag><c>abort</c></tag> <item> The runtime system aborts producing a core dump, if that is - enabled in the operating system. + enabled in the OS. </item> </taglist> - <p>Note that on many platforms, only the status codes 0-255 are - supported by the operating system. - </p> - <p>For integer <c><anno>Status</anno></c> the Erlang runtime system closes all ports - and allows async threads to finish their operations before exiting. - To exit without such flushing use - <c><anno>Option</anno></c> as <c>{flush,false}</c>. - </p> - <p>For statuses <c>string()</c> and <c>abort</c> the <c>flush</c> - option is ignored and flushing is <em>not</em> done. - </p> + <note><p>On many platforms, the OS supports only status + codes 0-255. A too large status code will be truncated by clearing + the high bits.</p></note> + <p>For integer <c><anno>Status</anno></c>, the Erlang runtime system + closes all ports and allows async threads to finish their + operations before exiting. To exit without such flushing, use + <c><anno>Option</anno></c> as <c>{flush,false}</c>.</p> + <p>For statuses <c>string()</c> and <c>abort</c>, option + <c>flush</c> is ignored and flushing is <em>not</em> done.</p> </desc> </func> + <func> <name name="hash" arity="2"/> - <fsummary>Hash function (deprecated)</fsummary> + <fsummary>Hash function (deprecated).</fsummary> <desc> <p>Returns a hash value for <c><anno>Term</anno></c> within the range - <c>1..<anno>Range</anno></c>. The allowed range is 1..2^27-1.</p> + <c>1..<anno>Range</anno></c>. The maximum range is 1..2^27-1.</p> <warning> - <p>This BIF is deprecated as the hash value may differ on - different architectures. Also the hash values for integer - terms larger than 2^27 as well as large binaries are very + <p>This BIF is deprecated, as the hash value can differ on + different architectures. The hash values for integer + terms higher than 2^27 and large binaries are poor. The BIF is retained for backward compatibility - reasons (it may have been used to hash records into a file), - but all new code should use one of the BIFs + reasons (it can have been used to hash records into a file), + but all new code is to use one of the BIFs <c>erlang:phash/2</c> or <c>erlang:phash2/1,2</c> instead.</p> </warning> </desc> </func> + <func> <name name="hd" arity="1"/> - <fsummary>Head of a list</fsummary> + <fsummary>Head of a list.</fsummary> <desc> - <p>Returns the head of <c><anno>List</anno></c>, that is, the first element.</p> + <p>Returns the head of <c><anno>List</anno></c>, that is, + the first element, for example:</p> <pre> > <input>hd([1,2,3,4,5]).</input> 1</pre> <p>Allowed in guard tests.</p> - <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is the empty list [].</p> + <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is the empty + list <c>[]</c>.</p> </desc> </func> + <func> <name name="hibernate" arity="3"/> - <fsummary>Hibernate a process until a message is sent to it</fsummary> + <fsummary>Hibernates a process until a message is sent to it.</fsummary> <desc> <p>Puts the calling process into a wait state where its memory - allocation has been reduced as much as possible, which is + allocation has been reduced as much as possible. This is useful if the process does not expect to receive any messages - in the near future.</p> - <p>The process will be awaken when a message is sent to it, and - control will resume in <c><anno>Module</anno>:<anno>Function</anno></c> with - the arguments given by <c><anno>Args</anno></c> with the call stack - emptied, meaning that the process will terminate when that - function returns. Thus <c>erlang:hibernate/3</c> will never - return to its caller.</p> + soon.</p> + <p>The process is awaken when a message is sent to it, and control + resumes in <c><anno>Module</anno>:<anno>Function</anno></c> with + the arguments given by <c><anno>Args</anno></c> with the call + stack emptied, meaning that the process terminates when that + function returns. Thus <c>erlang:hibernate/3</c> never + returns to its caller.</p> <p>If the process has any message in its message queue, - the process will be awaken immediately in the same way as - described above.</p> + the process is awakened immediately in the same way as + described earlier.</p> <p>In more technical terms, what <c>erlang:hibernate/3</c> does - is the following. It discards the call stack for the process. - Then it garbage collects the process. After the garbage - collection, all live data is in one continuous heap. The heap + is the following. It discards the call stack for the process, + and then garbage collects the process. After this, + all live data is in one continuous heap. The heap is then shrunken to the exact same size as the live data - which it holds (even if that size is less than the minimum + that it holds (even if that size is less than the minimum heap size for the process).</p> <p>If the size of the live data in the process is less than the minimum heap size, the first garbage collection occurring - after the process has been awaken will ensure that the heap + after the process is awakened ensures that the heap size is changed to a size not smaller than the minimum heap size.</p> - <p>Note that emptying the call stack means that any surrounding - <c>catch</c> is removed and has to be re-inserted after + <p>Notice that emptying the call stack means that any surrounding + <c>catch</c> is removed and must be reinserted after hibernation. One effect of this is that processes started using <c>proc_lib</c> (also indirectly, such as - <c>gen_server</c> processes), should use + <c>gen_server</c> processes), are to use <seealso marker="stdlib:proc_lib#hibernate/3">proc_lib:hibernate/3</seealso> - instead to ensure that the exception handler continues to work + instead, to ensure that the exception handler continues to work when the process wakes up.</p> </desc> </func> <func> <name name="insert_element" arity="3"/> - <fsummary>Insert an element at index in a tuple</fsummary> + <fsummary>Inserts an element at index in a tuple.</fsummary> <type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno>) + 1</type_desc> <desc> - <p> - Returns a new tuple with element <c><anno>Term</anno></c> insert at position - <c><anno>Index</anno></c> in tuple <c><anno>Tuple1</anno></c>. - All elements from position <c><anno>Index</anno></c> and upwards are subsequently - pushed one step higher in the new tuple <c><anno>Tuple2</anno></c>. - </p> + <p>Returns a new tuple with element <c><anno>Term</anno></c> + inserted at position + <c><anno>Index</anno></c> in tuple <c><anno>Tuple1</anno></c>. + All elements from position <c><anno>Index</anno></c> and upwards are + pushed one step higher in the new tuple <c><anno>Tuple2</anno></c>.</p> + <p>Example:</p> <pre> > <input>erlang:insert_element(2, {one, two, three}, new).</input> {one,new,two,three}</pre> </desc> </func> + <func> <name name="integer_to_binary" arity="1"/> - <fsummary>Text representation of an integer</fsummary> + <fsummary>Text representation of an integer.</fsummary> <desc> - <p>Returns a binary which corresponds to the text - representation of <c><anno>Integer</anno></c>.</p> + <p>Returns a binary corresponding to the text + representation of <c><anno>Integer</anno></c>, for example:</p> <pre> > <input>integer_to_binary(77).</input> <<"77">></pre> </desc> </func> + <func> <name name="integer_to_binary" arity="2"/> - <fsummary>Text representation of an integer</fsummary> + <fsummary>Text representation of an integer.</fsummary> <desc> - <p>Returns a binary which corresponds to the text - representation of <c><anno>Integer</anno></c> in base <c><anno>Base</anno></c>.</p> + <p>Returns a binary corresponding to the text + representation of <c><anno>Integer</anno></c> in base + <c><anno>Base</anno></c>, for example:</p> <pre> > <input>integer_to_binary(1023, 16).</input> <<"3FF">></pre> </desc> </func> + <func> <name name="integer_to_list" arity="1"/> - <fsummary>Text representation of an integer</fsummary> + <fsummary>Text representation of an integer.</fsummary> <desc> - <p>Returns a string which corresponds to the text - representation of <c><anno>Integer</anno></c>.</p> + <p>Returns a string corresponding to the text + representation of <c><anno>Integer</anno></c>, for example:</p> <pre> > <input>integer_to_list(77).</input> "77"</pre> </desc> </func> + <func> <name name="integer_to_list" arity="2"/> - <fsummary>Text representation of an integer</fsummary> + <fsummary>Text representation of an integer.</fsummary> <desc> - <p>Returns a string which corresponds to the text - representation of <c><anno>Integer</anno></c> in base <c><anno>Base</anno></c>.</p> + <p>Returns a string corresponding to the text + representation of <c><anno>Integer</anno></c> in base + <c><anno>Base</anno></c>, for example:</p> <pre> > <input>integer_to_list(1023, 16).</input> "3FF"</pre> </desc> </func> + <func> <name name="iolist_to_binary" arity="1"/> - <fsummary>Convert an iolist to a binary</fsummary> + <fsummary>Converts an iolist to a binary.</fsummary> <desc> - <p>Returns a binary which is made from the integers and - binaries in <c><anno>IoListOrBinary</anno></c>.</p> + <p>Returns a binary that is made from the integers and + binaries in <c><anno>IoListOrBinary</anno></c>, for example:</p> <pre> > <input>Bin1 = <<1,2,3>>.</input> <<1,2,3>> @@ -1541,269 +1980,311 @@ os_prompt% </pre> <<1,2,3,1,2,3,4,5,4,6>></pre> </desc> </func> + <func> <name name="iolist_size" arity="1"/> - <fsummary>Size of an iolist</fsummary> + <fsummary>Size of an iolist.</fsummary> <desc> - <p>Returns an integer which is the size in bytes - of the binary that would be the result of - <c>iolist_to_binary(<anno>Item</anno>)</c>.</p> + <p>Returns an integer that is the size in bytes + of the binary that would be the result of + <c>iolist_to_binary(<anno>Item</anno>)</c>, for example:</p> <pre> > <input>iolist_size([1,2|<<3,4>>]).</input> 4</pre> </desc> </func> + <func> <name name="is_alive" arity="0"/> - <fsummary>Check whether the local node is alive</fsummary> + <fsummary>Checks whether the local node is alive.</fsummary> <desc> - <p>Returns <c>true</c> if the local node is alive; that is, if - the node can be part of a distributed system. Otherwise, it - returns <c>false</c>.</p> + <p>Returns <c>true</c> if the local node is alive (that is, if + the node can be part of a distributed system), otherwise + <c>false</c>.</p> </desc> </func> + <func> <name name="is_atom" arity="1"/> - <fsummary>Check whether a term is an atom</fsummary> + <fsummary>Checks whether a term is an atom.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an atom; - otherwise returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an atom, + otherwise <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_binary" arity="1"/> - <fsummary>Check whether a term is a binary</fsummary> + <fsummary>Checks whether a term is a binary.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a binary; - otherwise returns <c>false</c>.</p> - + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a binary, + otherwise <c>false</c>.</p> <p>A binary always contains a complete number of bytes.</p> - <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_bitstring" arity="1"/> - <fsummary>Check whether a term is a bitstring</fsummary> + <fsummary>Checks whether a term is a bitstring.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a bitstring (including a binary); - otherwise returns <c>false</c>.</p> - + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a + bitstring (including a binary), otherwise <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_boolean" arity="1"/> - <fsummary>Check whether a term is a boolean</fsummary> + <fsummary>Checks whether a term is a boolean.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is - either the atom <c>true</c> or the atom <c>false</c> - (i.e. a boolean); otherwise returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is the + atom <c>true</c> or the atom <c>false</c> (that is, a boolean). + Otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_builtin" arity="3"/> - <fsummary>Check if a function is a BIF implemented in C</fsummary> + <fsummary>Checks if a function is a BIF implemented in C.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Module</anno>:<anno>Function</anno>/<anno>Arity</anno></c> is - a BIF implemented in C; otherwise returns <c>false</c>. - This BIF is useful for builders of cross reference tools.</p> + <p>This BIF is useful for builders of cross-reference tools.</p> + <p>Returns <c>true</c> if + <c><anno>Module</anno>:<anno>Function</anno>/<anno>Arity</anno></c> + is a BIF implemented in C, otherwise <c>false</c>.</p> </desc> </func> + <func> <name name="is_float" arity="1"/> - <fsummary>Check whether a term is a float</fsummary> + <fsummary>Checks whether a term is a float.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a floating point - number; otherwise returns <c>false</c>.</p> + number, otherwise <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_function" arity="1"/> - <fsummary>Check whether a term is a fun</fsummary> + <fsummary>Checks whether a term is a fun.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a fun; otherwise - returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a fun, otherwise + <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_function" arity="2"/> - <fsummary>Check whether a term is a fun with a given arity</fsummary> + <fsummary>Checks whether a term is a fun with a given arity.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a fun that can be - applied with <c><anno>Arity</anno></c> number of arguments; otherwise - returns <c>false</c>.</p> + applied with <c><anno>Arity</anno></c> number of arguments, otherwise + <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_integer" arity="1"/> - <fsummary>Check whether a term is an integer</fsummary> + <fsummary>Checks whether a term is an integer.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an integer; - otherwise returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an integer, + otherwise <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_list" arity="1"/> - <fsummary>Check whether a term is a list</fsummary> + <fsummary>Checks whether a term is a list.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a list with - zero or more elements; otherwise returns <c>false</c>.</p> + zero or more elements, otherwise <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + + <func> + <name name="is_map" arity="1"/> + <fsummary>Checks whether a term is a map.</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a map, + otherwise <c>false</c>.</p> + <p>Allowed in guard tests.</p> + </desc> + </func> + <func> <name name="is_number" arity="1"/> - <fsummary>Check whether a term is a number</fsummary> + <fsummary>Checks whether a term is a number.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is either an integer or a - floating point number; otherwise returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is an integer or a + floating point number. Otherwise returns <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_pid" arity="1"/> - <fsummary>Check whether a term is a pid</fsummary> + <fsummary>Checks whether a term is a process identifier.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a pid (process - identifier); otherwise returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a process + identifier, otherwise <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_port" arity="1"/> - <fsummary>Check whether a term is a port</fsummary> + <fsummary>Checks whether a term is a port.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a port identifier; - otherwise returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a port identifier, + otherwise <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_process_alive" arity="1"/> - <fsummary>Check whether a process is alive</fsummary> + <fsummary>Checks whether a process is alive.</fsummary> <desc> - <p> - <c><anno>Pid</anno></c> must refer to a process at the local node. - Returns <c>true</c> if the process exists and is alive, that - is, is not exiting and has not exited. Otherwise, returns + <p><c><anno>Pid</anno></c> must refer to a process at the local node.</p> + <p>Returns <c>true</c> if the process exists and is alive, that + is, is not exiting and has not exited. Otherwise returns <c>false</c>. </p> </desc> </func> + <func> <name name="is_record" arity="2"/> - <fsummary>Check whether a term appears to be a record</fsummary> + <fsummary>Checks whether a term appears to be a record.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple and its first - element is <c><anno>RecordTag</anno></c>. Otherwise, returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple and its + first element is <c><anno>RecordTag</anno></c>. + Otherwise returns <c>false</c>.</p> <note> <p>Normally the compiler treats calls to <c>is_record/2</c> - specially. It emits code to verify that <c><anno>Term</anno></c> is a - tuple, that its first element is <c><anno>RecordTag</anno></c>, and that - the size is correct. However, if the <c><anno>RecordTag</anno></c> is - not a literal atom, the <c>is_record/2</c> BIF will be - called instead and the size of the tuple will not be - verified.</p> + specially. It emits code to verify that <c><anno>Term</anno></c> + is a tuple, that its first element is + <c><anno>RecordTag</anno></c>, and that the + size is correct. However, if <c><anno>RecordTag</anno></c> is + not a literal atom, the BIF <c>is_record/2</c> is called + instead and the size of the tuple is not verified.</p> </note> - <p>Allowed in guard tests, if <c><anno>RecordTag</anno></c> is a literal - atom.</p> + <p>Allowed in guard tests, if <c><anno>RecordTag</anno></c> is + a literal atom.</p> </desc> </func> + <func> <name name="is_record" arity="3"/> - <fsummary>Check whether a term appears to be a record</fsummary> - <desc> - <p><c><anno>RecordTag</anno></c> must be an atom. Returns <c>true</c> if - <c><anno>Term</anno></c> is a tuple, its first element is <c><anno>RecordTag</anno></c>, - and its size is <c><anno>Size</anno></c>. Otherwise, returns <c>false</c>.</p> - <p>Allowed in guard tests, provided that <c><anno>RecordTag</anno></c> is + <fsummary>Checks whether a term appears to be a record.</fsummary> + <desc> + <p><c><anno>RecordTag</anno></c> must be an atom.</p> + <p>Returns <c>true</c> if + <c><anno>Term</anno></c> is a tuple, + its first element is <c><anno>RecordTag</anno></c>, + and its size is <c><anno>Size</anno></c>. + Otherwise returns <c>false</c>.</p> + <p>Allowed in guard tests if <c><anno>RecordTag</anno></c> is a literal atom and <c>Size</c> is a literal integer.</p> <note> - <p>This BIF is documented for completeness. In most cases - <c>is_record/2</c> should be used.</p> + <p>This BIF is documented for completeness. Usually + <c>is_record/2</c> is to be used.</p> </note> </desc> </func> + <func> <name name="is_reference" arity="1"/> - <fsummary>Check whether a term is a reference</fsummary> + <fsummary>Checks whether a term is a reference.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a reference; - otherwise returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a reference, + otherwise <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="is_tuple" arity="1"/> - <fsummary>Check whether a term is a tuple</fsummary> + <fsummary>Checks whether a term is a tuple.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple; - otherwise returns <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a tuple, + otherwise <c>false</c>.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="length" arity="1"/> - <fsummary>Length of a list</fsummary> + <fsummary>Length of a list.</fsummary> <desc> - <p>Returns the length of <c><anno>List</anno></c>.</p> + <p>Returns the length of <c><anno>List</anno></c>, for example:</p> <pre> > <input>length([1,2,3,4,5,6,7,8,9]).</input> 9</pre> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="link" arity="1"/> - <fsummary>Create a link to another process (or port)</fsummary> + <fsummary>Creates a link to another process (or port).</fsummary> <desc> <p>Creates a link between the calling process and another - process (or port) <c><anno>PidOrPort</anno></c>, if there is not such a link + process (or port) <c><anno>PidOrPort</anno></c>, if there is + not such a link already. If a process attempts to create a link to itself, nothing is done. Returns <c>true</c>.</p> - <p>If <c><anno>PidOrPort</anno></c> does not exist, the behavior of the BIF depends - on if the calling process is trapping exits or not (see + <p>If <c><anno>PidOrPort</anno></c> does not exist, the behavior + of the BIF + depends on if the calling process is trapping exits or not (see <seealso marker="#process_flag/2">process_flag/2</seealso>):</p> <list type="bulleted"> <item>If the calling process is not trapping exits, and - checking <c><anno>PidOrPort</anno></c> is cheap -- that is, if <c><anno>PidOrPort</anno></c> is - local -- <c>link/1</c> fails with reason <c>noproc</c>.</item> + checking <c><anno>PidOrPort</anno></c> is cheap + (that is, if <c><anno>PidOrPort</anno></c> + is local), <c>link/1</c> fails with reason <c>noproc</c>.</item> <item>Otherwise, if the calling process is trapping exits, - and/or <c><anno>PidOrPort</anno></c> is remote, <c>link/1</c> returns - <c>true</c>, but an exit signal with reason <c>noproc</c> + and/or <c><anno>PidOrPort</anno></c> is remote, <c>link/1</c> + returns <c>true</c>, but an exit signal with reason <c>noproc</c> is sent to the calling process.</item> </list> </desc> </func> + <func> <name name="list_to_atom" arity="1"/> - <fsummary>Convert from text representation to an atom</fsummary> - <desc> - <p>Returns the atom whose text representation is <c><anno>String</anno></c>.</p> - <p><c><anno>String</anno></c> may only contain ISO-latin-1 - characters (i.e. numbers below 256) as the current - implementation does not allow unicode characters >= 256 in - atoms. For more information on Unicode support in atoms - see <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8 encoded atoms</seealso> - in the chapter about the external term format in the ERTS User's Guide.</p> + <fsummary>Converts from text representation to an atom.</fsummary> + <desc> + <p>Returns the atom whose text representation is + <c><anno>String</anno></c>.</p> + <p><c><anno>String</anno></c> can only contain ISO-latin-1 + characters (that is, + numbers less than 256) as the implementation does not + allow unicode characters equal to or above 256 in atoms. + For more information on Unicode support in atoms, see + <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8 + encoded atoms</seealso> + in Section "External Term Format" in the User's Guide.</p> + <p>Example:</p> <pre> > <input>list_to_atom("Erlang").</input> 'Erlang'</pre> </desc> </func> + <func> <name name="list_to_binary" arity="1"/> - <fsummary>Convert a list to a binary</fsummary> + <fsummary>Converts a list to a binary.</fsummary> <desc> - <p>Returns a binary which is made from the integers and - binaries in <c><anno>IoList</anno></c>.</p> + <p>Returns a binary that is made from the integers and + binaries in <c><anno>IoList</anno></c>, for example:</p> <pre> > <input>Bin1 = <<1,2,3>>.</input> <<1,2,3>> @@ -1815,40 +2296,46 @@ os_prompt% </pre> <<1,2,3,1,2,3,4,5,4,6>></pre> </desc> </func> + <func> <name name="list_to_bitstring" arity="1"/> + <fsummary>Converts a list to a bitstring.</fsummary> <type name="bitstring_list"/> - <fsummary>Convert a list to a bitstring</fsummary> <desc> - <p>Returns a bitstring which is made from the integers and - bitstrings in <c><anno>BitstringList</anno></c>. (The last tail in <c><anno>BitstringList</anno></c> - is allowed to be a bitstring.)</p> + <p>Returns a bitstring that is made from the integers and + bitstrings in <c><anno>BitstringList</anno></c>. (The last tail in + <c><anno>BitstringList</anno></c> is allowed to be a bitstring.)</p> + <p>Example:</p> <pre> > <input>Bin1 = <<1,2,3>>.</input> <<1,2,3>> > <input>Bin2 = <<4,5>>.</input> <<4,5>> -> <input>Bin3 = <<6,7:4,>>.</input> -<<6>> +> <input>Bin3 = <<6,7:4>>.</input> +<<6,7:4>> > <input>list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).</input> -<<1,2,3,1,2,3,4,5,4,6,7:46>></pre> +<<1,2,3,1,2,3,4,5,4,6,7:4>></pre> </desc> </func> + <func> <name name="list_to_existing_atom" arity="1"/> - <fsummary>Convert from text representation to an atom</fsummary> + <fsummary>Converts from text representation to an atom.</fsummary> <desc> - <p>Returns the atom whose text representation is <c><anno>String</anno></c>, + <p>Returns the atom whose text representation is + <c><anno>String</anno></c>, but only if there already exists such atom.</p> <p>Failure: <c>badarg</c> if there does not already exist an atom whose text representation is <c><anno>String</anno></c>.</p> </desc> </func> + <func> <name name="list_to_float" arity="1"/> - <fsummary>Convert from text representation to a float</fsummary> + <fsummary>Converts from text representation to a float.</fsummary> <desc> - <p>Returns the float whose text representation is <c><anno>String</anno></c>.</p> + <p>Returns the float whose text representation is + <c><anno>String</anno></c>, for example:</p> <pre> > <input>list_to_float("2.2017764e+0").</input> 2.2017764</pre> @@ -1856,12 +2343,13 @@ os_prompt% </pre> representation of a float.</p> </desc> </func> + <func> <name name="list_to_integer" arity="1"/> - <fsummary>Convert from text representation to an integer</fsummary> + <fsummary>Converts from text representation to an integer.</fsummary> <desc> <p>Returns an integer whose text representation is - <c><anno>String</anno></c>.</p> + <c><anno>String</anno></c>, for example:</p> <pre> > <input>list_to_integer("123").</input> 123</pre> @@ -1869,12 +2357,14 @@ os_prompt% </pre> representation of an integer.</p> </desc> </func> + <func> <name name="list_to_integer" arity="2"/> - <fsummary>Convert from text representation to an integer</fsummary> + <fsummary>Converts from text representation to an integer.</fsummary> <desc> <p>Returns an integer whose text representation in base - <c><anno>Base</anno></c> is <c><anno>String</anno></c>.</p> + <c><anno>Base</anno></c> is <c><anno>String</anno></c>, + for example:</p> <pre> > <input>list_to_integer("3FF", 16).</input> 1023</pre> @@ -1882,47 +2372,52 @@ os_prompt% </pre> representation of an integer.</p> </desc> </func> + <func> <name name="list_to_pid" arity="1"/> - <fsummary>Convert from text representation to a pid</fsummary> + <fsummary>Converts from text representation to a pid.</fsummary> <desc> - <p>Returns a pid whose text representation is <c><anno>String</anno></c>.</p> - <warning> - <p>This BIF is intended for debugging and for use in - the Erlang operating system. It should not be used in - application programs.</p> - </warning> + <p>Returns a process identifier whose text representation is a + <c><anno>String</anno></c>, for example:</p> <pre> > <input>list_to_pid("<0.4.1>").</input> <0.4.1></pre> <p>Failure: <c>badarg</c> if <c><anno>String</anno></c> contains a bad - representation of a pid.</p> + representation of a process identifier.</p> + <warning> + <p>This BIF is intended for debugging and is not to be used + in application programs.</p> + </warning> </desc> </func> + <func> <name name="list_to_tuple" arity="1"/> - <fsummary>Convert a list to a tuple</fsummary> + <fsummary>Converts a list to a tuple.</fsummary> <desc> - <p>Returns a tuple which corresponds to <c><anno>List</anno></c>. <c><anno>List</anno></c> - can contain any Erlang terms.</p> + <p>Returns a tuple corresponding to <c><anno>List</anno></c>, + for example</p> <pre> > <input>list_to_tuple([share, ['Ericsson_B', 163]]).</input> {share, ['Ericsson_B', 163]}</pre> + <p><c><anno>List</anno></c> can contain any Erlang terms.</p> </desc> </func> + <func> <name name="load_module" arity="2"/> - <fsummary>Load object code for a module</fsummary> + <fsummary>Loads object code for a module.</fsummary> <desc> - <p>If <c><anno>Binary</anno></c> contains the object code for the module - <c><anno>Module</anno></c>, this BIF loads that object code. Also, if - the code for the module <c><anno>Module</anno></c> already exists, all + <p>If <c><anno>Binary</anno></c> contains the object code for module + <c><anno>Module</anno></c>, this BIF loads that object code. If + the code for module <c><anno>Module</anno></c> already exists, all export references are replaced so they point to the newly loaded code. The previously loaded code is kept in the system - as old code, as there may still be processes which are - executing that code. It returns either - <c>{module, <anno>Module</anno>}</c>, or <c>{error, <anno>Reason</anno>}</c> if loading - fails. <c><anno>Reason</anno></c> is one of the following:</p> + as old code, as there can still be processes executing + that code.</p> + <p>Returns either <c>{module, <anno>Module</anno>}</c>, or + <c>{error, <anno>Reason</anno>}</c> if loading fails. + <c><anno>Reason</anno></c> is any of the following:</p> <taglist> <tag><c>badfile</c></tag> <item> @@ -1932,118 +2427,122 @@ os_prompt% </pre> </item> <tag><c>not_purged</c></tag> <item> - <p><c><anno>Binary</anno></c> contains a module which cannot be loaded - because old code for this module already exists.</p> + <p><c><anno>Binary</anno></c> contains a module that cannot be + loaded because old code for this module already exists.</p> </item> </taglist> <warning> <p>This BIF is intended for the code server (see - <seealso marker="kernel:code">code(3)</seealso>) and should not be - used elsewhere.</p> + <seealso marker="kernel:code">code(3)</seealso>) + and is not to be used elsewhere.</p> </warning> </desc> </func> + <func> <name name="load_nif" arity="2"/> - <fsummary>Load NIF library</fsummary> + <fsummary>Loads NIF library.</fsummary> <desc> <note> - <p>In releases older than OTP R14B, NIFs were an - experimental feature. Versions of OTP older than R14B might + <p>Before OTP R14B, NIFs were an + experimental feature. Versions before OTP R14B can have different and possibly incompatible NIF semantics and - interfaces. For example, in R13B03 the return value on - failure was - <c>{error,Reason,Text}</c>.</p> + interfaces. For example, in OTP R13B03 the return value on + failure was <c>{error,Reason,Text}</c>.</p> </note> <p>Loads and links a dynamic library containing native - implemented functions (NIFs) for a module. <c><anno>Path</anno></c> is a - file path to the sharable object/dynamic library file minus - the OS-dependent file extension (.so for Unix and .dll for - Windows). See <seealso marker="erl_nif">erl_nif</seealso> - on how to implement a NIF library.</p> - <p><c><anno>LoadInfo</anno></c> can be any term. It will be passed on to + implemented functions (NIFs) for a module. <c><anno>Path</anno></c> + is a file path to the shareable object/dynamic library file minus + the OS-dependent file extension (<c>.so</c> for Unix and + <c>.dll</c> for Windows. For information on how to + implement a NIF library, see + <seealso marker="erl_nif">erl_nif</seealso>.</p> + <p><c><anno>LoadInfo</anno></c> can be any term. It is passed on to the library as part of the initialization. A good practice is to include a module version number to support future code upgrade scenarios.</p> <p>The call to <c>load_nif/2</c> must be made <em>directly</em> from the Erlang code of the module that the - NIF library belongs to.</p> - <p>It returns either <c>ok</c>, or <c>{error,{<anno>Reason</anno>,Text}}</c> - if loading fails. <c><anno>Reason</anno></c> is one of the atoms below, - while <c><anno>Text</anno></c> is a human readable string that may give - some more information about the failure.</p> + NIF library belongs to. It returns either <c>ok</c>, or + <c>{error,{<anno>Reason</anno>,Text}}</c> if loading fails. + <c><anno>Reason</anno></c> is one of the following atoms + while <c><anno>Text</anno></c> is a human readable string that + can give more information about the failure:</p> <taglist> <tag><c>load_failed</c></tag> - <item> - <p>The OS failed to load the NIF library.</p> + <item>The OS failed to load the NIF library. </item> <tag><c>bad_lib</c></tag> - <item> - <p>The library did not fulfil the requirements as a NIF - library of the calling module.</p> + <item>The library did not fulfill the requirements as a NIF + library of the calling module. </item> <tag><c>load | reload | upgrade</c></tag> - <item> - <p>The corresponding library callback was not successful.</p> + <item>The corresponding library callback was unsuccessful. </item> <tag><c>old_code</c></tag> - <item> - <p>The call to <c>load_nif/2</c> was made from the old - code of a module that has been upgraded. This is not - allowed.</p> + <item>The call to <c>load_nif/2</c> was made from the old + code of a module that has been upgraded; this is not + allowed. </item> </taglist> </desc> </func> + <func> <name name="loaded" arity="0"/> - <fsummary>List of all loaded modules</fsummary> + <fsummary>Lists all loaded modules.</fsummary> <desc> - <p>Returns a list of all loaded Erlang modules (current and/or + <p>Returns a list of all loaded Erlang modules (current and old code), including preloaded modules.</p> <p>See also <seealso marker="kernel:code">code(3)</seealso>.</p> </desc> </func> + <func> <name name="localtime" arity="0"/> - <fsummary>Current local date and time</fsummary> + <fsummary>Current local date and time.</fsummary> <desc> - <p>Returns the current local date and time - <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c>.</p> - <p>The time zone and daylight saving time correction depend - on the underlying OS.</p> + <p>Returns the current local date and time, + <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c>, + for example:</p> <pre> > <input>erlang:localtime().</input> {{1996,11,6},{14,45,17}}</pre> + <p>The time zone and Daylight Saving Time correction depend + on the underlying OS.</p> </desc> </func> + <func> <name name="localtime_to_universaltime" arity="1"/> - <fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary> + <fsummary>Converts from local to Universal Time Coordinated (UTC) date and time.</fsummary> <desc> <p>Converts local date and time to Universal Time Coordinated - (UTC), if this is supported by the underlying OS. Otherwise, - no conversion is done and <c><anno>Localtime</anno></c> is returned.</p> + (UTC), if supported by the underlying OS. Otherwise + no conversion is done and <c><anno>Localtime</anno></c> + is returned.</p> + <p>Example:</p> <pre> > <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).</input> {{1996,11,6},{13,45,17}}</pre> - <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> does not denote - a valid date and time.</p> + <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> denotes an + invalid date and time.</p> </desc> </func> + <func> <name name="localtime_to_universaltime" arity="2"/> - <fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary> + <fsummary>Converts from local to Universal Time Coordinated (UTC) date and time.</fsummary> <desc> <p>Converts local date and time to Universal Time Coordinated - (UTC) just like <c>erlang:localtime_to_universaltime/1</c>, - but the caller decides if daylight saving time is active or - not.</p> - <p>If <c><anno>IsDst</anno> == true</c> the <c><anno>Localtime</anno></c> is during - daylight saving time, if <c><anno>IsDst</anno> == false</c> it is not, - and if <c><anno>IsDst</anno> == undefined</c> the underlying OS may + (UTC) as <c>erlang:localtime_to_universaltime/1</c>, + but the caller decides if Daylight Saving Time is active.</p> + <p>If <c><anno>IsDst</anno> == true</c>, <c><anno>Localtime</anno></c> is + during Daylight Saving Time, if <c><anno>IsDst</anno> == false</c> it is + not. If <c><anno>IsDst</anno> == undefined</c>, the underlying OS can guess, which is the same as calling <c>erlang:localtime_to_universaltime(<anno>Localtime</anno>)</c>.</p> + <p>Examples:</p> <pre> > <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).</input> {{1996,11,6},{12,45,17}} @@ -2051,205 +2550,269 @@ os_prompt% </pre> {{1996,11,6},{13,45,17}} > <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).</input> {{1996,11,6},{13,45,17}}</pre> - <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> does not denote - a valid date and time.</p> + <p>Failure: <c>badarg</c> if <c><anno>Localtime</anno></c> denotes an + invalid date and time.</p> </desc> </func> + <func> <name name="make_ref" arity="0"/> - <fsummary>Return an almost unique reference</fsummary> + <fsummary>Returns a unique reference.</fsummary> <desc> - <p>Returns an almost unique reference.</p> - <p>The returned reference will re-occur after approximately 2^82 - calls; therefore it is unique enough for practical purposes.</p> - <pre> -> <input>make_ref().</input> -#Ref<0.0.0.135></pre> + <p>Returns a <seealso marker="doc/efficiency_guide:advanced#unique_references">unique + reference</seealso>. The reference is unique among + connected nodes.</p> + <warning><p>Known issue: When a node is restarted multiple + times with the same node name, references created + on a newer node can be mistaken for a reference + created on an older node with the same node name.</p></warning> </desc> </func> + <func> <name name="make_tuple" arity="2"/> - <fsummary>Create a new tuple of a given arity</fsummary> + <fsummary>Creates a new tuple of a given arity.</fsummary> <desc> - <p>Returns a new tuple of the given <c><anno>Arity</anno></c>, where all - elements are <c><anno>InitialValue</anno></c>.</p> + <p>Creates a new tuple of the given <c><anno>Arity</anno></c>, where all + elements are <c><anno>InitialValue</anno></c>, for example:</p> <pre> > <input>erlang:make_tuple(4, []).</input> {[],[],[],[]}</pre> </desc> </func> + <func> <name name="make_tuple" arity="3"/> - <fsummary>Create a new tuple with given arity and contents</fsummary> - <desc> - <p><c>erlang:make_tuple</c> first creates a tuple of size <c><anno>Arity</anno></c> - where each element has the value <c><anno>DefaultValue</anno></c>. It then fills - in values from <c><anno>InitList</anno></c>. Each list element in <c><anno>InitList</anno></c> - must be a two-tuple where the first element is a position in the - newly created tuple and the second element is any term. If a position - occurs more than once in the list, the term corresponding to - last occurrence will be used.</p> + <fsummary>Creates a new tuple with given arity and contents.</fsummary> + <desc> + <p>Creates a tuple of size <c><anno>Arity</anno></c>, where each element + has value <c><anno>DefaultValue</anno></c>, and then fills in + values from <c><anno>InitList</anno></c>. + Each list element in <c><anno>InitList</anno></c> + must be a two-tuple, where the first element is a position in the + newly created tuple and the second element is any term. If a + position occurs more than once in the list, the term corresponding + to the last occurrence is used.</p> + <p>Example:</p> <pre> > <input>erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).</input> {{[],aa,[],[],zz}</pre> </desc> </func> + + <func> + <name name="map_size" arity="1"/> + <fsummary>Returns the size of a map.</fsummary> + <desc> + <p>Returns an integer, which is the number of key-value pairs + in <c><anno>Map</anno></c>, for example:</p> + <pre> +> <input>map_size(#{a=>1, b=>2, c=>3}).</input> +3</pre> + <p>Allowed in guard tests.</p> + </desc> + </func> + + <func> + <name name="match_spec_test" arity="3"/> + <fsummary>Test that a match specification works</fsummary> + <desc> + <p> + This function is a utility to test a match_spec used in calls to + <seealso marker="stdlib:ets#select/2">ets:select/2</seealso> and + <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>. + The function both tests MatchSpec for "syntactic" correctness and + runs the match_spec against the object. If the match_spec contains + errors, the tuple {error, Errors} is returned where Errors is a list + of natural language descriptions of what was wrong with the match_spec. + </p> + <p> + If the <c><anno>Type</anno></c> is <c>table</c> the object to match + against should be a tuple. The function then returns + {ok,Result,[],Warnings} where Result is what would have been the + result in a real ets:select/2 call or false if the match_spec does + not match the object tuple. + </p> + + <p> + If <c><anno>Type</anno></c> is <c>trace</c> the object to match + against should be a list. The function returns + {ok, Result, Flags, Warnings} where Result is <c>true</c> if a trace + message should be emitted, <c>false</c> if a trace message should not + be emitted or the message term to be appended to the trace message. + Flags is a list containing all the trace flags that will be enabled, + at the moment this is only <c>return_trace</c>. + </p> + + <p> + This is a useful debugging and test tool, especially when writing complicated + match specifications. + </p> + <p> + See also + <seealso marker="stdlib:ets#test_ms/2">ets:test_ms/2</seealso>. + </p> + </desc> + </func> + <func> <name name="max" arity="2"/> - <fsummary>Return the largest of two term</fsummary> + <fsummary>Returns the largest of two terms.</fsummary> <desc> - <p>Return the largest of <c><anno>Term1</anno></c> and <c><anno>Term2</anno></c>; - if the terms compare equal, <c><anno>Term1</anno></c> will be returned.</p> + <p>Returns the largest of <c><anno>Term1</anno></c> and + <c><anno>Term2</anno></c>. + If the terms are equal, <c><anno>Term1</anno></c> is returned.</p> </desc> </func> + <func> <name name="md5" arity="1"/> - <fsummary>Compute an MD5 message digest</fsummary> + <fsummary>Computes an MD5 message digest.</fsummary> <desc> - <p>Computes an <c>MD5</c> message digest from <c><anno>Data</anno></c>, where - the length of the digest is 128 bits (16 bytes). <c><anno>Data</anno></c> + <p>Computes an MD5 message digest from <c><anno>Data</anno></c>, where + the length of the digest is 128 bits (16 bytes). + <c><anno>Data</anno></c> is a binary or a list of small integers and binaries.</p> - <p>See The MD5 Message Digest Algorithm (RFC 1321) for more - information about MD5.</p> - <warning><p>The MD5 Message Digest Algorithm is <em>not</em> considered - safe for code-signing or software integrity purposes.</p></warning> + <p>For more information about MD5, see RFC 1321 - The + MD5 Message-Digest Algorithm.</p> + <warning><p>The MD5 Message-Digest Algorithm is <em>not</em> considered + safe for code-signing or software-integrity purposes.</p></warning> </desc> </func> + <func> <name name="md5_final" arity="1"/> - <fsummary>Finish the update of an MD5 context and return the computed MD5 message digest</fsummary> + <fsummary>Finishes the update of an MD5 context and returns the computed MD5 message digest.</fsummary> <desc> <p>Finishes the update of an MD5 <c><anno>Context</anno></c> and returns the computed <c>MD5</c> message digest.</p> </desc> </func> + <func> <name name="md5_init" arity="0"/> - <fsummary>Create an MD5 context</fsummary> + <fsummary>Creates an MD5 context.</fsummary> <desc> <p>Creates an MD5 context, to be used in subsequent calls to <c>md5_update/2</c>.</p> </desc> </func> + <func> <name name="md5_update" arity="2"/> - <fsummary>Update an MD5 context with data, and return a new context</fsummary> + <fsummary>Updates an MD5 context with data and returns a new context.</fsummary> <desc> - <p>Updates an MD5 <c><anno>Context</anno></c> with <c><anno>Data</anno></c>, and returns - a <c><anno>NewContext</anno></c>.</p> + <p>Updates an MD5 <c><anno>Context</anno></c> with + <c><anno>Data</anno></c> and returns a + <c><anno>NewContext</anno></c>.</p> </desc> </func> + <func> <name name="memory" arity="0"/> + <fsummary>Information about dynamically allocated memory.</fsummary> <type name="memory_type"/> - <fsummary>Information about dynamically allocated memory</fsummary> - <desc> - <p>Returns a list containing information about memory - dynamically allocated by the Erlang emulator. Each element of - the list is a tuple <c>{Type, Size}</c>. The first element - <c><anno>Type</anno></c>is an atom describing memory type. The second - element <c><anno>Size</anno></c>is memory size in bytes. A description of - each memory type follows:</p> + <desc> + <p>Returns a list with information about memory + dynamically allocated by the Erlang emulator. Each list + element is a tuple <c>{Type, Size}</c>. The first element + <c><anno>Type</anno></c> is an atom describing memory type. The second + element <c><anno>Size</anno></c> is the memory size in bytes.</p> + <p>The memory types are as follows:</p> <taglist> <tag><c>total</c></tag> <item> - <p>The total amount of memory currently allocated, which is - the same as the sum of memory size for <c>processes</c> + <p>The total amount of memory currently allocated. This is + the same as the sum of the memory size for <c>processes</c> and <c>system</c>.</p> </item> <tag><c>processes</c></tag> <item> - <p>The total amount of memory currently allocated by + <p>The total amount of memory currently allocated for the Erlang processes.</p> </item> <tag><c>processes_used</c></tag> <item> <p>The total amount of memory currently used by the Erlang - processes.</p> - <p>This memory is part of the memory presented as + processes. This is part of the memory presented as <c>processes</c> memory.</p> </item> <tag><c>system</c></tag> <item> - <p>The total amount of memory currently allocated by + <p>The total amount of memory currently allocated for the emulator that is not directly related to any Erlang - process.</p> - <p>Memory presented as <c>processes</c> is not included in - this memory.</p> + process. Memory presented as <c>processes</c> is not + included in this memory.</p> </item> <tag><c>atom</c></tag> <item> - <p>The total amount of memory currently allocated for atoms.</p> - <p>This memory is part of the memory presented as + <p>The total amount of memory currently allocated for atoms. + This memory is part of the memory presented as <c>system</c> memory.</p> </item> <tag><c>atom_used</c></tag> <item> - <p>The total amount of memory currently used for atoms.</p> - <p>This memory is part of the memory presented as + <p>The total amount of memory currently used for atoms. + This memory is part of the memory presented as <c>atom</c> memory.</p> </item> <tag><c>binary</c></tag> <item> <p>The total amount of memory currently allocated for - binaries.</p> - <p>This memory is part of the memory presented as - <c>system</c> memory.</p> + binaries. This memory is part of the memory presented + as <c>system</c> memory.</p> </item> <tag><c>code</c></tag> <item> <p>The total amount of memory currently allocated for - Erlang code.</p> - <p>This memory is part of the memory presented as - <c>system</c> memory.</p> + Erlang code. This memory is part of the memory presented + as <c>system</c> memory.</p> </item> <tag><c>ets</c></tag> <item> <p>The total amount of memory currently allocated for ets - tables.</p> - <p>This memory is part of the memory presented as + tables. This memory is part of the memory presented as <c>system</c> memory.</p> </item> <tag><c>low</c></tag> <item> - <p>Only on 64-bit halfword emulator.</p> - <p>The total amount of memory allocated in low memory areas - that are restricted to less than 4 Gb even though - the system may have more physical memory.</p> - <p>May be removed in future releases of halfword emulator.</p> + <p>Only on 64-bit halfword emulator. + The total amount of memory allocated in low memory areas + that are restricted to less than 4 GB, although + the system can have more memory.</p> + <p>Can be removed in a future release of the halfword + emulator.</p> </item> <tag><c>maximum</c></tag> <item> <p>The maximum total amount of memory allocated since - the emulator was started.</p> - <p>This tuple is only present when the emulator is run with - instrumentation.</p> + the emulator was started. This tuple is only present + when the emulator is run with instrumentation.</p> <p>For information on how to run the emulator with - instrumentation see + instrumentation, see <seealso marker="tools:instrument">instrument(3)</seealso> and/or <seealso marker="erts:erl">erl(1)</seealso>.</p> </item> </taglist> <note> <p>The <c>system</c> value is not complete. Some allocated - memory that should be part of the <c>system</c> value are - not.</p> + memory that is to be part of this value is not.</p> <p>When the emulator is run with instrumentation, the <c>system</c> value is more accurate, but memory - directly allocated by <c>malloc</c> (and friends) are still + directly allocated for <c>malloc</c> (and friends) is still not part of the <c>system</c> value. Direct calls to - <c>malloc</c> are only done from OS specific runtime - libraries and perhaps from user implemented Erlang drivers + <c>malloc</c> are only done from OS-specific runtime + libraries and perhaps from user-implemented Erlang drivers that do not use the memory allocation functions in the driver interface.</p> - <p>Since the <c>total</c> value is the sum of <c>processes</c> - and <c>system</c> the error in <c>system</c> will propagate + <p>As the <c>total</c> value is the sum of <c>processes</c> + and <c>system</c>, the error in <c>system</c> propagates to the <c>total</c> value.</p> <p>The different amounts of memory that are summed are - <em>not</em> gathered atomically which also introduce + <em>not</em> gathered atomically, which introduces an error in the result.</p> </note> - <p>The different values has the following relation to each + <p>The different values have the following relation to each other. Values beginning with an uppercase letter is not part of the result.</p> <code type="none"> @@ -2257,69 +2820,62 @@ os_prompt% </pre> processes = processes_used + ProcessesNotUsed system = atom + binary + code + ets + OtherSystem atom = atom_used + AtomNotUsed - RealTotal = processes + RealSystem RealSystem = system + MissedSystem</code> - <p>More tuples in the returned list may be added in the future.</p> + <p>More tuples in the returned list can be added in a + future release.</p> <note> <p>The <c>total</c> value is supposed to be the total amount of memory dynamically allocated by the emulator. Shared libraries, the code of the emulator itself, and - the emulator stack(s) are not supposed to be included. That + the emulator stacks are not supposed to be included. That is, the <c>total</c> value is <em>not</em> supposed to be - equal to the total size of all pages mapped to the emulator. - Furthermore, due to fragmentation and pre-reservation of - memory areas, the size of the memory segments which contain - the dynamically allocated memory blocks can be substantially + equal to the total size of all pages mapped to the emulator.</p> + <p>Furthermore, because of fragmentation and prereservation of + memory areas, the size of the memory segments containing + the dynamically allocated memory blocks can be much larger than the total size of the dynamically allocated memory blocks.</p> </note> <note> - <p> - Since erts version 5.6.4 <c>erlang:memory/0</c> requires that + <p>As from <c>ERTS</c> 5.6.4, <c>erlang:memory/0</c> requires that all <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso> - allocators are enabled (default behaviour). - </p> + allocators are enabled (default behavior).</p> </note> - <p>Failure:</p> - <taglist> - <tag><c>notsup</c></tag> - <item> - If an <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso> - allocator has been disabled. - </item> - </taglist> + <p>Failure: <c>notsup</c> if an + <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso> + allocator has been disabled.</p> </desc> </func> + <func> <name name="memory" arity="1" clause_i="1"/> <name name="memory" arity="1" clause_i="2"/> + <fsummary>Information about dynamically allocated memory.</fsummary> <type name="memory_type"/> - <fsummary>Information about dynamically allocated memory</fsummary> <desc> <p>Returns the memory size in bytes allocated for memory of type <c><anno>Type</anno></c>. The argument can also be given as a list of <c>memory_type()</c> atoms, in which case a corresponding list of <c>{memory_type(), Size :: integer >= 0}</c> tuples is returned.</p> <note> - <p> - Since erts version 5.6.4 <c>erlang:memory/1</c> requires that + <p>As from <c>ERTS</c> version 5.6.4, + <c>erlang:memory/1</c> requires that all <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso> - allocators are enabled (default behaviour). - </p> + allocators are enabled (default behavior).</p> </note> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> <item> - If <c><anno>Type</anno></c> is not one of the memory types listed in the - documentation of + If <c><anno>Type</anno></c> is not one of the memory types + listed in the description of <seealso marker="#memory/0">erlang:memory/0</seealso>. </item> <tag><c>badarg</c></tag> <item> - If <c>maximum</c> is passed as <c><anno>Type</anno></c> and the emulator - is not run in instrumented mode. + If <c>maximum</c> is passed as <c><anno>Type</anno></c> and + the emulator is not run in instrumented mode. </item> <tag><c>notsup</c></tag> <item> @@ -2331,226 +2887,367 @@ os_prompt% </pre> <seealso marker="#memory/0">erlang:memory/0</seealso>.</p> </desc> </func> + <func> <name name="min" arity="2"/> - <fsummary>Return the smallest of two term</fsummary> + <fsummary>Returns the smallest of two terms.</fsummary> <desc> - <p>Return the smallest of <c><anno>Term1</anno></c> and <c><anno>Term2</anno></c>; - if the terms compare equal, <c><anno>Term1</anno></c> will be returned.</p> + <p>Returns the smallest of <c><anno>Term1</anno></c> and + <c><anno>Term2</anno></c>. + If the terms are equal, <c><anno>Term1</anno></c> is returned.</p> </desc> </func> + <func> <name name="module_loaded" arity="1"/> - <fsummary>Check if a module is loaded</fsummary> + <fsummary>Checks if a module is loaded.</fsummary> <desc> - <p>Returns <c>true</c> if the module <c><anno>Module</anno></c> is loaded, - otherwise returns <c>false</c>. It does not attempt to load + <p>Returns <c>true</c> if the module <c><anno>Module</anno></c> + is loaded, otherwise <c>false</c>. It does not attempt to load the module.</p> <warning> <p>This BIF is intended for the code server (see - <seealso marker="kernel:code">code(3)</seealso>) and should not be + <seealso marker="kernel:code">code(3)</seealso>) and is not to be used elsewhere.</p> </warning> </desc> </func> + <func> - <name name="monitor" arity="2"/> - <fsummary>Start monitoring</fsummary> - <desc> - <p>The calling process starts monitoring <c><anno>Item</anno></c> which is - an object of type <c><anno>Type</anno></c>.</p> - <p>Currently only processes can be monitored, i.e. the only - allowed <c><anno>Type</anno></c> is <c>process</c>, but other types may be - allowed in the future.</p> - <p><c><anno>Item</anno></c> can be:</p> - <taglist> - <tag><c>pid()</c></tag> - <item> - <p>The pid of the process to monitor.</p> - </item> - <tag><c>{RegName, Node}</c></tag> - <item> - <p>A tuple consisting of a registered name of a process and - a node name. The process residing on the node <c>Node</c> - with the registered name <c>RegName</c> will be monitored.</p> - </item> - <tag><c>RegName</c></tag> - <item> - <p>The process locally registered as <c>RegName</c> will be - monitored.</p> - </item> - </taglist> - <note> - <p>When a process is monitored by registered name, the process - that has the registered name at the time when - <c>monitor/2</c> is called will be monitored. - The monitor will not be effected, if the registered name is - unregistered.</p> - </note> - <p>A <c>'DOWN'</c> message will be sent to the monitoring - process if <c><anno>Item</anno></c> dies, if <c><anno>Item</anno></c> does not exist, - or if the connection is lost to the node which <c><anno>Item</anno></c> - resides on. A <c>'DOWN'</c> message has the following pattern:</p> - <code type="none"> -{'DOWN', MonitorRef, Type, Object, Info}</code> - <p>where <c>MonitorRef</c> and <c>Type</c> are the same as - described above, and:</p> + <name name="monitor" arity="2" clause_i="1"/> + <name name="monitor" arity="2" clause_i="2"/> + <name name="monitor" arity="2" clause_i="3"/> + <fsummary>Starts monitoring.</fsummary> + <type name="registered_name"/> + <type name="registered_process_identifier"/> + <type name="monitor_process_identifier"/> + <type name="monitor_port_identifier"/> + <desc> + <p>Sends a monitor request of type <c><anno>Type</anno></c> to the + entity identified by <c><anno>Item</anno></c>. If the monitored entity + does not exist or when it dies, the caller of <c>monitor/2</c> will + be notified by a message on the following format:</p> + <code type="none">{Tag, <anno>MonitorRef</anno>, <anno>Type</anno>, Object, Info}</code> + <note><p>The monitor request is an asynchronous signal. That is, it + takes time before the signal reaches its destination.</p></note> + + <p><c><anno>Type</anno></c> can be one of the following atoms: + <c>process</c>, <c>port</c> or <c>time_offset</c>.</p> + + <p>A monitor is triggered only once, after that it is removed from + both monitoring process and the monitored entity. + Monitors are fired when the monitored process or port terminates, + does not exist at the moment of creation, or if the connection to + it is lost. In the case with connection, we lose knowledge about + the fact if it still exists or not. The monitoring is also turned off + when <seealso marker="#demonitor/1">demonitor/1</seealso> + is called.</p> + + <p>When monitoring by name please note, that the <c>RegisteredName</c> + is resolved to <c>pid()</c> or <c>port()</c> only once + at the moment of monitor instantiation, later changes to the name + registration will not affect the existing monitor.</p> + + <p>When a monitor is triggered, a <c>'DOWN'</c> message that has the + following pattern <c>{'DOWN', MonitorRef, Type, Object, Info}</c> + is sent to the monitoring process.</p> + + <p>In monitor message <c>MonitorRef</c> and <c>Type</c> are the same as + described earlier, and:</p> <taglist> <tag><c>Object</c></tag> <item> - <p>A reference to the monitored object:</p> - <list type="bulleted"> - <item>the pid of the monitored process, if <c><anno>Item</anno></c> was - specified as a pid.</item> - <item><c>{RegName, Node}</c>, if <c><anno>Item</anno></c> was specified as - <c>{RegName, Node}</c>.</item> - <item><c>{RegName, Node}</c>, if <c><anno>Item</anno></c> was specified as - <c>RegName</c>. <c>Node</c> will in this case be the - name of the local node (<c>node()</c>).</item> - </list> + <p>The monitored entity, which triggered the event. When monitoring + a local process or port, <c>Object</c> will be equal to the + <c>pid()</c> or <c>port()</c> that was being monitored. When + monitoring process or port by name, <c>Object</c> will have format + <c>{RegisteredName, Node}</c> where <c>RegisteredName</c> is the + name which has been used with <c>monitor/2</c> call and + <c>Node</c> is local or remote node name (for ports monitored by + name, <c>Node</c> is always local node name).</p> </item> <tag><c>Info</c></tag> <item> <p>Either the exit reason of the process, <c>noproc</c> - (non-existing process), or <c>noconnection</c> (no - connection to <c><anno>Node</anno></c>).</p> - </item> + (process or port did not exist at the time of monitor creation), + or <c>noconnection</c> (no connection to the node where the + monitored process resides). </p></item> </taglist> - <note> - <p>If/when <c>monitor/2</c> is extended (e.g. to - handle other item types than <c>process</c>), other - possible values for <c>Object</c>, and <c>Info</c> in the - <c>'DOWN'</c> message will be introduced.</p> - </note> - <p>The monitoring is turned off either when the <c>'DOWN'</c> - message is sent, or when - <seealso marker="#demonitor/1">demonitor/1</seealso> - is called.</p> + <p>If an attempt is made to monitor a process on an older node - (where remote process monitoring is not implemented or one + (where remote process monitoring is not implemented or where remote process monitoring by registered name is not implemented), the call fails with <c>badarg</c>.</p> - <p>Making several calls to <c>monitor/2</c> for the same - <c><anno>Item</anno></c> is not an error; it results in as many, completely - independent, monitorings.</p> <note> - <p>The format of the <c>'DOWN'</c> message changed in the 5.2 - version of the emulator (OTP release R9B) for monitor <em>by registered name</em>. The <c>Object</c> element of + <p>The format of the <c>'DOWN'</c> message changed in ERTS + version 5.2 (OTP R9B) for monitoring + <em>by registered name</em>. Element <c>Object</c> of the <c>'DOWN'</c> message could in earlier versions - sometimes be the pid of the monitored process and sometimes - be the registered name. Now the <c>Object</c> element is + sometimes be the process identifier of the monitored process and sometimes + be the registered name. Now element <c>Object</c> is always a tuple consisting of the registered name and - the node name. Processes on new nodes (emulator version 5.2 - or greater) will always get <c>'DOWN'</c> messages on + the node name. Processes on new nodes (ERTS version 5.2 + or higher) always get <c>'DOWN'</c> messages on the new format even if they are monitoring processes on old - nodes. Processes on old nodes will always get <c>'DOWN'</c> + nodes. Processes on old nodes always get <c>'DOWN'</c> messages on the old format.</p> </note> + + <taglist> + <tag>Monitoring a <marker id="monitor_process"/><c>process</c></tag> + <item> + <p>Creates monitor between the current process and another + process identified by <c><anno>Item</anno></c>, which can be a + <c>pid()</c> (local or remote), an atom <c>RegisteredName</c> or + a tuple <c>{RegisteredName, Node}</c> for a registered process, + located elsewhere.</p> + </item> + + <tag>Monitoring a <marker id="monitor_port"/><c>port</c></tag> + <item> + <p>Creates monitor between the current process and a port + identified by <c><anno>Item</anno></c>, which can be a + <c>port()</c> (only local), an atom <c>RegisteredName</c> or + a tuple <c>{RegisteredName, Node}</c> for a registered port, + located on this node. Note, that attempt to monitor a remote port + will result in <c>badarg</c>.</p> + </item> + + <tag>Monitoring a + <marker id="monitor_time_offset"/><c>time_offset</c></tag> + <item> + <p>Monitor changes in + <seealso marker="#time_offset/0">time offset</seealso> + between + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso> and + <seealso marker="time_correction#Erlang_System_Time">Erlang + system time</seealso>. There is only one valid + <c><anno>Item</anno></c> in combination with the + <c>time_offset <anno>Type</anno></c>, namely the atom + <c>clock_service</c>. Note that the atom <c>clock_service</c> is + <em>not</em> the registered name of a process. In this specific + case it serves as an identifier of the runtime system internal + clock service at current runtime system instance.</p> + + <p>The monitor is triggered when the time offset is changed. + This either if the time offset value is changed, or if the + offset is changed from preliminary to final during + <seealso marker="#system_flag_time_offset">finalization + of the time offset</seealso> when the + <seealso marker="time_correction#Single_Time_Warp_Mode">single + time warp mode</seealso> is used. When a change from preliminary + to final time offset is made, the monitor will be triggered once + regardless of whether the time offset value was actually changed + or not.</p> + + <p>If the runtime system is in + <seealso marker="time_correction#Multi_Time_Warp_Mode">multi + time warp mode</seealso>, the time offset will be changed when + the runtime system detects that the + <seealso marker="time_correction#OS_System_Time">OS system + time</seealso> has changed. The runtime system will, however, + not detect this immediately when it happens. A task checking + the time offset is scheduled to execute at least once a minute, + so under normal operation this should be detected within a + minute, but during heavy load it might take longer time.</p> + + <p>The monitor will <em>not</em> be automatically removed + after it has been triggered. That is, repeated changes of + the time offset will trigger the monitor repeatedly.</p> + + <p>When the monitor is triggered a <c>'CHANGE'</c> message will + be sent to the monitoring process. A <c>'CHANGE'</c> message has + the following pattern:</p> + <code type="none">{'CHANGE', MonitorRef, Type, Item, NewTimeOffset}</code> + <p>where <c>MonitorRef</c>, <c><anno>Type</anno></c>, and + <c><anno>Item</anno></c> are the same as described above, and + <c>NewTimeOffset</c> is the new time offset.</p> + + <p>When the <c>'CHANGE'</c> message has been received you are + guaranteed not to retrieve the old time offset when calling + <seealso marker="#time_offset/0"><c>erlang:time_offset()</c></seealso>. + Note that you can observe the change of the time offset + when calling <c>erlang:time_offset()</c> before you + get the <c>'CHANGE'</c> message.</p> + </item> + </taglist> + + <p>Making several calls to <c>monitor/2</c> for the same + <c><anno>Item</anno></c> and/or <c><anno>Type</anno></c> is not + an error; it results in as many independent monitoring instances.</p> + + <p>The monitor functionality is expected to be extended. That is, + other <c><anno>Type</anno></c>s and <c><anno>Item</anno></c>s + are expected to be supported in a future release.</p> + + <note> + <p>If or when <c>monitor/2</c> is extended, other + possible values for <c>Tag</c>, <c>Object</c> and + <c>Info</c> in the monitor message will be introduced.</p> + </note> </desc> </func> + <func> <name name="monitor_node" arity="2"/> - <fsummary>Monitor the status of a node</fsummary> + <fsummary>Monitors the status of a node.</fsummary> <desc> - <p>Monitors the status of the node <c><anno>Node</anno></c>. If <c><anno>Flag</anno></c> - is <c>true</c>, monitoring is turned on; if <c><anno>Flag</anno></c> is - <c>false</c>, monitoring is turned off.</p> + <p>Monitors the status of the node <c><anno>Node</anno></c>. + If <c><anno>Flag</anno></c> + is <c>true</c>, monitoring is turned on. If <c><anno>Flag</anno></c> + is <c>false</c>, monitoring is turned off.</p> <p>Making several calls to <c>monitor_node(Node, true)</c> for - the same <c><anno>Node</anno></c> is not an error; it results in as many, - completely independent, monitorings.</p> + the same <c><anno>Node</anno></c> is not an error; it results + in as many independent monitoring instances.</p> <p>If <c><anno>Node</anno></c> fails or does not exist, the message <c>{nodedown, Node}</c> is delivered to the process. If a process has made two calls to <c>monitor_node(Node, true)</c> - and <c><anno>Node</anno></c> terminates, two <c>nodedown</c> messages are - delivered to the process. If there is no connection to - <c><anno>Node</anno></c>, there will be an attempt to create one. If this - fails, a <c>nodedown</c> message is delivered.</p> + and <c><anno>Node</anno></c> terminates, two <c>nodedown</c> messages + are delivered to the process. If there is no connection to + <c><anno>Node</anno></c>, an attempt is made to create one. + If this fails, a <c>nodedown</c> message is delivered.</p> <p>Nodes connected through hidden connections can be monitored - as any other node.</p> - <p>Failure: <c>badarg</c>if the local node is not alive.</p> + as any other nodes.</p> + <p>Failure: <c>badarg</c> if the local node is not alive.</p> </desc> </func> + <func> <name name="monitor_node" arity="3"/> - <fsummary>Monitor the status of a node</fsummary> + <fsummary>Monitors the status of a node.</fsummary> <desc> - <p>Behaves as <c>monitor_node/2</c> except that it allows an + <p>Behaves as + <seealso marker="#monitor_node/2">monitor_node/2</seealso> + except that it allows an extra option to be given, namely <c>allow_passive_connect</c>. - The option allows the BIF to wait the normal net connection - timeout for the <em>monitored node</em> to connect itself, + This option allows the BIF to wait the normal network connection + time-out for the <em>monitored node</em> to connect itself, even if it cannot be actively connected from this node - (i.e. it is blocked). The state where this might be useful can - only be achieved by using the kernel option - <c>dist_auto_connect once</c>. If that kernel option is not - used, the <c>allow_passive_connect</c> option has no - effect.</p> + (that is, it is blocked). The state where this can be useful + can only be achieved by using the <c>Kernel</c> option + <c>dist_auto_connect once</c>. If that option is not + used, option <c>allow_passive_connect</c> has no effect.</p> <note> - <p>The <c>allow_passive_connect</c> option is used + <p>Option <c>allow_passive_connect</c> is used internally and is seldom needed in applications where the - network topology and the kernel options in effect is known in - advance.</p> + network topology and the <c>Kernel</c> options in effect + are known in advance.</p> </note> <p>Failure: <c>badarg</c> if the local node is not alive or the option list is malformed.</p> </desc> </func> + + <func> + <name name="monotonic_time" arity="0"/> + <fsummary>Current Erlang monotonic time.</fsummary> + <desc> + <p>Returns the current + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso> in <c>native</c> + <seealso marker="#type_time_unit">time unit</seealso>. This + is a monotonically increasing time since some unspecified point in + time.</p> + + <note><p>This is a + <seealso marker="time_correction#Monotonically_Increasing">monotonically increasing</seealso> time, but <em>not</em> a + <seealso marker="time_correction#Strictly_Monotonically_Increasing">strictly monotonically increasing</seealso> + time. That is, consecutive calls to + <c>erlang:monotonic_time/0</c> can produce the same result.</p> + + <p>Different runtime system instances will use different + unspecified points in time as base for their Erlang monotonic clocks. + That is, it is <em>pointless</em> comparing monotonic times from + different runtime system instances. Different runtime system instances + may also place this unspecified point in time different relative + runtime system start. It may be placed in the future (time at start + is a negative value), the past (time at start is a + positive value), or the runtime system start (time at start is + zero). The monotonic time at runtime system start can be + retrieved by calling + <seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso>.</p></note> + </desc> + </func> + <func> + <name name="monotonic_time" arity="1"/> + <fsummary>Current Erlang monotonic time</fsummary> + <desc> + <p>Returns the current + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso> converted + into the <c><anno>Unit</anno></c> passed as argument.</p> + + <p>Same as calling + <seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso><c>, + native, <anno>Unit</anno>)</c> + however optimized for commonly used <c><anno>Unit</anno></c>s.</p> + </desc> + </func> <func> <name name="nif_error" arity="1"/> - <fsummary>Stop execution with a given reason</fsummary> + <fsummary>Stops execution with a given reason.</fsummary> <desc> <p>Works exactly like - <seealso marker="#error/1">erlang:error/1</seealso>, - but Dialyzer thinks that this BIF will return an arbitrary term. - When used in a stub function for a NIF to generate an - exception when the NIF library is not loaded, Dialyzer - will not generate false warnings.</p> + <seealso marker="#error/1">erlang:error/1</seealso>, but + <c>Dialyzer</c> thinks that this BIF will return an arbitrary + term. When used in a stub function for a NIF to generate an + exception when the NIF library is not loaded, <c>Dialyzer</c> + does not generate false warnings.</p> </desc> </func> + <func> <name name="nif_error" arity="2"/> - <fsummary>Stop execution with a given reason</fsummary> + <fsummary>Stops execution with a given reason.</fsummary> <desc> <p>Works exactly like - <seealso marker="#error/2">erlang:error/2</seealso>, - but Dialyzer thinks that this BIF will return an arbitrary term. - When used in a stub function for a NIF to generate an - exception when the NIF library is not loaded, Dialyzer - will not generate false warnings.</p> + <seealso marker="#error/2">erlang:error/2</seealso>, but + <c>Dialyzer</c> thinks that this BIF will return an arbitrary + term. When used in a stub function for a NIF to generate an + exception when the NIF library is not loaded, <c>Dialyzer</c> + does not generate false warnings.</p> </desc> </func> + <func> <name name="node" arity="0"/> - <fsummary>Name of the local node</fsummary> + <fsummary>Name of the local node.</fsummary> <desc> <p>Returns the name of the local node. If the node is not alive, <c>nonode@nohost</c> is returned instead.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="node" arity="1"/> - <fsummary>At which node is a pid, port or reference located</fsummary> + <fsummary>At which node a pid, port, or reference originates.</fsummary> <desc> - <p>Returns the node where <c><anno>Arg</anno></c> is located. <c><anno>Arg</anno></c> can - be a pid, a reference, or a port. If the local node is not + <p>Returns the node where <c><anno>Arg</anno></c> originates. + <c><anno>Arg</anno></c> can + be a process identifier, a reference, or a port. + If the local node is not alive, <c>nonode@nohost</c> is returned.</p> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="nodes" arity="0"/> - <fsummary>All visible nodes in the system</fsummary> + <fsummary>All visible nodes in the system.</fsummary> <desc> - <p>Returns a list of all visible nodes in the system, excluding + <p>Returns a list of all visible nodes in the system, except the local node. Same as <c>nodes(visible)</c>.</p> </desc> </func> + <func> <name name="nodes" arity="1"/> - <fsummary>All nodes of a certain type in the system</fsummary> + <fsummary>All nodes of a certain type in the system.</fsummary> <desc> - <p>Returns a list of nodes according to argument given. - The result returned when the argument is a list, is the list + <p>Returns a list of nodes according to the argument given. + The returned result when the argument is a list, is the list of nodes satisfying the disjunction(s) of the list elements.</p> <p><c><anno>NodeType</anno></c> can be any of the following:</p> <taglist> @@ -2572,128 +3269,131 @@ os_prompt% </pre> </item> <tag><c>known</c></tag> <item> - <p>Nodes which are known to this node, i.e., connected, - previously connected, etc.</p> + <p>Nodes that are known to this node. That is, connected + nodes and nodes referred to by process identifiers, port + identifiers and references located on this node. + The set of known nodes is garbage collected. Notice that + this garbage collection can be delayed. For more + information, see + <seealso marker="erlang#system_info_delayed_node_table_gc">delayed_node_table_gc</seealso>. + </p> </item> </taglist> <p>Some equalities: <c>[node()] = nodes(this)</c>, <c>nodes(connected) = nodes([visible, hidden])</c>, and <c>nodes() = nodes(visible)</c>.</p> - <p>If the local node is not alive, - <c>nodes(this) == nodes(known) == [nonode@nohost]</c>, for - any other <c><anno>Arg</anno></c> the empty list [] is returned.</p> </desc> </func> + <func> <name name="now" arity="0"/> + <fsummary>Elapsed time since 00:00 GMT.</fsummary> <type name="timestamp"/> - <fsummary>Elapsed time since 00:00 GMT</fsummary> <desc> + <warning><p><em>This function is deprecated! Do not use it!</em> + See the users guide chapter + <seealso marker="time_correction">Time and Time Correction</seealso> + for more information. Specifically the + <seealso marker="time_correction#Dos_and_Donts">Dos and Dont's</seealso> + section for information on what to use instead of <c>erlang:now/0</c>. + </p></warning> <p>Returns the tuple <c>{MegaSecs, Secs, MicroSecs}</c> which is - the elapsed time since 00:00 GMT, January 1, 1970 (zero hour) + the elapsed time since 00:00 GMT, January 1, 1970 (zero hour), on the assumption that the underlying OS supports this. - Otherwise, some other point in time is chosen. It is also - guaranteed that subsequent calls to this BIF returns + Otherwise some other point in time is chosen. It is also + guaranteed that subsequent calls to this BIF return continuously increasing values. Hence, the return value from - <c>now()</c> can be used to generate unique time-stamps, - and if it is called in a tight loop on a fast machine + <c>now()</c> can be used to generate unique time-stamps. + If it is called in a tight loop on a fast machine, the time of the node can become skewed.</p> - <p>It can only be used to check the local time of day if - the time-zone info of the underlying operating system is + <p>Can only be used to check the local time of day if + the time-zone information of the underlying OS is properly configured.</p> - <p>If you do not need the return value to be unique and - monotonically increasing, use - <seealso marker="kernel:os#timestamp/0">os:timestamp/0</seealso> - instead to avoid some overhead.</p> </desc> </func> + <func> <name name="open_port" arity="2"/> - <fsummary>Open a port</fsummary> + <fsummary>Opens a port.</fsummary> <desc> <p>Returns a port identifier as the result of opening a new Erlang port. A port can be seen as an external Erlang - process. <c><anno>PortName</anno></c> is one of the following:</p> + process.</p> + <p>The name of the executable as well as the arguments + given in <c>cd</c>, <c>env</c>, <c>args</c>, and <c>arg0</c> are + subject to Unicode file name translation if the system is running + in Unicode file name mode. To avoid + translation or to force, for example UTF-8, supply the executable + and/or arguments as a binary in the correct + encoding. For details, see the module + <seealso marker="kernel:file">file</seealso>, the function + <seealso marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>, and the + <seealso marker="stdlib:unicode_usage">STDLIB </seealso> + User's Guide.</p> + <note><p>The characters in the name (if given as a list) can + only be higher than 255 if the Erlang Virtual Machine is started + in Unicode file name translation mode. Otherwise the name + of the executable is limited to the ISO-latin-1 + character set.</p></note> + <p><c><anno>PortName</anno></c> can be any of the following:</p> <taglist> <tag><c>{spawn, <anno>Command</anno>}</c></tag> <item> - <p>Starts an external program. <c><anno>Command</anno></c> is the name - of the external program which will be run. <c><anno>Command</anno></c> + <p>Starts an external program. <c><anno>Command</anno></c> + is the name of the external program to be run. + <c><anno>Command</anno></c> runs outside the Erlang work space unless an Erlang - driver with the name <c><anno>Command</anno></c> is found. If found, - that driver will be started. A driver runs in the Erlang - workspace, which means that it is linked with the Erlang + driver with the name <c><anno>Command</anno></c> is found. + If found, that driver is started. A driver runs in the Erlang + work space, which means that it is linked with the Erlang runtime system.</p> <p>When starting external programs on Solaris, the system call <c>vfork</c> is used in preference to <c>fork</c> for performance reasons, although it has a history of - being less robust. If there are problems with using - <c>vfork</c>, setting the environment variable - <c>ERL_NO_VFORK</c> to any value will cause <c>fork</c> + being less robust. If there are problems using + <c>vfork</c>, setting environment variable + <c>ERL_NO_VFORK</c> to any value causes <c>fork</c> to be used instead.</p> - - <p>For external programs, the <c>PATH</c> is searched + <p>For external programs, <c>PATH</c> is searched (or an equivalent method is used to find programs, - depending on operating system). This is done by invoking - the shell on certain platforms. The first space - separated token of the command will be considered as the + depending on OS). This is done by invoking + the shell on certain platforms. The first space-separated + token of the command is considered as the name of the executable (or driver). This (among other things) makes this option unsuitable for running - programs having spaces in file or directory names. Use - {spawn_executable, <anno>Command</anno>} instead if spaces in executable - file names is desired.</p> + programs having spaces in file names or directory names. + If spaces in executable file names are desired, use + <c>{spawn_executable, <anno>Command</anno>}</c> instead.</p> </item> <tag><c>{spawn_driver, <anno>Command</anno>}</c></tag> <item> <p>Works like <c>{spawn, <anno>Command</anno>}</c>, but demands the - first (space separated) token of the command to be the name of a + first (space-separated) token of the command to be the name of a loaded driver. If no driver with that name is loaded, a <c>badarg</c> error is raised.</p> </item> <tag><c>{spawn_executable, <anno>FileName</anno>}</c></tag> <item> - <p>Works like <c>{spawn, <anno>FileName</anno>}</c>, but only runs - external executables. The <c><anno>FileName</anno></c> in its whole - is used as the name of the executable, including any - spaces. If arguments are to be passed, the - <c>args</c> and <c>arg0</c> <c><anno>PortSettings</anno></c> can be used.</p> - - <p>The shell is not usually invoked to start the - program, it's executed directly. Neither is the - <c>PATH</c> (or equivalent) searched. To find a program - in the PATH to execute, use <seealso - marker="kernel:os#find_executable/1">os:find_executable/1</seealso>.</p> + external executables. <c><anno>FileName</anno></c> in its whole + is used as the name of the executable, including any spaces. + If arguments are to be passed, the <c><anno>PortSettings</anno></c> + <c>args</c> and <c>arg0</c> can be used.</p> + <p>The shell is usually not invoked to start the + program, it is executed directly. <c>PATH</c> (or + equivalent) is not searched. To find a program + in <c>PATH</c> to execute, use + <seealso marker="kernel:os#find_executable/1">os:find_executable/1</seealso>.</p> <p>Only if a shell script or <c>.bat</c> file is - executed, the appropriate command interpreter will - implicitly be invoked, but there will still be no - command argument expansion or implicit PATH search.</p> - - <p>The name of the executable as well as the arguments - given in <c>args</c> and <c>arg0</c> is subject to - Unicode file name translation if the system is running - in Unicode file name mode. To avoid - translation or force i.e. UTF-8, supply the executable - and/or arguments as a binary in the correct - encoding. See the <seealso - marker="kernel:file">file</seealso> module, the - <seealso marker="kernel:file#native_name_encoding/0"> - file:native_name_encoding/0</seealso> function and the - <seealso marker="stdlib:unicode_usage">stdlib users guide - </seealso> for details.</p> - - <note><p>The characters in the name (if given as a list) - can only be > 255 if the Erlang VM is started in - Unicode file name translation mode, otherwise the name - of the executable is limited to the ISO-latin-1 - character set.</p></note> - - <p>If the <c><anno>FileName</anno></c> cannot be run, an error - exception, with the posix error code as the reason, is - raised. The error reason may differ between operating - systems. Typically the error <c>enoent</c> is raised - when one tries to run a program that is not found and - <c>eaccess</c> is raised when the given file is not + executed, the appropriate command interpreter is + invoked implicitly, but there is still no + command argument expansion or implicit <c>PATH</c> search.</p> + <p>If <c><anno>FileName</anno></c> cannot be run, an error + exception is raised, with the POSIX error code as the reason. + The error reason can differ between OSs. + Typically the error <c>enoent</c> is raised when an + attempt is made to run a program that is not found and + <c>eacces</c> is raised when the given file is not executable.</p> </item> <tag><c>{fd, <anno>In</anno>, <anno>Out</anno>}</c></tag> @@ -2702,19 +3402,18 @@ os_prompt% </pre> file descriptors used by Erlang. The file descriptor <c><anno>In</anno></c> can be used for standard input, and the file descriptor <c><anno>Out</anno></c> for standard output. It is only - used for various servers in the Erlang operating system - (<c>shell</c> and <c>user</c>). Hence, its use is very - limited.</p> + used for various servers in the Erlang OS (<c>shell</c> + and <c>user</c>). Hence, its use is limited.</p> </item> </taglist> <p><c><anno>PortSettings</anno></c> is a list of settings for the port. - Valid settings are:</p> + The valid settings are as follows:</p> <taglist> <tag><c>{packet, <anno>N</anno>}</c></tag> <item> <p>Messages are preceded by their length, sent in <c><anno>N</anno></c> - bytes, with the most significant byte first. Valid values - for <c>N</c> are 1, 2, or 4.</p> + bytes, with the most significant byte first. The valid values + for <c>N</c> are 1, 2, and 4.</p> </item> <tag><c>stream</c></tag> <item> @@ -2725,138 +3424,108 @@ os_prompt% </pre> <tag><c>{line, <anno>L</anno>}</c></tag> <item> <p>Messages are delivered on a per line basis. Each line - (delimited by the OS-dependent newline sequence) is - delivered in one single message. The message data format - is <c>{Flag, Line}</c>, where <c>Flag</c> is either - <c>eol</c> or <c>noeol</c> and <c>Line</c> is the actual - data delivered (without the newline sequence).</p> + (delimited by the OS-dependent new line sequence) is + delivered in a single message. The message data format + is <c>{Flag, Line}</c>, where <c>Flag</c> is + <c>eol</c> or <c>noeol</c>, and <c>Line</c> is the + data delivered (without the new line sequence).</p> <p><c><anno>L</anno></c> specifies the maximum line length in bytes. - Lines longer than this will be delivered in more than one - message, with the <c>Flag</c> set to <c>noeol</c> for all + Lines longer than this are delivered in more than one + message, with <c>Flag</c> set to <c>noeol</c> for all but the last message. If end of file is encountered - anywhere else than immediately following a newline - sequence, the last line will also be delivered with - the <c>Flag</c> set to <c>noeol</c>. In all other cases, + anywhere else than immediately following a new line + sequence, the last line is also delivered with + <c>Flag</c> set to <c>noeol</c>. Otherwise lines are delivered with <c>Flag</c> set to <c>eol</c>.</p> - <p>The <c>{packet, <anno>N</anno>}</c> and <c>{line, <anno>L</anno>}</c> settings are - mutually exclusive.</p> + <p>The <c>{packet, <anno>N</anno>}</c> and <c>{line, + <anno>L</anno>}</c> settings are mutually exclusive.</p> </item> <tag><c>{cd, <anno>Dir</anno>}</c></tag> <item> - <p>This is only valid for <c>{spawn, <anno>Command</anno>}</c> and - <c>{spawn_executable, <anno>FileName</anno>}</c>. + <p>Only valid for <c>{spawn, <anno>Command</anno>}</c> and + <c>{spawn_executable, <anno>FileName</anno>}</c>. The external program starts using <c><anno>Dir</anno></c> as its - working directory. <c><anno>Dir</anno></c> must be a string. - </p> + working directory. <c><anno>Dir</anno></c> must be a string.</p> </item> <tag><c>{env, <anno>Env</anno>}</c></tag> <item> - <p>This is only valid for <c>{spawn, <anno>Command</anno>}</c> and + <p>Only valid for <c>{spawn, <anno>Command</anno>}</c> and <c>{spawn_executable, <anno>FileName</anno>}</c>. The environment of the started process is extended using the environment specifications in <c><anno>Env</anno></c>.</p> - <p><c><anno>Env</anno></c> should be a list of tuples <c>{<anno>Name</anno>, <anno>Val</anno>}</c>, - where <c><anno>Name</anno></c> is the name of an environment variable, - and <c><anno>Val</anno></c> is the value it is to have in the spawned - port process. Both <c><anno>Name</anno></c> and <c><anno>Val</anno></c> must be - strings. The one exception is <c><anno>Val</anno></c> being the atom + <p><c><anno>Env</anno></c> is to be a list of tuples + <c>{<anno>Name</anno>, <anno>Val</anno>}</c>, + where <c><anno>Name</anno></c> is the name of an + environment variable, and <c><anno>Val</anno></c> is the + value it is to have in the spawned + port process. Both <c><anno>Name</anno></c> and + <c><anno>Val</anno></c> must be strings. The one + exception is <c><anno>Val</anno></c> being the atom <c>false</c> (in analogy with <c>os:getenv/1</c>), which - removes the environment variable. - </p> - <p>If Unicode filename encoding is in effect (see the <seealso - marker="erts:erl#file_name_encoding">erl manual - page</seealso>), the strings (both <c>Name</c> and - <c>Value</c>) may contain characters with codepoints > 255.</p> + removes the environment variable.</p> </item> <tag><c>{args, [ string() | binary() ]}</c></tag> <item> - - <p>This option is only valid for <c>{spawn_executable, <anno>FileName</anno>}</c> + <p>Only valid for <c>{spawn_executable, <anno>FileName</anno>}</c> and specifies arguments to the executable. Each argument is given as a separate string and (on Unix) eventually ends up as one element each in the argument vector. On - other platforms, similar behavior is mimicked.</p> - - <p>The arguments are not expanded by the shell prior to - being supplied to the executable, most notably this - means that file wildcard expansion will not happen. Use - <seealso - marker="stdlib:filelib#wildcard/1">filelib:wildcard/1</seealso> - to expand wildcards for the arguments. Note that even if + other platforms, a similar behavior is mimicked.</p> + <p>The arguments are not expanded by the shell before + being supplied to the executable. Most notably this + means that file wild card expansion does not happen. + To expand wild cards for the arguments, use + <seealso marker="stdlib:filelib#wildcard/1">filelib:wildcard/1</seealso>. + Notice that even if the program is a Unix shell script, meaning that the - shell will ultimately be invoked, wildcard expansion - will not happen and the script will be provided with the - untouched arguments. On Windows®, wildcard expansion - is always up to the program itself, why this isn't an - issue.</p> - - <p>Note also that the actual executable name (a.k.a. <c>argv[0]</c>) - should not be given in this list. The proper executable name will - automatically be used as argv[0] where applicable.</p> - - <p>When the Erlang VM is running in Unicode file name - mode, the arguments can contain any Unicode characters and - will be translated into whatever is appropriate on the - underlying OS, which means UTF-8 for all platforms except - Windows, which has other (more transparent) ways of - dealing with Unicode arguments to programs. To avoid - Unicode translation of arguments, they can be supplied as - binaries in whatever encoding is deemed appropriate.</p> - - <note><p>The characters in the arguments (if given as a - list of characters) can only be > 255 if the Erlang - VM is started in Unicode file name mode, - otherwise the arguments are limited to the - ISO-latin-1 character set.</p></note> - - <p>If one, for any reason, wants to explicitly set the - program name in the argument vector, the <c>arg0</c> - option can be used.</p> - + shell ultimately is invoked, wild card expansion + does not happen, and the script is provided with the + untouched arguments. On Windows, wild card expansion + is always up to the program itself, therefore this is + not an issue issue.</p> + <p>The executable name (also known as <c>argv[0]</c>) + is not to be given in this list. The proper executable name + is automatically used as argv[0], where applicable.</p> + <p>If you explicitly want to set the + program name in the argument vector, option <c>arg0</c> + can be used.</p> </item> <tag><c>{arg0, string() | binary()}</c></tag> <item> - - <p>This option is only valid for <c>{spawn_executable, <anno>FileName</anno>}</c> + <p>Only valid for <c>{spawn_executable, <anno>FileName</anno>}</c> and explicitly specifies the program name argument when - running an executable. This might in some circumstances, - on some operating systems, be desirable. How the program - responds to this is highly system dependent and no specific + running an executable. This can in some circumstances, + on some OSs, be desirable. How the program + responds to this is highly system-dependent and no specific effect is guaranteed.</p> - - <p>The unicode file name translation rules of the - <c>args</c> option apply to this option as well.</p> - </item> - <tag><c>exit_status</c></tag> <item> - <p>This is only valid for <c>{spawn, <anno>Command</anno>}</c> where - <c><anno>Command</anno></c> refers to an external program, and for - <c>{spawn_executable, <anno>FileName</anno>}</c>.</p> + <p>Only valid for <c>{spawn, <anno>Command</anno>}</c>, where + <c><anno>Command</anno></c> refers to an external program, and + for <c>{spawn_executable, <anno>FileName</anno>}</c>.</p> <p>When the external process connected to the port exits, a message of the form <c>{Port,{exit_status,Status}}</c> is sent to the connected process, where <c>Status</c> is the exit status of the external process. If the program - aborts, on Unix the same convention is used as the shells - do (i.e., 128+signal).</p> - <p>If the <c>eof</c> option has been given as well, - the <c>eof</c> message and the <c>exit_status</c> message - appear in an unspecified order.</p> - <p>If the port program closes its stdout without exiting, - the <c>exit_status</c> option will not work.</p> + aborts on Unix, the same convention is used as the shells + do (that is, 128+signal).</p> + <p>If option <c>eof</c> is also given, the messages <c>eof</c> + and <c>exit_status</c> appear in an unspecified order.</p> + <p>If the port program closes its <c>stdout</c> without exiting, + option <c>exit_status</c> does not work.</p> </item> <tag><c>use_stdio</c></tag> <item> - <p>This is only valid for <c>{spawn, <anno>Command</anno>}</c> and + <p>Only valid for <c>{spawn, <anno>Command</anno>}</c> and <c>{spawn_executable, <anno>FileName</anno>}</c>. It allows the standard input and output (file descriptors 0 - and 1) of the spawned (UNIX) process for communication + and 1) of the spawned (Unix) process for communication with Erlang.</p> </item> <tag><c>nouse_stdio</c></tag> <item> - <p>The opposite of <c>use_stdio</c>. Uses file descriptors + <p>The opposite of <c>use_stdio</c>. It uses file descriptors 3 and 4 for communication with Erlang.</p> </item> <tag><c>stderr_to_stdout</c></tag> @@ -2868,14 +3537,15 @@ os_prompt% </pre> </item> <tag><c>overlapped_io</c></tag> <item> - <p>Affects ports to external programs on Windows® only. - The standard input and standard output handles of the port program - will, if this option is supplied, be opened with the flag - FILE_FLAG_OVERLAPPED, so that the port program can (and has to) do + <p>Affects ports to external programs on Windows only. The + standard input and standard output handles of the port program + are, if this option is supplied, opened with flag + <c>FILE_FLAG_OVERLAPPED</c>, so that the port program can + (and must) do overlapped I/O on its standard handles. This is not normally the case for simple port programs, but an option of value for the - experienced Windows programmer. <em>On all other platforms, this - option is silently discarded</em>.</p> + experienced Windows programmer. <em>On all other platforms, this + option is silently discarded.</em></p> </item> <tag><c>in</c></tag> <item> @@ -2887,485 +3557,632 @@ os_prompt% </pre> </item> <tag><c>binary</c></tag> <item> - <p>All IO from the port are binary data objects as opposed + <p>All I/O from the port is binary data objects as opposed to lists of bytes.</p> </item> <tag><c>eof</c></tag> <item> - <p>The port will not be closed at the end of the file and - produce an exit signal. Instead, it will remain open and - a <c>{Port, eof}</c> message will be sent to the process + <p>The port is not closed at the end of the file and does not + produce an exit signal. Instead, it remains open and + a <c>{Port, eof}</c> message is sent to the process holding the port.</p> </item> <tag><c>hide</c></tag> <item> - <p>When running on Windows, suppress creation of a new + <p>When running on Windows, suppresses creation of a new console window when spawning the port program. (This option has no effect on other platforms.)</p> </item> - <tag><marker id="open_port_parallelism"><c>{parallelism, Boolean}</c></marker></tag> + <tag><c>{parallelism, Boolean}</c></tag> <item> - <p>Set scheduler hint for port parallelism. If set to <c>true</c>, - the VM will schedule port tasks when it by this can improve the - parallelism in the system. If set to <c>false</c>, the VM will - try to perform port tasks immediately and by this improving the - latency at the expense of parallelism. The default can be set on - system startup by passing the - <seealso marker="erl#+spp">+spp</seealso> command line argument - to <seealso marker="erl">erl(1)</seealso>. - </p> + <marker id="open_port_parallelism"></marker> + <p>Sets scheduler hint for port parallelism. If set to + <c>true</c>, the Virtual Machine schedules port tasks; + when doing so, it improves parallelism in the system. If set + to <c>false</c>, the Virtual Machine tries to + perform port tasks immediately, improving latency at the + expense of parallelism. The default can be set at system startup + by passing command-line argument + <seealso marker="erl#+spp">+spp</seealso> to <c>erl(1)</c>.</p> </item> </taglist> - <p>The default is <c>stream</c> for all types of port and + <p>Default is <c>stream</c> for all port types and <c>use_stdio</c> for spawned ports.</p> <p>Failure: If the port cannot be opened, the exit reason is - <c>badarg</c>, <c>system_limit</c>, or the Posix error code which - most closely describes the error, or <c>einval</c> if no Posix code - is appropriate:</p> + <c>badarg</c>, <c>system_limit</c>, or the POSIX error code that + most closely describes the error, or <c>einval</c> if no POSIX + code is appropriate:</p> <taglist> <tag><c>badarg</c></tag> - <item> - <p>Bad input arguments to <c>open_port</c>.</p> + <item>Bad input arguments to <c>open_port</c>. </item> <tag><c>system_limit</c></tag> - <item> - <p>All available ports in the Erlang emulator are in use.</p> + <item>All available ports in the Erlang emulator are in use. </item> <tag><c>enomem</c></tag> - <item> - <p>There was not enough memory to create the port.</p> + <item>Not enough memory to create the port. </item> <tag><c>eagain</c></tag> - <item> - <p>There are no more available operating system processes.</p> + <item>No more available OS processes. </item> <tag><c>enametoolong</c></tag> - <item> - <p>The external command given was too long.</p> + <item>Too long external command. </item> <tag><c>emfile</c></tag> - <item> - <p>There are no more available file descriptors (for the operating system process - that the Erlang emulator runs in).</p> + <item>No more available file descriptors (for the + OS process that the Erlang emulator runs in). </item> <tag><c>enfile</c></tag> - <item> - <p>The file table is full (for the entire operating system).</p> + <item>Full file table (for the entire OS). </item> <tag><c>eacces</c></tag> - <item> - <p>The <c>Command</c> given in <c>{spawn_executable, Command}</c> does not point out an executable file.</p> + <item><c>Command</c> given in <c>{spawn_executable, Command}</c> + does not point out an executable file. </item> <tag><c>enoent</c></tag> - <item> - <p>The <c><anno>FileName</anno></c> given in <c>{spawn_executable, <anno>FileName</anno>}</c> does not point out an existing file.</p> + <item><c><anno>FileName</anno></c> given in + <c>{spawn_executable, <anno>FileName</anno>}</c> + does not point out an existing file. </item> </taglist> <p>During use of a port opened using <c>{spawn, Name}</c>, - <c>{spawn_driver, Name}</c> or <c>{spawn_executable, Name}</c>, + <c>{spawn_driver, Name}</c>, or <c>{spawn_executable, Name}</c>, errors arising when sending messages to it are reported to the owning process using signals of the form - <c>{'EXIT', Port, PosixCode}</c>. See <c>file(3)</c> for - possible values of <c>PosixCode</c>.</p> + <c>{'EXIT', Port, PosixCode}</c>. For the possible values of + <c>PosixCode</c>, see the + <seealso marker="kernel:file">file(3)</seealso> + manual page in <c>Kernel</c>.</p> <p>The maximum number of ports that can be open at the same - time can be configured by passing the - <seealso marker="erl#max_ports"><c>+Q</c></seealso> - command line flag to - <seealso marker="erl"><c>erl(1)</c></seealso>.</p> + time can be configured by passing command-line flag + <seealso marker="erl#max_ports"><c>+Q</c></seealso> to + <c>erl(1)</c>.</p> </desc> </func> + <func> <name name="phash" arity="2"/> + <fsummary>Portable hash function.</fsummary> <type_desc variable="Range">Range = 1..2^32, Hash = 1..Range</type_desc> - <fsummary>Portable hash function</fsummary> <desc> - <p>Portable hash function that will give the same hash for + <p>Portable hash function that gives the same hash for the same Erlang term regardless of machine architecture and - ERTS version (the BIF was introduced in ERTS 4.9.1.1). Range - can be between 1 and 2^32, the function returns a hash value - for <c><anno>Term</anno></c> within the range <c>1..<anno>Range</anno></c>.</p> - <p>This BIF could be used instead of the old deprecated - <c>erlang:hash/2</c> BIF, as it calculates better hashes for - all data-types, but consider using <c>phash2/1,2</c> instead.</p> + <c>ERTS</c> version (the BIF was introduced in <c>ERTS</c> 4.9.1.1). + The function returns a hash value for + <c><anno>Term</anno></c> within the range + <c>1..<anno>Range</anno></c>. The maximum value for + <c><anno>Range</anno></c> is 2^32.</p> + <p>This BIF can be used instead of the old deprecated BIF + <c>erlang:hash/2</c>, as it calculates better hashes for + all data types, but consider using <c>phash2/1,2</c> instead.</p> </desc> </func> + <func> <name name="phash2" arity="1"/> <name name="phash2" arity="2"/> + <fsummary>Portable hash function.</fsummary> <type_desc variable="Range">1..2^32</type_desc> <type_desc variable="Hash">0..Range-1</type_desc> - <fsummary>Portable hash function</fsummary> <desc> - <p>Portable hash function that will give the same hash for + <p>Portable hash function that gives the same hash for the same Erlang term regardless of machine architecture and - ERTS version (the BIF was introduced in ERTS 5.2). Range can - be between 1 and 2^32, the function returns a hash value for - <c><anno>Term</anno></c> within the range <c>0..<anno>Range</anno>-1</c>. When called - without the <c><anno>Range</anno></c> argument, a value in the range - <c>0..2^27-1</c> is returned.</p> - <p>This BIF should always be used for hashing terms. It + <c>ERTS</c> version (the BIF was introduced in <c>ERTS</c> 5.2). + The function returns a hash value for + <c><anno>Term</anno></c> within the range + <c>0..<anno>Range</anno>-1</c>. The maximum value for + <c><anno>Range</anno></c> is 2^32. When without argument + <c><anno>Range</anno></c>, a value in the range + 0..2^27-1 is returned.</p> + <p>This BIF is always to be used for hashing terms. It distributes small integers better than <c>phash/2</c>, and it is faster for bignums and binaries.</p> - <p>Note that the range <c>0..<anno>Range</anno>-1</c> is different from - the range of <c>phash/2</c> (<c>1..<anno>Range</anno></c>).</p> + <p>Notice that the range <c>0..<anno>Range</anno>-1</c> is + different from the range of <c>phash/2</c>, which is + <c>1..<anno>Range</anno></c>.</p> </desc> </func> + <func> <name name="pid_to_list" arity="1"/> - <fsummary>Text representation of a pid</fsummary> + <fsummary>Text representation of a pid.</fsummary> <desc> - <p>Returns a string which corresponds to the text + <p>Returns a string corresponding to the text representation of <c><anno>Pid</anno></c>.</p> <warning> - <p>This BIF is intended for debugging and for use in - the Erlang operating system. It should not be used in - application programs.</p> + <p>This BIF is intended for debugging and is not to be used + in application programs.</p> </warning> </desc> </func> + <func> <name name="port_close" arity="1"/> - <fsummary>Close an open port</fsummary> + <fsummary>Closes an open port.</fsummary> <desc> <p>Closes an open port. Roughly the same as - <c><anno>Port</anno> ! {self(), close}</c> except for the error behaviour - (see below), being synchronous, and that the port does - <em>not</em> reply with <c>{Port, closed}</c>. Any process may + <c><anno>Port</anno> ! {self(), close}</c> except for the error behavior + (see the following), being synchronous, and that the port does + <em>not</em> reply with <c>{Port, closed}</c>. Any process can close a port with <c>port_close/1</c>, not only the port owner - (the connected process).</p> - <p>For comparison: <c><anno>Port</anno> ! {self(), close}</c> fails with - <c>badarg</c> if <c><anno>Port</anno></c> cannot be sent to (i.e., - <c><anno>Port</anno></c> refers neither to a port nor to a process). If - <c><anno>Port</anno></c> is a closed port nothing happens. If <c><anno>Port</anno></c> + (the connected process). If the calling process is linked to + the port identified by <c><anno>Port</anno></c>, the exit + signal from the port is guaranteed to be delivered before + <c>port_close/1</c> returns.</p> + <p>For comparison: <c><anno>Port</anno> ! {self(), close}</c> + only fails with <c>badarg</c> if <c><anno>Port</anno></c> does + not refer to a port or a process. If <c><anno>Port</anno></c> + is a closed port, nothing happens. If <c><anno>Port</anno></c> is an open port and the calling process is the port owner, - the port replies with <c>{Port, closed}</c> when all buffers - have been flushed and the port really closes, but if - the calling process is not the port owner the <em>port owner</em> fails with <c>badsig</c>.</p> - <p>Note that any process can close a port using - <c><anno>Port</anno> ! {PortOwner, close}</c> just as if it itself was + the port replies with <c>{Port, closed}</c> when all buffers + have been flushed and the port really closes. If the calling + process is not the port owner, the <em>port owner</em> fails + with <c>badsig</c>.</p> + <p>Notice that any process can close a port using + <c><anno>Port</anno> ! {PortOwner, close}</c> as if it itself was the port owner, but the reply always goes to the port owner.</p> - <p>As of OTP-R16 <c><anno>Port</anno> ! {PortOwner, close}</c> is truly - asynchronous. Note that this operation has always been + <p>As from OTP R16, <c><anno>Port</anno> ! {PortOwner, close}</c> is truly + asynchronous. Notice that this operation has always been documented as an asynchronous operation, while the underlying implementation has been synchronous. <c>port_close/1</c> is - however still fully synchronous. This due to its error + however still fully synchronous. This because of its error behavior.</p> - <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an open port or - the registered name of an open port.</p> + <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an identifier + of an open port, or the registered name of an open port. + If the calling process was previously linked to the closed + port, identified by <c><anno>Port</anno></c>, the exit + signal from the port is guaranteed to be delivered before + this <c>badarg</c> exception occurs.</p> </desc> </func> + <func> <name name="port_command" arity="2"/> - <fsummary>Send data to a port</fsummary> + <fsummary>Sends data to a port.</fsummary> <desc> <p>Sends data to a port. Same as - <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c> except for the error - behaviour and being synchronous (see below). Any process may - send data to a port with <c>port_command/2</c>, not only the + <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c> except + for the error + behavior and being synchronous (see the following). Any process + can send data to a port with <c>port_command/2</c>, not only the port owner (the connected process).</p> <p>For comparison: <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c> - fails with <c>badarg</c> if <c><anno>Port</anno></c> cannot be sent to - (i.e., <c><anno>Port</anno></c> refers neither to a port nor to a process). - If <c><anno>Port</anno></c> is a closed port the data message disappears + only fails with <c>badarg</c> if <c><anno>Port</anno></c> + does not refer to a port or a process. If + <c><anno>Port</anno></c> is a closed port, the data message + disappears without a sound. If <c><anno>Port</anno></c> is open and the calling process is not the port owner, the <em>port owner</em> fails with <c>badsig</c>. The port owner fails with <c>badsig</c> - also if <c><anno>Data</anno></c> is not a valid IO list.</p> - <p>Note that any process can send to a port using - <c><anno>Port</anno> ! {PortOwner, {command, <anno>Data</anno>}}</c> just as if it - itself was the port owner.</p> - <p>If the port is busy, the calling process will be suspended - until the port is not busy anymore.</p> - <p>As of OTP-R16 <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c> is - truly asynchronous. Note that this operation has always been + also if <c><anno>Data</anno></c> is an invalid I/O list.</p> + <p>Notice that any process can send to a port using + <c><anno>Port</anno> ! {PortOwner, {command, <anno>Data</anno>}}</c> + as if it itself was the port owner.</p> + <p>If the port is busy, the calling process is suspended + until the port is not busy any more.</p> + <p>As from OTP-R16, <c><anno>Port</anno> ! {PortOwner, {command, Data}}</c> + is truly asynchronous. Notice that this operation has always been documented as an asynchronous operation, while the underlying implementation has been synchronous. <c>port_command/2</c> is - however still fully synchronous. This due to its error + however still fully synchronous. This because of its error behavior.</p> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> <item> - If <c><anno>Port</anno></c> is not an open port or the registered name - of an open port. + If <c><anno>Port</anno></c> is not an identifier of an open + port, or the registered name of an open port. If the + calling process was previously linked to the closed port, + identified by <c><anno>Port</anno></c>, the exit signal + from the port is guaranteed to be delivered before this + <c>badarg</c> exception occurs. </item> <tag><c>badarg</c></tag> <item> - If <c><anno>Data</anno></c> is not a valid io list. + If <c><anno>Data</anno></c> is an invalid I/O list. </item> </taglist> </desc> </func> + <func> <name name="port_command" arity="3"/> - <fsummary>Send data to a port</fsummary> + <fsummary>Sends data to a port.</fsummary> <desc> <p>Sends data to a port. <c>port_command(Port, Data, [])</c> equals <c>port_command(Port, Data)</c>.</p> - <p>If the port command is aborted <c>false</c> is returned; - otherwise, <c>true</c> is returned.</p> - <p>If the port is busy, the calling process will be suspended - until the port is not busy anymore.</p> - <p>Currently the following <c><anno>Option</anno></c>s are valid:</p> + <p>If the port command is aborted, <c>false</c> is returned, + otherwise <c>true</c>.</p> + <p>If the port is busy, the calling process is suspended + until the port is not busy any more.</p> + <p>The following <c><anno>Option</anno></c>s are valid:</p> <taglist> <tag><c>force</c></tag> - <item>The calling process will not be suspended if the port is - busy; instead, the port command is forced through. The - call will fail with a <c>notsup</c> exception if the + <item>The calling process is not suspended if the port is + busy, instead the port command is forced through. The + call fails with a <c>notsup</c> exception if the driver of the port does not support this. For more - information see the - <seealso marker="driver_entry#driver_flags"><![CDATA[ERL_DRV_FLAG_SOFT_BUSY]]></seealso> - driver flag. + information, see driver flag + <seealso marker="driver_entry#driver_flags"><![CDATA[ERL_DRV_FLAG_SOFT_BUSY]]></seealso>. </item> <tag><c>nosuspend</c></tag> - <item>The calling process will not be suspended if the port is - busy; instead, the port command is aborted and + <item>The calling process is not suspended if the port is + busy, instead the port command is aborted and <c>false</c> is returned. </item> </taglist> <note> - <p>More options may be added in the future.</p> + <p>More options can be added in a future release.</p> </note> <p>Failures:</p> <taglist> <tag><c>badarg</c></tag> <item> - If <c><anno>Port</anno></c> is not an open port or the registered name - of an open port. + If <c><anno>Port</anno></c> is not an identifier of an open + port, or the registered name of an open port. If the + calling process was previously linked to the closed port, + identified by <c><anno>Port</anno></c>, the exit signal + from the port is guaranteed to be delivered before this + <c>badarg</c> exception occurs. </item> <tag><c>badarg</c></tag> <item> - If <c><anno>Data</anno></c> is not a valid io list. + If <c><anno>Data</anno></c> is an invalid I/O list. </item> <tag><c>badarg</c></tag> <item> - If <c><anno>OptionList</anno></c> is not a valid option list. + If <c><anno>OptionList</anno></c> is an invalid option list. </item> <tag><c>notsup</c></tag> <item> - If the <c>force</c> option has been passed, but the + If option <c>force</c> has been passed, but the driver of the port does not allow forcing through a busy port. </item> </taglist> </desc> </func> + <func> <name name="port_connect" arity="2"/> - <fsummary>Set the owner of a port</fsummary> + <fsummary>Sets the owner of a port.</fsummary> <desc> <p>Sets the port owner (the connected port) to <c><anno>Pid</anno></c>. - Roughly the same as <c><anno>Port</anno> ! {Owner, {connect, <anno>Pid</anno>}}</c> + Roughly the same as + <c><anno>Port</anno> ! {Owner, {connect, <anno>Pid</anno>}}</c> except for the following:</p> <list type="bulleted"> <item> - <p>The error behavior differs, see below.</p> + <p>The error behavior differs, see the following.</p> </item> <item> <p>The port does <em>not</em> reply with <c>{Port,connected}</c>.</p> </item> <item> - <p><c>port_connect/1</c> is synchronous, see below.</p> + <p><c>port_connect/1</c> is synchronous, see the following.</p> </item> <item> <p>The new port owner gets linked to the port.</p> </item> </list> - <p>The old port owner stays linked to the port and have to call - <c>unlink(Port)</c> if this is not desired. Any process may + <p>The old port owner stays linked to the port and must call + <c>unlink(Port)</c> if this is not desired. Any process can set the port owner to be any process with <c>port_connect/2</c>.</p> - <p>For comparison: <c><anno>Port</anno> ! {self(), {connect, <anno>Pid</anno>}}</c> fails - with <c>badarg</c> if <c><anno>Port</anno></c> cannot be sent to (i.e., - <c><anno>Port</anno></c> refers neither to a port nor to a process). If - <c><anno>Port</anno></c> is a closed port nothing happens. If <c><anno>Port</anno></c> + <p>For comparison: + <c><anno>Port</anno> ! {self(), {connect, <anno>Pid</anno>}}</c> + only fails with <c>badarg</c> if <c><anno>Port</anno></c> + does not refer to a port or a process. If + <c><anno>Port</anno></c> is a closed port, nothing happens. + If <c><anno>Port</anno></c> is an open port and the calling process is the port owner, the port replies with <c>{Port, connected}</c> to the old - port owner. Note that the old port owner is still linked to - the port, and that the new is not. If <c><anno>Port</anno></c> is an open + port owner. Notice that the old port owner is still linked to + the port, while the new is not. If <c><anno>Port</anno></c> is an open port and the calling process is not the port owner, the <em>port owner</em> fails with <c>badsig</c>. The port owner fails with <c>badsig</c> also if <c><anno>Pid</anno></c> is not an - existing local pid.</p> - <p>Note that any process can set the port owner using - <c><anno>Port</anno> ! {PortOwner, {connect, <anno>Pid</anno>}}</c> just as if it - itself was the port owner, but the reply always goes to + existing local process identifier.</p> + <p>Notice that any process can set the port owner using + <c><anno>Port</anno> ! {PortOwner, {connect, <anno>Pid</anno>}}</c> + as if it itself was the port owner, but the reply always goes to the port owner.</p> - <p>As of OTP-R16 <c><anno>Port</anno> ! {PortOwner, {connect, <anno>Pid</anno>}}</c> is - truly asynchronous. Note that this operation has always been + <p>As from OTP-R16, + <c><anno>Port</anno> ! {PortOwner, {connect, <anno>Pid</anno>}}</c> is + truly asynchronous. Notice that this operation has always been documented as an asynchronous operation, while the underlying implementation has been synchronous. <c>port_connect/2</c> is - however still fully synchronous. This due to its error + however still fully synchronous. This because of its error behavior.</p> - <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an open port - or the registered name of an open port, or if <c>Pid</c> is - not an existing local pid.</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Port</anno></c> is not an identifier of an open port, or + the registered name of an open port. If the calling + process was previously linked to the closed port, + identified by <c><anno>Port</anno></c>, the exit signal + from the port is guaranteed to be delivered before this + <c>badarg</c> exception occurs. + </item> + <tag><c>badarg</c></tag> + <item>If process identified by <c>Pid</c> is not an existing + local process.</item> + </taglist> </desc> </func> + <func> <name name="port_control" arity="3"/> - <fsummary>Perform a synchronous control operation on a port</fsummary> + <fsummary>Performs a synchronous control operation on a port.</fsummary> <desc> <p>Performs a synchronous control operation on a port. - The meaning of <c><anno>Operation</anno></c> and <c><anno>Data</anno></c> depends on - the port, i.e., on the port driver. Not all port drivers + The meaning of <c><anno>Operation</anno></c> and + <c><anno>Data</anno></c> depends on + the port, that is, on the port driver. Not all port drivers support this control feature.</p> - <p>Returns: a list of integers in the range 0 through 255, or a + <p>Returns a list of integers in the range 0..255, or a binary, depending on the port driver. The meaning of the returned data also depends on the port driver.</p> - <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an open port or - the registered name of an open port, if <c><anno>Operation</anno></c> - cannot fit in a 32-bit integer, if the port driver does not - support synchronous control operations, or if the port driver - so decides for any reason (probably something wrong with - <c><anno>Operation</anno></c> or <c><anno>Data</anno></c>).</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Port</anno></c> is not an open port or the registered + name of an open port. + </item> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Operation</anno></c> cannot fit in a 32-bit integer. + </item> + <tag><c>badarg</c></tag> + <item> + If the port driver does not support synchronous control + operations. + </item> + <tag><c>badarg</c></tag> + <item> + If the port driver so decides for any reason (probably + something wrong with <c><anno>Operation</anno></c> or + <c><anno>Data</anno></c>). + </item> + </taglist> </desc> </func> + <func> <name name="port_call" arity="3"/> - <fsummary>Synchronous call to a port with term data</fsummary> + <fsummary>Performs a synchronous call to a port with term data.</fsummary> <desc> <p>Performs a synchronous call to a port. The meaning of - <c><anno>Operation</anno></c> and <c><anno>Data</anno></c> depends on the port, i.e., + <c><anno>Operation</anno></c> and <c><anno>Data</anno></c> + depends on the port, that is, on the port driver. Not all port drivers support this feature.</p> - <p><c><anno>Port</anno></c> is a port identifier, referring to a driver.</p> + <p><c><anno>Port</anno></c> is a port identifier, + referring to a driver.</p> <p><c><anno>Operation</anno></c> is an integer, which is passed on to the driver.</p> - <p><c><anno>Data</anno></c> is any Erlang term. This data is converted to - binary term format and sent to the port.</p> - <p>Returns: a term from the driver. The meaning of the returned + <p><c><anno>Data</anno></c> is any Erlang term. This data is converted + to binary term format and sent to the port.</p> + <p>Returns a term from the driver. The meaning of the returned data also depends on the port driver.</p> - <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not an open port or - the registered name of an open port, if <c><anno>Operation</anno></c> - cannot fit in a 32-bit integer, if the port driver does not - support synchronous control operations, or if the port driver - so decides for any reason (probably something wrong with - <c><anno>Operation</anno></c> or <c><anno>Data</anno></c>).</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Port</anno></c> is not an identifier of an open port, + or the registered name of an open port. If the calling + process was previously linked to the closed port, + identified by <c><anno>Port</anno></c>, the exit signal + from the port is guaranteed to be delivered before this + <c>badarg</c> exception occurs. + </item> + <tag><c>badarg</c></tag> + <item> + If <c><anno>Operation</anno></c> does not fit in a 32-bit integer. + </item> + <tag><c>badarg</c></tag> + <item> + If the port driver does not support synchronous control + operations. + </item> + <tag><c>badarg</c></tag> + <item> + If the port driver so decides for any reason (probably + something wrong with <c><anno>Operation</anno></c> + or <c><anno>Data</anno></c>). + </item> + </taglist> </desc> </func> + <func> <name name="port_info" arity="1"/> - <fsummary>Information about a port</fsummary> + <fsummary>Information about a port.</fsummary> <desc> <p>Returns a list containing tuples with information about - the <c><anno>Port</anno></c>, or <c>undefined</c> if the port is not open. - The order of the tuples is not defined, nor are all the - tuples mandatory.</p> - <p>Currently the result will containt information about the - following <c>Item</c>s: <c>registered_name</c> (if the port has - a registered name), <c>id</c>, <c>connected</c>, <c>links</c>, - <c>name</c>, <c>input</c>, and <c>output</c>. For more information - about the different <c>Item</c>s, see + <c><anno>Port</anno></c>, or <c>undefined</c> if the port is not open. + The order of the tuples is undefined, and all the + tuples are not mandatory. + If the port is closed and the calling process + was previously linked to the port, the exit signal from the + port is guaranteed to be delivered before <c>port_info/1</c> + returns <c>undefined</c>.</p> + <p>The result contains information about the following + <c>Item</c>s:</p> + <list type="bulleted"> + <item><c>registered_name</c> (if the port has a registered + name)</item> + <item><c>id</c></item> + <item><c>connected</c></item> + <item><c>links</c></item> + <item><c>name</c></item> + <item><c>input</c></item> + <item><c>output</c></item> + </list> + <p>For more information about the different <c>Item</c>s, see <seealso marker="#port_info/2">port_info/2</seealso>.</p> <p>Failure: <c>badarg</c> if <c>Port</c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> <name name="port_info" arity="2" clause_i="1"/> - <fsummary>Information about the connected process of a port</fsummary> + <fsummary>Information about the connected process of a port.</fsummary> <desc> <p><c><anno>Pid</anno></c> is the process identifier of the process connected to the port.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> <name name="port_info" arity="2" clause_i="2"/> - <fsummary>Information about the internal index of a port</fsummary> + <fsummary>Information about the internal index of a port.</fsummary> <desc> <p><c><anno>Index</anno></c> is the internal index of the port. This - index may be used to separate ports.</p> + index can be used to separate ports.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> <name name="port_info" arity="2" clause_i="3"/> - <fsummary>Information about the input of a port</fsummary> + <fsummary>Information about the input of a port.</fsummary> <desc> <p><c><anno>Bytes</anno></c> is the total number of bytes read from the port.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> <name name="port_info" arity="2" clause_i="4"/> - <fsummary>Information about the links of a port</fsummary> + <fsummary>Information about the links of a port.</fsummary> <desc> <p><c><anno>Pids</anno></c> is a list of the process identifiers of the processes that the port is linked to.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> <name name="port_info" arity="2" clause_i="5"/> - <fsummary>Information about the locking of a port</fsummary> + <fsummary>Information about the locking of a port.</fsummary> <desc> - <p><c><anno>Locking</anno></c> is currently either <c>false</c> - (emulator without SMP support), <c>port_level</c> (port specific - locking), or <c>driver_level</c> (driver specific locking). Note - that these results are highly implementation specific and might - change in the future.</p> + <p><c><anno>Locking</anno></c> is one of the following:</p> + <list type="bulleted"> + <item><c>false</c> (emulator without SMP support)</item> + <item><c>port_level</c> (port-specific locking)</item> + <item><c>driver_level</c> (driver-specific locking)</item> + </list> + <p>Notice that these results are highly implementation-specific + and can change in a future release.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> <name name="port_info" arity="2" clause_i="6"/> - <fsummary>Information about the memory size of a port</fsummary> + <fsummary>Information about the memory size of a port.</fsummary> <desc> - <p><c><anno>Bytes</anno></c> is the total amount of memory, - in bytes, allocated for this port by the runtime system. Note - that the port itself might have allocated memory which is not + <p><c><anno>Bytes</anno></c> is the total number of + bytes allocated for this port by the runtime system. The + port itself can have allocated memory that is not included in <c><anno>Bytes</anno></c>.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> <name name="port_info" arity="2" clause_i="7"/> - <fsummary>Information about the monitors of a port</fsummary> + <fsummary>Information about the monitors of a port.</fsummary> <desc> <p><c><anno>Monitors</anno></c> represent processes that this port - is monitoring.</p> + monitors.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> <name name="port_info" arity="2" clause_i="8"/> - <fsummary>Information about the name of a port</fsummary> + <fsummary>Which processes are monitoring this port.</fsummary> + <desc> + <p>Returns list of pids that are monitoring given port at the + moment.</p> + <p>If the port identified by <c><anno>Port</anno></c> is not open, + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> + <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local + port identifier, or an atom.</p> + </desc> + </func> + + <func> + <name name="port_info" arity="2" clause_i="9"/> + <fsummary>Information about the name of a port.</fsummary> <desc> <p><c><anno>Name</anno></c> is the command name set by <seealso marker="#open_port/2">open_port/2</seealso>.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> - <name name="port_info" arity="2" clause_i="9"/> - <fsummary>Information about the OS pid of a port</fsummary> + <name name="port_info" arity="2" clause_i="10"/> + <fsummary>Information about the OS pid of a port.</fsummary> <desc> <p><c><anno>OsPid</anno></c> is the process identifier (or equivalent) of an OS process created with @@ -3373,416 +4190,600 @@ os_prompt% </pre> Command}, Options)</seealso>. If the port is not the result of spawning an OS process, the value is <c>undefined</c>.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> - <name name="port_info" arity="2" clause_i="10"/> - <fsummary>Information about the output of a port</fsummary> + <name name="port_info" arity="2" clause_i="11"/> + <fsummary>Information about the output of a port.</fsummary> <desc> <p><c><anno>Bytes</anno></c> is the total number of bytes written - to the port from Erlang processes using either + to the port from Erlang processes using <seealso marker="#port_command/2">port_command/2</seealso>, <seealso marker="#port_command/3">port_command/3</seealso>, - or <c><anno>Port</anno> ! {Owner, {command, Data}</c>. - </p> + or <c><anno>Port</anno> ! {Owner, {command, Data}</c>.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> - <name name="port_info" arity="2" clause_i="11"/> - <fsummary>Information about the parallelism hint of a port</fsummary> + <name name="port_info" arity="2" clause_i="12"/> + <fsummary>Information about the parallelism hint of a port.</fsummary> <desc> <p><c><anno>Boolean</anno></c> corresponds to the port parallelism - hint being used by this port. For more information see - the <seealso marker="#open_port_parallelism">parallelism</seealso> - option of <seealso marker="#open_port/2">open_port/2</seealso>.</p> + hint being used by this port. For more information, see option + <seealso marker="#open_port_parallelism">parallelism</seealso> + of <seealso marker="#open_port/2">open_port/2</seealso>.</p> </desc> </func> + <func> - <name name="port_info" arity="2" clause_i="12"/> - <fsummary>Information about the queue size of a port</fsummary> + <name name="port_info" arity="2" clause_i="13"/> + <fsummary>Information about the queue size of a port.</fsummary> <desc> - <p><c><anno>Bytes</anno></c> is the total amount of data, - in bytes, queued by the port using the ERTS driver queue + <p><c><anno>Bytes</anno></c> is the total number + of bytes queued by the port using the <c>ERTS</c> driver queue implementation.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> - <name name="port_info" arity="2" clause_i="13"/> - <fsummary>Information about the registered name of a port</fsummary> + <name name="port_info" arity="2" clause_i="14"/> + <fsummary>Information about the registered name of a port.</fsummary> <desc> <p><c><anno>RegisteredName</anno></c> is the registered name of the port. If the port has no registered name, <c>[]</c> is returned.</p> <p>If the port identified by <c><anno>Port</anno></c> is not open, - <c>undefined</c> is returned.</p> + <c>undefined</c> is returned. If the port is closed and the + calling process was previously linked to the port, the exit + signal from the port is guaranteed to be delivered before + <c>port_info/2</c> returns <c>undefined</c>.</p> <p>Failure: <c>badarg</c> if <c><anno>Port</anno></c> is not a local port identifier, or an atom.</p> </desc> </func> + <func> <name name="port_to_list" arity="1"/> - <fsummary>Text representation of a port identifier</fsummary> + <fsummary>Text representation of a port identifier.</fsummary> <desc> - <p>Returns a string which corresponds to the text + <p>Returns a string corresponding to the text representation of the port identifier <c><anno>Port</anno></c>.</p> <warning> - <p>This BIF is intended for debugging and for use in - the Erlang operating system. It should not be used in - application programs.</p> + <p>This BIF is intended for debugging. It is not to be used + in application programs.</p> </warning> </desc> </func> + <func> <name name="ports" arity="0"/> - <fsummary>All open ports</fsummary> + <fsummary>Lists all existing ports.</fsummary> <desc> <p>Returns a list of port identifiers corresponding to all the - ports currently existing on the local node.</p> - - <p>Note that a port that is exiting, exists but is not open.</p> + ports existing on the local node.</p> + <p>Notice that an exiting port exists, but is not open.</p> </desc> </func> + <func> <name name="pre_loaded" arity="0"/> - <fsummary>List of all pre-loaded modules</fsummary> + <fsummary>Lists all pre-loaded modules.</fsummary> <desc> - <p>Returns a list of Erlang modules which are pre-loaded in + <p>Returns a list of Erlang modules that are preloaded in the system. As all loading of code is done through the file system, the file system must have been loaded previously. - Hence, at least the module <c>init</c> must be pre-loaded.</p> + Hence, at least the module <c>init</c> must be preloaded.</p> </desc> </func> + <func> <name name="process_display" arity="2"/> - <fsummary>Write information about a local process on standard error</fsummary> + <fsummary>Writes information about a local process on standard error.</fsummary> <desc> <p>Writes information about the local process <c><anno>Pid</anno></c> on - standard error. The currently allowed value for the atom + standard error. The only allowed value for the atom <c><anno>Type</anno></c> is <c>backtrace</c>, which shows the contents of the call stack, including information about the call chain, with the current function printed first. The format of the output is not further defined.</p> </desc> </func> + <func> <name name="process_flag" arity="2" clause_i="1"/> - <fsummary>Set process flag trap_exit for the calling process</fsummary> + <fsummary>Sets process flag <c>trap_exit</c> for the calling process.</fsummary> <desc> <p>When <c>trap_exit</c> is set to <c>true</c>, exit signals - arriving to a process are converted to <c>{'EXIT', From, Reason}</c> messages, which can be received as ordinary + arriving to a process are converted to <c>{'EXIT', From, Reason}</c> + messages, which can be received as ordinary messages. If <c>trap_exit</c> is set to <c>false</c>, the process exits if it receives an exit signal other than <c>normal</c> and the exit signal is propagated to its - linked processes. Application processes should normally - not trap exits.</p> + linked processes. Application processes are normally + not to trap exits.</p> <p>Returns the old value of the flag.</p> <p>See also <seealso marker="#exit/2">exit/2</seealso>.</p> </desc> </func> + <func> <name name="process_flag" arity="2" clause_i="2"/> - <fsummary>Set process flag error_handler for the calling process</fsummary> + <fsummary>Sets process flag <c>error_handler</c> for the calling process.</fsummary> <desc> - <p>This is used by a process to redefine the error handler + <p>Used by a process to redefine the error handler for undefined function calls and undefined registered - processes. Inexperienced users should not use this flag - since code auto-loading is dependent on the correct + processes. Inexperienced users are not to use this flag, + as code auto-loading depends on the correct operation of the error handling module.</p> <p>Returns the old value of the flag.</p> </desc> </func> + + <marker id="process_flag_min_heap_size"/> <func> <name name="process_flag" arity="2" clause_i="3"/> - <fsummary>Set process flag min_heap_size for the calling process</fsummary> + <fsummary>Sets process flag <c>min_heap_size</c> for the calling process.</fsummary> <desc> - <p>This changes the minimum heap size for the calling - process.</p> + <p>Changes the minimum heap size for the calling process.</p> <p>Returns the old value of the flag.</p> </desc> </func> + <func> <name name="process_flag" arity="2" clause_i="4"/> - <fsummary>Set process flag min_bin_vheap_size for the calling process</fsummary> + <fsummary>Sets process flag <c>min_bin_vheap_size</c> for the calling process.</fsummary> <desc> - <p>This changes the minimum binary virtual heap size for the calling + <p>Changes the minimum binary virtual heap size for the calling process.</p> - <p>Returns the old value of the flag.</p> </desc> + <p>Returns the old value of the flag.</p> + </desc> </func> + <marker id="process_flag_max_heap_size"/> <func> <name name="process_flag" arity="2" clause_i="5"/> - <type name="priority_level"/> - <fsummary>Set process flag priority for the calling process</fsummary> + <fsummary>Sets process flag <c>max_heap_size</c> for the calling process.</fsummary> + <type name="max_heap_size"/> <desc> - <p><marker id="process_flag_priority"></marker> - This sets the process priority. <c><anno>Level</anno></c> is an atom. - There are currently four priority levels: <c>low</c>, - <c>normal</c>, <c>high</c>, and <c>max</c>. The default - priority level is <c>normal</c>. <em>NOTE</em>: The - <c>max</c> priority level is reserved for internal use in - the Erlang runtime system, and should <em>not</em> be used - by others. + <p> + This flag sets the maximum heap size for the calling process. + If <c><anno>MaxHeapSize</anno></c> is an integer, the system default + values for <c>kill</c> and <c>error_logger</c> are used. </p> - <p>Internally in each priority level processes are scheduled - in a round robin fashion. + <taglist> + <tag><c>size</c></tag> + <item> + <p> + The maximum size in words of the process. If set to zero, the + heap size limit is disabled. Badarg will be thrown if the value is + smaller than + <seealso marker="#process_flag_min_heap_size"><c>min_heap_size</c></seealso>. + The size check is only done when a garbage collection is triggered. + </p> + <p> + <c>size</c> is the entire heap of the process when garbage collection + is triggered, this includes all generational heaps, the process stack, + any <seealso marker="#process_flag_message_queue_data"> + messages that are considered to be part of the heap</seealso> and any + extra memory that the garbage collector needs during collection. + </p> + <p> + <c>size</c> is the same as can be retrieved using + <seealso marker="#process_info_total_heap_size"> + <c>erlang:process_info(Pid, total_heap_size)</c></seealso>, + or by adding <c>heap_block_size</c>, <c>old_heap_block_size</c> + and <c>mbuf_size</c> from <seealso marker="#process_info_garbage_collection_info"> + <c>erlang:process_info(Pid, garbage_collection_info)</c></seealso>. + </p> + </item> + <tag><c>kill</c></tag> + <item> + <p> + When set to <c>true</c> the runtime system will send an + untrappable exit signal with reason <c>kill</c> to the process + if the maximum heap size is reached. The garbage collection + that triggered the <c>kill</c> will not be completed, instead the + process will exit as soon as is possible. When set to <c>false</c> + no exit signal will be sent to the process, instead it will + continue executing. + </p> + <p> + If <c>kill</c> is not defined in the map + the system default will be used. The default system default + is <c>true</c>. It can be changed by either the erl + <seealso marker="erl#+hmaxk">+hmaxk</seealso> option, + or <seealso marker="#system_flag_max_heap_size"><c> + erlang:system_flag(max_heap_size, MaxHeapSize)</c></seealso>. + </p> + </item> + <tag><c>error_logger</c></tag> + <item> + <p> + When set to <c>true</c> the runtime system will send a + message to the current <seealso marker="kernel:error_logger"><c>error_logger</c></seealso> + containing details about the process when the maximum + heap size is reached. One <c>error_logger</c> report will + be sent each time the limit is reached. + </p> + <p> + If <c>error_logger</c> is not defined in the map the system + default will be used. The default system default is <c>true</c>. + It can be changed by either the erl <seealso marker="erl#+hmaxel">+hmaxel</seealso> + option, or <seealso marker="#system_flag_max_heap_size"><c> + erlang:system_flag(max_heap_size, MaxHeapSize)</c></seealso>. + </p> + </item> + </taglist> + <p> + The heap size of a process is quite hard to predict, especially the + amount of memory that is used during the garbage collection. When + contemplating using this option, it is recommended to first run + it in production with <c>kill</c> set to <c>false</c> and inspect + the <c>error_logger</c> reports to see what the normal peak sizes + of the processes in the system is and then tune the value + accordingly. </p> + </desc> + </func> + <marker id="process_flag_message_queue_data"/> + <func> + <name name="process_flag" arity="2" clause_i="6"/> + <fsummary>Set process flag <c>message_queue_data</c> for the calling process</fsummary> + <type name="message_queue_data"/> + <desc> + <p>This flag determines how messages in the message queue + are stored. When the flag is:</p> + <taglist> + <tag><c>off_heap</c></tag> + <item><p> + <em>All</em> messages in the message queue will be stored + outside of the process heap. This implies that <em>no</em> + messages in the message queue will be part of a garbage + collection of the process. + </p></item> + <tag><c>on_heap</c></tag> + <item><p> + All messages in the message queue will eventually be + placed on heap. They may however temporarily be stored + off heap. This is how messages always have been stored + up until ERTS version 8.0. + </p></item> + </taglist> + <p> + The default <c>message_queue_data</c> process flag is determined + by the <seealso marker="erl#+hmqd"><c>+hmqd</c></seealso> + <c>erl</c> command line argument. + </p> + <p> + If the process potentially may get a hugh amount of messages, + you are recommended to set the flag to <c>off_heap</c>. This + since a garbage collection with lots of messages placed on + the heap may become extremly expensive and the process may + consume large amounts of memory. Performance of the + actual message passing is however generally better when not + using the <c>off_heap</c> flag. + </p> + <p> + When changing this flag messages will be moved. This work + has been initiated but not completed when this function + call returns. + </p> + <p>Returns the old value of the flag.</p> + </desc> + </func> + <func> + <name name="process_flag" arity="2" clause_i="7"/> + <fsummary>Sets process flag <c>priority</c> for the calling process.</fsummary> + <type name="priority_level"/> + <desc> + <p><marker id="process_flag_priority"></marker> + Sets the process priority. <c><anno>Level</anno></c> is an atom. + There are four priority levels: <c>low</c>, + <c>normal</c>, <c>high</c>, and <c>max</c>. Default + is <c>normal</c>.</p> + <note> + <p>Priority level <c>max</c> is reserved for internal use in + the Erlang runtime system, and is <em>not</em> to be used + by others.</p> + </note> + <p>Internally in each priority level, processes are scheduled + in a round robin fashion.</p> <p>Execution of processes on priority <c>normal</c> and - priority <c>low</c> will be interleaved. Processes on - priority <c>low</c> will be selected for execution less - frequently than processes on priority <c>normal</c>. - </p> - <p>When there are runnable processes on priority <c>high</c> - no processes on priority <c>low</c>, or <c>normal</c> will - be selected for execution. Note, however, that this does - <em>not</em> mean that no processes on priority <c>low</c>, - or <c>normal</c> will be able to run when there are - processes on priority <c>high</c> running. On the runtime - system with SMP support there might be more processes running - in parallel than processes on priority <c>high</c>, i.e., - a <c>low</c>, and a <c>high</c> priority process might - execute at the same time. - </p> - <p>When there are runnable processes on priority <c>max</c> + <c>low</c> are interleaved. Processes on priority + <c>low</c> are selected for execution less + frequently than processes on priority <c>normal</c>.</p> + <p>When there are runnable processes on priority <c>high</c>, + no processes on priority <c>low</c> or <c>normal</c> are + selected for execution. Notice however, that this does + <em>not</em> mean that no processes on priority <c>low</c> + or <c>normal</c> can run when there are processes + running on priority <c>high</c>. On the runtime + system with SMP support, more processes can be running + in parallel than processes on priority <c>high</c>, that is, + a <c>low</c> and a <c>high</c> priority process can + execute at the same time.</p> + <p>When there are runnable processes on priority <c>max</c>, no processes on priority <c>low</c>, <c>normal</c>, or - <c>high</c> will be selected for execution. As with the - <c>high</c> priority, processes on lower priorities might - execute in parallel with processes on priority <c>max</c>. - </p> + <c>high</c> are selected for execution. As with priority + <c>high</c>, processes on lower priorities can + execute in parallel with processes on priority <c>max</c>.</p> <p>Scheduling is preemptive. Regardless of priority, a process - is preempted when it has consumed more than a certain amount + is preempted when it has consumed more than a certain number of reductions since the last time it was selected for - execution. - </p> - <p><em>NOTE</em>: You should not depend on the scheduling + execution.</p> + <note> + <p>Do not depend on the scheduling to remain exactly as it is today. Scheduling, at least on - the runtime system with SMP support, is very likely to be - modified in the future in order to better utilize available - processor cores. - </p> - <p>There is currently <em>no</em> automatic mechanism for - avoiding priority inversion, such as priority inheritance, - or priority ceilings. When using priorities you have - to take this into account and handle such scenarios by - yourself. - </p> + the runtime system with SMP support, is likely to be + changed in a future release to use available + processor cores better.</p> + </note> + <p>There is <em>no</em> automatic mechanism for + avoiding priority inversion, such as priority inheritance + or priority ceilings. When using priorities, + take this into account and handle such scenarios by + yourself.</p> <p>Making calls from a <c>high</c> priority process into code - that you don't have control over may cause the <c>high</c> - priority process to wait for a processes with lower - priority, i.e., effectively decreasing the priority of the + that you have no control over can cause the <c>high</c> + priority process to wait for a process with lower + priority. That is, effectively decreasing the priority of the <c>high</c> priority process during the call. Even if this - isn't the case with one version of the code that you don't - have under your control, it might be the case in a future - version of it. This might, for example, happen if a - <c>high</c> priority process triggers code loading, since - the code server runs on priority <c>normal</c>. - </p> + is not the case with one version of the code that you have no + control over, it can be the case in a future + version of it. This can, for example, occur if a + <c>high</c> priority process triggers code loading, as + the code server runs on priority <c>normal</c>.</p> <p>Other priorities than <c>normal</c> are normally not needed. - When other priorities are used, they need to be used - with care, especially the <c>high</c> priority <em>must</em> - be used with care. A process on <c>high</c> priority should - only perform work for short periods of time. Busy looping for - long periods of time in a <c>high</c> priority process will - most likely cause problems, since there are important servers - in OTP running on priority <c>normal</c>. - </p> + When other priorities are used, use them with care, + <em>especially</em> priority <c>high</c>. A + process on priority <c>high</c> is only + to perform work for short periods. Busy looping for + long periods in a <c>high</c> priority process does + most likely cause problems, as important OTP servers + run on priority <c>normal</c>.</p> <p>Returns the old value of the flag.</p> </desc> </func> + <func> - <name name="process_flag" arity="2" clause_i="6"/> - <fsummary>Set process flag save_calls for the calling process</fsummary> + <name name="process_flag" arity="2" clause_i="8"/> + <fsummary>Sets process flag <c>save_calls</c> for the calling process.</fsummary> <desc> <p><c><anno>N</anno></c> must be an integer in the interval 0..10000. - If <c><anno>N</anno></c> > 0, call saving is made active for the - process, which means that information about the <c><anno>N</anno></c> - most recent global function calls, BIF calls, sends and + If <c><anno>N</anno></c> is greater than 0, call saving is made + active for the + process. This means that information about the <c><anno>N</anno></c> + most recent global function calls, BIF calls, sends, and receives made by the process are saved in a list, which can be retrieved with <c>process_info(Pid, last_calls)</c>. A global function call is one in which the module of the function is explicitly mentioned. Only a fixed amount of information - is saved: a tuple <c>{Module, Function, Arity}</c> for - function calls, and the mere atoms <c>send</c>, - <c>'receive'</c> and <c>timeout</c> for sends and receives - (<c>'receive'</c> when a message is received and - <c>timeout</c> when a receive times out). If <c>N</c> = 0, + is saved, as follows:</p> + <list type="bulleted"> + <item>A tuple <c>{Module, Function, Arity}</c> for + function calls</item> + <item> The atoms <c>send</c>, <c>'receive'</c>, and + <c>timeout</c> for sends and receives (<c>'receive'</c> + when a message is received and <c>timeout</c> when a + receive times out)</item> + </list> + <p>If <c>N</c> = 0, call saving is disabled for the process, which is the default. Whenever the size of the call saving list is set, its contents are reset.</p> <p>Returns the old value of the flag.</p> </desc> </func> + <func> - <name name="process_flag" arity="2" clause_i="7"/> - <fsummary>Set process flag sensitive for the calling process</fsummary> + <name name="process_flag" arity="2" clause_i="9"/> + <fsummary>Sets process flag <c>sensitive</c> for the calling process.</fsummary> <desc> - <p>Set or clear the <c>sensitive</c> flag for the current process. + <p>Sets or clears flag <c>sensitive</c> for the current process. When a process has been marked as sensitive by calling - <c>process_flag(sensitive, true)</c>, features in the run-time - system that can be used for examining the data and/or inner working + <c>process_flag(sensitive, true)</c>, features in the runtime + system that can be used for examining the data or inner working of the process are silently disabled.</p> <p>Features that are disabled include (but are not limited to) the following:</p> - <p>Tracing: Trace flags can still be set for the process, but no - trace messages of any kind will be generated. - (If the <c>sensitive</c> flag is turned off, trace messages will - again be generated if there are any trace flags set.)</p> - <p>Sequential tracing: The sequential trace token will be propagated - as usual, but no sequential trace messages will be generated.</p> - <p><c>process_info/1,2</c> cannot be used to read out the message - queue or the process dictionary (both will be returned as empty lists).</p> + <list type="bulleted"> + <item>Tracing: Trace flags can still be set for the process, + but no trace messages of any kind are generated. (If flag + <c>sensitive</c> is turned off, trace messages are again + generated if any trace flags are set.)</item> + <item>Sequential tracing: The sequential trace token is + propagated as usual, but no sequential trace messages are + generated.</item> + </list> + <p><c>process_info/1,2</c> cannot be used to read out the + message queue or the process dictionary (both are returned + as empty lists).</p> <p>Stack back-traces cannot be displayed for the process.</p> <p>In crash dumps, the stack, messages, and the process dictionary - will be omitted.</p> + are omitted.</p> <p>If <c>{save_calls,N}</c> has been set for the process, no - function calls will be saved to the call saving list. - (The call saving list will not be cleared; furthermore, send, receive, - and timeout events will still be added to the list.)</p> + function calls are saved to the call saving list. + (The call saving list is not cleared. Furthermore, send, receive, + and timeout events are still added to the list.)</p> <p>Returns the old value of the flag.</p> </desc> </func> + <func> <name name="process_flag" arity="3"/> - <fsummary>Set process flags for a process</fsummary> + <fsummary>Sets process flags for a process.</fsummary> <desc> - <p>Sets certain flags for the process <c><anno>Pid</anno></c>, in the same - manner as + <p>Sets certain flags for the process <c><anno>Pid</anno></c>, + in the same manner as <seealso marker="#process_flag/2">process_flag/2</seealso>. - Returns the old value of the flag. The allowed values for + Returns the old value of the flag. The valid values for <c><anno>Flag</anno></c> are only a subset of those allowed in - <c>process_flag/2</c>, namely: <c>save_calls</c>.</p> - <p>Failure: <c>badarg</c> if <c><anno>Pid</anno></c> is not a local process.</p> + <c>process_flag/2</c>, namely <c>save_calls</c>.</p> + <p>Failure: <c>badarg</c> if <c><anno>Pid</anno></c> + is not a local process.</p> </desc> </func> + <func> <name name="process_info" arity="1"/> + <fsummary>Information about a process.</fsummary> <type name="process_info_result_item"/> <type name="priority_level"/> <type name="stack_item"/> - <fsummary>Information about a process</fsummary> + <type name="max_heap_size" /> + <type name="message_queue_data" /> <desc> <p>Returns a list containing <c><anno>InfoTuple</anno></c>s with miscellaneous information about the process identified by - <c>Pid</c>, or <c>undefined</c> if the process is not alive. - </p> - <p> - The order of the <c><anno>InfoTuple</anno></c>s is not defined, nor - are all the <c><anno>InfoTuple</anno></c>s mandatory. The <c><anno>InfoTuple</anno></c>s - part of the result may be changed without prior notice. - Currently <c><anno>InfoTuple</anno></c>s with the following items - are part of the result: - <c>current_function</c>, <c>initial_call</c>, <c>status</c>, - <c>message_queue_len</c>, <c>messages</c>, <c>links</c>, - <c>dictionary</c>, <c>trap_exit</c>, <c>error_handler</c>, - <c>priority</c>, <c>group_leader</c>, <c>total_heap_size</c>, - <c>heap_size</c>, <c>stack_size</c>, <c>reductions</c>, and - <c>garbage_collection</c>. - If the process identified by <c><anno>Pid</anno></c> has a registered name - also an <c><anno>InfoTuple</anno></c> with the item <c>registered_name</c> - will appear. - </p> - <p>See <seealso marker="#process_info/2">process_info/2</seealso> - for information about specific <c><anno>InfoTuple</anno></c>s.</p> + <c>Pid</c>, or <c>undefined</c> if the process is not alive.</p> + <p>The order of the <c><anno>InfoTuple</anno></c>s is undefined and + all <c><anno>InfoTuple</anno></c>s are not mandatory. + The <c><anno>InfoTuple</anno></c>s + part of the result can be changed without prior notice.</p> + <p>The <c><anno>InfoTuple</anno></c>s with the following items + are part of the result:</p> + <list type="bulleted"> + <item><c>current_function</c></item> + <item><c>initial_call</c></item> + <item><c>status</c></item> + <item><c>message_queue_len</c></item> + <item><c>messages</c></item> + <item><c>links</c></item> + <item><c>dictionary</c></item> + <item><c>trap_exit</c></item> + <item><c>error_handler</c></item> + <item><c>priority</c></item> + <item><c>group_leader</c></item> + <item><c>total_heap_size</c></item> + <item><c>heap_size</c></item> + <item><c>stack_size</c></item> + <item><c>reductions</c></item> + <item><c>garbage_collection</c></item> + </list> + <p>If the process identified by <c><anno>Pid</anno></c> has a + registered name, + also an <c><anno>InfoTuple</anno></c> with item <c>registered_name</c> + appears.</p> + <p>For information about specific <c><anno>InfoTuple</anno></c>s, see + <seealso marker="#process_info/2">process_info/2</seealso>.</p> <warning> - <p>This BIF is intended for <em>debugging only</em>, use - <seealso marker="#process_info/2">process_info/2</seealso> - for all other purposes. - </p> + <p>This BIF is intended for <em>debugging only</em>. For + all other purposes, use + <seealso marker="#process_info/2">process_info/2</seealso>.</p> </warning> - <p>Failure: <c>badarg</c> if <c>Pid</c> is not a local process.</p> + <p>Failure: <c>badarg</c> if <c><anno>Pid</anno></c> is not a + local process.</p> </desc> </func> + <func> <name name="process_info" arity="2" clause_i="1"/> <name name="process_info" arity="2" clause_i="2"/> + <fsummary>Information about a process.</fsummary> <type name="process_info_item"/> <type name="process_info_result_item"/> <type name="stack_item"/> <type name="priority_level"/> - <fsummary>Information about a process</fsummary> - <desc> - <p>Returns information about the process identified by <c><anno>Pid</anno></c> - as specified by the <c><anno>Item</anno></c> or the <c><anno>ItemList</anno></c>, or <c>undefined</c> if the - process is not alive. - </p> - <p>If the process is alive and a single <c><anno>Item</anno></c> is given, - the returned value is the corresponding - <c><anno>InfoTuple</anno></c> unless <c>Item =:= registered_name</c> - and the process has no registered name. In this case - <c>[]</c> is returned. This strange behavior is due to - historical reasons, and is kept for backward compatibility. - </p> - <p>If an <c>ItemList</c> is given, the result is an - <c><anno>InfoTupleList</anno></c>. The <c><anno>InfoTuple</anno></c>s in the - <c><anno>InfoTupleList</anno></c> will appear with the corresponding - <c><anno>Item</anno></c>s in the same order as the <c><anno>Item</anno></c>s appeared - in the <c><anno>ItemList</anno></c>. Valid <c><anno>Item</anno></c>s may appear multiple - times in the <c><anno>ItemList</anno></c>. - </p> - <note><p>If <c>registered_name</c> is part of an <c><anno>ItemList</anno></c> + <type name="max_heap_size" /> + <type name="message_queue_data" /> + <desc> + <p>Returns information about the process identified by + <c><anno>Pid</anno></c>, as specified by + <c><anno>Item</anno></c> or <c><anno>ItemList</anno></c>. + Returns <c>undefined</c> if the process is not alive.</p> + <p>If the process is alive and a single <c><anno>Item</anno></c> + is given, the returned value is the corresponding + <c><anno>InfoTuple</anno></c>, unless <c>Item =:= registered_name</c> + and the process has no registered name. In this case, + <c>[]</c> is returned. This strange behavior is because of + historical reasons, and is kept for backward compatibility.</p> + <p>If <c><anno>ItemList</anno></c> is given, the result is + <c><anno>InfoTupleList</anno></c>. + The <c><anno>InfoTuple</anno></c>s in + <c><anno>InfoTupleList</anno></c> appear with the corresponding + <c><anno>Item</anno></c>s in the same order as the + <c><anno>Item</anno></c>s appeared + in <c><anno>ItemList</anno></c>. Valid <c><anno>Item</anno></c>s can + appear multiple times in <c><anno>ItemList</anno></c>.</p> + <note><p>If <c>registered_name</c> is part of <c><anno>ItemList</anno></c> and the process has no name registered a - <c>{registered_name, []}</c> <c><anno>InfoTuple</anno></c> <em>will</em> - appear in the resulting <c><anno>InfoTupleList</anno></c>. This - behavior is different than when a single - <c>Item =:= registered_name</c> is given, and than when - <c>process_info/1</c> is used. - </p></note> - <p>Currently the following <c><anno>InfoTuple</anno></c>s with corresponding + <c>{registered_name, []}</c>, <c><anno>InfoTuple</anno></c> + <em>will</em> appear in the resulting + <c><anno>InfoTupleList</anno></c>. This + behavior is different when a single + <c>Item =:= registered_name</c> is given, and when + <c>process_info/1</c> is used.</p> + </note> + <p>The following <c><anno>InfoTuple</anno></c>s with corresponding <c><anno>Item</anno></c>s are valid:</p> <taglist> <tag><c>{backtrace, <anno>Bin</anno>}</c></tag> <item> - <p>The binary <c><anno>Bin</anno></c> contains the same information as - the output from + <p>Binary <c><anno>Bin</anno></c> contains the same information + as the output from <c>erlang:process_display(<anno>Pid</anno>, backtrace)</c>. Use <c>binary_to_list/1</c> to obtain the string of characters from the binary.</p> </item> <tag><c>{binary, <anno>BinInfo</anno>}</c></tag> <item> - <p><c><anno>BinInfo</anno></c> is a list containing miscellaneous information - about binaries currently being referred to by this process. - This <c><anno>InfoTuple</anno></c> may be changed or removed without prior - notice.</p> + <p><c><anno>BinInfo</anno></c> is a list containing miscellaneous + information about binaries currently being referred to by this + process. This <c><anno>InfoTuple</anno></c> can be changed or + removed without prior notice.</p> </item> <tag><c>{catchlevel, <anno>CatchLevel</anno>}</c></tag> <item> <p><c><anno>CatchLevel</anno></c> is the number of currently active - catches in this process. This <c><anno>InfoTuple</anno></c> may be + catches in this process. This <c><anno>InfoTuple</anno></c> can be changed or removed without prior notice.</p> </item> - <tag><c>{current_function, {<anno>Module</anno>, <anno>Function</anno>, <anno>Arity</anno>}}</c></tag> + <tag><c>{current_function, {<anno>Module</anno>, + <anno>Function</anno>, Arity}}</c></tag> <item> - <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>, <c><anno>Arity</anno></c> is + <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>, + <c><anno>Arity</anno></c> is the current function call of the process.</p> </item> - <tag><c>{current_location, {<anno>Module</anno>, <anno>Function</anno>, <anno>Arity</anno>, <anno>Location</anno>}}</c></tag> + <tag><c>{current_location, {<anno>Module</anno>, + <anno>Function</anno>, <anno>Arity</anno>, + <anno>Location</anno>}}</c></tag> <item> - <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>, <c><anno>Arity</anno></c> is + <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>, + <c><anno>Arity</anno></c> is the current function call of the process. - <c><anno>Location</anno></c> is a list of two-tuples that describes the - location in the source code. - </p> + <c><anno>Location</anno></c> is a list of two-tuples describing the + location in the source code.</p> </item> <tag><c>{current_stacktrace, <anno>Stack</anno>}</c></tag> <item> - <p>Return the current call stack back-trace (<em>stacktrace</em>) + <p>Returns the current call stack back-trace (<em>stacktrace</em>) of the process. The stack has the same format as returned by - <seealso marker="#get_stacktrace/0">erlang:get_stacktrace/0</seealso>. - </p> + <seealso marker="#get_stacktrace/0">erlang:get_stacktrace/0</seealso>.</p> </item> <tag><c>{dictionary, <anno>Dictionary</anno>}</c></tag> <item> - <p><c><anno>Dictionary</anno></c> is the dictionary of the process.</p> + <p><c><anno>Dictionary</anno></c> is the process dictionary.</p> </item> <tag><c>{error_handler, <anno>Module</anno>}</c></tag> <item> @@ -3791,34 +4792,50 @@ os_prompt% </pre> </item> <tag><c>{garbage_collection, <anno>GCInfo</anno>}</c></tag> <item> - <p><c><anno>GCInfo</anno></c> is a list which contains miscellaneous + <p><c><anno>GCInfo</anno></c> is a list containing miscellaneous information about garbage collection for this process. - The content of <c><anno>GCInfo</anno></c> may be changed without + The content of <c><anno>GCInfo</anno></c> can be changed without prior notice.</p> </item> + <tag> + <marker id="process_info_garbage_collection_info"/> + <c>{garbage_collection_info, <anno>GCInfo</anno>}</c> + </tag> + <item> + <p><c><anno>GCInfo</anno></c> is a list containing miscellaneous + detailed information about garbage collection for this process. + The content of <c><anno>GCInfo</anno></c> can be changed without + prior notice. + See <seealso marker="#gc_minor_start">gc_minor_start</seealso> in + <seealso marker="#trace/3">erlang:trace/3</seealso> for details about + what each item means. + </p> + </item> <tag><c>{group_leader, <anno>GroupLeader</anno>}</c></tag> <item> - <p><c><anno>GroupLeader</anno></c> is group leader for the IO of + <p><c><anno>GroupLeader</anno></c> is group leader for the I/O of the process.</p> </item> <tag><c>{heap_size, <anno>Size</anno>}</c></tag> <item> - <p><c><anno>Size</anno></c> is the size in words of youngest heap generation - of the process. This generation currently include the stack - of the process. This information is highly implementation - dependent, and may change if the implementation change. - </p> + <p><c><anno>Size</anno></c> is the size in words of the youngest heap + generation of the process. This generation includes + the process stack. This information is highly + implementation-dependent, and can change if the + implementation changes.</p> </item> - <tag><c>{initial_call, {Module, Function, Arity}}</c></tag> + <tag><c>{initial_call, {<anno>Module</anno>, <anno>Function</anno>, + <anno>Arity</anno>}}</c></tag> <item> - <p><c>Module</c>, <c>Function</c>, <c>Arity</c> is + <p><c><anno>Module</anno></c>, <c><anno>Function</anno></c>, + <c><anno>Arity</anno></c> is the initial function call with which the process was spawned.</p> </item> <tag><c>{links, <anno>PidsAndPorts</anno>}</c></tag> <item> - <p><c><anno>PidsAndPorts</anno></c> is a list of pids and - port identifiers, with processes or ports to which the process + <p><c><anno>PidsAndPorts</anno></c> is a list of process identifiers + and port identifiers, with processes or ports to which the process has a link.</p> </item> <tag><c>{last_calls, false|Calls}</c></tag> @@ -3832,14 +4849,14 @@ os_prompt% </pre> <tag><c>{memory, <anno>Size</anno>}</c></tag> <item> <p><c><anno>Size</anno></c> is the size in bytes of the process. This - includes call stack, heap and internal structures.</p> + includes call stack, heap, and internal structures.</p> </item> <tag><c>{message_queue_len, <anno>MessageQueueLen</anno>}</c></tag> <item> <p><c><anno>MessageQueueLen</anno></c> is the number of messages currently in the message queue of the process. This is the length of the list <c><anno>MessageQueue</anno></c> returned as - the info item <c>messages</c> (see below).</p> + the information item <c>messages</c> (see the following).</p> </item> <tag><c>{messages, <anno>MessageQueue</anno>}</c></tag> <item> @@ -3848,31 +4865,53 @@ os_prompt% </pre> </item> <tag><c>{min_heap_size, <anno>MinHeapSize</anno>}</c></tag> <item> - <p><c><anno>MinHeapSize</anno></c> is the minimum heap size for the process.</p> + <p><c><anno>MinHeapSize</anno></c> is the minimum heap size + for the process.</p> </item> <tag><c>{min_bin_vheap_size, <anno>MinBinVHeapSize</anno>}</c></tag> <item> - <p><c><anno>MinBinVHeapSize</anno></c> is the minimum binary virtual heap size for the process.</p> + <p><c><anno>MinBinVHeapSize</anno></c> is the minimum binary virtual + heap size for the process.</p> </item> <tag><c>{monitored_by, <anno>Pids</anno>}</c></tag> <item> - <p>A list of pids that are monitoring the process (with + <p>A list of process identifiers monitoring the process (with <c>monitor/2</c>).</p> </item> <tag><c>{monitors, <anno>Monitors</anno>}</c></tag> <item> <p>A list of monitors (started by <c>monitor/2</c>) that are active for the process. For a local process - monitor or a remote process monitor by pid, the list item - is <c>{process, <anno>Pid</anno>}</c>, and for a remote process - monitor by name, the list item is - <c>{process, {<anno>RegName</anno>, <anno>Node</anno>}}</c>.</p> + monitor or a remote process monitor by a process + identifier, the list consists of:</p> + <taglist> + <tag><c>{process, <anno>Pid</anno>}</c></tag> + <item>Process is monitored by pid.</item> + <tag><c>{process, {<anno>RegName</anno>, <anno>Node</anno>}}</c></tag> + <item>Local or remote process is monitored by name.</item> + <tag><c>{port, PortId}</c></tag> + <item>Local port is monitored by port id.</item> + <tag><c>{port, {<anno>RegName</anno>, <anno>Node</anno>}}</c></tag> + <item>Local port is monitored by name. Please note, that + remote port monitors are not supported, so <c>Node</c> will + always be the local node name.</item> + </taglist> + </item> + <tag><c>{message_queue_data, <anno>MQD</anno>}</c></tag> + <item> + <p>Returns the current state of the <c>message_queue_data</c> + process flag. <c><anno>MQD</anno></c> is either <c>off_heap</c>, + or <c>on_heap</c>. For more information, see the + documentation of + <seealso marker="#process_flag_message_queue_data"><c>process_flag(message_queue_data, + MQD)</c></seealso>.</p> </item> - <tag><c>{priority, Level}</c></tag> + <tag><c>{priority, <anno>Level</anno>}</c></tag> <item> <p><c><anno>Level</anno></c> is the current priority level for - the process. For more information on priorities see - <seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso>.</p> + the process. For more information on priorities, see + <seealso marker="#process_flag_priority">process_flag(priority, + Level)</seealso>.</p> </item> <tag><c>{reductions, <anno>Number</anno>}</c></tag> <item> @@ -3887,240 +4926,353 @@ os_prompt% </pre> </item> <tag><c>{sequential_trace_token, [] | <anno>SequentialTraceToken</anno>}</c></tag> <item> - <p><c><anno>SequentialTraceToken</anno></c> the sequential trace token for - the process. This <c><anno>InfoTuple</anno></c> may be changed or removed - without prior notice.</p> + <p><c><anno>SequentialTraceToken</anno></c> is the sequential trace + token for the process. This <c><anno>InfoTuple</anno></c> can be + changed or removed without prior notice.</p> </item> <tag><c>{stack_size, <anno>Size</anno>}</c></tag> <item> - <p><c><anno>Size</anno></c> is the stack size of the process in words.</p> + <p><c><anno>Size</anno></c> is the stack size, in words, + of the process.</p> </item> <tag><c>{status, <anno>Status</anno>}</c></tag> <item> - <p><c><anno>Status</anno></c> is the status of the process. <c><anno>Status</anno></c> - is <c>exiting</c>, <c>garbage_collecting</c>, - <c>waiting</c> (for a message), <c>running</c>, - <c>runnable</c> (ready to run, but another process is - running), or <c>suspended</c> (suspended on a "busy" port - or by the <c>erlang:suspend_process/[1,2]</c> BIF).</p> + <p><c><anno>Status</anno></c> is the status of the process and is one + of the following:</p> + <list type="bulleted"> + <item><c>exiting</c></item> + <item><c>garbage_collecting</c></item> + <item><c>waiting</c> (for a message)</item> + <item><c>running</c></item> + <item><c>runnable</c> (ready to run, but another process is + running)</item> + <item><c>suspended</c> (suspended on a "busy" port + or by the BIF <c>erlang:suspend_process/[1,2]</c>)</item> + </list> </item> <tag><c>{suspending, <anno>SuspendeeList</anno>}</c></tag> <item> - <p><c><anno>SuspendeeList</anno></c> is a list of <c>{<anno>Suspendee</anno>, - <anno>ActiveSuspendCount</anno>, <anno>OutstandingSuspendCount</anno>}</c> tuples. - <c><anno>Suspendee</anno></c> is the pid of a process that have been or is to - be suspended by the process identified by <c><anno>Pid</anno></c> via the - <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso> - BIF, or the - <seealso marker="#suspend_process/1">erlang:suspend_process/1</seealso> - BIF. <c><anno>ActiveSuspendCount</anno></c> is the number of times the - <c><anno>Suspendee</anno></c> has been suspended by <c><anno>Pid</anno></c>. + <p><c><anno>SuspendeeList</anno></c> is a list of + <c>{<anno>Suspendee</anno>, <anno>ActiveSuspendCount</anno>, + <anno>OutstandingSuspendCount</anno>}</c> tuples. + <c><anno>Suspendee</anno></c> is the process identifier of a + process that has been, or is to be, + suspended by the process identified by <c><anno>Pid</anno></c> + through one of the following BIFs:</p> + <list type="bulleted"> + <item> + <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso> + </item> + <item> + <seealso marker="#suspend_process/1">erlang:suspend_process/1</seealso> + </item> + </list> + <p><c><anno>ActiveSuspendCount</anno></c> is the number of + times <c><anno>Suspendee</anno></c> has been suspended by + <c><anno>Pid</anno></c>. <c><anno>OutstandingSuspendCount</anno></c> is the number of not yet - completed suspend requests sent by <c><anno>Pid</anno></c>. That is, - if <c><anno>ActiveSuspendCount</anno> =/= 0</c>, <c><anno>Suspendee</anno></c> is - currently in the suspended state, and if - <c><anno>OutstandingSuspendCount</anno> =/= 0</c> the <c>asynchronous</c> - option of <c>erlang:suspend_process/2</c> has been used and - the suspendee has not yet been suspended by <c><anno>Pid</anno></c>. - Note that the <c><anno>ActiveSuspendCount</anno></c> and - <c><anno>OutstandingSuspendCount</anno></c> are not the total suspend count - on <c><anno>Suspendee</anno></c>, only the parts contributed by <c>Pid</c>. - </p> + completed suspend requests sent by <c><anno>Pid</anno></c>, that is:</p> + <list type="bulleted"> + <item>If <c><anno>ActiveSuspendCount</anno> =/= 0</c>, + <c><anno>Suspendee</anno></c> is + currently in the suspended state. + </item> + <item>If <c><anno>OutstandingSuspendCount</anno> =/= 0</c>, option + <c>asynchronous</c> of <c>erlang:suspend_process/2</c> + has been used and the suspendee has not yet been + suspended by <c><anno>Pid</anno></c>. + </item> + </list> + <p>Notice that <c><anno>ActiveSuspendCount</anno></c> and + <c><anno>OutstandingSuspendCount</anno></c> are not the + total suspend count on <c><anno>Suspendee</anno></c>, + only the parts contributed by <c><anno>Pid</anno></c>.</p> </item> - <tag><c>{total_heap_size, <anno>Size</anno>}</c></tag> + <tag> + <marker id="process_info_total_heap_size"/> + <c>{total_heap_size, <anno>Size</anno>}</c> + </tag> <item> - <p><c><anno>Size</anno></c> is the total size in words of all heap - fragments of the process. This currently include the stack - of the process. - </p> + <p><c><anno>Size</anno></c> is the total size, in words, of all heap + fragments of the process. This includes the process stack and + any unreceived messages that are considered to be part of the + heap. </p> </item> <tag><c>{trace, <anno>InternalTraceFlags</anno>}</c></tag> <item> - <p><c><anno>InternalTraceFlags</anno></c> is an integer representing - internal trace flag for this process. This <c><anno>InfoTuple</anno></c> - may be changed or removed without prior notice.</p> + <p><c><anno>InternalTraceFlags</anno></c> is an integer + representing the internal trace flag for this process. + This <c><anno>InfoTuple</anno></c> + can be changed or removed without prior notice.</p> </item> <tag><c>{trap_exit, <anno>Boolean</anno>}</c></tag> <item> - <p><c><anno>Boolean</anno></c> is <c>true</c> if the process is trapping - exits, otherwise it is <c>false</c>.</p> + <p><c><anno>Boolean</anno></c> is <c>true</c> if the process + is trapping exits, otherwise <c>false</c>.</p> </item> </taglist> - <p>Note however, that not all implementations support every one - of the above <c><anno>Item</anno></c>s.</p> - <p>Failure: <c>badarg</c> if <c><anno>Pid</anno></c> is not a local process, - or if <c><anno>Item</anno></c> is not a valid <c><anno>Item</anno></c>.</p> + <p>Notice that not all implementations support all + these <c><anno>Item</anno></c>s.</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item>If <c><anno>Pid</anno></c> is not a local process.</item> + <tag><c>badarg</c></tag> + <item>If <c><anno>Item</anno></c> is an invalid item.</item> + </taglist> </desc> </func> + <func> <name name="processes" arity="0"/> - <fsummary>All processes</fsummary> + <fsummary>All processes.</fsummary> <desc> <p>Returns a list of process identifiers corresponding to - all the processes currently existing on the local node. - </p> - <p>Note that a process that is exiting, exists but is not alive, i.e., - <c>is_process_alive/1</c> will return <c>false</c> for a process - that is exiting, but its process identifier will be part - of the result returned from <c>processes/0</c>. - </p> + all the processes currently existing on the local node.</p> + <p>Notice that an exiting process exists, but is not alive. + That is, <c>is_process_alive/1</c> returns <c>false</c> + for an exiting process, but its process identifier is part + of the result returned from <c>processes/0</c>.</p> + <p>Example:</p> <pre> > <input>processes().</input> [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]</pre> </desc> </func> + <func> <name name="purge_module" arity="1"/> - <fsummary>Remove old code for a module</fsummary> + <fsummary>Removes old code for a module.</fsummary> <desc> - <p>Removes old code for <c><anno>Module</anno></c>. Before this BIF is used, - <c>erlang:check_process_code/2</c> should be called to check - that no processes are executing old code in the module.</p> + <p>Removes old code for <c><anno>Module</anno></c>. + Before this BIF is used, + <c>erlang:check_process_code/2</c> is to be called to check + that no processes execute old code in the module.</p> <warning> <p>This BIF is intended for the code server (see - <seealso marker="kernel:code">code(3)</seealso>) and should not be - used elsewhere.</p> + <seealso marker="kernel:code">code(3)</seealso>) + and is not to be used elsewhere.</p> </warning> + <note> + <p>As from <c>ERTS</c> 8.0 (OTP 19), any lingering processes + that still execute the old code will be killed by this function. + In earlier versions, such incorrect use could cause much + more fatal failures, like emulator crash.</p> + </note> <p>Failure: <c>badarg</c> if there is no old code for <c><anno>Module</anno></c>.</p> </desc> </func> + <func> <name name="put" arity="2"/> - <fsummary>Add a new value to the process dictionary</fsummary> - <desc> - <p>Adds a new <c><anno>Key</anno></c> to the process dictionary, associated - with the value <c><anno>Val</anno></c>, and returns <c>undefined</c>. If - <c><anno>Key</anno></c> already exists, the old value is deleted and - replaced by <c><anno>Val</anno></c> and the function returns the old value.</p> - <note> - <p>The values stored when <c>put</c> is evaluated within - the scope of a <c>catch</c> will not be retracted if a - <c>throw</c> is evaluated, or if an error occurs.</p> - </note> + <fsummary>Adds a new value to the process dictionary.</fsummary> + <desc> + <p>Adds a new <c><anno>Key</anno></c> to the process dictionary, + associated with the value <c><anno>Val</anno></c>, and returns + <c>undefined</c>. If <c><anno>Key</anno></c> exists, the old + value is deleted and replaced by <c><anno>Val</anno></c>, and + the function returns the old value.</p> + <p>Example:</p> <pre> > <input>X = put(name, walrus), Y = put(name, carpenter),</input> <input>Z = get(name),</input> <input>{X, Y, Z}.</input> {undefined,walrus,carpenter}</pre> + <note> + <p>The values stored when <c>put</c> is evaluated within + the scope of a <c>catch</c> are not retracted if a + <c>throw</c> is evaluated, or if an error occurs.</p> + </note> </desc> </func> + <func> <name name="raise" arity="3"/> + <fsummary>Stops execution with an exception of given class, reason, and call stack backtrace.</fsummary> <type name="raise_stacktrace"/> - <fsummary>Stop execution with an exception of given class, reason and call stack backtrace</fsummary> <desc> <p>Stops the execution of the calling process with an - exception of given class, reason and call stack backtrace + exception of given class, reason, and call stack backtrace (<em>stacktrace</em>).</p> - <warning> - <p>This BIF is intended for debugging and for use in - the Erlang operating system. In general, it should - be avoided in applications, unless you know - very well what you are doing.</p> - </warning> - <p><c><anno>Class</anno></c> is one of <c>error</c>, <c>exit</c> or - <c>throw</c>, so if it were not for the stacktrace - <c>erlang:raise(<anno>Class</anno>, <anno>Reason</anno>, <anno>Stacktrace</anno>)</c> is - equivalent to <c>erlang:<anno>Class</anno>(<anno>Reason</anno>)</c>. - <c><anno>Reason</anno></c> is any term and <c><anno>Stacktrace</anno></c> is a list as - returned from <c>get_stacktrace()</c>, that is a list of - 4-tuples <c>{Module, Function, Arity | Args, - Location}</c> where <c>Module</c> and <c>Function</c> - are atoms and the third element is an integer arity or an - argument list. The stacktrace may also contain <c>{Fun, - Args, Location}</c> tuples where - <c>Fun</c> is a local fun and <c>Args</c> is an argument list.</p> - <p>The <c>Location</c> element at the end is optional. + <p><c><anno>Class</anno></c> is <c>error</c>, <c>exit</c>, or + <c>throw</c>. So, if it were not for the stacktrace, + <c>erlang:raise(<anno>Class</anno>, <anno>Reason</anno>, + <anno>Stacktrace</anno>)</c> is + equivalent to <c>erlang:<anno>Class</anno>(<anno>Reason</anno>)</c>.</p> + <p><c><anno>Reason</anno></c> is any term. + <c><anno>Stacktrace</anno></c> is a list as + returned from <c>get_stacktrace()</c>, that is, a list of + four-tuples <c>{Module, Function, Arity | Args, + Location}</c>, where <c>Module</c> and <c>Function</c> + are atoms, and the third element is an integer arity or an + argument list. The stacktrace can also contain <c>{Fun, + Args, Location}</c> tuples, where <c>Fun</c> is a local + fun and <c>Args</c> is an argument list.</p> + <p>Element <c>Location</c> at the end is optional. Omitting it is equivalent to specifying an empty list.</p> <p>The stacktrace is used as the exception stacktrace for the - calling process; it will be truncated to the current + calling process; it is truncated to the current maximum stacktrace depth.</p> - <p>Because evaluating this function causes the process to - terminate, it has no return value - unless the arguments are - invalid, in which case the function <em>returns the error reason</em>, that is <c>badarg</c>. If you want to be - really sure not to return you can call - <c>error(erlang:raise(<anno>Class</anno>, <anno>Reason</anno>, <anno>Stacktrace</anno>))</c> + <p>Since evaluating this function causes the process to + terminate, it has no return value unless the arguments are + invalid, in which case the function <em>returns the error + reason</em> <c>badarg</c>. If you want to be + sure not to return, you can call + <c>error(erlang:raise(<anno>Class</anno>, <anno>Reason</anno>, + <anno>Stacktrace</anno>))</c> and hope to distinguish exceptions later.</p> </desc> </func> + <func> - <name name="read_timer" arity="1"/> - <fsummary>Number of milliseconds remaining for a timer</fsummary> - <desc> - <p><c><anno>TimerRef</anno></c> is a timer reference returned by - <seealso marker="#send_after/3">erlang:send_after/3</seealso> - or - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>. - If the timer is active, the function returns the time in - milliseconds left until the timer will expire, otherwise - <c>false</c> (which means that <c><anno>TimerRef</anno></c> was never a - timer, that it has been cancelled, or that it has already - delivered its message).</p> + <name name="read_timer" arity="2"/> + <fsummary>Reads the state of a timer.</fsummary> + <desc> + <p> + Read the state of a timer that has been created by either + <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>, + or <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>. + <c><anno>TimerRef</anno></c> identifies the timer, and + was returned by the BIF that created the timer. + </p> + <p>Available <c><anno>Option</anno>s</c>:</p> + <taglist> + <tag><c>{async, Async}</c></tag> + <item> + <p> + Asynchronous request for state information. <c>Async</c> + defaults to <c>false</c> which will cause the operation + to be performed synchronously. In this case, the <c>Result</c> + is returned by <c>erlang:read_timer()</c>. When + <c>Async</c> is <c>true</c>, <c>erlang:read_timer()</c> + sends an asynchronous request for the state information + to the timer service that manages the timer, and then returns + <c>ok</c>. A message on the format <c>{read_timer, + <anno>TimerRef</anno>, <anno>Result</anno>}</c> is + sent to the caller of <c>erlang:read_timer()</c> when the + operation has been processed. + </p> + </item> + </taglist> + <p> + More <c><anno>Option</anno></c>s may be added in the future. + </p> + <p> + If <c><anno>Result</anno></c> is an integer, it represents the + time in milli-seconds left until the timer expires.</p> + <p> + If <c><anno>Result</anno></c> is <c>false</c>, a + timer corresponding to <c><anno>TimerRef</anno></c> could not + be found. This can be because the timer had expired, + it had been canceled, or because <c><anno>TimerRef</anno></c> + never has corresponded to a timer. Even if the timer has expired, + it does not tell you whether or not the timeout message has + arrived at its destination yet. + </p> + <note> + <p> + The timer service that manages the timer may be co-located + with another scheduler than the scheduler that the calling + process is executing on. If this is the case, communication + with the timer service takes much longer time than if it + is located locally. If the calling process is in critical + path, and can do other things while waiting for the result + of this operation, you want to use option <c>{async, true}</c>. + If using option <c>{async, false}</c>, the calling + process will be blocked until the operation has been + performed. + </p> + </note> <p>See also - <seealso marker="#send_after/3">erlang:send_after/3</seealso>, - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>, + <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>, + <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>, and - <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>.</p> + <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>.</p> + </desc> + </func> + <func> + <name name="read_timer" arity="1"/> + <fsummary>Reads the state of a timer.</fsummary> + <desc> + <p>Read the state of a timer. The same as calling + <seealso marker="#read_timer/2"><c>erlang:read_timer(TimerRef, + [])</c></seealso>.</p> </desc> </func> + <func> <name name="ref_to_list" arity="1"/> - <fsummary>Text representation of a reference</fsummary> + <fsummary>Text representation of a reference.</fsummary> <desc> - <p>Returns a string which corresponds to the text + <p>Returns a string corresponding to the text representation of <c><anno>Ref</anno></c>.</p> <warning> - <p>This BIF is intended for debugging and for use in - the Erlang operating system. It should not be used in - application programs.</p> + <p>This BIF is intended for debugging and is not to be used + in application programs.</p> </warning> </desc> </func> + <func> <name name="register" arity="2"/> - <fsummary>Register a name for a pid (or port)</fsummary> + <fsummary>Registers a name for a pid (or port).</fsummary> <desc> - <p>Associates the name <c><anno>RegName</anno></c> with a pid or a port - identifier. <c><anno>RegName</anno></c>, which must be an atom, can be used - instead of the pid / port identifier in the send operator + <p>Associates the name <c><anno>RegName</anno></c> with a process + identifier (pid) or a port identifier. + <c><anno>RegName</anno></c>, which must be an atom, can be used + instead of the pid or port identifier in send operator (<c><anno>RegName</anno> ! Message</c>).</p> + <p>Example:</p> <pre> > <input>register(db, Pid).</input> true</pre> - <p>Failure: <c>badarg</c> if <c><anno>PidOrPort</anno></c> is not an existing, - local process or port, if <c><anno>RegName</anno></c> is already in use, - if the process or port is already registered (already has a - name), or if <c><anno>RegName</anno></c> is the atom <c>undefined</c>.</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item>If <c><anno>PidOrPort</anno></c> is not an existing local + process or port.</item> + <tag><c>badarg</c></tag> + <item>If <c><anno>RegName</anno></c> is already in use.</item> + <tag><c>badarg</c></tag> + <item>If the process or port is already registered + (already has a name).</item> + <tag><c>badarg</c></tag> + <item>If <c><anno>RegName</anno></c> is the atom + <c>undefined</c>.</item> + </taglist> </desc> </func> + <func> <name name="registered" arity="0"/> - <fsummary>All registered names</fsummary> + <fsummary>All registered names.</fsummary> <desc> - <p>Returns a list of names which have been registered using - <seealso marker="#register/2">register/2</seealso>.</p> + <p>Returns a list of names that have been registered using + <seealso marker="#register/2">register/2</seealso>, for + example:</p> <pre> > <input>registered().</input> [code_server, file_server, init, user, my_db]</pre> </desc> </func> + <func> <name name="resume_process" arity="1"/> - <fsummary>Resume a suspended process</fsummary> + <fsummary>Resumes a suspended process.</fsummary> <desc> <p>Decreases the suspend count on the process identified by - <c><anno>Suspendee</anno></c>. <c><anno>Suspendee</anno></c> should previously have been - suspended via - <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>, + <c><anno>Suspendee</anno></c>. <c><anno>Suspendee</anno></c> + is previously to have been suspended through + <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso> or <seealso marker="#suspend_process/1">erlang:suspend_process/1</seealso> - by the process calling <c>erlang:resume_process(<anno>Suspendee</anno>)</c>. When - the suspend count on <c><anno>Suspendee</anno></c> reach zero, <c><anno>Suspendee</anno></c> - will be resumed, i.e., the state of the <c>Suspendee</c> is changed - from suspended into the state <c><anno>Suspendee</anno></c> was in before it was - suspended. - </p> + by the process calling + <c>erlang:resume_process(<anno>Suspendee</anno>)</c>. When the + suspend count on <c><anno>Suspendee</anno></c> reaches zero, + <c><anno>Suspendee</anno></c> is resumed, that is, its state + is changed from suspended into the state it had before it was + suspended.</p> <warning> <p>This BIF is intended for debugging only.</p> </warning> @@ -4128,7 +5280,7 @@ true</pre> <taglist> <tag><c>badarg</c></tag> <item> - If <c><anno>Suspendee</anno></c> isn't a process identifier. + If <c><anno>Suspendee</anno></c> is not a process identifier. </item> <tag><c>badarg</c></tag> <item> @@ -4138,58 +5290,65 @@ true</pre> </item> <tag><c>badarg</c></tag> <item> - If the process identified by <c><anno>Suspendee</anno></c> is not alive. + If the process identified by <c><anno>Suspendee</anno></c> + is not alive. </item> </taglist> </desc> </func> + <func> <name name="round" arity="1"/> - <fsummary>Return an integer by rounding a number</fsummary> + <fsummary>Returns an integer by rounding a number.</fsummary> <desc> - <p>Returns an integer by rounding <c><anno>Number</anno></c>.</p> + <p>Returns an integer by rounding <c><anno>Number</anno></c>, + for example:</p> <pre> -> <input>round(5.5).</input> +<input>round(5.5).</input> 6</pre> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="self" arity="0"/> - <fsummary>Pid of the calling process</fsummary> + <fsummary>Returns pid of the calling process.</fsummary> <desc> - <p>Returns the pid (process identifier) of the calling process.</p> + <p>Returns the process identifier of the calling process, for + example:</p> <pre> > <input>self().</input> <0.26.0></pre> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="send" arity="2"/> - <fsummary>Send a message</fsummary> + <fsummary>Sends a message.</fsummary> <type name="dst"/> <desc> - <p>Sends a message and returns <c><anno>Msg</anno></c>. This is the same as - <c><anno>Dest</anno> ! <anno>Msg</anno></c>.</p> - <p><c><anno>Dest</anno></c> may be a remote or local pid, a (local) port, a - locally registered name, or a tuple <c>{<anno>RegName</anno>, <anno>Node</anno>}</c> + <p>Sends a message and returns <c><anno>Msg</anno></c>. This + is the same as <c><anno>Dest</anno> ! <anno>Msg</anno></c>.</p> + <p><c><anno>Dest</anno></c> can be a remote or local process identifier, + a (local) port, a locally registered name, or a tuple + <c>{<anno>RegName</anno>, <anno>Node</anno>}</c> for a registered name at another node.</p> </desc> </func> + <func> <name name="send" arity="3"/> + <fsummary>Sends a message conditionally.</fsummary> <type name="dst"/> - <fsummary>Send a message conditionally</fsummary> - <desc> - <p>Sends a message and returns <c>ok</c>, or does not send - the message but returns something else (see below). Otherwise - the same as - <seealso marker="#send/2">erlang:send/2</seealso>. See - also - <seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2,3</seealso>. - for more detailed explanation and warnings.</p> - <p>The possible options are:</p> + <desc> + <p>Either sends a message and returns <c>ok</c>, or does not send + the message but returns something else (see the following). + Otherwise the same as + <seealso marker="#send/2">erlang:send/2</seealso>. + For more detailed explanation and warnings, see + <seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2,3</seealso>.</p> + <p>The options are as follows:</p> <taglist> <tag><c>nosuspend</c></tag> <item> @@ -4199,319 +5358,375 @@ true</pre> <tag><c>noconnect</c></tag> <item> <p>If the destination node would have to be auto-connected - before doing the send, <c>noconnect</c> is returned + to do the send, <c>noconnect</c> is returned instead.</p> </item> </taglist> <warning> - <p>As with <c>erlang:send_nosuspend/2,3</c>: Use with extreme - care!</p> + <p>As with <c>erlang:send_nosuspend/2,3</c>: use with extreme + care.</p> </warning> </desc> </func> + <func> - <name name="send_after" arity="3"/> - <type_desc variable="Time">0 <= Time <= 4294967295</type_desc> + <name name="send_after" arity="4"/> <fsummary>Start a timer</fsummary> <desc> - <p>Starts a timer which will send the message <c>Msg</c> - to <c><anno>Dest</anno></c> after <c><anno>Time</anno></c> milliseconds.</p> - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to be a <c>pid()</c> of a local process, dead or alive.</p> - <p>The <c><anno>Time</anno></c> value can, in the current implementation, not be greater than 4294967295.</p> - <p>If <c><anno>Dest</anno></c> is an <c>atom()</c>, it is supposed to be the name of - a registered process. The process referred to by the name is - looked up at the time of delivery. No error is given if - the name does not refer to a process.</p> - - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer will be automatically - canceled if the process referred to by the <c>pid()</c> is not alive, - or when the process exits. This feature was introduced in - erts version 5.4.11. Note that timers will not be - automatically canceled when <c><anno>Dest</anno></c> is an <c>atom</c>.</p> - <p>See also - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>, - <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>, - and - <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p> - <p>Failure: <c>badarg</c> if the arguments does not satisfy - the requirements specified above.</p> + <p> + Starts a timer. When the timer expires, the message + <c><anno>Msg</anno></c> is sent to the process + identified by <c><anno>Dest</anno></c>. Apart from + the format of the timeout message, + <c>erlang:send_after/4</c> works exactly as + <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>.</p> </desc> </func> <func> + <name name="send_after" arity="3"/> + <fsummary>Starts a timer.</fsummary> + <desc> + <p>Starts a timer. The same as calling + <seealso marker="#send_after/4"><c>erlang:send_after(<anno>Time</anno>, + <anno>Dest</anno>, <anno>Msg</anno>, [])</c></seealso>.</p> + </desc> + </func> + + <func> <name name="send_nosuspend" arity="2"/> - <fsummary>Try to send a message without ever blocking</fsummary> + <fsummary>Tries to send a message without ever blocking.</fsummary> <type name="dst"/> <desc> <p>The same as - <seealso marker="#send/3">erlang:send(<anno>Dest</anno>, <anno>Msg</anno>, [nosuspend])</seealso>, but returns <c>true</c> if + <seealso marker="#send/3">erlang:send(<anno>Dest</anno>, + <anno>Msg</anno>, [nosuspend])</seealso>, + but returns <c>true</c> if the message was sent and <c>false</c> if the message was not sent because the sender would have had to be suspended.</p> - <p>This function is intended for send operations towards an + <p>This function is intended for send operations to an unreliable remote node without ever blocking the sending (Erlang) process. If the connection to the remote node (usually not a real Erlang node, but a node written in C or - Java) is overloaded, this function <em>will not send the message</em> but return <c>false</c> instead.</p> - <p>The same happens, if <c><anno>Dest</anno></c> refers to a local port that - is busy. For all other destinations (allowed for the ordinary - send operator <c>'!'</c>) this function sends the message and + Java) is overloaded, this function <em>does not send the message</em> + and returns <c>false</c>.</p> + <p>The same occurs if <c><anno>Dest</anno></c> refers to a local port + that is busy. For all other destinations (allowed for the ordinary + send operator <c>'!'</c>), this function sends the message and returns <c>true</c>.</p> - <p>This function is only to be used in very rare circumstances + <p>This function is only to be used in rare circumstances where a process communicates with Erlang nodes that can - disappear without any trace causing the TCP buffers and - the drivers queue to be over-full before the node will actually - be shut down (due to tick timeouts) by <c>net_kernel</c>. The - normal reaction to take when this happens is some kind of + disappear without any trace, causing the TCP buffers and + the drivers queue to be over-full before the node is + shut down (because of tick time-outs) by <c>net_kernel</c>. + The normal reaction to take when this occurs is some kind of premature shutdown of the other node.</p> - <p>Note that ignoring the return value from this function would - result in <em>unreliable</em> message passing, which is + <p>Notice that ignoring the return value from this function would + result in an <em>unreliable</em> message passing, which is contradictory to the Erlang programming model. The message is <em>not</em> sent if this function returns <c>false</c>.</p> - <p>Note also that in many systems, transient states of + <p>In many systems, transient states of overloaded queues are normal. The fact that this function - returns <c>false</c> does not in any way mean that the other + returns <c>false</c> does not mean that the other node is guaranteed to be non-responsive, it could be a - temporary overload. Also a return value of <c>true</c> does - only mean that the message could be sent on the (TCP) channel - without blocking, the message is not guaranteed to have - arrived at the remote node. Also in the case of a disconnected + temporary overload. Also, a return value of <c>true</c> does + only mean that the message can be sent on the (TCP) channel + without blocking, the message is not guaranteed to + arrive at the remote node. For a disconnected non-responsive node, the return value is <c>true</c> (mimics - the behaviour of the <c>!</c> operator). The expected - behaviour as well as the actions to take when the function - returns <c>false</c> are application and hardware specific.</p> + the behavior of operator <c>!</c>). The expected + behavior and the actions to take when the function + returns <c>false</c> are application- and hardware-specific.</p> <warning> - <p>Use with extreme care!</p> + <p>Use with extreme care.</p> </warning> </desc> </func> + <func> <name name="send_nosuspend" arity="3"/> - <fsummary>Try to send a message without ever blocking</fsummary> + <fsummary>Tries to send a message without ever blocking.</fsummary> <type name="dst"/> <desc> <p>The same as - <seealso marker="#send/3">erlang:send(<anno>Dest</anno>, <anno>Msg</anno>, [nosuspend | <anno>Options</anno>])</seealso>, - but with boolean return value.</p> + <seealso marker="#send/3">erlang:send(<anno>Dest</anno>, + <anno>Msg</anno>, [nosuspend | <anno>Options</anno>])</seealso>, + but with a Boolean return value.</p> <p>This function behaves like - <seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2)</seealso>, - but takes a third parameter, a list of options. The only - currently implemented option is <c>noconnect</c>. The option - <c>noconnect</c> makes the function return <c>false</c> if + <seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2</seealso>, + but takes a third parameter, a list of options. + The only option is <c>noconnect</c>, which + makes the function return <c>false</c> if the remote node is not currently reachable by the local - node. The normal behaviour is to try to connect to the node, - which may stall the process for a shorter period. The use of - the <c>noconnect</c> option makes it possible to be - absolutely sure not to get even the slightest delay when + node. The normal behavior is to try to connect to the node, + which can stall the process during a short period. The use of + option <c>noconnect</c> makes it possible to be + sure not to get the slightest delay when sending to a remote process. This is especially useful when - communicating with nodes who expect to always be - the connecting part (i.e. nodes written in C or Java).</p> + communicating with nodes that expect to always be + the connecting part (that is, nodes written in C or Java).</p> <p>Whenever the function returns <c>false</c> (either when a suspend would occur or when <c>noconnect</c> was specified and the node was not already connected), the message is guaranteed <em>not</em> to have been sent.</p> <warning> - <p>Use with extreme care!</p> + <p>Use with extreme care.</p> </warning> </desc> </func> + <func> <name name="set_cookie" arity="2"/> - <fsummary>Set the magic cookie of a node</fsummary> + <fsummary>Sets the magic cookie of a node.</fsummary> <desc> <p>Sets the magic cookie of <c><anno>Node</anno></c> to the atom - <c><anno>Cookie</anno></c>. If <c><anno>Node</anno></c> is the local node, the function + <c><anno>Cookie</anno></c>. If <c><anno>Node</anno></c> is the + local node, the function also sets the cookie of all other unknown nodes to - <c><anno>Cookie</anno></c> (see - <seealso marker="doc/reference_manual:distributed">Distributed Erlang</seealso> in the Erlang Reference Manual).</p> + <c><anno>Cookie</anno></c> (see Section + <seealso marker="doc/reference_manual:distributed">Distributed Erlang</seealso> + in the Erlang Reference Manual in System Documentation).</p> <p>Failure: <c>function_clause</c> if the local node is not alive.</p> </desc> </func> + <func> <name name="setelement" arity="3"/> - <type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno>)</type_desc> - <fsummary>Set Nth element of a tuple</fsummary> + <fsummary>Sets the Nth element of a tuple.</fsummary> + <type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno></type_desc> <desc> - <p>Returns a tuple which is a copy of the argument <c><anno>Tuple1</anno></c> - with the element given by the integer argument <c><anno>Index</anno></c> + <p>Returns a tuple that is a copy of argument + <c><anno>Tuple1</anno></c> + with the element given by integer argument + <c><anno>Index</anno></c> (the first element is the element with index 1) replaced by - the argument <c><anno>Value</anno></c>.</p> + argument <c><anno>Value</anno></c>, for example:</p> <pre> > <input>setelement(2, {10, green, bottles}, red).</input> {10,red,bottles}</pre> </desc> </func> + <func> <name name="size" arity="1"/> - <fsummary>Size of a tuple or binary</fsummary> + <fsummary>Size of a tuple or binary.</fsummary> <desc> - <p>Returns an integer which is the size of the argument - <c><anno>Item</anno></c>, which must be either a tuple or a binary.</p> + <p>Returns the number of elements in a tuple or the number of + bytes in a binary or bitstring, for example:</p> <pre> > <input>size({morni, mulle, bwange}).</input> -3</pre> +3 +> <input>size(<<11, 22, 33>>).</input> +3 +</pre> + <p>For bitstrings the number of whole bytes is returned. That is, if the number of bits + in the bitstring is not divisible by 8, the resulting + number of bytes is rounded <em>down</em>.</p> <p>Allowed in guard tests.</p> + <p>See also + <seealso marker="#tuple_size/1"><c>tuple_size/1</c></seealso>, + <seealso marker="#byte_size/1"><c>byte_size/1</c></seealso> + and + <seealso marker="#bit_size/1"><c>bit_size/1</c></seealso>.</p> </desc> </func> + <func> <name name="spawn" arity="1"/> - <fsummary>Create a new process with a fun as entry point</fsummary> + <fsummary>Creates a new process with a fun as entry point.</fsummary> <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Fun</anno></c> to the empty list <c>[]</c>. Otherwise works - like <seealso marker="#spawn/3">spawn/3</seealso>.</p> + <p>Returns the process identifier of a new process started by the + application of <c><anno>Fun</anno></c> to the empty list + <c>[]</c>. Otherwise + works like <seealso marker="#spawn/3">spawn/3</seealso>.</p> </desc> </func> + <func> <name name="spawn" arity="2"/> - <fsummary>Create a new process with a fun as entry point on a given node</fsummary> + <fsummary>Creates a new process with a fun as entry point on a given node.</fsummary> <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Fun</anno></c> to the empty list <c>[]</c> on <c><anno>Node</anno></c>. If - <c><anno>Node</anno></c> does not exist, a useless pid is returned. - Otherwise works like + <p>Returns the process identifier of a new process started + by the application of <c><anno>Fun</anno></c> to the + empty list <c>[]</c> on <c><anno>Node</anno></c>. If + <c><anno>Node</anno></c> does not exist, a useless pid is + returned. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p> </desc> </func> + <func> <name name="spawn" arity="3"/> - <fsummary>Create a new process with a function as entry point</fsummary> - <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c>. The new process - created will be placed in the system scheduler queue and be - run some time later.</p> - <p><c>error_handler:undefined_function(<anno>Module</anno>, <anno>Function</anno>, <anno>Args</anno>)</c> is evaluated by the new process if - <c><anno>Module</anno>:<anno>Function</anno>/Arity</c> does not exist (where - <c>Arity</c> is the length of <c><anno>Args</anno></c>). The error handler + <fsummary>Creates a new process with a function as entry point.</fsummary> + <desc> + <p>Returns the process identifier of a new process started by + the application of <c><anno>Module</anno>:<anno>Function</anno></c> + to <c><anno>Args</anno></c>.</p> + <p><c>error_handler:undefined_function(<anno>Module</anno>, + <anno>Function</anno>, <anno>Args</anno>)</c> + is evaluated by the new process if + <c><anno>Module</anno>:<anno>Function</anno>/Arity</c> + does not exist (where <c>Arity</c> is the length of + <c><anno>Args</anno></c>). The error handler can be redefined (see <seealso marker="#process_flag/2">process_flag/2</seealso>). If <c>error_handler</c> is undefined, or the user has - redefined the default <c>error_handler</c> its replacement is - undefined, a failure with the reason <c>undef</c> will occur.</p> + redefined the default <c>error_handler</c> and its replacement is + undefined, a failure with reason <c>undef</c> occurs.</p> + <p>Example:</p> <pre> > <input>spawn(speed, regulator, [high_speed, thin_cut]).</input> <0.13.1></pre> </desc> </func> + <func> <name name="spawn" arity="4"/> - <fsummary>Create a new process with a function as entry point on a given node</fsummary> + <fsummary>Creates a new process with a function as entry point on a given node.</fsummary> <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c> on <c>Node</c>. If - <c><anno>Node</anno></c> does not exists, a useless pid is returned. + <p>Returns the process identifier (pid) of a new process started + by the application + of <c><anno>Module</anno>:<anno>Function</anno></c> + to <c><anno>Args</anno></c> on <c><anno>Node</anno></c>. If + <c><anno>Node</anno></c> does not exist, a useless pid is returned. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p> </desc> </func> + <func> <name name="spawn_link" arity="1"/> - <fsummary>Create and link to a new process with a fun as entry point</fsummary> + <fsummary>Creates and links to a new process with a fun as entry point.</fsummary> <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Fun</anno></c> to the empty list []. A link is created between + <p>Returns the process identifier of a new process started by + the application of <c><anno>Fun</anno></c> to the empty list + <c>[]</c>. A link is created between the calling process and the new process, atomically. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p> </desc> </func> + <func> <name name="spawn_link" arity="2"/> - <fsummary>Create and link to a new process with a fun as entry point on a specified node</fsummary> + <fsummary>Creates and links to a new process with a fun as entry point on a specified node.</fsummary> <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Fun</anno></c> to the empty list [] on <c><anno>Node</anno></c>. A link is + <p>Returns the process identifier (pid) of a new process started + by the application of <c><anno>Fun</anno></c> to the empty + list <c>[]</c> on <c><anno>Node</anno></c>. A link is created between the calling process and the new process, - atomically. If <c><anno>Node</anno></c> does not exist, a useless pid is - returned (and due to the link, an exit signal with exit - reason <c>noconnection</c> will be received). Otherwise works - like <seealso marker="#spawn/3">spawn/3</seealso>.</p> + atomically. If <c><anno>Node</anno></c> does not exist, + a useless pid is returned and an exit signal with + reason <c>noconnection</c> is sent to the calling + process. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p> </desc> </func> + <func> <name name="spawn_link" arity="3"/> - <fsummary>Create and link to a new process with a function as entry point</fsummary> + <fsummary>Creates and links to a new process with a function as entry point.</fsummary> <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c>. A link is created + <p>Returns the process identifier of a new process started by + the application of <c><anno>Module</anno>:<anno>Function</anno></c> + to <c><anno>Args</anno></c>. A link is created between the calling process and the new process, atomically. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p> </desc> </func> + <func> <name name="spawn_link" arity="4"/> - <fsummary>Create and link to a new process with a function as entry point on a given node</fsummary> + <fsummary>Creates and links to a new process with a function as entry point on a given node.</fsummary> <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c> on <c>Node</c>. A + <p>Returns the process identifier (pid) of a new process + started by the application + of <c><anno>Module</anno>:<anno>Function</anno></c> + to <c><anno>Args</anno></c> on <c><anno>Node</anno></c>. A link is created between the calling process and the new - process, atomically. If <c><anno>Node</anno></c> does not exist, a useless - pid is returned (and due to the link, an exit signal with exit - reason <c>noconnection</c> will be received). Otherwise works - like <seealso marker="#spawn/3">spawn/3</seealso>.</p> + process, atomically. If <c><anno>Node</anno></c> does + not exist, a useless pid is returned and an exit signal with + reason <c>noconnection</c> is sent to the calling + process. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p> </desc> </func> + <func> <name name="spawn_monitor" arity="1"/> - <fsummary>Create and monitor a new process with a fun as entry point</fsummary> + <fsummary>Creates and monitors a new process with a fun as entry point.</fsummary> <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Fun</anno></c> to the empty list [] and reference for a monitor - created to the new process. + <p>Returns the process identifier of a new process, started by + the application of <c><anno>Fun</anno></c> to the empty list + <c>[]</c>, + and a reference for a monitor created to the new process. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p> </desc> </func> + <func> <name name="spawn_monitor" arity="3"/> - <fsummary>Create and monitor a new process with a function as entry point</fsummary> + <fsummary>Creates and monitors a new process with a function as entry point.</fsummary> <desc> <p>A new process is started by the application - of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c>, and the process is - monitored at the same time. Returns the pid and a reference - for the monitor. - Otherwise works like + of <c><anno>Module</anno>:<anno>Function</anno></c> + to <c><anno>Args</anno></c>. The process is + monitored at the same time. Returns the process identifier + and a reference for the monitor. Otherwise works like <seealso marker="#spawn/3">spawn/3</seealso>.</p> </desc> </func> + <func> <name name="spawn_opt" arity="2"/> - <type name="priority_level" /> - <fsummary>Create a new process with a fun as entry point</fsummary> + <fsummary>Creates a new process with a fun as entry point.</fsummary> + <type name="priority_level"/> + <type name="max_heap_size" /> + <type name="message_queue_data" /> + <type name="spawn_opt_option" /> <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Fun</anno></c> to the empty list <c>[]</c>. Otherwise - works like + <p>Returns the process identifier (pid) of a new process + started by the application of <c><anno>Fun</anno></c> + to the empty list <c>[]</c>. Otherwise works like <seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p> - <p>If the option <c>monitor</c> is given, the newly created - process will be monitored and both the pid and reference for - the monitor will be returned.</p> + <p>If option <c>monitor</c> is given, the newly created + process is monitored, and both the pid and reference for + the monitor is returned.</p> </desc> </func> + <func> <name name="spawn_opt" arity="3"/> - <type name="priority_level" /> - <fsummary>Create a new process with a fun as entry point on a given node</fsummary> - <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Fun</anno></c> to the empty list <c>[]</c> on <c><anno>Node</anno></c>. If - <c><anno>Node</anno></c> does not exist, a useless pid is returned. - Otherwise works like + <fsummary>Creates a new process with a fun as entry point on a given node.</fsummary> + <type name="priority_level"/> + <type name="max_heap_size" /> + <type name="message_queue_data" /> + <type name="spawn_opt_option" /> + <desc> + <p>Returns the process identifier (pid) of a new process started + by the application of <c><anno>Fun</anno></c> to the + empty list <c>[]</c> on <c><anno>Node</anno></c>. If + <c><anno>Node</anno></c> does not exist, a useless pid is + returned. Otherwise works like <seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p> </desc> </func> + <func> <name name="spawn_opt" arity="4"/> - <type name="priority_level" /> - <fsummary>Create a new process with a function as entry point</fsummary> + <fsummary>Creates a new process with a function as entry point.</fsummary> + <type name="priority_level"/> + <type name="max_heap_size" /> + <type name="message_queue_data" /> + <type name="spawn_opt_option" /> <desc> - <p>Works exactly like + <p>Works as <seealso marker="#spawn/3">spawn/3</seealso>, except that an extra option list is given when creating the process.</p> - <p>If the option <c>monitor</c> is given, the newly created - process will be monitored and both the pid and reference for - the monitor will be returned.</p> + <p>If option <c>monitor</c> is given, the newly created + process is monitored, and both the pid and reference for + the monitor is returned.</p> + <p>The options are as follows:</p> <taglist> <tag><c>link</c></tag> <item> @@ -4520,110 +5735,148 @@ true</pre> </item> <tag><c>monitor</c></tag> <item> - <p>Monitor the new process (just like + <p>Monitors the new process (like <seealso marker="#monitor/2">monitor/2</seealso> does).</p> </item> - <tag><c>{priority, <anno>Level</anno>}</c></tag> + <tag><c>{priority, <anno>Level</anno></c></tag> <item> <p>Sets the priority of the new process. Equivalent to executing - <seealso marker="#process_flag_priority">process_flag(priority, <anno>Level</anno>)</seealso> in the start function of the new process, - except that the priority will be set before the process is - selected for execution for the first time. For more information - on priorities see - <seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso>.</p> + <seealso marker="#process_flag_priority">process_flag(priority, + <anno>Level</anno>)</seealso> + in the start function of the new process, + except that the priority is set before the process is + selected for execution for the first time. For more + information on priorities, see + <seealso marker="#process_flag_priority">process_flag(priority, + <anno>Level</anno>)</seealso>.</p> </item> <tag><c>{fullsweep_after, <anno>Number</anno>}</c></tag> <item> - <p>This option is only useful for performance tuning. - In general, you should not use this option unless you - know that there is problem with execution times and/or - memory consumption, and you should measure to make sure - that the option improved matters. - </p> + <p>Useful only for performance tuning. Do not use this + option unless you + know that there is problem with execution times or + memory consumption, and ensure + that the option improves matters.</p> <p>The Erlang runtime system uses a generational garbage collection scheme, using an "old heap" for data that has survived at least one garbage collection. When there is no more room on the old heap, a fullsweep garbage - collection will be done.</p> - <p>The <c>fullsweep_after</c> option makes it possible to + collection is done.</p> + <p>Option <c>fullsweep_after</c> makes it possible to specify the maximum number of generational collections - before forcing a fullsweep even if there is still room on - the old heap. Setting the number to zero effectively - disables the general collection algorithm, meaning that + before forcing a fullsweep, even if there is room on + the old heap. Setting the number to zero + disables the general collection algorithm, that is, all live data is copied at every garbage collection.</p> - <p>Here are a few cases when it could be useful to change - <c>fullsweep_after</c>. Firstly, if binaries that are no - longer used should be thrown away as soon as possible. - (Set <c><anno>Number</anno></c> to zero.) Secondly, a process that - mostly have short-lived data will be fullsweeped seldom - or never, meaning that the old heap will contain mostly - garbage. To ensure a fullsweep once in a while, set - <c><anno>Number</anno></c> to a suitable value such as 10 or 20. - Thirdly, in embedded systems with limited amount of RAM - and no virtual memory, one might want to preserve memory - by setting <c><anno>Number</anno></c> to zero. (The value may be set - globally, see - <seealso marker="#system_flag/2">erlang:system_flag/2</seealso>.)</p> + <p>A few cases when it can be useful to change + <c>fullsweep_after</c>:</p> + <list type="bulleted"> + <item>If binaries that are no longer used are to be + thrown away as soon as possible. (Set + <c><anno>Number</anno></c> to zero.) + </item> + <item>A process that mostly have short-lived data is + fullsweeped seldom or never, that is, the old heap + contains mostly garbage. To ensure a fullsweep + occasionally, set <c><anno>Number</anno></c> to a + suitable value, such as 10 or 20. + </item> + <item>In embedded systems with a limited amount of RAM + and no virtual memory, you might want to preserve memory + by setting <c><anno>Number</anno></c> to zero. + (The value can be set globally, see + <seealso marker="#system_flag/2">erlang:system_flag/2</seealso>.) + </item> + </list> </item> <tag><c>{min_heap_size, <anno>Size</anno>}</c></tag> <item> - <p>This option is only useful for performance tuning. - In general, you should not use this option unless you - know that there is problem with execution times and/or - memory consumption, and you should measure to make sure - that the option improved matters. - </p> - <p>Gives a minimum heap size in words. Setting this value - higher than the system default might speed up some + <p>Useful only for performance tuning. Do not use this + option unless you know that there is problem with + execution times or memory consumption, and + ensure that the option improves matters.</p> + <p>Gives a minimum heap size, in words. Setting this value + higher than the system default can speed up some processes because less garbage collection is done. - Setting too high value, however, might waste memory and - slow down the system due to worse data locality. - Therefore, it is recommended to use this option only for + However, setting a too high value can waste memory and + slow down the system because of worse data locality. + Therefore, use this option only for fine-tuning an application and to measure the execution time with various <c><anno>Size</anno></c> values.</p> </item> <tag><c>{min_bin_vheap_size, <anno>VSize</anno>}</c></tag> <item> - <p>This option is only useful for performance tuning. - In general, you should not use this option unless you - know that there is problem with execution times and/or - memory consumption, and you should measure to make sure - that the option improved matters. - </p> - <p>Gives a minimum binary virtual heap size in words. Setting this value - higher than the system default might speed up some + <p>Useful only for performance tuning. Do not use this + option unless you know that there is problem with + execution times or memory consumption, and + ensure that the option improves matters.</p> + <p>Gives a minimum binary virtual heap size, in words. + Setting this value + higher than the system default can speed up some processes because less garbage collection is done. - Setting too high value, however, might waste memory. - Therefore, it is recommended to use this option only for + However, setting a too high value can waste memory. + Therefore, use this option only for fine-tuning an application and to measure the execution time with various <c><anno>VSize</anno></c> values.</p> </item> - + <tag><c>{max_heap_size, <anno>Size</anno>}</c></tag> + <item> + <p>Sets the <c>max_heap_size</c> process flag. The default + <c>max_heap_size</c> is determined by the + <seealso marker="erl#+hmax"><c>+hmax</c></seealso> <c>erl</c> + command line argument. For more information, see the + documentation of + <seealso marker="#process_flag_max_heap_size"><c>process_flag(max_heap_size, + <anno>Size</anno>)</c></seealso>.</p> + </item> + <tag><c>{message_queue_data, <anno>MQD</anno>}</c></tag> + <item> + <p>Sets the state of the <c>message_queue_data</c> process + flag. <c><anno>MQD</anno></c> should be either <c>off_heap</c>, + or <c>on_heap</c>. The default + <c>message_queue_data</c> process flag is determined by the + <seealso marker="erl#+hmqd"><c>+hmqd</c></seealso> <c>erl</c> + command line argument. For more information, see the + documentation of + <seealso marker="#process_flag_message_queue_data"><c>process_flag(message_queue_data, + <anno>MQD</anno>)</c></seealso>.</p> + </item> </taglist> </desc> </func> + <func> <name name="spawn_opt" arity="5"/> - <type name="priority_level" /> - <fsummary>Create a new process with a function as entry point on a given node</fsummary> - <desc> - <p>Returns the pid of a new process started by the application - of <c><anno>Module</anno>:<anno>Function</anno></c> to <c><anno>Args</anno></c> on <c>Node</c>. If + <fsummary>Creates a new process with a function as entry point on a given node.</fsummary> + <type name="priority_level"/> + <type name="max_heap_size" /> + <type name="message_queue_data" /> + <type name="spawn_opt_option" /> + <desc> + <p>Returns the process identifier (pid) of a new process started + by the application + of <c><anno>Module</anno>:<anno>Function</anno></c> to + <c><anno>Args</anno></c> on <c><anno>Node</anno></c>. If <c><anno>Node</anno></c> does not exist, a useless pid is returned. Otherwise works like <seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p> + <note><p>Option <c>monitor</c> is not supported by + <c>spawn_opt/5</c>.</p></note> </desc> </func> + <func> <name name="split_binary" arity="2"/> + <fsummary>Splits a binary into two.</fsummary> <type_desc variable="Pos">0..byte_size(Bin)</type_desc> - <fsummary>Split a binary into two</fsummary> <desc> - <p>Returns a tuple containing the binaries which are the result - of splitting <c><anno>Bin</anno></c> into two parts at position <c><anno>Pos</anno></c>. + <p>Returns a tuple containing the binaries that are the result + of splitting <c><anno>Bin</anno></c> into two parts at + position <c><anno>Pos</anno></c>. This is not a destructive operation. After the operation, - there will be three binaries altogether.</p> + there are three binaries altogether.</p> + <p>Example:</p> <pre> > <input>B = list_to_binary("0123456789").</input> <<"0123456789">> @@ -4637,156 +5890,409 @@ true</pre> 7</pre> </desc> </func> + <func> - <name name="start_timer" arity="3"/> - <type_desc variable="Time">0 <= Time <= 4294967295</type_desc> - <fsummary>Start a timer</fsummary> + <name name="start_timer" arity="4"/> + <fsummary>Starts a timer.</fsummary> <desc> - <p>Starts a timer which will send the message - <c>{timeout, <anno>TimerRef</anno>, <anno>Msg</anno>}</c> to <c><anno>Dest</anno></c> - after <c><anno>Time</anno></c> milliseconds.</p> - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to be a <c>pid()</c> of a local process, dead or alive.</p> - <p>The <c><anno>Time</anno></c> value can, in the current implementation, not be greater than 4294967295.</p> - <p>If <c><anno>Dest</anno></c> is an <c>atom()</c>, it is supposed to be the name of - a registered process. The process referred to by the name is - looked up at the time of delivery. No error is given if - the name does not refer to a process.</p> - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer will be automatically - canceled if the process referred to by the <c>pid()</c> is not alive, - or when the process exits. This feature was introduced in - erts version 5.4.11. Note that timers will not be - automatically canceled when <c><anno>Dest</anno></c> is an <c>atom()</c>.</p> + <p> + Starts a timer. When the timer expires, the message + <c>{timeout, <anno>TimerRef</anno>, <anno>Msg</anno>}</c> + is sent to the process identified by + <c><anno>Dest</anno></c>. + </p> + <p>Available <c><anno>Option</anno></c>s:</p> + <taglist> + <tag><c>{abs, false}</c></tag> + <item> + <p> + This is the default. It means the + <c><anno>Time</anno></c> value is interpreted + as a time in milli-seconds <em>relative</em> current + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso>. + </p> + </item> + <tag><c>{abs, true}</c></tag> + <item> + <p> + Absolute <c><anno>Time</anno></c> value. The + <c><anno>Time</anno></c> value is interpreted as an + absolute Erlang monotonic time in milli-seconds. + </p> + </item> + </taglist> + <p> + More <c><anno>Option</anno></c>s may be added in the future. + </p> + <p> + The absolute point in time, the timer is set to expire on, + has to be in the interval + <c>[</c><seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso><c>, + </c><seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso><c>]</c>. + Further, if a relative time is specified, the <c><anno>Time</anno></c> value + is not allowed to be negative. + </p> + <p> + If <c><anno>Dest</anno></c> is a <c>pid()</c>, it must + be a <c>pid()</c> of a process created on the current + runtime system instance. This process may or may not + have terminated. If <c><anno>Dest</anno></c> is an + <c>atom()</c>, it is interpreted as the name of a + locally registered process. The process referred to by the + name is looked up at the time of timer expiration. No error + is given if the name does not refer to a process. + </p> + <p> + If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer is + automatically canceled if the process referred to by the + <c>pid()</c> is not alive, or if the process exits. This + feature was introduced in ERTS version 5.4.11. Notice that + timers are not automatically canceled when + <c><anno>Dest</anno></c> is an <c>atom()</c>. + </p> <p>See also - <seealso marker="#send_after/3">erlang:send_after/3</seealso>, - <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>, + <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>, + <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>, and - <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p> - <p>Failure: <c>badarg</c> if the arguments does not satisfy - the requirements specified above.</p> + <seealso marker="#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p> + <p>Failure: <c>badarg</c> if the arguments do not satisfy + the requirements specified here.</p> </desc> </func> + <func> - <name name="statistics" arity="1" clause_i="1"/> - <fsummary>Information about context switches</fsummary> + <name name="start_timer" arity="3"/> + <fsummary>Starts a timer.</fsummary> <desc> - <p><c><anno>ContextSwitches</anno></c> is the total number of context - switches since the system started.</p> + <p>Starts a timer. The same as calling + <seealso marker="#start_timer/4"><c>erlang:start_timer(<anno>Time</anno>, + <anno>Dest</anno>, <anno>Msg</anno>, [])</c></seealso>.</p> </desc> </func> + + <func> + <name name="statistics" arity="1" clause_i="1"/> + <fsummary>Information about active processes and ports.</fsummary> + <desc><marker id="statistics_active_tasks"></marker> + <p> + Returns a list where each element represents the amount + of active processes and ports on each run queue and its + associated scheduler. That is, the number of processes and + ports that are ready to run, or are currently running. The + element location in the list corresponds to the scheduler + and its run queue. The first element corresponds to scheduler + number 1 and so on. The information is <em>not</em> gathered + atomically. That is, the result is not necessarily a + consistent snapshot of the state, but instead quite + efficiently gathered. See also, + <seealso marker="#statistics_total_active_tasks"><c>statistics(total_active_tasks)</c></seealso>, + <seealso marker="#statistics_run_queue_lengths"><c>statistics(run_queue_lengths)</c></seealso>, and + <seealso marker="#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso>. + </p> + </desc> + </func> + <func> <name name="statistics" arity="1" clause_i="2"/> - <fsummary>Information about exact reductions</fsummary> + <fsummary>Information about context switches.</fsummary> <desc> - <marker id="statistics_exact_reductions"></marker> - <note><p><c>statistics(exact_reductions)</c> is - a more expensive operation than - <seealso marker="#statistics_reductions">statistics(reductions)</seealso> - especially on an Erlang machine with SMP support.</p> - </note> + <p>Returns the total number of context switches since the + system started.</p> </desc> </func> + <func> <name name="statistics" arity="1" clause_i="3"/> - <fsummary>Information about garbage collection</fsummary> + <fsummary>Information about exact reductions.</fsummary> <desc> - <p>This information may not be valid for all implementations.</p> - <pre> -> <input>statistics(garbage_collection).</input> -{85,23961,0} -</pre> + <marker id="statistics_exact_reductions"></marker> + <p>Returns the number of exact reductions.</p> + <note><p><c>statistics(exact_reductions)</c> is + a more expensive operation than + <seealso marker="#statistics_reductions">statistics(reductions)</seealso>, + especially on an Erlang machine with SMP support.</p> + </note> </desc> </func> + <func> <name name="statistics" arity="1" clause_i="4"/> - <fsummary>Information about io</fsummary> + <fsummary>Information about garbage collection.</fsummary> <desc> - <p><c><anno>Input</anno></c> is the total number of bytes received - through ports, and <c><anno>Output</anno></c> is the total number of - bytes output to ports.</p> + <p>Returns information about garbage collection, for example:</p> + <pre> +> <input>statistics(garbage_collection).</input> +{85,23961,0}</pre> + <p>This information can be invalid for some implementations.</p> </desc> </func> + <func> <name name="statistics" arity="1" clause_i="5"/> - <fsummary>Information about reductions</fsummary> + <fsummary>Information about I/O.</fsummary> <desc> - <marker id="statistics_reductions"></marker> - <note> - <p>Since erts-5.5 (OTP release R11B) - this value does not include reductions performed in current - time slices of currently scheduled processes. If an - exact value is wanted, use - <seealso marker="#statistics_exact_reductions">statistics(exact_reductions)</seealso>.</p> - </note> - <pre> -> <input>statistics(reductions).</input> -{2046,11} -</pre> + <p>Returns <c><anno>Input</anno></c>, + which is the total number of bytes + received through ports, and <c><anno>Output</anno></c>, + which is the total number of bytes output to ports.</p> </desc> </func> + <func> <name name="statistics" arity="1" clause_i="6"/> - <fsummary>Information about the run-queue</fsummary> + <fsummary>Information about microstate accounting.</fsummary> <desc> - <p>Returns the length of the run queue, that is, the number - of processes that are ready to run.</p> + <marker id="statistics_microstate_accounting"></marker> + <p> + Microstate accounting can be used to measure how much time the Erlang + runtime system spends doing various tasks. It is designed to be as + lightweight as possible, but there will be some overhead when this + is enabled. Microstate accounting is meant to be a profiling tool + to help figure out performance bottlenecks. + To <c>start</c>/<c>stop</c>/<c>reset</c> microstate_accounting you use + the system_flag + <seealso marker="#system_flag_microstate_accounting"> + <c>microstate_accounting</c></seealso>. + </p> + <p> + <c>erlang:statistics(microstate_accounting)</c> returns a list of maps + representing some of the OS threads within ERTS. Each map contains + <c>type</c> and <c>id</c> fields that can be used to identify what + thread it is, and also a counters field that contains data about how + much time has been spent in the various states.</p> + <pre> +> <input>erlang:statistics(microstate_accounting).</input> +[#{counters => #{aux => 1899182914, + check_io => 2605863602, + emulator => 45731880463, + gc => 1512206910, + other => 5421338456, + port => 221631, + sleep => 5150294100}, + id => 1, + type => scheduler}|...] + </pre> + <p>The time unit is the same as returned by + <seealso marker="kernel:os#perf_counter/0"> + <c>os:perf_counter/0</c></seealso>. + So to convert it to milliseconds you could do something like this:</p> + <pre> +lists:map( + fun(#{ counters := Cnt } = M) -> + MsCnt = maps:map(fun(_K, PerfCount) -> + erlang:convert_time_unit(PerfCount, perf_counter, 1000) + end, Cnt), + M#{ counters := MsCnt } + end, erlang:statistics(microstate_accounting)). + </pre> + <p> + It is important to note that these values are not guaranteed to be + the exact time spent in each state. This is because of various + optimisation done in order to keep the overhead as small as possible. + </p> + + <p>Currently the following <c><anno>MSAcc_Thread_Type</anno></c> are available:</p> + <taglist> + <tag><c>scheduler</c></tag> + <item>The main execution threads that do most of the work.</item> + <tag><c>async</c></tag><item>Async threads are used by various + linked-in drivers (mainly the file drivers) do offload non-cpu + intensive work.</item> + <tag><c>aux</c></tag><item>Takes care of any work that is not + specifically assigned to a scheduler.</item> + </taglist> + <p>Currently the following <c><anno>MSAcc_Thread_State</anno></c>s are available. + All states are exclusive, meaning that a thread cannot be in two states + at once. So if you add the numbers of all counters in a thread + you will get the total run-time for that thread.</p> + <taglist> + <tag><c>aux</c></tag> + <item>Time spent handling auxiliary jobs.</item> + <tag><c>check_io</c></tag> + <item>Time spent checking for new I/O events.</item> + <tag><c>emulator</c></tag> + <item>Time spent executing erlang processes.</item> + <tag><c>gc</c></tag> + <item>Time spent doing garbage collection. When extra states are + enabled this is the time spent doing non-fullsweep garbage + collections.</item> + <tag><c>other</c></tag> + <item>Time spent doing unaccounted things.</item> + <tag><c>port</c></tag> + <item>Time spent executing ports.</item> + <tag><c>sleep</c></tag> + <item>Time spent sleeping.</item> + </taglist> + <p>It is possible to add more fine grained <c><anno>MSAcc_Thread_State</anno></c>s + through configure. + (e.g. <c>./configure --with-microstate-accounting=extra</c>). + Enabling these states will cause a performance degradation when + microstate accounting is turned off and increase the overhead when + it is turned on.</p> + <taglist> + <tag><c>alloc</c></tag> + <item>Time spent managing memory. Without extra states this time is + spread out over all other states.</item> + <tag><c>bif</c></tag> + <item>Time spent in bifs. Without extra states this time is part of + the <c>emulator</c> state.</item> + <tag><c>busy_wait</c></tag> + <item>Time spent busy waiting. This is also the state where a + scheduler no longer reports that it is active when using + <seealso marker="#statistics_scheduler_wall_time"> + <c>erlang:statistics(scheduler_wall_time)</c></seealso>. + So if you add all other states but this and sleep and then divide that + by all time in the thread you should get something very similar to the + scheduler_wall_time fraction. Without extra states this time is part + of the <c>other</c> state.</item> + <tag><c>ets</c></tag> + <item>Time spent executing ETS bifs. Without extra states this time is + part of the <c>emulator</c> state.</item> + <tag><c>gc_full</c></tag> + <item>Time spent doing fullsweep garbage collection. Without extra + states this time is part of the <c>gc</c> state.</item> + <tag><c>nif</c></tag> + <item>Time spent in nifs. Without extra states this time is part of + the <c>emulator</c> state.</item> + <tag><c>send</c></tag> + <item>Time spent sending messages (processes only). Without extra + states this time is part of the <c>emulator</c> state.</item> + <tag><c>timers</c></tag> + <item>Time spent managing timers. Without extra states this time is + part of the <c>other</c> state.</item> + </taglist> + <p>There is a utility module called + <seealso marker="runtime_tools:msacc"><c>msacc</c></seealso> in + runtime_tools that can be used to more easily analyse these + statistics.</p> + + <p> + Returns <c>undefined</c> if the system flag + <seealso marker="#system_flag_microstate_accounting"> + <c>microstate_accounting</c></seealso> + is turned off. + </p> + <p>The list of thread information is unsorted and may appear in + different order between calls.</p> + <note><p>The threads and states are subject to change without any + prior notice.</p></note> </desc> </func> <func> <name name="statistics" arity="1" clause_i="7"/> - <fsummary>Information about run-time</fsummary> + <fsummary>Information about reductions.</fsummary> <desc> - <p>Note that the run-time is the sum of the run-time for all - threads in the Erlang run-time system and may therefore be greater - than the wall-clock time.</p> + <marker id="statistics_reductions"></marker> + <p>Returns information about reductions, for example:</p> <pre> -> <input>statistics(runtime).</input> -{1690,1620} -</pre> +> <input>statistics(reductions).</input> +{2046,11}</pre> + <note><p>As from <c>ERTS</c> 5.5 (OTP R11B), + this value does not include reductions performed in current + time slices of currently scheduled processes. If an + exact value is wanted, use + <seealso marker="#statistics_exact_reductions">statistics(exact_reductions)</seealso>.</p> + </note> </desc> </func> + <func> <name name="statistics" arity="1" clause_i="8"/> - <fsummary>Information about each schedulers work time</fsummary> - <desc> - <marker id="statistics_scheduler_wall_time"></marker> - <p> - Returns a list of tuples with <c>{<anno>SchedulerId</anno>, - <anno>ActiveTime</anno>, <anno>TotalTime</anno>}</c>, where - <c>SchedulerId</c> is an integer id of the scheduler, <c>ActiveTime</c> is - the duration the scheduler has been busy, <c>TotalTime</c> is the total time duration since - <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso> - activation. The time unit is not defined and may be subject to change - between releases, operating systems and system restarts. - <c>scheduler_wall_time</c> should only be used to calculate relative - values for scheduler-utilization. <c>ActiveTime</c> can never exceed <c>TotalTime</c>. - </p> + <fsummary>Information about the run-queues.</fsummary> + <desc><marker id="statistics_run_queue"></marker> + <p> + Returns the total length of the run-queues. That is, the number + of processes and ports that are ready to run on all available + run-queues. The information is gathered atomically. That + is, the result is a consistent snapshot of the state, but + this operation is much more expensive compared to + <seealso marker="#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso>. + This especially when a large amount of schedulers is used. + </p> + </desc> + </func> - <p>The definition of a busy scheduler is when it is not idle or not - scheduling (selecting) a process or port, meaning; executing process - code, executing linked-in-driver or NIF code, executing - built-in-functions or any other runtime handling, garbage collecting - or handling any other memory management. Note, a scheduler may also be - busy even if the operating system has scheduled out the scheduler - thread. - </p> + <func> + <name name="statistics" arity="1" clause_i="9"/> + <fsummary>Information about the run-queue lengths.</fsummary> + <desc><marker id="statistics_run_queue_lengths"></marker> + <p> + Returns a list where each element represents the amount + of processes and ports ready to run for each run queue. The + element location in the list corresponds to the run queue + of a scheduler. The first element corresponds to the run + queue of scheduler number 1 and so on. The information is + <em>not</em> gathered atomically. That is, the result is + not necessarily a consistent snapshot of the state, but + instead quite efficiently gathered. See also, + <seealso marker="#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso>, + <seealso marker="#statistics_active_tasks"><c>statistics(active_tasks)</c></seealso>, and + <seealso marker="#statistics_total_active_tasks"><c>statistics(total_active_tasks)</c></seealso>. + </p> + </desc> + </func> - <p> - Returns <c>undefined</c> if the system flag - <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso> - is turned off. - </p> + <func> + <name name="statistics" arity="1" clause_i="10"/> + <fsummary>Information about runtime.</fsummary> + <desc> + <p>Returns information about runtime, in milliseconds.</p> + <p>This is the sum of the runtime for all threads + in the Erlang runtime system and can therefore be greater + than the wall clock time.</p> + <p>Example:</p> + <pre> +> <input>statistics(runtime).</input> +{1690,1620}</pre> + </desc> + </func> - <p>The list of scheduler information is unsorted and may appear in different order - between calls. - </p> - <p>Using <c>scheduler_wall_time</c> to calculate scheduler utilization.</p> + <func> + <name name="statistics" arity="1" clause_i="11"/> + <fsummary>Information about each schedulers work time.</fsummary> + <desc> + <marker id="statistics_scheduler_wall_time"></marker> + <p>Returns a list of tuples with + <c>{<anno>SchedulerId</anno>, <anno>ActiveTime</anno>, + <anno>TotalTime</anno>}</c>, where + <c><anno>SchedulerId</anno></c> is an integer ID of the scheduler, + <c><anno>ActiveTime</anno></c> is + the duration the scheduler has been busy, and + <c><anno>TotalTime</anno></c> is the total time duration since + <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso> + activation. The time unit is undefined and can be subject + to change between releases, OSs, and system restarts. + <c>scheduler_wall_time</c> is only to be used to + calculate relative values for scheduler-utilization. + <c><anno>ActiveTime</anno></c> can never exceed + <c><anno>TotalTime</anno></c>.</p> + <p>The definition of a busy scheduler is when it is not idle + and is not scheduling (selecting) a process or port, + that is:</p> + <list type="bulleted"> + <item>Executing process code</item> + <item>Executing linked-in-driver or NIF code</item> + <item>Executing built-in-functions, or any other runtime + handling</item> + <item>Garbage collecting</item> + <item>Handling any other memory management</item> + </list> + <p>Notice that a scheduler can also be busy even if the + OS has scheduled out the scheduler thread.</p> + <p>Returns <c>undefined</c> if system flag + <seealso marker="#system_flag_scheduler_wall_time">scheduler_wall_time</seealso> + is turned off.</p> + <p>The list of scheduler information is unsorted and can + appear in different order between calls.</p> + <p>Using <c>scheduler_wall_time</c> to calculate scheduler-utilization:</p> <pre> > <input>erlang:system_flag(scheduler_wall_time, true).</input> false > <input>Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.</input> -ok -</pre> - <p>Some time later we will take another snapshot and calculate scheduler-utilization per scheduler.</p> +ok</pre> + <p>Some time later the user takes another snapshot and calculates + scheduler-utilization per scheduler, for example:</p> <pre> > <input>Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.</input> ok @@ -4799,86 +6305,127 @@ ok {5,0.9717956667018103}, {6,0.9739235846420741}, {7,0.973237033077876}, - {8,0.9741297293248656}] -</pre> - <p>Using the same snapshots to calculate a total scheduler-utilization.</p> + {8,0.9741297293248656}]</pre> + <p>Using the same snapshots to calculate a total scheduler-utilization:</p> <pre> > <input>{A, T} = lists:foldl(fun({{_, A0, T0}, {_, A1, T1}}, {Ai,Ti}) -> {Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), A/T.</input> -0.9769136803764825 -</pre> +0.9769136803764825</pre> <note> - <p><c>scheduler_wall_time</c> is by default disabled. Use <c>erlang:system_flag(scheduler_wall_time, true)</c> to enable it. </p> + <p><c>scheduler_wall_time</c> is by default disabled. To + enable it, use + <c>erlang:system_flag(scheduler_wall_time, true)</c>.</p> </note> </desc> </func> + <func> - <name name="statistics" arity="1" clause_i="9"/> - <fsummary>Information about wall-clock</fsummary> + <name name="statistics" arity="1" clause_i="12"/> + <fsummary>Information about active processes and ports.</fsummary> + <desc><marker id="statistics_total_active_tasks"></marker> + <p> + Returns the total amount of active processes and ports in + the system. That is, the number of processes and ports that + are ready to run, or are currently running. The information + is <em>not</em> gathered atomically. That is, the result + is not necessarily a consistent snapshot of the state, but + instead quite efficiently gathered. See also, + <seealso marker="#statistics_active_tasks"><c>statistics(active_tasks)</c></seealso>, + <seealso marker="#statistics_run_queue_lengths"><c>statistics(run_queue_lengths)</c></seealso>, and + <seealso marker="#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso>. + </p> + </desc> + </func> + + <func> + <name name="statistics" arity="1" clause_i="13"/> + <fsummary>Information about the run-queue lengths.</fsummary> + <desc><marker id="statistics_total_run_queue_lengths"></marker> + <p> + Returns the total length of the run-queues. That is, the number + of processes and ports that are ready to run on all available + run-queues. The information is <em>not</em> gathered atomically. + That is, the result is not necessarily a consistent snapshot of + the state, but much more efficiently gathered compared to + <seealso marker="#statistics_run_queue"><c>statistics(run_queue)</c></seealso>. + See also, + <seealso marker="#statistics_run_queue_lengths"><c>statistics(run_queue_lengths)</c></seealso>, + <seealso marker="#statistics_total_active_tasks"><c>statistics(total_active_tasks)</c></seealso>, and + <seealso marker="#statistics_active_tasks"><c>statistics(active_tasks)</c></seealso>. + </p> + </desc> + </func> + + <func> + <name name="statistics" arity="1" clause_i="14"/> + <fsummary>Information about wall clock.</fsummary> <desc> - <p><c>wall_clock</c> can be used in the same manner as + <p>Returns information about wall clock. <c>wall_clock</c> can + be used in the same manner as <c>runtime</c>, except that real time is measured as opposed to runtime or CPU time.</p> </desc> </func> + <func> <name name="suspend_process" arity="2"/> - <fsummary>Suspend a process</fsummary> + <fsummary>Suspends a process.</fsummary> <desc> <p>Increases the suspend count on the process identified by - <c><anno>Suspendee</anno></c> and puts it in the suspended state if it isn't - already in the suspended state. A suspended process will not be - scheduled for execution until the process has been resumed. - </p> - + <c><anno>Suspendee</anno></c> and puts it in the suspended + state if it is not + already in that state. A suspended process will not be + scheduled for execution until the process has been resumed.</p> <p>A process can be suspended by multiple processes and can be suspended multiple times by a single process. A suspended - process will not leave the suspended state until its suspend - count reach zero. The suspend count of <c><anno>Suspendee</anno></c> - is decreased when + process does not leave the suspended state until its suspend + count reaches zero. The suspend count of + <c><anno>Suspendee</anno></c> is decreased when <seealso marker="#resume_process/1">erlang:resume_process(<anno>Suspendee</anno>)</seealso> is called by the same process that called - <c>erlang:suspend_process(<anno>Suspendee</anno>)</c>. All increased suspend - counts on other processes acquired by a process will automatically be + <c>erlang:suspend_process(<anno>Suspendee</anno>)</c>. + All increased suspend + counts on other processes acquired by a process are automatically decreased when the process terminates.</p> - - <p>Currently the following options (<c><anno>Opt</anno></c>s) are available:</p> + <p>The options (<c><anno>Opt</anno></c>s) are as follows:</p> <taglist> <tag><c>asynchronous</c></tag> <item> A suspend request is sent to the process identified by - <c><anno>Suspendee</anno></c>. <c><anno>Suspendee</anno></c> will eventually suspend - unless it is resumed before it was able to suspend. The caller - of <c>erlang:suspend_process/2</c> will return immediately, - regardless of whether the <c><anno>Suspendee</anno></c> has suspended yet - or not. Note that the point in time when the <c><anno>Suspendee</anno></c> - will actually suspend cannot be deduced from other events - in the system. The only guarantee given is that the - <c><anno>Suspendee</anno></c> will <em>eventually</em> suspend (unless it - is resumed). If the <c>asynchronous</c> option has <em>not</em> - been passed, the caller of <c>erlang:suspend_process/2</c> will - be blocked until the <c><anno>Suspendee</anno></c> has actually suspended. + <c><anno>Suspendee</anno></c>. <c><anno>Suspendee</anno></c> + eventually suspends + unless it is resumed before it could suspend. The caller + of <c>erlang:suspend_process/2</c> returns immediately, + regardless of whether <c><anno>Suspendee</anno></c> has + suspended yet or not. The point in time when + <c><anno>Suspendee</anno></c> suspends cannot be deduced + from other events in the system. It is only guaranteed that + <c><anno>Suspendee</anno></c> <em>eventually</em> suspends + (unless it + is resumed). If option <c>asynchronous</c> has <em>not</em> + been passed, the caller of <c>erlang:suspend_process/2</c> is + blocked until <c><anno>Suspendee</anno></c> has suspended. </item> <tag><c>unless_suspending</c></tag> <item> - The process identified by <c><anno>Suspendee</anno></c> will be suspended - unless the calling process already is suspending the - <c><anno>Suspendee</anno></c>. If <c>unless_suspending</c> is combined - with the <c>asynchronous</c> option, a suspend request will be - sent unless the calling process already is suspending the - <c><anno>Suspendee</anno></c> or if a suspend request already has been sent - and is in transit. If the calling process already is suspending - the <c><anno>Suspendee</anno></c>, or if combined with the <c>asynchronous</c> - option and a send request already is in transit, - <c>false</c> is returned and the suspend count on <c><anno>Suspendee</anno></c> - will remain unchanged. + The process identified by <c><anno>Suspendee</anno></c> is + suspended unless the calling process already is suspending + <c><anno>Suspendee</anno></c>. + If <c>unless_suspending</c> is combined + with option <c>asynchronous</c>, a suspend request is + sent unless the calling process already is suspending + <c><anno>Suspendee</anno></c> or if a suspend request + already has been sent and is in transit. If the calling + process already is suspending <c><anno>Suspendee</anno></c>, + or if combined with option <c>asynchronous</c> + and a send request already is in transit, + <c>false</c> is returned and the suspend count on + <c><anno>Suspendee</anno></c> remains unchanged. </item> </taglist> - <p>If the suspend count on the process identified by - <c><anno>Suspendee</anno></c> was increased, <c>true</c> is returned; otherwise, - <c>false</c> is returned.</p> - + <c><anno>Suspendee</anno></c> is increased, <c>true</c> + is returned, otherwise <c>false</c>.</p> <warning> <p>This BIF is intended for debugging only.</p> </warning> @@ -4886,282 +6433,362 @@ ok <taglist> <tag><c>badarg</c></tag> <item> - If <c><anno>Suspendee</anno></c> isn't a process identifier. + If <c><anno>Suspendee</anno></c> is not a process identifier. </item> <tag><c>badarg</c></tag> <item> - If the process identified by <c><anno>Suspendee</anno></c> is same the process as - the process calling <c>erlang:suspend_process/2</c>. + If the process identified by <c><anno>Suspendee</anno></c> + is the same process + as the process calling <c>erlang:suspend_process/2</c>. </item> <tag><c>badarg</c></tag> <item> - If the process identified by <c><anno>Suspendee</anno></c> is not alive. + If the process identified by <c><anno>Suspendee</anno></c> + is not alive. </item> <tag><c>badarg</c></tag> <item> - If the process identified by <c><anno>Suspendee</anno></c> resides on another node. + If the process identified by <c><anno>Suspendee</anno></c> + resides on another node. </item> <tag><c>badarg</c></tag> <item> - If <c><anno>OptList</anno></c> isn't a proper list of valid <c><anno>Opt</anno></c>s. + If <c><anno>OptList</anno></c> is not a proper list of valid + <c><anno>Opt</anno></c>s. </item> <tag><c>system_limit</c></tag> <item> - If the process identified by <c><anno>Suspendee</anno></c> has been suspended more - times by the calling process than can be represented by the - currently used internal data structures. The current system limit - is larger than 2 000 000 000 suspends, and it will never be less - than that. + If the process identified by <c><anno>Suspendee</anno></c> + has been suspended + more times by the calling process than can be represented by the + currently used internal data structures. The system limit is + higher than 2,000,000,000 suspends and will never be lower. </item> </taglist> </desc> </func> + <func> <name name="suspend_process" arity="1"/> - <fsummary>Suspend a process</fsummary> + <fsummary>Suspends a process.</fsummary> <desc> - <p>Suspends the process identified by <c><anno>Suspendee</anno></c>. The - same as calling - <seealso marker="#suspend_process/2">erlang:suspend_process(<anno>Suspendee</anno>, [])</seealso>. For more information see the documentation of <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>. - </p> + <p>Suspends the process identified by + <c><anno>Suspendee</anno></c>. The same as calling + <seealso marker="#suspend_process/2">erlang:suspend_process(<anno>Suspendee</anno>, + [])</seealso>.</p> <warning> <p>This BIF is intended for debugging only.</p> </warning> </desc> </func> + <func> <name name="system_flag" arity="2" clause_i="1"/> - <fsummary>Set system flag backtrace_depth</fsummary> + <fsummary>Sets system flag <c>backtrace_depth</c>.</fsummary> <desc> <p>Sets the maximum depth of call stack back-traces in the exit reason element of <c>'EXIT'</c> tuples.</p> <p>Returns the old value of the flag.</p> </desc> </func> + <func> <name name="system_flag" arity="2" clause_i="2"/> + <fsummary>Sets system flag <c>cpu_topology</c>.</fsummary> <type name="cpu_topology"/> <type name="level_entry"/> <type name="level_tag"/> <type name="sub_level"/> <type name="info_list"/> - <fsummary>Set system flag cpu_topology</fsummary> <desc> <warning> <p><marker id="system_flag_cpu_topology"></marker> - This argument is <em>deprecated</em> and - scheduled for removal in erts-5.10/OTP-R16. Instead of using - this argument you are advised to use the <c>erl</c> command - line argument <seealso marker="erts:erl#+sct">+sct</seealso>. - When this argument has been removed a final CPU topology to use - will be determined at emulator boot time.</p> + This argument is <em>deprecated</em> and scheduled for + removal in <c>ERTS</c> 5.10/OTP R16. Instead of using this + argument, use command-line argument + <seealso marker="erts:erl#+sct">+sct</seealso> in + <c>erl(1)</c>.</p> + <p>When this argument is removed, a final CPU topology + to use is determined at emulator boot time.</p> </warning> - <p>Sets the user defined <c><anno>CpuTopology</anno></c>. The user defined - CPU topology will override any automatically detected - CPU topology. By passing <c>undefined</c> as <c><anno>CpuTopology</anno></c> - the system will revert back to the CPU topology automatically + <p>Sets the user-defined <c><anno>CpuTopology</anno></c>. + The user-defined + CPU topology overrides any automatically detected + CPU topology. By passing <c>undefined</c> as + <c><anno>CpuTopology</anno></c>, + the system reverts to the CPU topology automatically detected. The returned value equals the value returned from <c>erlang:system_info(cpu_topology)</c> before the - change was made. - </p> + change was made.</p> <p>Returns the old value of the flag.</p> <p>The CPU topology is used when binding schedulers to logical processors. If schedulers are already bound when the CPU - topology is changed, the schedulers will be sent a request - to rebind according to the new CPU topology. - </p> - <p>The user defined CPU topology can also be set by passing - the <seealso marker="erts:erl#+sct">+sct</seealso> command - line argument to <c>erl</c>. - </p> - <p>For information on the <c><anno>CpuTopology</anno></c> type - and more, see the documentation of - <seealso marker="#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso>, - and the <c>erl</c> <seealso marker="erts:erl#+sct">+sct</seealso> - and <seealso marker="erts:erl#+sbt">+sbt</seealso> - command line flags. - </p> + topology is changed, the schedulers are sent a request + to rebind according to the new CPU topology.</p> + <p>The user-defined CPU topology can also be set by passing + command-line argument + <seealso marker="erts:erl#+sct">+sct</seealso> to + <c>erl(1)</c>.</p> + <p>For information on type <c><anno>CpuTopology</anno></c> + and more, see + <seealso marker="#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso> + as well as the command-line flags + <seealso marker="erts:erl#+sct">+sct</seealso> and + <seealso marker="erts:erl#+sbt">+sbt</seealso> in + <c>erl(1)</c>.</p> </desc> </func> + <func> <name name="system_flag" arity="2" clause_i="3"/> - <fsummary>Set system flag fullsweep_after</fsummary> + <fsummary>Sets <c>system_flag_dirty_cpu_schedulers_online</c>.</fsummary> + <desc> + <p><marker id="system_flag_dirty_cpu_schedulers_online"></marker> + Sets the number of dirty CPU schedulers online. Range is + <![CDATA[1 <= DirtyCPUSchedulersOnline <= N]]>, where <c>N</c> + is the smallest of the return values of + <c>erlang:system_info(dirty_cpu_schedulers)</c> and + <c>erlang:system_info(schedulers_online)</c>.</p> + <p>Returns the old value of the flag.</p> + <p>The number of dirty CPU schedulers online can change if the + number of schedulers online changes. For example, if 12 + schedulers and 6 dirty CPU schedulers are online, and + <c>system_flag/2</c> is used to set the number of + schedulers online to 6, then the number of dirty CPU + schedulers online is automatically decreased by half as well, + down to 3. Similarly, the number of dirty CPU schedulers + online increases proportionally to increases in the number of + schedulers online.</p> + <note><p>The dirty schedulers functionality is experimental. + Enable support for dirty schedulers when building OTP to + try out the functionality.</p> + </note> + <p>For more information, see + <seealso marker="#system_info_dirty_cpu_schedulers">erlang:system_info(dirty_cpu_schedulers)</seealso> + and + <seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>.</p> + </desc> + </func> + + <func> + <name name="system_flag" arity="2" clause_i="4"/> + <fsummary>Sets system flag <c>fullsweep_after</c>.</fsummary> <desc> - <p><c><anno>Number</anno></c> is a non-negative integer which indicates + <p>Sets system flag <c>fullsweep_after</c>. + <c><anno>Number</anno></c> is a non-negative integer indicating how many times generational garbage collections can be done without forcing a fullsweep collection. The value - applies to new processes; processes already running are + applies to new processes, while processes already running are not affected.</p> <p>Returns the old value of the flag.</p> <p>In low-memory systems (especially without virtual - memory), setting the value to 0 can help to conserve + memory), setting the value to <c>0</c> can help to conserve memory.</p> - <p>An alternative way to set this value is through the - (operating system) environment variable - <c>ERL_FULLSWEEP_AFTER</c>.</p> + <p>This value can also be set through (OS) + environment variable <c>ERL_FULLSWEEP_AFTER</c>.</p> </desc> </func> + <func> - <name name="system_flag" arity="2" clause_i="4"/> - <fsummary>Set system flag min_heap_size</fsummary> - <desc> - <p>Sets the default minimum heap size for processes. The - size is given in words. The new <c>min_heap_size</c> only - effects processes spawned after the change of - <c>min_heap_size</c> has been made. - The <c>min_heap_size</c> can be set for individual - processes by use of + <name name="system_flag" arity="2" clause_i="5"/> + <fsummary>Set system flag microstate_accounting</fsummary> + <desc><p><marker id="system_flag_microstate_accounting"></marker> + Turns on/off microstate accounting measurements. By passing reset it is possible to reset + all counters to 0.</p> + <p>For more information see, + <seealso marker="#statistics_microstate_accounting">erlang:statistics(microstate_accounting)</seealso>. + </p> + </desc> + </func> + <func> + <name name="system_flag" arity="2" clause_i="6"/> + <fsummary>Sets system flag <c>min_heap_size</c>.</fsummary> + <desc> + <p>Sets the default minimum heap size for processes. The size + is given in words. The new <c>min_heap_size</c> effects + only processes spawned after the change of + <c>min_heap_size</c> has been made. <c>min_heap_size</c> + can be set for individual processes by using <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or - <seealso marker="#process_flag/2">process_flag/2</seealso>. </p> + <seealso marker="#process_flag/2">process_flag/2</seealso>.</p> <p>Returns the old value of the flag.</p> </desc> </func> + <func> - <name name="system_flag" arity="2" clause_i="5"/> - <fsummary>Set system flag min_bin_vheap_size</fsummary> + <name name="system_flag" arity="2" clause_i="7"/> + <fsummary>Sets system flag <c>min_bin_vheap_size</c>.</fsummary> <desc> - <p>Sets the default minimum binary virtual heap size for processes. The - size is given in words. The new <c>min_bin_vhheap_size</c> only - effects processes spawned after the change of + <p>Sets the default minimum binary virtual heap size for + processes. The size is given in words. + The new <c>min_bin_vhheap_size</c> effects only + processes spawned after the change of <c>min_bin_vhheap_size</c> has been made. - The <c>min_bin_vheap_size</c> can be set for individual - processes by use of + <c>min_bin_vheap_size</c> can be set for individual + processes by using <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or - <seealso marker="#process_flag/2">process_flag/2</seealso>. </p> + <seealso marker="#process_flag/2">process_flag/2</seealso>.</p> <p>Returns the old value of the flag.</p> </desc> </func> + + <marker id="system_flag_max_heap_size"></marker> <func> - <name name="system_flag" arity="2" clause_i="6"/> - <fsummary>Set system flag multi_scheduling</fsummary> + <name name="system_flag" arity="2" clause_i="8"/> + <fsummary>Sets system flag <c>max_heap_size</c></fsummary> + <type name="max_heap_size"/> + <desc> + <p> + Sets the default maximum heap size settings for processes. + The size is given in words. The new <c>max_heap_size</c> + effects only processes spawned efter the change has been made. + <c>max_heap_size</c> can be set for individual processes using + <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or + <seealso marker="#process_flag_message_queue_data">process_flag/2</seealso>.</p> + <p>Returns the old value of the flag.</p> + </desc> + </func> + + <func> + <name name="system_flag" arity="2" clause_i="9"/> + <fsummary>Sets system flag <c>multi_scheduling</c>.</fsummary> <desc> <p><marker id="system_flag_multi_scheduling"></marker> If multi-scheduling is enabled, more than one scheduler thread is used by the emulator. Multi-scheduling can be - blocked. When multi-scheduling has been blocked, only - one scheduler thread will schedule Erlang processes.</p> - <p>If <c><anno>BlockState</anno> =:= block</c>, multi-scheduling will - be blocked. If <c><anno>BlockState</anno> =:= unblock</c> and no-one - else is blocking multi-scheduling and this process has - only blocked one time, multi-scheduling will be unblocked. - One process can block multi-scheduling multiple times. - If a process has blocked multiple times, it has to - unblock exactly as many times as it has blocked before it - has released its multi-scheduling block. If a process that - has blocked multi-scheduling exits, it will release its - blocking of multi-scheduling.</p> + blocked in two different ways. Either all schedulers but + one is blocked, or all <em>normal</em> schedulers but + one is blocked. When only normal schedulers are blocked + dirty schedulers are free to continue to schedule + processes.</p> + <p>If <c><anno>BlockState</anno> =:= block</c>, multi-scheduling is + blocked. That is, one and only one scheduler thread will + execute. If <c><anno>BlockState</anno> =:= unblock</c> and no one + else blocks multi-scheduling, and this process has + blocked only once, multi-scheduling is unblocked.</p> + <p>If <c><anno>BlockState</anno> =:= block_normal</c>, normal + multi-scheduling is blocked. That is, only one normal scheduler + thread will execute, but multiple dirty schedulers may execute. + If <c><anno>BlockState</anno> =:= unblock_normal</c> and no one + else blocks normal multi-scheduling, and this process has + blocked only once, normal multi-scheduling is unblocked.</p> + <p>One process can block multi-scheduling as well as normal + multi-scheduling multiple times. If a process has blocked + multiple times, it must unblock exactly as many times as it + has blocked before it has released its multi-scheduling + block. If a process that has blocked multi-scheduling or normal + multi scheduling exits, it automatically releases its blocking + of multi-scheduling and normal multi-scheduling.</p> <p>The return values are <c>disabled</c>, <c>blocked</c>, - or <c>enabled</c>. The returned value describes the - state just after the call to + <c>blocked_normal</c>, or <c>enabled</c>. The returned value + describes the state just after the call to <c>erlang:system_flag(multi_scheduling, <anno>BlockState</anno>)</c> - has been made. The return values are described in the - documentation of <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>.</p> - <p><em>NOTE</em>: Blocking of multi-scheduling should normally - not be needed. If you feel that you need to - block multi-scheduling, think through the - problem at least a couple of times again. - Blocking multi-scheduling should only be used - as a last resort since it will most likely be - a <em>very inefficient</em> way to solve the - problem.</p> - <p>See also <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, + has been made. For information about the return values, see + <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>.</p> + <note><p>Blocking of multi-scheduling and normal multi-scheduling + is normally not needed. If you feel that you need to use these + features, consider it a few more times again. Blocking + multi-scheduling is only to be used as a last resort, as it is + most likely a <em>very inefficient</em> way to solve the problem.</p> + </note> + <p>See also + <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, + <seealso marker="#system_info_normal_multi_scheduling_blockers">erlang:system_info(normal_multi_scheduling_blockers)</seealso>, <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> </desc> </func> + <func> - <name name="system_flag" arity="2" clause_i="7"/> + <name name="system_flag" arity="2" clause_i="10"/> + <fsummary>Sets system flag <c>scheduler_bind_type</c>.</fsummary> <type name="scheduler_bind_type"/> - <fsummary>Set system flag scheduler_bind_type</fsummary> <desc> <warning> <p><marker id="system_flag_scheduler_bind_type"></marker> - This argument is <em>deprecated</em> and - scheduled for removal in erts-5.10/OTP-R16. Instead of using - this argument you are advised to use the <c>erl</c> command - line argument <seealso marker="erts:erl#+sbt">+sbt</seealso>. - When this argument has been removed a final scheduler bind type - to use will be determined at emulator boot time.</p> + This argument is <em>deprecated</em> and scheduled for + removal in <c>ERTS</c> 5.10/OTP R16. Instead of using this + argument, use command-line argument + <seealso marker="erts:erl#+sbt">+sbt</seealso> in <c>erl(1)</c>. + When this argument is removed, a final scheduler bind + type to use is determined at emulator boot time.</p> </warning> <p>Controls if and how schedulers are bound to logical processors.</p> - <p>When <c>erlang:system_flag(scheduler_bind_type, <anno>How</anno>)</c> is - called, an asynchronous signal is sent to all schedulers - online which causes them to try to bind or unbind as requested. - <em>NOTE:</em> If a scheduler fails to bind, this - will often be silently ignored. This since it isn't always - possible to verify valid logical processor identifiers. If - an error is reported, it will be reported to the - <c>error_logger</c>. If you want to verify that the - schedulers actually have bound as requested, call - <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>. - </p> - <p>Schedulers can currently only be bound on newer Linux, + <p>When <c>erlang:system_flag(scheduler_bind_type, <anno>How</anno>)</c> + is called, an asynchronous signal is sent to all schedulers + online, causing them to try to bind or unbind as requested.</p> + <note><p>If a scheduler fails to bind, this is often silently + ignored, as it is not always possible to verify valid + logical processor identifiers. If an error is reported, + it is reported to <c>error_logger</c>. To verify that the + schedulers have bound as requested, call + <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.</p> + </note> + <p>Schedulers can be bound on newer Linux, Solaris, FreeBSD, and Windows systems, but more systems will be - supported in the future. - </p> + supported in future releases.</p> <p>In order for the runtime system to be able to bind schedulers, - the CPU topology needs to be known. If the runtime system fails - to automatically detect the CPU topology, it can be defined. + the CPU topology must be known. If the runtime system fails + to detect the CPU topology automatically, it can be defined. For more information on how to define the CPU topology, see - the <c>erl</c> <seealso marker="erts:erl#+sct">+sct</seealso> command - line flag. - </p> - <p>The runtime system will by default <em>not</em> bind schedulers - to logical processors. - </p> - <p><em>NOTE:</em> If the Erlang runtime system is the only - operating system process that binds threads to logical processors, - this improves the performance of the runtime system. However, - if other operating system processes (as for example another Erlang - runtime system) also bind threads to logical processors, there - might be a performance penalty instead. In some cases this - performance penalty might be severe. If this is the case, you - are advised to not bind the schedulers.</p> - <p>Schedulers can be bound in different ways. The <c><anno>How</anno></c> - argument determines how schedulers are bound. <c><anno>How</anno></c> can - currently be one of:</p> + command-line flag <seealso marker="erts:erl#+sct">+sct</seealso> + in <c>erl(1)</c>.</p> + <p>The runtime system does by default <em>not</em> bind schedulers + to logical processors.</p> + <note><p>If the Erlang runtime system is the only OS + process binding threads to logical processors, this + improves the performance of the runtime system. However, + if other OS processes (for example, another Erlang + runtime system) also bind threads to logical processors, + there can be a performance penalty instead. Sometimes this + performance penalty can be severe. If so, it is recommended + to not bind the schedulers.</p> + </note> + <p>Schedulers can be bound in different ways. Argument + <c><anno>How</anno></c> determines how schedulers are + bound and can be any of the following:</p> <taglist> <tag><c>unbound</c></tag> - <item><p>Same as the <c>erl</c> command line argument - <seealso marker="erts:erl#+sbt">+sbt u</seealso>. + <item><p>Same as command-line argument + <seealso marker="erts:erl#+sbt">+sbt u</seealso> in <c>erl(1)</c>. </p></item> <tag><c>no_spread</c></tag> - <item><p>Same as the <c>erl</c> command line argument - <seealso marker="erts:erl#+sbt">+sbt ns</seealso>. + <item><p>Same as command-line argument + <seealso marker="erts:erl#+sbt">+sbt ns</seealso> in <c>erl(1)</c>. </p></item> <tag><c>thread_spread</c></tag> - <item><p>Same as the <c>erl</c> command line argument - <seealso marker="erts:erl#+sbt">+sbt ts</seealso>. + <item><p>Same as command-line argument + <seealso marker="erts:erl#+sbt">+sbt ts</seealso> in <c>erl(1)</c>. </p></item> <tag><c>processor_spread</c></tag> - <item><p>Same as the <c>erl</c> command line argument - <seealso marker="erts:erl#+sbt">+sbt ps</seealso>. + <item><p>Same as command-line argument + <seealso marker="erts:erl#+sbt">+sbt ps</seealso> in <c>erl(1)</c>. </p></item> <tag><c>spread</c></tag> - <item><p>Same as the <c>erl</c> command line argument - <seealso marker="erts:erl#+sbt">+sbt s</seealso>. + <item><p>Same as command-line argument + <seealso marker="erts:erl#+sbt">+sbt s</seealso> in <c>erl(1)</c>. </p></item> <tag><c>no_node_thread_spread</c></tag> - <item><p>Same as the <c>erl</c> command line argument - <seealso marker="erts:erl#+sbt">+sbt nnts</seealso>. + <item><p>Same as command-line argument + <seealso marker="erts:erl#+sbt">+sbt nnts</seealso> in <c>erl(1)</c>. </p></item> <tag><c>no_node_processor_spread</c></tag> - <item><p>Same as the <c>erl</c> command line argument - <seealso marker="erts:erl#+sbt">+sbt nnps</seealso>. + <item><p>Same as command-line argument + <seealso marker="erts:erl#+sbt">+sbt nnps</seealso> in <c>erl(1)</c>. </p></item> <tag><c>thread_no_node_processor_spread</c></tag> - <item><p>Same as the <c>erl</c> command line argument - <seealso marker="erts:erl#+sbt">+sbt tnnps</seealso>. + <item><p>Same as command-line argument + <seealso marker="erts:erl#+sbt">+sbt tnnps</seealso> in <c>erl(1)</c>. </p></item> <tag><c>default_bind</c></tag> - <item><p>Same as the <c>erl</c> command line argument - <seealso marker="erts:erl#+sbt">+sbt db</seealso>. + <item><p>Same as command-line argument + <seealso marker="erts:erl#+sbt">+sbt db</seealso> in <c>erl(1)</c>. </p></item> </taglist> - <p>The value returned equals <c><anno>How</anno></c> before the - <c>scheduler_bind_type</c> flag was changed.</p> - <p>Failure:</p> + <p>The returned value equals <c><anno>How</anno></c> before flag + <c>scheduler_bind_type</c> was changed.</p> + <p>Failures:</p> <taglist> <tag><c>notsup</c></tag> <item> @@ -5169,130 +6796,171 @@ ok </item> <tag><c>badarg</c></tag> <item> - <p>If <c>How</c> isn't one of the documented alternatives.</p> + <p>If <c><anno>How</anno></c> is not one of the documented + alternatives.</p> </item> <tag><c>badarg</c></tag> <item> - <p>If no CPU topology information is available.</p> + <p>If CPU topology information is unavailable.</p> </item> </taglist> <p>The scheduler bind type can also be set by passing - the <seealso marker="erts:erl#+sbt">+sbt</seealso> command - line argument to <c>erl</c>. - </p> + command-line argument + <seealso marker="erts:erl#+sbt">+sbt</seealso> to <c>erl(1)</c>.</p> <p>For more information, see <seealso marker="#system_info_scheduler_bind_type">erlang:system_info(scheduler_bind_type)</seealso>, <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>, - the <c>erl</c> <seealso marker="erts:erl#+sbt">+sbt</seealso> - and <seealso marker="erts:erl#+sct">+sct</seealso> command line - flags. - </p> + as well as command-line flags + <seealso marker="erts:erl#+sbt">+sbt</seealso> + and <seealso marker="erts:erl#+sct">+sct</seealso> + in <c>erl(1)</c>.</p> </desc> </func> + <func> - <name name="system_flag" arity="2" clause_i="8"/> - <fsummary>Set system flag scheduler_wall_time</fsummary> + <name name="system_flag" arity="2" clause_i="11"/> + <fsummary>Sets system flag <c>scheduler_wall_time</c>.</fsummary> <desc><p><marker id="system_flag_scheduler_wall_time"></marker> - Turns on/off scheduler wall time measurements. </p> - <p>For more information see, - <seealso marker="#statistics_scheduler_wall_time">erlang:statistics(scheduler_wall_time)</seealso>. - </p> + Turns on or off scheduler wall time measurements.</p> + <p>For more information, see + <seealso marker="#statistics_scheduler_wall_time">erlang:statistics(scheduler_wall_time)</seealso>.</p> </desc> </func> + <func> - <name name="system_flag" arity="2" clause_i="9"/> - <fsummary>Set system flag schedulers_online</fsummary> + <name name="system_flag" arity="2" clause_i="12"/> + <fsummary>Sets system flag <c>schedulers_online</c>.</fsummary> <desc> <p><marker id="system_flag_schedulers_online"></marker> - Sets the amount of schedulers online. Valid range is - <![CDATA[1 <= SchedulersOnline <= erlang:system_info(schedulers)]]>. - </p> + Sets the number of schedulers online. Range is + <![CDATA[1 <= SchedulersOnline <= erlang:system_info(schedulers)]]>.</p> <p>Returns the old value of the flag.</p> - <p>For more information see, - <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>, + <p>If the emulator was built with support for + <seealso marker="#system_flag_dirty_cpu_schedulers_online">dirty schedulers</seealso>, + changing the number of schedulers online can also change the + number of dirty CPU schedulers online. For example, if 12 + schedulers and 6 dirty CPU schedulers are online, and + <c>system_flag/2</c> is used to set the number of schedulers + online to 6, then the number of dirty CPU schedulers online + is automatically decreased by half as well, down to 3. + Similarly, the number of dirty CPU schedulers online increases + proportionally to increases in the number of schedulers online.</p> + <p>For more information, see + <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso> and - <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>. - </p> + <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>.</p> </desc> </func> + <func> - <name name="system_flag" arity="2" clause_i="10"/> - <fsummary>Set system flag trace_control_word</fsummary> + <name name="system_flag" arity="2" clause_i="13"/> + <fsummary>Sets system flag <c>trace_control_word</c>.</fsummary> <desc> - <p>Sets the value of the node's trace control word to - <c><anno>TCW</anno></c>. <c><anno>TCW</anno></c> should be an unsigned integer. For - more information see documentation of the + <p>Sets the value of the node trace control word to + <c><anno>TCW</anno></c>, which is to be an unsigned integer. + For more information, see the function <seealso marker="erts:match_spec#set_tcw">set_tcw</seealso> - function in the match specification documentation in the - ERTS User's Guide.</p> + in Section "Match Specifications in Erlang" in the + User's Guide.</p> <p>Returns the old value of the flag.</p> </desc> </func> + + <func> + <name name="system_flag" arity="2" clause_i="14"/> + <fsummary>Finalize the Time Offset</fsummary> + <desc> + <p><marker id="system_flag_time_offset"></marker> + Finalizes the <seealso marker="#time_offset/0">time offset</seealso> + when <seealso marker="time_correction#Single_Time_Warp_Mode">single + time warp mode</seealso> is used. If another time warp mode + is used, the time offset state is left unchanged.</p> + <p>Returns the old state identifier. That is:</p> + <list> + <item><p>If <c>preliminary</c> is returned, finalization was + performed and the time offset is now final.</p></item> + + <item><p>If <c>final</c> is returned, the time offset was + already in the final state. This either because another + <c>erlang:system_flag(time_offset, finalize)</c> call, or + because <seealso marker="time_correction#No_Time_Warp_Mode">no + time warp mode</seealso> is used.</p></item> + + <item><p>If <c>volatile</c> is returned, the time offset + cannot be finalized because + <seealso marker="time_correction#Multi_Time_Warp_Mode">multi + time warp mode</seealso> is used.</p></item> + </list> + </desc> + </func> + <func> <name name="system_info" arity="1" clause_i="1"/> <name name="system_info" arity="1" clause_i="2"/> <name name="system_info" arity="1" clause_i="3"/> <name name="system_info" arity="1" clause_i="4"/> <name name="system_info" arity="1" clause_i="5"/> + <fsummary>Information about the system allocators.</fsummary> <type variable="Allocator" name_i="2"/> <type variable="Version" name_i="2"/> <type variable="Features" name_i="2"/> <type variable="Settings" name_i="2"/> <type variable="Alloc" name_i="3"/> - <fsummary>Information about the allocators of the system</fsummary> <desc> - <p> - Returns various information about the - <marker id="system_info_allocator_tags">allocators</marker> of the + <marker id="system_info_allocator_tags"></marker> + <p>Returns various information about the allocators of the current system (emulator) as specified by <c><anno>Item</anno></c>:</p> + <marker id="system_info_allocated_areas"></marker> <taglist> - <tag><marker id="system_info_allocated_areas"><c>allocated_areas</c></marker></tag> + <tag><c>allocated_areas</c></tag> <item> <p>Returns a list of tuples with information about miscellaneous allocated memory areas.</p> - <p>Each tuple contains an atom describing type of memory as - first element and amount of allocated memory in bytes as - second element. In those cases when there is information - present about allocated and used memory, a third element - is present. This third element contains the amount of + <p>Each tuple contains an atom describing the type of + memory as first element and the amount of allocated + memory in bytes as second element. When information + about allocated and used memory is present, also a + third element is present, containing the amount of used memory in bytes.</p> <p><c>erlang:system_info(allocated_areas)</c> is intended - for debugging, and the content is highly implementation - dependent. The content of the results will therefore - change when needed without prior notice.</p> - <p><em>Note:</em> The sum of these values is <em>not</em> + for debugging, and the content is highly + implementation-dependent. The content of the results + therefore changes when needed without prior notice.</p> + <p>Notice that the sum of these values is <em>not</em> the total amount of memory allocated by the emulator. Some values are part of other values, and some memory - areas are not part of the result. If you are interested - in the total amount of memory allocated by the emulator - see <seealso marker="#memory/0">erlang:memory/0,1</seealso>.</p> + areas are not part of the result. For information about + the total amount of memory allocated by the emulator, see + <seealso marker="#memory/0">erlang:memory/0,1</seealso>.</p> </item> - <tag><marker id="system_info_allocator"><c>allocator</c></marker></tag> + <tag><c>allocator</c></tag> <item> - <p>Returns <c>{<anno>Allocator</anno>, <anno>Version</anno>, <anno>Features</anno>, <anno>Settings</anno>}.</c></p> - <p>Explanation:</p> + <marker id="system_info_allocator"></marker> + <p>Returns <c>{<anno>Allocator</anno>, <anno>Version</anno>, + <anno>Features</anno>, <anno>Settings</anno></c>, where:</p> <list type="bulleted"> <item> - <p><c><anno>Allocator</anno></c> corresponds to the <c>malloc()</c> - implementation used. If <c><anno>Allocator</anno></c> equals + <p><c><anno>Allocator</anno></c> corresponds to the + <c>malloc()</c> implementation used. If + <c><anno>Allocator</anno></c> equals <c>undefined</c>, the <c>malloc()</c> implementation - used could not be identified. Currently - <c>glibc</c> can be identified.</p> + used cannot be identified. <c>glibc</c> can be + identified.</p> </item> <item> - <p><c><anno>Version</anno></c> is a list of integers (but not a - string) representing the version of + <p><c><anno>Version</anno></c> is a list of integers + (but not a string) representing the version of the <c>malloc()</c> implementation used.</p> </item> <item> - <p><c><anno>Features</anno></c> is a list of atoms representing - allocation features used.</p> + <p><c><anno>Features</anno></c> is a list of atoms + representing the allocation features used.</p> </item> <item> - <p><c><anno>Settings</anno></c> is a list of subsystems, their - configurable parameters, and used values. Settings - may differ between different combinations of + <p><c><anno>Settings</anno></c> is a list of subsystems, + their configurable parameters, and used values. Settings + can differ between different combinations of platforms, allocators, and allocation features. Memory sizes are given in bytes.</p> </item> @@ -5300,161 +6968,246 @@ ok <p>See also "System Flags Effecting erts_alloc" in <seealso marker="erts:erts_alloc#flags">erts_alloc(3)</seealso>.</p> </item> - <tag><marker id="system_info_alloc_util_allocators"><c>alloc_util_allocators</c></marker></tag> + <tag><c>alloc_util_allocators</c></tag> <item> - <p>Returns a list of the names of all allocators - using the ERTS internal <c>alloc_util</c> framework - as atoms. For more information see the - <seealso marker="erts:erts_alloc#alloc_util">"the - alloc_util framework" section in the - erts_alloc(3)</seealso> documentation. - </p> + <marker id="system_info_alloc_util_allocators"></marker> + <p>Returns a list of the names of all allocators using + the <c>ERTS</c> internal <c>alloc_util</c> framework + as atoms. For more information, see Section + <seealso marker="erts:erts_alloc#alloc_util">"The + alloc_util framework" in erts_alloc(3)</seealso>.</p> </item> - <tag><marker id="system_info_allocator_tuple"><c>{allocator, <anno>Alloc</anno>}</c></marker></tag> + <tag><c>{allocator, <anno>Alloc</anno>}</c></tag> <item> + <marker id="system_info_allocator_tuple"></marker> <p>Returns information about the specified allocator. - As of erts version 5.6.1 the return value is a list - of <c>{instance, InstanceNo, InstanceInfo}</c> tuples + As from <c>ERTS</c> 5.6.1, the return value is a list + of <c>{instance, InstanceNo, InstanceInfo}</c> tuples, where <c>InstanceInfo</c> contains information about - a specific instance of the allocator. - If <c><anno>Alloc</anno></c> is not a recognized allocator, - <c>undefined</c> is returned. If <c><anno>Alloc</anno></c> is disabled, + a specific instance of the allocator. If <c><anno>Alloc</anno></c> is not a + recognized allocator, <c>undefined</c> is returned. + If <c><anno>Alloc</anno></c> is disabled, <c>false</c> is returned.</p> - <p><em>Note:</em> The information returned is highly - implementation dependent and may be changed, or removed + <p>Notice that the information returned is highly + implementation-dependent and can be changed or removed at any time without prior notice. It was initially intended as a tool when developing new allocators, but - since it might be of interest for others it has been + as it can be of interest for others it has been briefly documented.</p> <p>The recognized allocators are listed in <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>. - After reading the <c>erts_alloc(3)</c> documentation, + Information about super carriers can be obtained from + <c>ERTS</c> 8.0 with <c>{allocator, erts_mmap}</c> or from + <c>ERTS</c> 5.10.4, the returned list when calling with + <c>{allocator, mseg_alloc}</c> also includes an + <c>{erts_mmap, _}</c> tuple as one element in the list.</p> + + <p>After reading the <c>erts_alloc(3)</c> documentation, the returned information - should more or less speak for itself. But it can be worth + more or less speaks for itself, but it can be worth explaining some things. Call counts are presented by two - values. The first value is giga calls, and the second - value is calls. <c>mbcs</c>, and <c>sbcs</c> are - abbreviations for, respectively, multi-block carriers, and - single-block carriers. Sizes are presented in bytes. When - it is not a size that is presented, it is the amount of - something. Sizes and amounts are often presented by three - values, the first is current value, the second is maximum - value since the last call to - <c>erlang:system_info({allocator, Alloc})</c>, and - the third is maximum value since the emulator was started. - If only one value is present, it is the current value. + values, the first value is giga calls, and the second + value is calls. <c>mbcs</c> and <c>sbcs</c> denote + multi-block carriers, and single-block carriers, + respectively. Sizes are presented in bytes. When a + size is not presented, it is the amount of something. + Sizes and amounts are often presented by three values:</p> + <list type="bulleted"> + <item>The first is the current value.</item> + <item>The second is the maximum value since the last call + to <c>erlang:system_info({allocator, Alloc})</c>.</item> + <item>The third is the maximum value since the emulator + was started.</item> + </list> + <p>If only one value is present, it is the current value. <c>fix_alloc</c> memory block types are presented by two - values. The first value is memory pool size and - the second value used memory size.</p> + values. The first value is the memory pool size and + the second value is the used memory size.</p> </item> - <tag><marker id="system_info_allocator_sizes"><c>{allocator_sizes, <anno>Alloc</anno>}</c></marker></tag> + <tag><c>{allocator_sizes, <anno>Alloc</anno>}</c></tag> <item> + <marker id="system_info_allocator_sizes"></marker> <p>Returns various size information for the specified allocator. The information returned is a subset of the information returned by - <seealso marker="#system_info_allocator_tuple">erlang:system_info({allocator, <anno>Alloc</anno>})</seealso>. + <seealso marker="#system_info_allocator_tuple"><c>erlang:system_info({allocator, <anno>Alloc</anno>})</c></seealso>. </p> </item> </taglist> </desc> </func> + <func> <name name="system_info" arity="1" clause_i="10"/> <name name="system_info" arity="1" clause_i="11"/> + <fsummary>Information about the CPU topology of the system.</fsummary> <type name="cpu_topology"/> <type name="level_entry"/> <type_desc name="cpu_topology"> - <marker id="system_info_cpu_topology"></marker> All <c><anno>LevelEntry</anno></c>s of a list must contain the same <c><anno>LevelTag</anno></c>, except on the top level where both <c>node</c> and - <c>processor</c> <c><anno>LevelTag</anno></c>s may co-exist. + <c>processor</c> <c><anno>LevelTag</anno></c>s can coexist. </type_desc> <type_desc name="level_entry"> - <c>{<anno>LevelTag</anno>, <anno>SubLevel</anno>} == {<anno>LevelTag</anno>, [], <anno>SubLevel</anno>}</c> + <c>{<anno>LevelTag</anno>, + <anno>SubLevel</anno>} == {<anno>LevelTag</anno>, [], + <anno>SubLevel</anno>}</c> </type_desc> <type name="level_tag"/> <type_desc name="level_tag"> - More <c><anno>LevelTag</anno></c>s may be introduced in the future. + More <c><anno>LevelTag</anno></c>s can be introduced in a + future release. </type_desc> <type name="sub_level"/> <type name="info_list"/> <type_desc name="info_list"> - The <c>info_list()</c> may be extended in the future. + The <c>info_list()</c> can be extended in a future release. </type_desc> - <fsummary>Information about the CPU topology of the system</fsummary> <desc> - <p>Returns various information about the - <marker id="system_info_cpu_topology_tags">CPU topology</marker> - of the current system - (emulator) as specified by <c><anno>Item</anno></c>:</p> + <marker id="system_info_cpu_topology_tags"></marker> + <marker id="system_info_cpu_topology"></marker> + <p>Returns various information about the CPU topology of + the current system (emulator) as specified by + <c><anno>Item</anno></c>:</p> <taglist> <tag><c>cpu_topology</c></tag> <item> - <p>Returns the <c><anno>CpuTopology</anno></c> which currently is used by the - emulator. The CPU topology is used when binding schedulers + <p>Returns the <c><anno>CpuTopology</anno></c> currently used by + the emulator. The CPU topology is used when binding schedulers to logical processors. The CPU topology used is the - <seealso marker="erlang#system_info_cpu_topology_defined">user - defined CPU topology</seealso> if such exists; otherwise, the - <seealso marker="erlang#system_info_cpu_topology_detected">automatically - detected CPU topology</seealso> if such exists. If no CPU topology + <seealso marker="erlang#system_info_cpu_topology_defined">user-defined CPU topology</seealso>, + if such exists, otherwise the + <seealso marker="erlang#system_info_cpu_topology_detected">automatically detected CPU topology</seealso>, + if such exists. If no CPU topology exists, <c>undefined</c> is returned.</p> - <p><c>node</c> refers to NUMA (non-uniform memory access) - nodes, and <c>thread</c> refers to hardware threads - (e.g. Intels hyper-threads).</p> - <p>A level in the <c><anno>CpuTopology</anno></c> term can be omitted if - only one entry exists and the <c><anno>InfoList</anno></c> is empty. - </p> + <p><c>node</c> refers to Non-Uniform Memory Access (NUMA) + nodes. <c>thread</c> refers to hardware threads + (for example, Intel hyper-threads).</p> + <p>A level in term <c><anno>CpuTopology</anno></c> can be + omitted if only one entry exists and + <c><anno>InfoList</anno></c> is empty.</p> <p><c>thread</c> can only be a sub level to <c>core</c>. - <c>core</c> can be a sub level to either <c>processor</c> - or <c>node</c>. <c>processor</c> can either be on the + <c>core</c> can be a sub level to <c>processor</c> + or <c>node</c>. <c>processor</c> can be on the top level or a sub level to <c>node</c>. <c>node</c> - can either be on the top level or a sub level to + can be on the top level or a sub level to <c>processor</c>. That is, NUMA nodes can be processor internal or processor external. A CPU topology can consist of a mix of processor internal and external - NUMA nodes, as long as each logical CPU belongs to one - and only one NUMA node. Cache hierarchy is not part of - the <c><anno>CpuTopology</anno></c> type yet, but will be in the - future. Other things may also make it into the CPU - topology in the future. In other words, expect the - <c><anno>CpuTopology</anno></c> type to change. - </p> + NUMA nodes, as long as each logical CPU belongs to + <em>one</em> NUMA node. Cache hierarchy is not part of + the <c><anno>CpuTopology</anno></c> type, but will be in a + future release. Other things can also make it into the CPU + topology in a future release. In other words, expect the + <c><anno>CpuTopology</anno></c> type to change.</p> + </item> + <tag><c>{cpu_topology, defined}</c></tag> + <item> + <marker id="system_info_cpu_topology_defined"></marker> + <p>Returns the user-defined <c><anno>CpuTopology</anno></c>. + For more information, see command-line flag + <seealso marker="erts:erl#+sct">+sct</seealso> in + <c>erl(1)</c> and argument + <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>.</p> + </item> + <tag><c>{cpu_topology, detected}</c></tag> + <item> + <marker id="system_info_cpu_topology_detected"></marker> + <p>Returns the automatically detected + <c><anno>CpuTopology</anno>y</c>. The + emulator detects the CPU topology on some newer + Linux, Solaris, FreeBSD, and Windows systems. + On Windows system with more than 32 logical processors, + the CPU topology is not detected.</p> + <p>For more information, see argument + <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>.</p> </item> - <tag><marker id="system_info_cpu_topology_defined"><c>{cpu_topology, defined}</c></marker></tag> + <tag><c>{cpu_topology, used}</c></tag> <item> - <p>Returns the user defined <c><anno>CpuTopology</anno></c>. For more - information see the documentation of - the <c>erl</c> <seealso marker="erts:erl#+sct">+sct</seealso> command - line flag, and the documentation of the - <seealso marker="#system_info_cpu_topology">cpu_topology</seealso> - argument. - </p> + <p>Returns <c><anno>CpuTopology</anno></c> used by the emulator. + For more information, see argument + <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>.</p> </item> - <tag><marker id="system_info_cpu_topology_detected"><c>{cpu_topology, detected}</c></marker></tag> + </taglist> + </desc> + </func> + + <func> + <name name="system_info" arity="1" clause_i="27"/> + <name name="system_info" arity="1" clause_i="28"/> + <name name="system_info" arity="1" clause_i="36"/> + <name name="system_info" arity="1" clause_i="37"/> + <name name="system_info" arity="1" clause_i="38"/> + <name name="system_info" arity="1" clause_i="39"/> + <fsummary>Information about the default process heap settings.</fsummary> + <type name="message_queue_data"/> + <type name="max_heap_size"/> + <desc> + <taglist> + <tag><c>fullsweep_after</c></tag> <item> - <p>Returns the automatically detected <c><anno>CpuTopology</anno></c>. The - emulator currently only detects the CPU topology on some newer - Linux, Solaris, FreeBSD, and Windows systems. On Windows system with - more than 32 logical processors the CPU topology is not detected. - </p> - <p>For more information see the documentation of the - <seealso marker="#system_info_cpu_topology">cpu_topology</seealso> - argument. - </p> + <p>Returns <c>{fullsweep_after, integer() >= 0}</c>, which is + the <c>fullsweep_after</c> garbage collection setting used + by default. For more information, see + <c>garbage_collection</c> described in the following.</p> </item> - <tag><c>{cpu_topology, used}</c></tag> + <tag><c>garbage_collection</c></tag> <item> - <p>Returns the <c><anno>CpuTopology</anno></c> which is used by the - emulator. For more information see the - documentation of the - <seealso marker="#system_info_cpu_topology">cpu_topology</seealso> - argument. - </p> + <p>Returns a list describing the default garbage collection + settings. A process spawned on the local node by a + <c>spawn</c> or <c>spawn_link</c> uses these + garbage collection settings. The default settings can be + changed by using + <seealso marker="#system_flag/2">system_flag/2</seealso>. + <seealso marker="#spawn_opt/4">spawn_opt/4</seealso> + can spawn a process that does not use the default + settings.</p> + </item> + <tag><c>max_heap_size</c></tag> + <item> + <p>Returns <c>{max_heap_size, <anno>MaxHeapSize</anno>}</c>, + where <c><anno>MaxHeapSize</anno></c> is the current + system-wide max heap size settings for spawned processes. + This setting can be set using the <c>erl</c> command line + flags <seealso marker="erl#+hmax"><c>+hmax</c></seealso>, + <seealso marker="erl#+hmaxk"><c>+hmaxk</c></seealso> and + <seealso marker="erl#+hmaxel"><c>+hmaxel</c></seealso>. It can + also be changed at run-time using + <seealso marker="#system_flag_max_heap_size"> + <c>erlang:system_flag(max_heap_size, MaxHeapSize)</c></seealso>. + For more details about the <c>max_heap_size</c> process flag + see <seealso marker="#process_flag_max_heap_size"> + <c>process_flag(max_heap_size, MaxHeapSize)</c></seealso>. + </p> + </item> + <tag><c>min_heap_size</c></tag> + <item> + <p>Returns <c>{min_heap_size, <anno>MinHeapSize</anno>}</c>, + where <c><anno>MinHeapSize</anno></c> is the current + system-wide minimum heap size for spawned processes.</p> + </item> + <tag><marker id="system_info_message_queue_data"/><c>message_queue_data</c></tag> + <item> + <p>Returns the default value of the <c>message_queue_data</c> + process flag which is either <c>off_heap</c>, or <c>on_heap</c>. + This default is set by the <c>erl</c> command line argument + <seealso marker="erl#+hmqd"><c>+hmqd</c></seealso>. For more information on the + <c>message_queue_data</c> process flag, see documentation of + <seealso marker="#process_flag_message_queue_data"><c>process_flag(message_queue_data, + MQD)</c></seealso>.</p> + </item> + <tag><c>min_bin_vheap_size</c></tag> + <item> + <p>Returns <c>{min_bin_vheap_size, + <anno>MinBinVHeapSize</anno>}</c>, where + <c><anno>MinBinVHeapSize</anno></c> is the current system-wide + minimum binary virtual heap size for spawned processes.</p> </item> </taglist> </desc> </func> + <func> <name name="system_info" arity="1" clause_i="6"/> <name name="system_info" arity="1" clause_i="7"/> @@ -5475,8 +7228,6 @@ ok <name name="system_info" arity="1" clause_i="24"/> <name name="system_info" arity="1" clause_i="25"/> <name name="system_info" arity="1" clause_i="26"/> - <name name="system_info" arity="1" clause_i="27"/> - <name name="system_info" arity="1" clause_i="28"/> <name name="system_info" arity="1" clause_i="29"/> <name name="system_info" arity="1" clause_i="30"/> <name name="system_info" arity="1" clause_i="31"/> @@ -5484,10 +7235,6 @@ ok <name name="system_info" arity="1" clause_i="33"/> <name name="system_info" arity="1" clause_i="34"/> <name name="system_info" arity="1" clause_i="35"/> - <name name="system_info" arity="1" clause_i="36"/> - <name name="system_info" arity="1" clause_i="37"/> - <name name="system_info" arity="1" clause_i="38"/> - <name name="system_info" arity="1" clause_i="39"/> <name name="system_info" arity="1" clause_i="40"/> <name name="system_info" arity="1" clause_i="41"/> <name name="system_info" arity="1" clause_i="42"/> @@ -5500,7 +7247,25 @@ ok <name name="system_info" arity="1" clause_i="49"/> <name name="system_info" arity="1" clause_i="50"/> <name name="system_info" arity="1" clause_i="51"/> - <fsummary>Information about the system</fsummary> + <name name="system_info" arity="1" clause_i="52"/> + <name name="system_info" arity="1" clause_i="53"/> + <name name="system_info" arity="1" clause_i="54"/> + <name name="system_info" arity="1" clause_i="55"/> + <name name="system_info" arity="1" clause_i="56"/> + <name name="system_info" arity="1" clause_i="57"/> + <name name="system_info" arity="1" clause_i="58"/> + <name name="system_info" arity="1" clause_i="59"/> + <name name="system_info" arity="1" clause_i="60"/> + <name name="system_info" arity="1" clause_i="61"/> + <name name="system_info" arity="1" clause_i="62"/> + <name name="system_info" arity="1" clause_i="63"/> + <name name="system_info" arity="1" clause_i="64"/> + <name name="system_info" arity="1" clause_i="65"/> + <name name="system_info" arity="1" clause_i="66"/> + <name name="system_info" arity="1" clause_i="67"/> + <name name="system_info" arity="1" clause_i="68"/> + <name name="system_info" arity="1" clause_i="69"/> + <fsummary>Information about the system.</fsummary> <desc> <p>Returns various information about the current system (emulator) as specified by <c><anno>Item</anno></c>:</p> @@ -5517,8 +7282,7 @@ ok Other possible return values are <c>debug</c>, <c>purify</c>, <c>quantify</c>, <c>purecov</c>, <c>gcov</c>, <c>valgrind</c>, <c>gprof</c>, and <c>lcnt</c>. Possible return values - may be added and/or removed at any time without prior notice. - </p> + can be added or removed at any time without prior notice.</p> </item> <tag><c>c_compiler_used</c></tag> <item> @@ -5526,26 +7290,25 @@ ok compiling the runtime system. The first element is an atom describing the name of the compiler, or <c>undefined</c> if unknown. The second element is a term describing the - version of the compiler, or <c>undefined</c> if unknown. - </p> + version of the compiler, or <c>undefined</c> if unknown.</p> </item> <tag><c>check_io</c></tag> <item> <p>Returns a list containing miscellaneous information - regarding the emulators internal I/O checking. Note, - the content of the returned list may vary between - platforms and over time. The only thing guaranteed is + about the emulators internal I/O checking. Notice that + the content of the returned list can vary between + platforms and over time. It is only guaranteed that a list is returned.</p> </item> <tag><c>compat_rel</c></tag> <item> <p>Returns the compatibility mode of the local node as an integer. The integer returned represents the - Erlang/OTP release which the current emulator has been + Erlang/OTP release that the current emulator has been set to be backward compatible with. The compatibility - mode can be configured at startup by using the command - line flag <c>+R</c>, see - <seealso marker="erts:erl#compat_rel">erl(1)</seealso>.</p> + mode can be configured at startup by using command-line flag + <seealso marker="erts:erl#compat_rel">+R</seealso> in + <c>erl(1)</c>.</p> </item> <tag><c>cpu_topology</c></tag> <item> @@ -5558,95 +7321,185 @@ ok creation of a node is stored in process identifiers, port identifiers, and references. This makes it (to some extent) possible to distinguish between identifiers from - different incarnations of a node. Currently valid - creations are integers in the range 1..3, but this may - (probably will) change in the future. If the node is not - alive, 0 is returned.</p> + different incarnations of a node. The valid + creations are integers in the range 1..3, but this will + probably change in a future release. If the node is not + alive, <c>0</c> is returned.</p> </item> <tag><c>debug_compiled</c></tag> <item> <p>Returns <c>true</c> if the emulator has been debug - compiled; otherwise, <c>false</c>. - </p> + compiled, otherwise <c>false</c>.</p> + </item> + <tag><c>delayed_node_table_gc</c></tag> + <item> + <marker id="system_info_delayed_node_table_gc"></marker> + <p>Returns the amount of time in seconds garbage collection + of an entry in a node table is delayed. This limit can be set + on startup by passing the command line flag + <seealso marker="erts:erl#+zdntgc">+zdntgc</seealso> + to <c>erl</c>. For more information see the documentation of the + command line flag.</p> + </item> + <tag><c>dirty_cpu_schedulers</c></tag> + <item> + <marker id="system_info_dirty_cpu_schedulers"></marker> + <p>Returns the number of dirty CPU scheduler threads used by + the emulator. Dirty CPU schedulers execute CPU-bound + native functions, such as NIFs, linked-in driver code, + and BIFs that cannot be managed cleanly by the normal + emulator schedulers.</p> + <p>The number of dirty CPU scheduler threads is determined + at emulator boot time and cannot be changed after that. + However, the number of dirty CPU scheduler threads online + can be changed at any time. The number of dirty CPU + schedulers can be set at startup by passing + command-line flag + <seealso marker="erts:erl#+SDcpu">+SDcpu</seealso> or + <seealso marker="erts:erl#+SDPcpu">+SDPcpu</seealso> in + <c>erl(1)</c>.</p> + <p>Notice that the dirty schedulers functionality is + experimental. Enable support for dirty schedulers when + building OTP to try out the functionality.</p> + <p>See also + <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>, + <seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>, + <seealso marker="#system_info_dirty_io_schedulers">erlang:system_info(dirty_io_schedulers)</seealso>, + <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>, + <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>, and + <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>.</p> + </item> + <tag><c>dirty_cpu_schedulers_online</c></tag> + <item> + <marker id="system_info_dirty_cpu_schedulers_online"></marker> + <p>Returns the number of dirty CPU schedulers online. + The return value satisfies + <c><![CDATA[1 <= DirtyCPUSchedulersOnline <= N]]></c>, + where <c>N</c> is the smallest of the return values of + <c>erlang:system_info(dirty_cpu_schedulers)</c> and + <c>erlang:system_info(schedulers_online)</c>.</p> + <p>The number of dirty CPU schedulers online can be set at + startup by passing command-line flag + <seealso marker="erts:erl#+SDcpu">+SDcpu</seealso> in + <c>erl(1)</c>.</p> + <p>Notice that the dirty schedulers functionality is + experimental. Enable support for dirty schedulers when + building OTP to try out the functionality.</p> + <p>For more information, see + <seealso marker="#system_info_dirty_cpu_schedulers">erlang:system_info(dirty_cpu_schedulers)</seealso>, + <seealso marker="#system_info_dirty_io_schedulers">erlang:system_info(dirty_io_schedulers)</seealso>, + <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>, and + <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>.</p> + </item> + <tag><c>dirty_io_schedulers</c></tag> + <item> + <marker id="system_info_dirty_io_schedulers"></marker> + <p>Returns the number of dirty I/O schedulers as an integer. + Dirty I/O schedulers execute I/O-bound native functions, + such as NIFs and linked-in driver code, which cannot be + managed cleanly by the normal emulator schedulers.</p> + <p>This value can be set at startup by passing command-line + argument <seealso marker="erts:erl#+SDio">+SDio</seealso> + in <c>erl(1)</c>.</p> + <p>Notice that the dirty schedulers functionality is + experimental. Enable support for dirty schedulers when + building OTP to try out the functionality.</p> + <p>For more information, see + <seealso marker="#system_info_dirty_cpu_schedulers">erlang:system_info(dirty_cpu_schedulers)</seealso>, + <seealso marker="#system_info_dirty_cpu_schedulers_online">erlang:system_info(dirty_cpu_schedulers_online)</seealso>, and + <seealso marker="#system_flag_dirty_cpu_schedulers_online">erlang:system_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOnline)</seealso>.</p> </item> <tag><c>dist</c></tag> <item> <p>Returns a binary containing a string of distribution information formatted as in Erlang crash dumps. For more - information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> - chapter in the ERTS User's Guide.</p> + information, see Section + <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> + in the User's Guide.</p> + </item> + <tag><c>dist_buf_busy_limit</c></tag> + <item> + <marker id="system_info_dist_buf_busy_limit"></marker> + <p>Returns the value of the distribution buffer busy limit + in bytes. This limit can be set at startup by passing + command-line flag + <seealso marker="erts:erl#+zdbbl">+zdbbl</seealso> + to <c>erl</c>.</p> </item> <tag><c>dist_ctrl</c></tag> <item> <p>Returns a list of tuples - <c>{Node, ControllingEntity}</c>, one entry for each - connected remote node. The <c><anno>Node</anno></c> is the name of the - node and the <c><anno>ControllingEntity</anno></c> is the port or pid - responsible for the communication to that node. More - specifically, the <c><anno>ControllingEntity</anno></c> for nodes - connected via TCP/IP (the normal case) is the socket - actually used in communication with the specific node.</p> + <c>{<anno>Node</anno>, <anno>ControllingEntity</anno>}</c>, + one entry for each connected remote node. + <c><anno>Node</anno></c> is the node name + and <c><anno>ControllingEntity</anno></c> is the port or process + identifier responsible for the communication to that node. + More specifically, <c><anno>ControllingEntity</anno></c> for + nodes connected through TCP/IP (the normal case) is the socket + used in communication with the specific node.</p> </item> <tag><c>driver_version</c></tag> <item> - <p>Returns a string containing the erlang driver version - used by the runtime system. It will be on the form + <p>Returns a string containing the Erlang driver version + used by the runtime system. It has the form <seealso marker="erts:erl_driver#version_management">"<major ver>.<minor ver>"</seealso>.</p> </item> <tag><c>dynamic_trace</c></tag> <item> <p>Returns an atom describing the dynamic trace framework - compiled into the virtual machine. It can currently be either - <c>dtrace</c>, <c>systemtap</c> or <c>none</c>. For a - commercial or standard build, this is always <c>none</c>, - the other return values indicate a custom configuration - (e.g. <c>./configure --with-dynamic-trace=dtrace</c>). See - the <seealso marker="runtime_tools:dyntrace">dyntrace - </seealso> manual page and the + compiled into the virtual machine. It can be + <c>dtrace</c>, <c>systemtap</c>, or <c>none</c>. For a + commercial or standard build, it is always <c>none</c>. + The other return values indicate a custom configuration + (for example, <c>./configure --with-dynamic-trace=dtrace</c>). + For more information about dynamic tracing, see the + <seealso marker="runtime_tools:dyntrace">dyntrace</seealso> + manual page and the <c>README.dtrace</c>/<c>README.systemtap</c> files in the - Erlang source code top directory for more information - about dynamic tracing.</p> + Erlang source code top directory.</p> </item> <tag><c>dynamic_trace_probes</c></tag> <item> - <p>Returns a <c>boolean()</c> indicating if dynamic trace probes - (either dtrace or systemtap) are built into the - emulator. This can only be <c>true</c> if the virtual - machine was built for dynamic tracing - (i.e. <c>system_info(dynamic_trace)</c> returns + <p>Returns a <c>boolean()</c> indicating if dynamic trace + probes (<c>dtrace</c> or <c>systemtap</c>) are built into + the emulator. This can only be <c>true</c> if the Virtual + Machine was built for dynamic tracing (that is, + <c>system_info(dynamic_trace)</c> returns <c>dtrace</c> or <c>systemtap</c>).</p> </item> + <tag><marker id="system_info_end_time"/><c>end_time</c></tag> + <item><p>The last <seealso marker="#monotonic_time/0">Erlang monotonic + time</seealso> in <c>native</c> + <seealso marker="#type_time_unit">time unit</seealso> that + can be represented internally in the current Erlang runtime system + instance. The time between the + <seealso marker="#system_info_start_time">start time</seealso> and + the end time is at least a quarter of a millennium.</p></item> <tag><c>elib_malloc</c></tag> <item> <p>This option will be removed in a future release. - The return value will always be <c>false</c> since - the elib_malloc allocator has been removed.</p> + The return value will always be <c>false</c>, as the + <c>elib_malloc</c> allocator has been removed.</p> </item> - <tag><marker id="system_info_dist_buf_busy_limit"><c>dist_buf_busy_limit</c></marker></tag> + <tag><marker id="system_info_eager_check_io"/><c>eager_check_io</c></tag> <item> - <p>Returns the value of the distribution buffer busy limit - in bytes. This limit can be set on startup by passing the - <seealso marker="erts:erl#+zdbbl">+zdbbl</seealso> command line - flag to <c>erl</c>.</p> + <p> + Returns the value of the <c>erl</c> command line flag + <seealso marker="erl#+secio">+secio</seealso> + which is either <c>true</c> or <c>false</c>. See the + documentation of the command line flag for information about + the different values. + </p> </item> - <tag><c>fullsweep_after</c></tag> + <tag><c>ets_limit</c></tag> <item> - <p>Returns <c>{fullsweep_after, integer() >= 0}</c> which is the - <c>fullsweep_after</c> garbage collection setting used - by default. For more information see - <c>garbage_collection</c> described below.</p> - </item> - <tag><c>garbage_collection</c></tag> - <item> - <p>Returns a list describing the default garbage collection - settings. A process spawned on the local node by a - <c>spawn</c> or <c>spawn_link</c> will use these - garbage collection settings. The default settings can be - changed by use of - <seealso marker="#system_flag/2">system_flag/2</seealso>. - <seealso marker="#spawn_opt/4">spawn_opt/4</seealso> - can spawn a process that does not use the default - settings.</p> + <p>Returns the maximum number of ETS tables allowed. This + limit can be increased at startup by passing + command-line flag + <seealso marker="erts:erl#+e">+e</seealso> to + <c>erl(1)</c> or by setting environment variable + <c>ERL_MAX_ETS_TABLES</c> before starting the Erlang + runtime system.</p> </item> <tag><c>heap_sizes</c></tag> <item> @@ -5656,8 +7509,8 @@ ok </item> <tag><c>heap_type</c></tag> <item> - <p>Returns the heap type used by the current emulator. - Currently only the following heap type exists:</p> + <p>Returns the heap type used by the current emulator. One + heap type exists:</p> <taglist> <tag><c>private</c></tag> <item> @@ -5672,79 +7525,70 @@ ok <item> <p>Returns a binary containing a string of miscellaneous system information formatted as in Erlang crash dumps. - For more information see the - <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter in the ERTS - User's Guide.</p> + For more information, see Section + <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> + in the User's Guide.</p> </item> <tag><c>kernel_poll</c></tag> <item> <p>Returns <c>true</c> if the emulator uses some kind of - kernel-poll implementation; otherwise, <c>false</c>.</p> + kernel-poll implementation, otherwise <c>false</c>.</p> </item> <tag><c>loaded</c></tag> <item> <p>Returns a binary containing a string of loaded module information formatted as in Erlang crash dumps. For more - information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter - in the ERTS User's Guide.</p> + information, see Section + <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> + in the User's Guide.</p> </item> - <tag><marker id="logical_processors"><c>logical_processors</c></marker></tag> + <tag><c>logical_processors</c></tag> <item> + <marker id="logical_processors"></marker> <p>Returns the detected number of logical processors configured - on the system. The return value is either an integer, or - the atom <c>unknown</c> if the emulator wasn't able to - detect logical processors configured. - </p> + in the system. The return value is either an integer, or + the atom <c>unknown</c> if the emulator cannot + detect the configured logical processors.</p> </item> - <tag><marker id="logical_processors_available"><c>logical_processors_available</c></marker></tag> + <tag><c>logical_processors_available</c></tag> <item> - <p>Returns the detected number of logical processors available to - the Erlang runtime system. The return value is either an - integer, or the atom <c>unknown</c> if the emulator wasn't - able to detect logical processors available. The number - of logical processors available is less than or equal to - the number of <seealso marker="#logical_processors_online">logical - processors online</seealso>. - </p> + <marker id="logical_processors_available"></marker> + <p>Returns the detected number of logical processors available + to the Erlang runtime system. The return value is either an + integer, or the atom <c>unknown</c> if the emulator + cannot detect the available logical processors. The number + of available logical processors is less than or equal to + the number of + <seealso marker="#logical_processors_online">logical processors online</seealso>.</p> </item> - <tag><marker id="logical_processors_online"><c>logical_processors_online</c></marker></tag> + <tag><c>logical_processors_online</c></tag> <item> + <marker id="logical_processors_online"></marker> <p>Returns the detected number of logical processors online on the system. The return value is either an integer, - or the atom <c>unknown</c> if the emulator wasn't able to + or the atom <c>unknown</c> if the emulator cannot detect logical processors online. The number of logical processors online is less than or equal to the number of - <seealso marker="#logical_processors">logical processors - configured</seealso>. - </p> + <seealso marker="#logical_processors">logical processors configured</seealso>.</p> </item> <tag><c>machine</c></tag> <item> <p>Returns a string containing the Erlang machine name.</p> </item> - <tag><c>min_heap_size</c></tag> - <item> - <p>Returns <c>{min_heap_size, <anno>MinHeapSize</anno>}</c> where <c><anno>MinHeapSize</anno></c> is the current system wide - minimum heap size for spawned processes.</p> - </item> - <tag><c>min_bin_vheap_size</c></tag> - <item> - <p>Returns <c>{min_bin_vheap_size, <anno>MinBinVHeapSize</anno>}</c> where <c><anno>MinBinVHeapSize</anno></c> is the current system wide - minimum binary virtual heap size for spawned processes.</p> - </item> <tag><c>modified_timing_level</c></tag> <item> - <p>Returns the modified timing level (an integer) if - modified timing has been enabled; otherwise, - <c>undefined</c>. See the <c>+T</c> command line flag - in the documentation of the - <seealso marker="erts:erl#+T">erl(1)</seealso> - command for more information on modified timing.</p> + <p>Returns the modified timing-level (an integer) if + modified timing is enabled, otherwise, <c>undefined</c>. + For more information about modified timing, see + command-line flag + <seealso marker="erts:erl#+T">+T</seealso> + in <c>erl(1)</c></p> </item> - <tag><marker id="system_info_multi_scheduling"><c>multi_scheduling</c></marker></tag> + <tag><c>multi_scheduling</c></tag> <item> - <p>Returns <c>disabled</c>, <c>blocked</c>, or <c>enabled</c>. - A description of the return values:</p> + <marker id="system_info_multi_scheduling"></marker> + <p>Returns <c>disabled</c>, <c>blocked</c>, <c>blocked_normal</c>, + or <c>enabled</c>:</p> <taglist> <tag><c>disabled</c></tag> <item> @@ -5755,167 +7599,347 @@ ok <tag><c>blocked</c></tag> <item> <p>The emulator has more than one scheduler thread, - but all scheduler threads but one have been blocked, - i.e., only one scheduler thread will schedule - Erlang processes and execute Erlang code.</p> + but all scheduler threads except one are blocked. + That is, only one scheduler thread schedules + Erlang processes and executes Erlang code.</p> + </item> + <tag><c>blocked_normal</c></tag> + <item> + <p>The emulator has more than one scheduler thread, + but all normal scheduler threads except one are + blocked. Note that dirty schedulers are not + blocked, and may schedule Erlang processes and + execute native code.</p> </item> <tag><c>enabled</c></tag> <item> <p>The emulator has more than one scheduler thread, - and no scheduler threads have been blocked, i.e., - all available scheduler threads will schedule + and no scheduler threads are blocked. That is, + all available scheduler threads schedule Erlang processes and execute Erlang code.</p> </item> </taglist> - <p>See also <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>, - <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and + <p>See also + <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>, + <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, + <seealso marker="#system_info_normal_multi_scheduling_blockers">erlang:system_info(normal_multi_scheduling_blockers)</seealso>, + and <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> </item> - <tag><marker id="system_info_multi_scheduling_blockers"><c>multi_scheduling_blockers</c></marker></tag> + <tag><c>multi_scheduling_blockers</c></tag> <item> - <p>Returns a list of <c><anno>PID</anno></c>s when multi-scheduling - is blocked; otherwise, the empty list. The <c><anno>PID</anno></c>s - in the list is <c><anno>PID</anno></c>s of the processes currently - blocking multi-scheduling. A <c><anno>PID</anno></c> will only be - present once in the list, even if the corresponding + <marker id="system_info_multi_scheduling_blockers"></marker> + <p>Returns a list of <c><anno>Pid</anno></c>s when + multi-scheduling is blocked, otherwise the empty list is + returned. The <c><anno>Pid</anno></c>s in the list + represent all the processes currently + blocking multi-scheduling. A <c><anno>Pid</anno></c> occurs + only once in the list, even if the corresponding process has blocked multiple times.</p> - <p>See also <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>, - <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and + <p>See also + <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>, + <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, + <seealso marker="#system_info_normal_multi_scheduling_blockers">erlang:system_info(normal_multi_scheduling_blockers)</seealso>, + + and + <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> + </item> + <tag><c>nif_version</c></tag> + <item> + <p>Returns a string containing the version of the Erlang NIF interface + used by the runtime system. It is on the form + "<major ver>.<minor ver>".</p> + </item> + <tag><c>normal_multi_scheduling_blockers</c></tag> + <item> + <marker id="system_info_normal_multi_scheduling_blockers"></marker> + <p>Returns a list of <c><anno>Pid</anno></c>s when + normal multi-scheduling is blocked (i.e. all normal schedulers + but one is blocked), otherwise the empty list is returned. + The <c><anno>Pid</anno></c>s in the list represent all the + processes currently blocking normal multi-scheduling. + A <c><anno>Pid</anno></c> occurs only once in the list, even if + the corresponding process has blocked multiple times.</p> + <p>See also + <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>, + <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, + <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, + + and <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> </item> - <tag><marker id="system_info_otp_release"><c>otp_release</c></marker></tag> + <tag><marker id="system_info_otp_release"/><c>otp_release</c></tag> + <item> + <marker id="system_info_otp_release"></marker> + <p>Returns a string containing the OTP release number of the + OTP release that the currently executing <c>ERTS</c> application is + part of.</p> + <p>As from OTP 17, the OTP release number corresponds to + the major OTP version number. No + <c>erlang:system_info()</c> argument gives the exact OTP + version. This is because the exact OTP version in the general case + is difficult to determine. For more information, see the description + of versions in <seealso marker="doc/system_principles:versions"> + System principles</seealso> in System Documentation.</p> + </item> + <tag><marker id="system_info_os_monotonic_time_source"/><c>os_monotonic_time_source</c></tag> + <item> + <p>Returns a list containing information about the source of + <seealso marker="erts:time_correction#OS_Monotonic_Time">OS + monotonic time</seealso> that is used by the runtime system.</p> + <p>If <c>[]</c> is returned, no OS monotonic time is + available. The list contains two-tuples with <c>Key</c>s + as first element, and <c>Value</c>s as second element. The + order of these tuples is undefined. The following + tuples can be part of the list, but more tuples can be + introduced in the future:</p> + <taglist> + <tag><c>{function, Function}</c></tag> + <item><p><c>Function</c> is the name of the function + used. This tuple always exist if OS monotonic time is + available to the runtime system.</p></item> + + <tag><c>{clock_id, ClockId}</c></tag> + <item><p>This tuple only exist if <c>Function</c> + can be used with different clocks. <c>ClockId</c> + corresponds to the clock identifier used when calling + <c>Function</c>.</p></item> + + <tag><c>{resolution, OsMonotonicTimeResolution}</c></tag> + <item><p>Highest possible + <seealso marker="time_correction#Time_Resolution">resolution</seealso> + of current OS monotonic time source as parts per + second. If no resolution information can be retrieved + from the OS, <c>OsMonotonicTimeResolution</c> is + set to the resolution of the time unit of + <c>Function</c>s return value. That is, the actual + resolution can be lower than + <c>OsMonotonicTimeResolution</c>. Also note that + the resolution does not say anything about the + <seealso marker="time_correction#Time_Accuracy">accuracy</seealso>, + and whether the + <seealso marker="time_correction#Time_Precision">precision</seealso> + do align with the resolution. You do, + however, know that the precision is not better than + <c>OsMonotonicTimeResolution</c>.</p></item> + + <tag><c>{extended, Extended}</c></tag> + <item><p><c>Extended</c> equals <c>yes</c> if + the range of time values has been extended; + otherwise, <c>Extended</c> equals <c>no</c>. The + range needs to be extended if <c>Function</c> + returns values that wrap fast. This typically + is the case when the return value is a 32-bit + value.</p></item> + + <tag><c>{parallel, Parallel}</c></tag> + <item><p><c>Parallel</c> equals <c>yes</c> if + <c>Function</c> is called in parallel from multiple + threads. If it is not called in parallel, because + calls needs to be serialized, <c>Parallel</c> equals + <c>no</c>.</p></item> + + <tag><c>{time, OsMonotonicTime}</c></tag> + <item><p><c>OsMonotonicTime</c> equals current OS + monotonic time in <c>native</c> + <seealso marker="#type_time_unit">time unit</seealso>.</p></item> + </taglist> + </item> + <tag><marker id="system_info_os_system_time_source"/><c>os_system_time_source</c></tag> <item> - <p>Returns a string containing the OTP release number.</p> + <p>Returns a list containing information about the source of + <seealso marker="erts:time_correction#OS_System_Time">OS + system time</seealso> that is used by the runtime system.</p> + <p>The list contains two-tuples with <c>Key</c>s + as first element, and <c>Value</c>s as second element. The + order if these tuples is undefined. The following + tuples can be part of the list, but more tuples can be + introduced in the future:</p> + <taglist> + <tag><c>{function, Function}</c></tag> + <item><p><c>Function</c> is the name of the funcion + used.</p></item> + + <tag><c>{clock_id, ClockId}</c></tag> + <item><p>This tuple only exist if <c>Function</c> + can be used with different clocks. <c>ClockId</c> + corresponds to the clock identifier used when calling + <c>Function</c>.</p></item> + + <tag><c>{resolution, OsSystemTimeResolution}</c></tag> + <item><p>Highest possible + <seealso marker="time_correction#Time_Resolution">resolution</seealso> + of current OS system time source as parts per + second. If no resolution information can be retrieved + from the OS, <c>OsSystemTimeResolution</c> is + set to the resolution of the time unit of + <c>Function</c>s return value. That is, the actual + resolution may be lower than + <c>OsSystemTimeResolution</c>. Also note that + the resolution does not say anything about the + <seealso marker="time_correction#Time_Accuracy">accuracy</seealso>, + and whether the + <seealso marker="time_correction#Time_Precision">precision</seealso> + do align with the resolution. You do, + however, know that the precision is not better than + <c>OsSystemTimeResolution</c>.</p></item> + + <tag><c>{parallel, Parallel}</c></tag> + <item><p><c>Parallel</c> equals <c>yes</c> if + <c>Function</c> is called in parallel from multiple + threads. If it is not called in parallel, because + calls needs to be serialized, <c>Parallel</c> equals + <c>no</c>.</p></item> + + <tag><c>{time, OsSystemTime}</c></tag> + <item><p><c>OsSystemTime</c> equals current OS + system time in <c>native</c> + <seealso marker="#type_time_unit">time unit</seealso>.</p></item> + </taglist> </item> - <tag><marker id="system_info_port_parallelism"><c>port_parallelism</c></marker></tag> - <item><p>Returns the default port parallelism scheduling hint used. - For more information see the - <seealso marker="erl#+spp">+spp</seealso> command line argument - of <seealso marker="erl">erl(1)</seealso>.</p></item> + <tag><c>port_parallelism</c></tag> + <item> + <marker id="system_info_port_parallelism"></marker> + <p>Returns the default port parallelism scheduling hint used. + For more information, see command-line argument + <seealso marker="erl#+spp">+spp</seealso> in <c>erl(1)</c>.</p></item> <tag><marker id="system_info_port_count"/><c>port_count</c></tag> <item> - <p>Returns the number of ports currently existing at - the local node as an integer. The same value as - <c>length(erlang:ports())</c> returns, but more efficient.</p> + <p>Returns the number of ports currently existing at the + local node. The value is given as an integer. This is + the same value as returned by + <c>length(erlang:ports())</c>, but more efficient.</p> </item> - <tag><marker id="system_info_port_limit"><c>port_limit</c></marker></tag> + <tag><c>port_limit</c></tag> <item> + <marker id="system_info_port_limit"></marker> <p>Returns the maximum number of simultaneously existing - ports at the local node as an integer. This limit - can be configured at startup by using the - <seealso marker="erl#+Q">+Q</seealso> - command line flag of - <seealso marker="erl">erl(1)</seealso>.</p> + ports at the local node as an integer. This limit can be + configured at startup by using command-line flag + <seealso marker="erl#+Q">+Q</seealso> in <c>erl(1)</c>.</p> </item> <tag><marker id="system_info_process_count"/><c>process_count</c></tag> <item> - <p>Returns the number of processes currently existing at - the local node as an integer. The same value as - <c>length(processes())</c> returns, but more efficient.</p> + <p>Returns the number of processes currently existing at the + local node. The value is given as an integer. This is + the same value as returned by + <c>length(processes())</c>, but more efficient.</p> </item> - <tag><marker id="system_info_process_limit"><c>process_limit</c></marker></tag> + <tag><c>process_limit</c></tag> <item> + <marker id="system_info_process_limit"></marker> <p>Returns the maximum number of simultaneously existing - processes at the local node as an integer. This limit - can be configured at startup by using the - <seealso marker="erl#+P">+P</seealso> - command line flag of - <seealso marker="erl">erl(1)</seealso>.</p> + processes at the local node. The value is given as an + integer. This limit can be configured at startup by using + command-line flag <seealso marker="erl#+P">+P</seealso> + in <c>erl(1)</c>.</p> </item> <tag><c>procs</c></tag> <item> <p>Returns a binary containing a string of process and port information formatted as in Erlang crash dumps. For more - information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter - in the ERTS User's Guide.</p> + information, see Section + <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> + in the User's Guide.</p> </item> - <tag><marker id="system_info_scheduler_bind_type"><c>scheduler_bind_type</c></marker></tag> + <tag><c>scheduler_bind_type</c></tag> <item> - <p>Returns information on how user has requested + <marker id="system_info_scheduler_bind_type"></marker> + <p>Returns information about how the user has requested schedulers to be bound or not bound.</p> - <p><em>NOTE:</em> Even though user has requested - schedulers to be bound, they might have silently failed - to bind. In order to inspect actual scheduler bindings call - <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>. - </p> - <p>For more information, see - the <c>erl</c> <seealso marker="erts:erl#+sbt">+sbt</seealso> - command line argument, and - <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>. - </p> - </item> - <tag><marker id="system_info_scheduler_bindings"><c>scheduler_bindings</c></marker></tag> - <item> - <p>Returns information on currently used scheduler + <p>Notice that even though a user has requested + schedulers to be bound, they can silently have failed + to bind. To inspect the scheduler bindings, call + <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.</p> + <p>For more information, see command-line argument + <seealso marker="erts:erl#+sbt">+sbt</seealso> + in <c>erl(1)</c> and + <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.</p> + </item> + <tag><c>scheduler_bindings</c></tag> + <item> + <marker id="system_info_scheduler_bindings"></marker> + <p>Returns information about the currently used scheduler bindings.</p> <p>A tuple of a size equal to - <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso> is returned. The elements of the tuple are integers + <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso> + is returned. The tuple elements are integers or the atom <c>unbound</c>. Logical processor identifiers are represented as integers. The <c>N</c>th element of the tuple equals the current binding for the scheduler with the scheduler identifier equal to - <c>N</c>. E.g., if the schedulers have been bound, + <c>N</c>. For example, if the schedulers are bound, <c>element(erlang:system_info(scheduler_id), - erlang:system_info(scheduler_bindings))</c> will return + erlang:system_info(scheduler_bindings))</c> returns the identifier of the logical processor that the calling - process is executing on. - </p> - <p>Note that only schedulers online can be bound to logical + process is executing on.</p> + <p>Notice that only schedulers online can be bound to logical processors.</p> - <p>For more information, see - the <c>erl</c> <seealso marker="erts:erl#+sbt">+sbt</seealso> - command line argument, + <p>For more information, see command-line argument + <seealso marker="erts:erl#+sbt">+sbt</seealso> + in <c>erl(1)</c> and <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>. </p> </item> - <tag><marker id="system_info_scheduler_id"><c>scheduler_id</c></marker></tag> + <tag><c>scheduler_id</c></tag> <item> - <p>Returns the scheduler id (<c>SchedulerId</c>) of the + <marker id="system_info_scheduler_id"></marker> + <p>Returns the scheduler ID (<c>SchedulerId</c>) of the scheduler thread that the calling process is executing - on. <c><anno>SchedulerId</anno></c> is a positive integer; where - <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]></c>. See also + on. <c><anno>SchedulerId</anno></c> is a positive integer, + where + <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]></c>. + See also <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> </item> - <tag><marker id="system_info_schedulers"><c>schedulers</c></marker></tag> + <tag><c>schedulers</c></tag> <item> + <marker id="system_info_schedulers"></marker> <p>Returns the number of scheduler threads used by the emulator. Scheduler threads online schedules Erlang processes and Erlang ports, and execute Erlang code - and Erlang linked in driver code.</p> + and Erlang linked-in driver code.</p> <p>The number of scheduler threads is determined at - emulator boot time and cannot be changed after - that. The amount of schedulers online can - however be changed at any time.</p> - <p>See also <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>, + emulator boot time and cannot be changed later. + However, the number of schedulers online can + be changed at any time.</p> + <p>See also + <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>, <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>, <seealso marker="#system_info_scheduler_id">erlang:system_info(scheduler_id)</seealso>, <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>, - <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and - and <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>.</p> + <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, + <seealso marker="#system_info_normal_multi_scheduling_blockers">erlang:system_info(normal_multi_scheduling_blockers)</seealso> + and + <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>.</p> </item> - <tag><marker id="system_info_schedulers_online"><c>schedulers_online</c></marker></tag> + <tag><c>schedulers_online</c></tag> <item> - <p>Returns the amount of schedulers online. The scheduler - identifiers of schedulers online satisfy the following - relationship: - <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers_online)]]></c>. - </p> + <marker id="system_info_schedulers_online"></marker> + <p>Returns the number of schedulers online. The scheduler + identifiers of schedulers online satisfy the relationship + <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers_online)]]></c>.</p> <p>For more information, see - <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>, + <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso> and - <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>. - </p> <name name="system_info" arity="1" clause_i="49"/> - + <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>.</p> </item> <tag><c>smp_support</c></tag> <item> <p>Returns <c>true</c> if the emulator has been compiled - with smp support; otherwise, <c>false</c>.</p> - </item> + with SMP support, otherwise <c>false</c> is returned.</p> + </item> + <tag><marker id="system_info_start_time"/><c>start_time</c></tag> + <item><p>The <seealso marker="#monotonic_time/0">Erlang monotonic + time</seealso> in <c>native</c> + <seealso marker="#type_time_unit">time unit</seealso> at the + time when current Erlang runtime system instance started. See also + <seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso>. + </p></item> <tag><c>system_version</c></tag> <item> <p>Returns a string containing version number and - some important properties such as the number of schedulers.</p> + some important properties, such as the number of schedulers.</p> </item> <tag><c>system_architecture</c></tag> <item> @@ -5925,102 +7949,168 @@ ok <tag><c>threads</c></tag> <item> <p>Returns <c>true</c> if the emulator has been compiled - with thread support; otherwise, <c>false</c> is - returned.</p> + with thread support, otherwise <c>false</c> is returned.</p> </item> - <tag><marker id="system_info_thread_pool_size"><c>thread_pool_size</c></marker></tag> + <tag><c>thread_pool_size</c></tag> <item> + <marker id="system_info_thread_pool_size"></marker> <p>Returns the number of async threads in the async thread pool used for asynchronous driver calls - (<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>) - as an integer.</p> + (<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>). + The value is given as an integer.</p> + </item> + + <tag><c>time_correction</c></tag> + <item> + <marker id="system_info_time_correction"></marker> + <p>Returns a boolean value indicating whether + <seealso marker="time_correction#Time_Correction">time correction</seealso> + is enabled or not. + </p></item> + <tag><c>time_offset</c></tag> + <item> + <marker id="system_info_time_offset"></marker> + <p>Returns the state of the time offset:</p> + <taglist> + <tag><c>preliminary</c></tag> + <item><p>The time offset is preliminary, and will be changed + at a later time when being finalized. The preliminary time offset + is used during the preliminary phase of the + <seealso marker="time_correction#Single_Time_Warp_Mode">single + time warp mode</seealso>.</p></item> + + <tag><c>final</c></tag> + <item><p>The time offset is final. This either because + <seealso marker="time_correction#No_Time_Warp_Mode">no + time warp mode</seealso> is used, or because the time + offset have been finalized when + <seealso marker="time_correction#Single_Time_Warp_Mode">single + time warp mode</seealso> is used.</p></item> + + <tag><c>volatile</c></tag> + <item><p>The time offset is volatile. That is, it can + change at any time. This is because + <seealso marker="time_correction#Multi_Time_Warp_Mode">multi + time warp mode</seealso> is used.</p></item> + </taglist> + </item> + <tag><marker id="system_info_time_warp_mode"/><c>time_warp_mode</c></tag> + <item><p>Returns a value identifying the + <seealso marker="time_correction#Time_Warp_Modes">time warp + mode</seealso> being used:</p> + <taglist> + <tag><c>no_time_warp</c></tag> + <item><p>The <seealso marker="time_correction#No_Time_Warp_Mode">no + time warp mode</seealso> is used.</p></item> + + <tag><c>single_time_warp</c></tag> + <item><p>The <seealso marker="time_correction#Single_Time_Warp_Mode">single + time warp mode</seealso> is used.</p></item> + + <tag><c>multi_time_warp</c></tag> + <item><p>The <seealso marker="time_correction#Multi_Time_Warp_Mode">multi + time warp mode</seealso> is used.</p></item> + </taglist> + </item> + <tag><c>tolerant_timeofday</c></tag> + <item> + <marker id="system_info_tolerant_timeofday"></marker> + <p>Returns whether a pre erts-7.0 backwards compatible compensation + for sudden changes of system time is <c>enabled</c> or <c>disabled</c>. + Such compensation is <c>enabled</c> when the + <seealso marker="#system_info_time_offset">time offset</seealso> is + <c>final</c>, and + <seealso marker="#system_info_time_correction">time correction</seealso> + is enabled.</p> </item> <tag><c>trace_control_word</c></tag> <item> - <p>Returns the value of the node's trace control word. - For more information see documentation of the function - <c>get_tcw</c> in "Match Specifications in Erlang", - <seealso marker="erts:match_spec#get_tcw">ERTS User's Guide</seealso>.</p> + <p>Returns the value of the node trace control word. For + more information, see function <c>get_tcw</c> in Section + <seealso marker="erts:match_spec#get_tcw">Match Specifications in Erlang</seealso> in the User's Guide.</p> </item> - <tag><marker id="update_cpu_info"><c>update_cpu_info</c></marker></tag> + <tag><c>update_cpu_info</c></tag> <item> - <p>The runtime system rereads the CPU information available and - updates its internally stored information about the - <seealso marker="#system_info_cpu_topology_detected">detected CPU - topology</seealso> and the amount of logical processors + <marker id="update_cpu_info"></marker> + <p>The runtime system rereads the CPU information available + and updates its internally stored information about the + <seealso marker="#system_info_cpu_topology_detected">detected + CPU topology</seealso> and the number of logical processors <seealso marker="#logical_processors">configured</seealso>, <seealso marker="#logical_processors_online">online</seealso>, and - <seealso marker="#logical_processors_available">available</seealso>. - If the CPU information has changed since the last time it was read, - the atom <c>changed</c> is returned; otherwise, the atom - <c>unchanged</c> is returned. If the CPU information has changed + <seealso marker="#logical_processors_available">available</seealso>.</p> + <p>If the CPU information has changed since the last time + it was read, the atom <c>changed</c> is returned, otherwise + the atom <c>unchanged</c>. If the CPU information has changed, you probably want to - <seealso marker="#system_flag_schedulers_online">adjust the amount - of schedulers online</seealso>. You typically want to have as - many schedulers online as - <seealso marker="#logical_processors_available">logical processors - available</seealso>. - </p> + <seealso marker="#system_flag_schedulers_online">adjust the + number of schedulers online</seealso>. You typically want + to have as many schedulers online as + <seealso marker="#logical_processors_available">logical + processors available</seealso>.</p> </item> - <tag><marker id="system_info_version"><c>version</c></marker></tag> + <tag><c>version</c></tag> <item> + <marker id="system_info_version"></marker> <p>Returns a string containing the version number of the emulator.</p> </item> <tag><c>wordsize</c></tag> <item> - <p>Same as <c>{wordsize, internal}.</c></p> + <p>Same as <c>{wordsize, internal}</c>.</p> </item> <tag><c>{wordsize, internal}</c></tag> <item> <p>Returns the size of Erlang term words in bytes as an - integer, i.e. on a 32-bit architecture 4 is returned, - and on a pure 64-bit architecture 8 is returned. On a + integer, that is, 4 is returned on a 32-bit architecture, + and 8 is returned on a pure 64-bit architecture. On a halfword 64-bit emulator, 4 is returned, as the Erlang - terms are stored using a virtual wordsize of half the - system's wordsize.</p> + terms are stored using a virtual word size of half the + system word size.</p> </item> <tag><c>{wordsize, external}</c></tag> <item> - <p>Returns the true wordsize of the emulator, i.e. the size - of a pointer, in bytes as an integer. On a pure 32-bit - architecture 4 is returned, on both a halfword and pure + <p>Returns the true word size of the emulator, that is, + the size of a pointer. The value is given in bytes + as an integer. On a pure 32-bit architecture, 4 is + returned. On both a half word and on a pure 64-bit architecture, 8 is returned.</p> </item> </taglist> <note> - <p>The <c>scheduler</c> argument has changed name to - <c>scheduler_id</c>. This in order to avoid mixup with - the <c>schedulers</c> argument. The <c>scheduler</c> - argument was introduced in ERTS version 5.5 and renamed - in ERTS version 5.5.1.</p> + <p>Argument <c>scheduler</c> has changed name to + <c>scheduler_id</c> to avoid mix up with argument + <c>schedulers</c>. Argument <c>scheduler</c> was + introduced in <c>ERTS</c> 5.5 and renamed in + <c>ERTS</c> 5.5.1.</p> </note> </desc> </func> <func> <name name="system_monitor" arity="0"/> + <fsummary>Current system performance monitoring settings.</fsummary> <type name="system_monitor_option"/> - <fsummary>Current system performance monitoring settings</fsummary> <desc> <p>Returns the current system monitoring settings set by <seealso marker="#system_monitor/2">erlang:system_monitor/2</seealso> - as <c>{<anno>MonitorPid</anno>, <anno>Options</anno>}</c>, or <c>undefined</c> if there - are no settings. The order of the options may be different + as <c>{<anno>MonitorPid</anno>, <anno>Options</anno>}</c>, + or <c>undefined</c> if there + are no settings. The order of the options can be different from the one that was set.</p> </desc> </func> <func> <name name="system_monitor" arity="1"/> + <fsummary>Sets or clears system performance monitoring options.</fsummary> <type name="system_monitor_option"/> - <fsummary>Set or clear system performance monitoring options</fsummary> <desc> - <p>When called with the argument <c>undefined</c>, all + <p>When called with argument <c>undefined</c>, all system performance monitoring settings are cleared.</p> - <p>Calling the function with <c>{<anno>MonitorPid</anno>, <anno>Options</anno>}</c> as - argument, is the same as calling - <seealso marker="#system_monitor/2">erlang:system_monitor(<anno>MonitorPid</anno>, <anno>Options</anno>)</seealso>.</p> + <p>Calling the function with <c>{<anno>MonitorPid</anno>, + <anno>Options</anno>}</c> as argument is the same as calling + <seealso marker="#system_monitor/2"><c>erlang:system_monitor(<anno>MonitorPid</anno>, <anno>Options</anno>)</c></seealso>.</p> <p>Returns the previous system monitor settings just like <seealso marker="#system_monitor/0">erlang:system_monitor/0</seealso>.</p> </desc> @@ -6028,102 +8118,102 @@ ok <func> <name name="system_monitor" arity="2"/> + <fsummary>Sets system performance monitoring options.</fsummary> <type name="system_monitor_option"/> - <fsummary>Set system performance monitoring options</fsummary> <desc> - <p>Sets system performance monitoring options. <c><anno>MonitorPid</anno></c> - is a local pid that will receive system monitor messages, and - the second argument is a list of monitoring options:</p> + <p>Sets the system performance monitoring options. + <c><anno>MonitorPid</anno></c> is a local process identifier (pid) + receiving system monitor messages. The + second argument is a list of monitoring options:</p> <taglist> <tag><c>{long_gc, Time}</c></tag> <item> <p>If a garbage collection in the system takes at least - <c>Time</c> wallclock milliseconds, a message + <c>Time</c> wall clock milliseconds, a message <c>{monitor, GcPid, long_gc, Info}</c> is sent to - <c><anno>MonitorPid</anno></c>. <c>GcPid</c> is the pid that was - garbage collected and <c>Info</c> is a list of two-element - tuples describing the result of the garbage collection. - One of the tuples is <c>{timeout, GcTime}</c> where - <c>GcTime</c> is the actual time for the garbage + <c><anno>MonitorPid</anno></c>. <c>GcPid</c> is the pid that + was garbage collected. <c>Info</c> is a list of two-element + tuples describing the result of the garbage collection.</p> + <p>One of the tuples is <c>{timeout, GcTime}</c>, where + <c>GcTime</c> is the time for the garbage collection in milliseconds. The other tuples are - tagged with <c>heap_size</c>, <c>heap_block_size</c>, - <c>stack_size</c>, <c>mbuf_size</c>, <c>old_heap_size</c>, - and <c>old_heap_block_size</c>. These tuples are - explained in the documentation of the - <seealso marker="#gc_start">gc_start</seealso> - trace message (see - <seealso marker="#trace/3">erlang:trace/3</seealso>). - New tuples may be added, and the order of the tuples in - the <c>Info</c> list may be changed at any time without prior - notice. - </p> + tagged with <c>heap_size</c>, <c>heap_block_size</c> + <c>stack_size</c>, <c>mbuf_size</c>, <c>old_heap_size</c>, + and <c>old_heap_block_size</c>. These tuples are + explained in the description of trace message + <seealso marker="#gc_minor_start">gc_minor_start</seealso> (see + <seealso marker="#trace/3">erlang:trace/3</seealso>). + New tuples can be added, and the order of the tuples in + the <c>Info</c> list can be changed at any time without + prior notice.</p> </item> <tag><c>{long_schedule, Time}</c></tag> <item> - <p>If a process or port in the system runs uninterrupted + <p>If a process or port in the system runs uninterrupted for at least <c>Time</c> wall clock milliseconds, a message <c>{monitor, PidOrPort, long_schedule, Info}</c> is sent to <c>MonitorPid</c>. <c>PidOrPort</c> is the - process or port that was running and <c>Info</c> is a - list of two-element tuples describing the event. In case - of a <c>pid()</c>, the tuples <c>{timeout, Millis}</c>, - <c>{in, Location}</c> and <c>{out, Location}</c> will be + process or port that was running. <c>Info</c> is a + list of two-element tuples describing the event.</p> + <p>If a <c>pid()</c>, the tuples <c>{timeout, Millis}</c>, + <c>{in, Location}</c>, and <c>{out, Location}</c> are present, where <c>Location</c> is either an MFA (<c>{Module, Function, Arity}</c>) describing the function where the process was scheduled in/out, or the - atom <c>undefined</c>. In case of a <c>port()</c>, the + atom <c>undefined</c>.</p> + <p>If a <c>port()</c>, the tuples <c>{timeout, Millis}</c> and <c>{port_op,Op}</c> - will be present. <c>Op</c> will be one of <c>proc_sig</c>, + are present. <c>Op</c> is one of <c>proc_sig</c>, <c>timeout</c>, <c>input</c>, <c>output</c>, - <c>event</c> or <c>dist_cmd</c>, depending on which - driver callback was executing. <c>proc_sig</c> is an - internal operation and should never appear, while the + <c>event</c>, or <c>dist_cmd</c>, depending on which + driver callback was executing.</p> + <p><c>proc_sig</c> is an + internal operation and is never to appear, while the others represent the corresponding driver callbacks <c>timeout</c>, <c>ready_input</c>, <c>ready_output</c>, - <c>event</c> and finally <c>outputv</c> (when the port - is used by distribution). The <c>Millis</c> value in - the <c>timeout</c> tuple will tell you the actual - uninterrupted execution time of the process or port, - which will always be <c>>=</c> the <c>Time</c> value - supplied when starting the trace. New tuples may be - added to the <c>Info</c> list in the future, and the - order of the tuples in the list may be changed at any - time without prior notice. - </p> - <p>This can be used to detect problems with NIF's or - drivers that take too long to execute. Generally, 1 ms - is considered a good maximum time for a driver callback - or a NIF. However, a time sharing system should usually - consider everything below 100 ms as "possible" and - fairly "normal". Schedule times above that might however - indicate swapping or a NIF/driver that is - misbehaving. Misbehaving NIF's and drivers could cause - bad resource utilization and bad overall performance of - the system.</p> + <c>event</c>, and <c>outputv</c> (when the port + is used by distribution). Value <c>Millis</c> in + the <c>timeout</c> tuple informs about the + uninterrupted execution time of the process or port, which + always is equal to or higher than the <c>Time</c> value + supplied when starting the trace. New tuples can be + added to the <c>Info</c> list in a future release. The + order of the tuples in the list can be changed at any + time without prior notice.</p> + <p>This can be used to detect problems with NIFs or + drivers that take too long to execute. 1 ms is + considered a good maximum time for a driver callback + or a NIF. However, a time-sharing system is usually to + consider everything below 100 ms as "possible" and + fairly "normal". However, longer schedule times can + indicate swapping or a misbehaving NIF/driver. + Misbehaving NIFs and drivers can cause bad resource + utilization and bad overall system performance.</p> </item> <tag><c>{large_heap, Size}</c></tag> <item> <p>If a garbage collection in the system results in the allocated size of a heap being at least <c>Size</c> words, a message <c>{monitor, GcPid, large_heap, Info}</c> - is sent to <c><anno>MonitorPid</anno></c>. <c>GcPid</c> and <c>Info</c> - are the same as for <c>long_gc</c> above, except that - the tuple tagged with <c>timeout</c> is not present. - <em>Note</em>: As of erts version 5.6 the monitor message - is sent if the sum of the sizes of all memory blocks allocated - for all heap generations is equal to or larger than <c>Size</c>. - Previously the monitor message was sent if the memory block - allocated for the youngest generation was equal to or larger - than <c>Size</c>. - </p> + is sent to <c><anno>MonitorPid</anno></c>. + <c>GcPid</c> and <c>Info</c> + are the same as for <c>long_gc</c> earlier, except that + the tuple tagged with <c>timeout</c> is not present.</p> + <p>The monitor message is sent if the sum of the sizes of + all memory blocks allocated for all heap generations after + a garbage collection is equal to or higher than <c>Size</c>.</p> + <p>When a process is killed by <seealso marker="#process_flag_max_heap_size"> + <c>max_heap_size</c></seealso>, it is killed before the + garbage collection is complete and thus no large heap message + will be sent.</p> </item> <tag><c>busy_port</c></tag> <item> <p>If a process in the system gets suspended because it sends to a busy port, a message <c>{monitor, SusPid, busy_port, Port}</c> is sent to - <c><anno>MonitorPid</anno></c>. <c>SusPid</c> is the pid that got - suspended when sending to <c>Port</c>.</p> + <c><anno>MonitorPid</anno></c>. <c>SusPid</c> is the pid + that got suspended when sending to <c>Port</c>.</p> </item> <tag><c>busy_dist_port</c></tag> <item> @@ -6131,8 +8221,8 @@ ok sends to a process on a remote node whose inter-node communication was handled by a busy port, a message <c>{monitor, SusPid, busy_dist_port, Port}</c> is sent to - <c><anno>MonitorPid</anno></c>. <c>SusPid</c> is the pid that got - suspended when sending through the inter-node + <c><anno>MonitorPid</anno></c>. <c>SusPid</c> is the pid + that got suspended when sending through the inter-node communication port <c>Port</c>.</p> </item> </taglist> @@ -6141,85 +8231,152 @@ ok <note> <p>If a monitoring process gets so large that it itself starts to cause system monitor messages when garbage - collecting, the messages will enlarge the process's + collecting, the messages enlarge the process message queue and probably make the problem worse.</p> <p>Keep the monitoring process neat and do not set the system monitor limits too tight.</p> </note> - <p>Failure: <c>badarg</c> if <c><anno>MonitorPid</anno></c> does not exist or is not a local process.</p> + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item>If <c><anno>MonitorPid</anno></c> does not exist.</item> + <tag><c>badarg</c></tag> + <item>If <c><anno>MonitorPid</anno></c> is not a local process.</item> + </taglist> </desc> </func> <func> <name name="system_profile" arity="0"/> + <fsummary>Current system profiling settings.</fsummary> <type name="system_profile_option"/> - <fsummary>Current system profiling settings</fsummary> <desc> <p>Returns the current system profiling settings set by <seealso marker="#system_profile/2">erlang:system_profile/2</seealso> - as <c>{<anno>ProfilerPid</anno>, <anno>Options</anno>}</c>, or <c>undefined</c> if there - are no settings. The order of the options may be different + as <c>{<anno>ProfilerPid</anno>, <anno>Options</anno>}</c>, + or <c>undefined</c> if there + are no settings. The order of the options can be different from the one that was set.</p> </desc> </func> <func> <name name="system_profile" arity="2"/> + <fsummary>Current system profiling settings.</fsummary> <type name="system_profile_option"/> - <fsummary>Current system profiling settings</fsummary> <desc> <p>Sets system profiler options. <c><anno>ProfilerPid</anno></c> - is a local pid or port that will receive profiling messages. The - receiver is excluded from all profiling. + is a local process identifier (pid) or port receiving profiling + messages. The receiver is excluded from all profiling. The second argument is a list of profiling options:</p> <taglist> <tag><c>exclusive</c></tag> <item> - <p> - If a synchronous call to a port from a process is done, the + <p>If a synchronous call to a port from a process is done, the calling process is considered not runnable during the call runtime to the port. The calling process is notified as - <c>inactive</c> and subsequently <c>active</c> when the port - callback returns. - </p> + <c>inactive</c>, and later <c>active</c> when the port + callback returns.</p> + </item> + <tag><c>monotonic_timestamp</c></tag> + <item> + <p>Timestamps in profile messages will use + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso>. The time-stamp (Ts) has the same + format and value as produced by + <c>erlang:monotonic_time(nano_seconds)</c>.</p> </item> <tag><c>runnable_procs</c></tag> <item> - <p>If a process is put into or removed from the run queue a message, - <c>{profile, Pid, State, Mfa, Ts}</c>, is sent to - <c><anno>ProfilerPid</anno></c>. Running processes that is reinserted into the - run queue after having been preemptively scheduled out will not trigger this - message. - </p> + <p>If a process is put into or removed from the run queue, a + message, <c>{profile, Pid, State, Mfa, Ts}</c>, is sent to + <c><anno>ProfilerPid</anno></c>. Running processes that + are reinserted into the run queue after having been + preempted do not trigger this message.</p> </item> <tag><c>runnable_ports</c></tag> <item> - <p>If a port is put into or removed from the run queue a message, - <c>{profile, Port, State, 0, Ts}</c>, is sent to - <c><anno>ProfilerPid</anno></c>. - </p> + <p>If a port is put into or removed from the run queue, a + message, <c>{profile, Port, State, 0, Ts}</c>, is sent to + <c><anno>ProfilerPid</anno></c>.</p> </item> <tag><c>scheduler</c></tag> <item> - <p>If a scheduler is put to sleep or awoken a message, - <c>{profile, scheduler, Id, State, NoScheds, Ts}</c>, is sent - to <c><anno>ProfilerPid</anno></c>. - </p> + <p>If a scheduler is put to sleep or awoken, a message, + <c>{profile, scheduler, Id, State, NoScheds, Ts}</c>, is + sent to <c><anno>ProfilerPid</anno></c>.</p> + </item> + <tag><c>strict_monotonic_timestamp</c></tag> + <item> + <p>Timestamps in profile messages will consisting of + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso> and a monotonically increasing + integer. The time-stamp (Ts) has the same format and value + as produced by <c>{erlang:monotonic_time(nano_seconds), + erlang:unique_integer([monotonic])}</c>.</p> + </item> + <tag><c>timestamp</c></tag> + <item> + <p>Timestamps in profile messages will include a + time-stamp (Ts) that has the same form as returned by + <c>erlang:now()</c>. This is also the default if no + timestamp flag is given. If <c>cpu_timestamp</c> has + been enabled via <c>erlang:trace/3</c>, this will also + effect the timestamp produced in profiling messages + when <c>timestamp</c> flag is enabled.</p> </item> </taglist> - <note><p><c>erlang:system_profile</c> is considered experimental and - its behaviour may change in the future.</p> + <note><p><c>erlang:system_profile</c> is considered experimental + and its behavior can change in a future release.</p> </note> </desc> </func> + <func> + <name name="system_time" arity="0"/> + <fsummary>Current Erlang system time</fsummary> + <desc> + <p>Returns current + <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso> + in <c>native</c> + <seealso marker="#type_time_unit">time unit</seealso>.</p> + + <p>Calling <c>erlang:system_time()</c> is equivalent to: + <seealso marker="#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso><c> + + + </c><seealso marker="#time_offset/0"><c>erlang:time_offset()</c></seealso>.</p> + + <note><p>This time is <em>not</em> a monotonically increasing time + in the general case. For more information, see the documentation of + <seealso marker="time_correction#Time_Warp_Modes">time warp modes</seealso> in the + ERTS User's Guide.</p></note> + </desc> + </func> + <func> + <name name="system_time" arity="1"/> + <fsummary>Current Erlang system time</fsummary> + <desc> + <p>Returns current + <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso> + converted into the <c><anno>Unit</anno></c> passed as argument.</p> + + <p>Calling <c>erlang:system_time(<anno>Unit</anno>)</c> is equivalent to: + <seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#system_time/0"><c>erlang:system_time()</c></seealso><c>, + native, <anno>Unit</anno>)</c>.</p> + <note><p>This time is <em>not</em> a monotonically increasing time + in the general case. For more information, see the documentation of + <seealso marker="time_correction#Time_Warp_Modes">time warp modes</seealso> in the + ERTS User's Guide.</p></note> + </desc> + </func> <func> <name name="term_to_binary" arity="1"/> - <fsummary>Encode a term to an Erlang external term format binary</fsummary> + <fsummary>Encodes a term to an Erlang external term format binary.</fsummary> <desc> - <p>Returns a binary data object which is the result of encoding - <c><anno>Term</anno></c> according to the Erlang external term format.</p> - <p>This can be used for a variety of purposes, for example + <p>Returns a binary data object that is the result of encoding + <c><anno>Term</anno></c> according to the Erlang external + term format.</p> + <p>This can be used for various purposes, for example, writing a term to a file in an efficient way, or sending an Erlang term to some type of communications channel not supported by distributed Erlang.</p> @@ -6227,851 +8384,1482 @@ ok <seealso marker="#binary_to_term/1">binary_to_term/1</seealso>.</p> </desc> </func> + <func> <name name="term_to_binary" arity="2"/> - <fsummary>Encode a term to en Erlang external term format binary</fsummary> - <desc> - <p>Returns a binary data object which is the result of encoding - <c><anno>Term</anno></c> according to the Erlang external term format.</p> - <p>If the option <c>compressed</c> is provided, the external - term format will be compressed. The compressed format is - automatically recognized by <c>binary_to_term/1</c> in R7B and later.</p> - <p>It is also possible to specify a compression level by giving - the option <c>{compressed, <anno>Level</anno>}</c>, where <c><anno>Level</anno></c> is an - integer from 0 through 9. <c>0</c> means that no compression - will be done (it is the same as not giving any <c>compressed</c> option); - <c>1</c> will take the least time but may not compress as well as - the higher levels; <c>9</c> will take the most time and may produce - a smaller result. Note the "mays" in the preceding sentence; depending - on the input term, level 9 compression may or may not produce a smaller - result than level 1 compression.</p> - <p>Currently, <c>compressed</c> gives the same result as - <c>{compressed, 6}</c>.</p> - <p>The option <c>{minor_version, <anno>Version</anno>}</c> can be use to control - some details of the encoding. This option was - introduced in R11B-4. Currently, the allowed values for <c><anno>Version</anno></c> - are <c>0</c> and <c>1</c>.</p> - <p><c>{minor_version, 1}</c> forces any floats in the term to be encoded - in a more space-efficient and exact way (namely in the 64-bit IEEE format, - rather than converted to a textual representation). <c>binary_to_term/1</c> - in R11B-4 and later is able decode the new representation.</p> - <p><c>{minor_version, 0}</c> is currently the default, meaning that floats - will be encoded using a textual representation; this option is useful if - you want to ensure that releases prior to R11B-4 can decode resulting + <fsummary>Encodes a term to en Erlang external term format binary.</fsummary> + <desc> + <p>Returns a binary data object that is the result of encoding + <c><anno>Term</anno></c> according to the Erlang external + term format.</p> + <p>If option <c>compressed</c> is provided, the external term + format is compressed. The compressed format is automatically + recognized by <c>binary_to_term/1</c> as from Erlang R7B.</p> + <p>A compression level can be specified by giving option + <c>{compressed, <anno>Level</anno>}</c>. + <c><anno>Level</anno></c> is an integer + with range 0..9, where:</p> + <list type="bulleted"> + <item><c>0</c> - No compression is done (it is the same as + giving no <c>compressed</c> option).</item> + <item><c>1</c> - Takes least time but may not compress + as well as the higher levels.</item> + <item><c>6</c> - Default level when option <c>compressed</c> + is provided.</item> + <item><c>9</c> - Takes most time and tries to produce a smaller + result. Notice "tries" in the preceding sentence; depending + on the input term, level 9 compression either does or does + not produce a smaller result than level 1 compression.</item> + </list> + <p>Option <c>{minor_version, <anno>Version</anno>}</c> + can be used to control + some encoding details. This option was introduced in OTP R11B-4. + The valid values for <c><anno>Version</anno></c> are + <c>0</c> and <c>1</c>.</p> + <p>As from OTP 17.0, <c>{minor_version, 1}</c> is the default. It + forces any floats in the term to be encoded in a more + space-efficient and exact way (namely in the 64-bit IEEE format, + rather than converted to a textual representation).</p> + <p>As from OTP R11B-4, <c>binary_to_term/1</c> can decode this + representation.</p> + <p><c>{minor_version, 0}</c> means that floats are encoded + using a textual representation. This option is useful to + ensure that releases before OTP R11B-4 can decode resulting binary.</p> <p>See also <seealso marker="#binary_to_term/1">binary_to_term/1</seealso>.</p> </desc> </func> + <func> <name name="throw" arity="1"/> - <fsummary>Throw an exception</fsummary> + <fsummary>Throws an exception.</fsummary> <desc> <p>A non-local return from a function. If evaluated within a - <c>catch</c>, <c>catch</c> will return the value <c><anno>Any</anno></c>.</p> + <c>catch</c>, <c>catch</c> returns value <c><anno>Any</anno></c>.</p> + <p>Example:</p> <pre> > <input>catch throw({hello, there}).</input> {hello,there}</pre> <p>Failure: <c>nocatch</c> if not evaluated within a catch.</p> </desc> </func> + <func> <name name="time" arity="0"/> - <fsummary>Current time</fsummary> + <fsummary>Current time.</fsummary> <desc> <p>Returns the current time as <c>{Hour, Minute, Second}</c>.</p> - <p>The time zone and daylight saving time correction depend on + <p>The time zone and Daylight Saving Time correction depend on the underlying OS.</p> + <p>Example:</p> <pre> > <input>time().</input> {9,42,44}</pre> </desc> </func> + + <func> + <name name="time_offset" arity="0"/> + <fsummary>Current time offset</fsummary> + <desc> + <p>Returns the current time offset between + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang monotonic time</seealso> + and + <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso> in + <c>native</c> <seealso marker="#type_time_unit">time unit</seealso>. + Current time offset added to an Erlang monotonic time gives + corresponding Erlang system time.</p> + + <p>The time offset may or may not change during operation depending + on the <seealso marker="time_correction#Time_Warp_Modes">time + warp mode</seealso> used.</p> + + <note> + <p>A change in time offset may be observed at slightly + different points in time by different processes.</p> + + <p>If the runtime system is in + <seealso marker="time_correction#Multi_Time_Warp_Mode">multi + time warp mode</seealso>, the time offset will be changed when + the runtime system detects that the + <seealso marker="time_correction#OS_System_Time">OS system + time</seealso> has changed. The runtime system will, however, + not detect this immediately when it happens. A task checking + the time offset is scheduled to execute at least once a minute, + so under normal operation this should be detected within a + minute, but during heavy load it might take longer time.</p> + </note> + </desc> + </func> + <func> + <name name="time_offset" arity="1"/> + <fsummary>Current time offset</fsummary> + <desc> + <p>Returns the current time offset between + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang monotonic time</seealso> + and + <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso> + converted into the <c><anno>Unit</anno></c> passed as argument.</p> + + <p>Same as calling + <seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#time_offset/0"><c>erlang:time_offset()</c></seealso><c>, native, <anno>Unit</anno>)</c> + however optimized for commonly used <c><anno>Unit</anno></c>s.</p> + </desc> + </func> + <func> + <name name="timestamp" arity="0"/> + <fsummary>Current Erlang System time</fsummary> + <type name="timestamp"/> + <desc> + <p>Returns current + <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso> + on the format <c>{MegaSecs, Secs, MicroSecs}</c>. This format is + the same as <seealso marker="kernel:os#timestamp/0"><c>os:timestamp/0</c></seealso> + and the deprecated <seealso marker="#now/0"><c>erlang:now/0</c></seealso> + uses. The reason for the existence of <c>erlang:timestamp()</c> is + purely to simplify usage for existing code that assumes this timestamp + format. Current Erlang system time can more efficiently be retrieved in + the time unit of your choice using + <seealso marker="#system_time/1"><c>erlang:system_time/1</c></seealso>.</p> + + <p>The <c>erlang:timestamp()</c> BIF is equivalent to:</p><code type="none"> +timestamp() -> + ErlangSystemTime = erlang:system_time(micro_seconds), + MegaSecs = ErlangSystemTime div 1000000000000, + Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000, + MicroSecs = ErlangSystemTime rem 1000000, + {MegaSecs, Secs, MicroSecs}.</code> + <p>It, however, uses a native implementation which does + not build garbage on the heap and with slightly better + performance.</p> + + <note><p>This time is <em>not</em> a monotonically increasing time + in the general case. For more information, see the documentation of + <seealso marker="time_correction#Time_Warp_Modes">time warp modes</seealso> in the + ERTS User's Guide.</p></note> + </desc> + + </func> <func> <name name="tl" arity="1"/> - <fsummary>Tail of a list</fsummary> + <fsummary>Tail of a list.</fsummary> <desc> - <p>Returns the tail of <c><anno>List</anno></c>, that is, the list minus - the first element.</p> + <p>Returns the tail of <c><anno>List</anno></c>, that is, + the list minus the first element, for example:</p> <pre> > <input>tl([geesties, guilies, beasties]).</input> [guilies, beasties]</pre> <p>Allowed in guard tests.</p> - <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> is the empty list [].</p> + <p>Failure: <c>badarg</c> if <c><anno>List</anno></c> + is the empty list <c>[]</c>.</p> </desc> </func> + <func> <name name="trace" arity="3"/> + <fsummary>Sets trace flags for a process or processes.</fsummary> <type name="trace_flag"/> - <fsummary>Set trace flags for a process or processes</fsummary> <desc> <p>Turns on (if <c><anno>How</anno> == true</c>) or off (if - <c><anno>How</anno> == false</c>) the trace flags in <c><anno>FlagList</anno></c> for - the process or processes represented by <c><anno>PidSpec</anno></c>.</p> - <p><c><anno>PidSpec</anno></c> is either a pid for a local process, or one of - the following atoms:</p> + <c><anno>How</anno> == false</c>) the trace flags in + <c><anno>FlagList</anno></c> for + the process or processes represented by + <c><anno>PidPortSpec</anno></c>.</p> + <p><c><anno>PidPortSpec</anno></c> is either a process identifier + (pid) for a local process, a port identifier, + or one of the following atoms:</p> <taglist> + <tag><c>all</c></tag> + <item> + <p>All currently existing processes and ports and all that + will be created in the future.</p> + </item> + <tag><c>processes</c></tag> + <item> + <p>All currently existing processes and all that will be created in the future.</p> + </item> + <tag><c>ports</c></tag> + <item> + <p>All currently existing ports and all that will be created in the future.</p> + </item> <tag><c>existing</c></tag> <item> - <p>All processes currently existing.</p> + <p>All currently existing processes and ports.</p> + </item> + <tag><c>existing_processes</c></tag> + <item> + <p>All currently existing processes.</p> + </item> + <tag><c>existing_ports</c></tag> + <item> + <p>All currently existing ports.</p> </item> <tag><c>new</c></tag> <item> + <p>All processes and ports that will be created in the future.</p> + </item> + <tag><c>new_processes</c></tag> + <item> <p>All processes that will be created in the future.</p> </item> - <tag><c>all</c></tag> + <tag><c>new_ports</c></tag> <item> - <p>All currently existing processes and all processes that - will be created in the future.</p> + <p>All ports that will be created in the future.</p> </item> </taglist> - <p><c><anno>FlagList</anno></c> can contain any number of the following - flags (the "message tags" refers to the list of messages - following below):</p> + <p><c><anno>FlagList</anno></c> can contain any number of the + following flags (the "message tags" refers to the list of + <seealso marker="#trace_3_trace_messages">trace messages</seealso>):</p> <taglist> <tag><c>all</c></tag> <item> - <p>Set all trace flags except <c>{tracer, Tracer}</c> and - <c>cpu_timestamp</c> that are in their nature different + <p>Sets all trace flags except <c>tracer</c> and + <c>cpu_timestamp</c>, which are in their nature different than the others.</p> </item> <tag><c>send</c></tag> <item> - <p>Trace sending of messages.</p> - <p>Message tags: <c>send</c>, - <c>send_to_non_existing_process</c>.</p> + <p>Traces sending of messages.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_send"><c>send</c></seealso> and + <seealso marker="#trace_3_trace_messages_send_to_non_existing_process"><c>send_to_non_existing_process</c></seealso>.</p> </item> <tag><c>'receive'</c></tag> <item> - <p>Trace receiving of messages.</p> - <p>Message tags: <c>'receive'</c>.</p> + <p>Traces receiving of messages.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_receive"><c>'receive'</c></seealso>.</p> </item> - <tag><c>procs</c></tag> +<tag><c>call</c></tag> <item> - <p>Trace process related events.</p> - <p>Message tags: <c>spawn</c>, <c>exit</c>, - <c>register</c>, <c>unregister</c>, <c>link</c>, - <c>unlink</c>, <c>getting_linked</c>, - <c>getting_unlinked</c>.</p> - </item> - <tag><c>call</c></tag> - <item> - <p>Trace certain function calls. Specify which function + <p>Traces certain function calls. Specify which function calls to trace by calling <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p> - <p>Message tags: <c>call</c>, <c>return_from</c>.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_call"><c>call</c></seealso> and + <seealso marker="#trace_3_trace_messages_return_from"><c>return_from</c></seealso>.</p> </item> <tag><c>silent</c></tag> <item> - <p>Used in conjunction with the <c>call</c> trace flag. - The <c>call</c>, <c>return_from</c> and <c>return_to</c> - trace messages are inhibited if this flag is set, - but if there are match specs they are executed as normal.</p> + <p>Used with the <c>call</c> trace flag. + The <c>call</c>, <c>return_from</c>, and <c>return_to</c> + trace messages are inhibited if this flag is set, but they + are executed as normal if there are match specifications.</p> <p>Silent mode is inhibited by executing <c>erlang:trace(_, false, [silent|_])</c>, - or by a match spec executing the <c>{silent, false}</c> - function.</p> + or by a match specification executing the function + <c>{silent, false}</c>.</p> <p>The <c>silent</c> trace flag facilitates setting up a trace on many or even all processes in the system. - Then the interesting trace can be activated and - deactivated using the <c>{silent,Bool}</c> - match spec function, giving a high degree - of control of which functions with which - arguments that triggers the trace.</p> - <p>Message tags: <c>call</c>, <c>return_from</c>, - <c>return_to</c>. Or rather, the absence of.</p> + The trace can then be activated and deactivated using the match + specification function <c>{silent,Bool}</c>, giving + a high degree of control of which functions with which + arguments that trigger the trace.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_call"><c>call</c></seealso>, + <seealso marker="#trace_3_trace_messages_return_from"><c>return_from</c></seealso>, and + <seealso marker="#trace_3_trace_messages_return_to"><c>return_to</c></seealso>. Or rather, the absence of.</p> </item> <tag><c>return_to</c></tag> <item> - <p>Used in conjunction with the <c>call</c> trace flag. - Trace the actual return from a traced function back to + <p>Used with the <c>call</c> trace flag. + Traces the return from a traced function back to its caller. Only works for functions traced with - the <c>local</c> option to + option <c>local</c> to <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p> <p>The semantics is that a trace message is sent when a - call traced function actually returns, that is, when a - chain of tail recursive calls is ended. There will be - only one trace message sent per chain of tail recursive - calls, why the properties of tail recursiveness for + call traced function returns, that is, when a + chain of tail recursive calls ends. Only one trace + message is sent per chain of tail recursive calls, + so the properties of tail recursiveness for function calls are kept while tracing with this flag. Using <c>call</c> and <c>return_to</c> trace together makes it possible to know exactly in which function a process executes at any time.</p> <p>To get trace messages containing return values from - functions, use the <c>{return_trace}</c> match_spec - action instead.</p> - <p>Message tags: <c>return_to</c>.</p> + functions, use the <c>{return_trace}</c> match + specification action instead.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_return_to"><c>return_to</c></seealso>.</p> + </item> + <tag><c>procs</c></tag> + <item> + <p>Traces process-related events.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_spawn"><c>spawn</c></seealso>, + <seealso marker="#trace_3_trace_messages_spawned"><c>spawned</c></seealso>, + <seealso marker="#trace_3_trace_messages_exit"><c>exit</c></seealso>, + <seealso marker="#trace_3_trace_messages_register"><c>register</c></seealso>, + <seealso marker="#trace_3_trace_messages_unregister"><c>unregister</c></seealso>, + <seealso marker="#trace_3_trace_messages_link"><c>link</c></seealso>, + <seealso marker="#trace_3_trace_messages_unlink"><c>unlink</c></seealso>, + <seealso marker="#trace_3_trace_messages_getting_linked"><c>getting_linked</c></seealso>, and + <seealso marker="#trace_3_trace_messages_getting_unlinked"><c>getting_unlinked</c></seealso>.</p> + </item> + <tag><c>ports</c></tag> + <item> + <p>Traces port-related events.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_open"><c>open</c></seealso>, + <seealso marker="#trace_3_trace_messages_closed"><c>closed</c></seealso>, + <seealso marker="#trace_3_trace_messages_register"><c>register</c></seealso>, + <seealso marker="#trace_3_trace_messages_unregister"><c>unregister</c></seealso>, + <seealso marker="#trace_3_trace_messages_getting_linked"><c>getting_linked</c></seealso>, and + <seealso marker="#trace_3_trace_messages_getting_unlinked"><c>getting_unlinked</c></seealso>.</p> </item> <tag><c>running</c></tag> <item> - <p>Trace scheduling of processes.</p> - <p>Message tags: <c>in</c>, and <c>out</c>.</p> + <p>Traces scheduling of processes.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_in_proc"><c>in</c></seealso> and + <seealso marker="#trace_3_trace_messages_out_proc"><c>out</c></seealso>.</p> </item> <tag><c>exiting</c></tag> <item> - <p>Trace scheduling of an exiting processes.</p> - <p>Message tags: <c>in_exiting</c>, <c>out_exiting</c>, and - <c>out_exited</c>.</p> + <p>Traces scheduling of exiting processes.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_in_exiting_proc"><c>in_exiting</c></seealso>, + <seealso marker="#trace_3_trace_messages_out_exiting_proc"><c>out_exiting</c></seealso>, and + <seealso marker="#trace_3_trace_messages_out_exited_proc"><c>out_exited</c></seealso>.</p> + </item> + <tag><c>running_procs</c></tag> + <item> + <p>Traces scheduling of processes just like <c>running</c>. + However this option also includes schedule events when the + process executes within the context of a port without + being scheduled out itself.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_in_proc"><c>in</c></seealso> and + <seealso marker="#trace_3_trace_messages_out_proc"><c>out</c></seealso>.</p> + </item> + <tag><c>running_ports</c></tag> + <item> + <p>Traces scheduling of ports.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_in_port"><c>in</c></seealso> and + <seealso marker="#trace_3_trace_messages_out_port"><c>out</c></seealso>.</p> </item> <tag><c>garbage_collection</c></tag> <item> - <p>Trace garbage collections of processes.</p> - <p>Message tags: <c>gc_start</c>, <c>gc_end</c>.</p> + <p>Traces garbage collections of processes.</p> + <p>Message tags: <seealso marker="#trace_3_trace_messages_gc_minor_start"><c>gc_minor_start</c></seealso>, + <seealso marker="#trace_3_trace_messages_gc_max_heap_size"><c>gc_max_heap_size</c></seealso> and + <seealso marker="#trace_3_trace_messages_gc_minor_end"><c>gc_minor_end</c></seealso>.</p> </item> <tag><c>timestamp</c></tag> <item> - <p>Include a time stamp in all trace messages. The time - stamp (Ts) is of the same form as returned by + <p>Includes a time-stamp in all trace messages. The + time-stamp (Ts) has the same form as returned by <c>erlang:now()</c>.</p> </item> <tag><c>cpu_timestamp</c></tag> <item> <p>A global trace flag for the Erlang node that makes all - trace timestamps be in CPU time, not wallclock. It is - only allowed with <c>PidSpec==all</c>. If the host - machine operating system does not support high resolution + trace time-stamps using the <c>timestamp</c> flag to be + in CPU time, not wall clock time. That is, <c>cpu_timestamp</c> + will not be used if <c>monotonic_timestamp</c>, or + <c>strict_monotonic_timestamp</c> is enabled. + Only allowed with <c><anno>PidPortSpec</anno>==all</c>. If the + host machine OS does not support high-resolution CPU time measurements, <c>trace/3</c> exits with - <c>badarg</c>.</p> + <c>badarg</c>. Notice that most OS do + not synchronize this value across cores, so be prepared + that time might seem to go backwards when using this option.</p> + </item> + <tag><c>monotonic_timestamp</c></tag> + <item> + <p>Includes an + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso> time-stamp in all trace messages. The + time-stamp (Ts) has the same format and value as produced by + <seealso marker="#monotonic_time-1"><c>erlang:monotonic_time(nano_seconds)</c></seealso>. + This flag overrides the <c>cpu_timestamp</c> flag.</p> + </item> + <tag><c>strict_monotonic_timestamp</c></tag> + <item> + <p>Includes an timestamp consisting of + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso> and a monotonically increasing + integer in all trace messages. The time-stamp (Ts) has the + same format and value as produced by + <c>{</c><seealso marker="#monotonic_time-1"><c>erlang:monotonic_time(nano_seconds)</c></seealso><c>,</c> + <seealso marker="#unique_integer-1"><c>erlang:unique_integer([monotonic])</c></seealso><c>}</c>. + This flag overrides the <c>cpu_timestamp</c> flag.</p> </item> <tag><c>arity</c></tag> <item> - <p>Used in conjunction with the <c>call</c> trace flag. - <c>{M, F, Arity}</c> will be specified instead of + <p>Used with the <c>call</c> trace flag. + <c>{M, F, Arity}</c> is specified instead of <c>{M, F, Args}</c> in call trace messages.</p> </item> <tag><c>set_on_spawn</c></tag> <item> <p>Makes any process created by a traced process inherit - its trace flags, including the <c>set_on_spawn</c> flag.</p> + its trace flags, including flag <c>set_on_spawn</c>.</p> </item> <tag><c>set_on_first_spawn</c></tag> <item> <p>Makes the first process created by a traced process - inherit its trace flags, excluding - the <c>set_on_first_spawn</c> flag.</p> + inherit its trace flags, excluding flag + <c>set_on_first_spawn</c>.</p> </item> <tag><c>set_on_link</c></tag> <item> <p>Makes any process linked by a traced process inherit its - trace flags, including the <c>set_on_link</c> flag.</p> + trace flags, including flag <c>set_on_link</c>.</p> </item> <tag><c>set_on_first_link</c></tag> <item> <p>Makes the first process linked to by a traced process - inherit its trace flags, excluding - the <c>set_on_first_link</c> flag.</p> + inherit its trace flags, excluding flag + <c>set_on_first_link</c>.</p> </item> <tag><c>{tracer, Tracer}</c></tag> <item> - <p>Specify where to send the trace messages. <c>Tracer</c> - must be the pid of a local process or the port identifier - of a local port. If this flag is not given, trace - messages will be sent to the process that called - <c>erlang:trace/3</c>.</p> + <p>Specifies where to send the trace messages. <c>Tracer</c> + must be the process identifier of a local process + or the port identifier of a local port.</p> + </item> + <tag><c>{tracer, TracerModule, TracerState}</c></tag> + <item> + <p>Specifies that a tracer module should be called + instead of sending a trace message. The tracer module + can then ignore or change the trace message. For more details + on how to write a tracer module see + <seealso marker="erts:erl_tracer"><c>erl_tracer</c></seealso> + </p> </item> </taglist> + <p>If no <c>tracer</c> is given, the calling process + will be receiving all of the trace messages</p> <p>The effect of combining <c>set_on_first_link</c> with <c>set_on_link</c> is the same as having <c>set_on_first_link</c> alone. Likewise for <c>set_on_spawn</c> and <c>set_on_first_spawn</c>.</p> - <p>If the <c>timestamp</c> flag is not given, the tracing - process will receive the trace messages described below. - <c>Pid</c> is the pid of the traced process in which - the traced event has occurred. The third element of the tuple - is the message tag.</p> - <p>If the <c>timestamp</c> flag is given, the first element of - the tuple will be <c>trace_ts</c> instead and the timestamp - is added last in the tuple.</p> + <p>The tracing process receives the <em>trace messages</em> described + in the following list. <c>Pid</c> is the process identifier of the + traced process in which the traced event has occurred. The + third tuple element is the message tag.</p> + <p>If flag <c>timestamp</c>, <c>strict_monotonic_timestamp</c>, or + <c>monotonic_timestamp</c> is given, the first tuple + element is <c>trace_ts</c> instead, and the time-stamp + is added as an extra element last in the message tuple. If + multiple timestamp flags are passed, <c>timestamp</c> has + precedence over <c>strict_monotonic_timestamp</c> which + in turn has precedence over <c>monotonic_timestamp</c>. All + timestamp flags are remembered, so if two are passed + and the one with highest precedence later is disabled + the other one will become active.</p> + <marker id="trace_3_trace_messages"></marker> <taglist> - <tag><c>{trace, Pid, 'receive', Msg}</c></tag> + <tag> + <marker id="trace_3_trace_messages_send"></marker> + <c>{trace, PidPort, send, Msg, To}</c> + </tag> <item> - <p>When <c>Pid</c> receives the message <c>Msg</c>.</p> + <p>When <c>PidPort</c> sends message <c>Msg</c> to + process <c>To</c>.</p> </item> - <tag><c>{trace, Pid, send, Msg, To}</c></tag> + <tag> + <marker id="trace_3_trace_messages_send_to_non_existing_process"></marker> + <c>{trace, PidPort, send_to_non_existing_process, Msg, To}</c> + </tag> <item> - <p>When <c>Pid</c> sends the message <c>Msg</c> to - the process <c>To</c>.</p> + <p>When <c>PidPort</c> sends message <c>Msg</c> to + the non-existing process <c>To</c>.</p> </item> - <tag><c>{trace, Pid, send_to_non_existing_process, Msg, To}</c></tag> + <tag> + <marker id="trace_3_trace_messages_receive"></marker> + <c>{trace, PidPort, 'receive', Msg}</c> + </tag> <item> - <p>When <c>Pid</c> sends the message <c>Msg</c> to - the non-existing process <c>To</c>.</p> + <p>When <c>PidPort</c> receives message <c>Msg</c>. + If <c>Msg</c> is set to timeout, then a receive + statement may have timedout, or the process received + a message with the payload <c>timeout</c>.</p> </item> - <tag><c>{trace, Pid, call, {M, F, Args}}</c></tag> + <tag> + <marker id="trace_3_trace_messages_call"></marker> + <c>{trace, Pid, call, {M, F, Args}}</c> + </tag> <item> <p>When <c>Pid</c> calls a traced function. The return values of calls are never supplied, only the call and its arguments.</p> - <p>Note that the trace flag <c>arity</c> can be used to + <p>Trace flag <c>arity</c> can be used to change the contents of this message, so that <c>Arity</c> is specified instead of <c>Args</c>.</p> </item> - <tag><c>{trace, Pid, return_to, {M, F, Arity}}</c></tag> + <tag> + <marker id="trace_3_trace_messages_return_to"></marker> + <c>{trace, Pid, return_to, {M, F, Arity}}</c> + </tag> <item> <p>When <c>Pid</c> returns <em>to</em> the specified function. This trace message is sent if both - the <c>call</c> and the <c>return_to</c> flags are set, + the flags <c>call</c> and <c>return_to</c> are set, and the function is set to be traced on <em>local</em> function calls. The message is only sent when returning - from a chain of tail recursive function calls where at + from a chain of tail recursive function calls, where at least one call generated a <c>call</c> trace message - (that is, the functions match specification matched and + (that is, the functions match specification matched, and <c>{message, false}</c> was not an action).</p> </item> - <tag><c>{trace, Pid, return_from, {M, F, Arity}, ReturnValue}</c></tag> + <tag> + <marker id="trace_3_trace_messages_return_from"></marker> + <c>{trace, Pid, return_from, {M, F, Arity}, ReturnValue}</c> + </tag> <item> <p>When <c>Pid</c> returns <em>from</em> the specified - function. This trace message is sent if the <c>call</c> - flag is set, and the function has a match specification + function. This trace message is sent if flag <c>call</c> + is set, and the function has a match specification with a <c>return_trace</c> or <c>exception_trace</c> action.</p> </item> - <tag><c>{trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}</c></tag> + <tag> + <marker id="trace_3_trace_messages_exception_from"></marker> + <c>{trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}</c> + </tag> <item> <p>When <c>Pid</c> exits <em>from</em> the specified - function due to an exception. This trace message is sent - if the <c>call</c> flag is set, and the function has + function because of an exception. This trace message is + sent if flag <c>call</c> is set, and the function has a match specification with an <c>exception_trace</c> action.</p> </item> - <tag><c>{trace, Pid, spawn, Pid2, {M, F, Args}}</c></tag> + <tag> + <marker id="trace_3_trace_messages_spawn"></marker> + <c>{trace, Pid, spawn, Pid2, {M, F, Args}}</c> + </tag> <item> <p>When <c>Pid</c> spawns a new process <c>Pid2</c> with the specified function call as entry point.</p> - <p>Note that <c>Args</c> is supposed to be the argument - list, but may be any term in the case of an erroneous - spawn.</p> + <p><c>Args</c> is supposed to be the argument list, + but can be any term if the spawn is erroneous.</p> + </item> + <tag> + <marker id="trace_3_trace_messages_spawned"></marker> + <c>{trace, Pid, spawned, Pid2, {M, F, Args}}</c> + </tag> + <item> + <p>When <c>Pid</c> is spawned by process <c>Pid2</c> with + the specified function call as entry point.</p> + <p><c>Args</c> is supposed to be the argument list, + but can be any term if the spawn is erroneous.</p> </item> - <tag><c>{trace, Pid, exit, Reason}</c></tag> + <tag> + <marker id="trace_3_trace_messages_exit"></marker> + <c>{trace, Pid, exit, Reason}</c> + </tag> <item> <p>When <c>Pid</c> exits with reason <c>Reason</c>.</p> </item> - <tag><c>{trace, Pid, link, Pid2}</c></tag> + <tag> + <marker id="trace_3_trace_messages_register"></marker> + <c>{trace, PidPort, register, RegName}</c> + </tag> + <item> + <p>When <c>PidPort</c> gets the name <c>RegName</c> registered.</p> + </item> + <tag> + <marker id="trace_3_trace_messages_unregister"></marker> + <c>{trace, PidPort, unregister, RegName}</c> + </tag> + <item> + <p>When <c>PidPort</c> gets the name <c>RegName</c> unregistered. + This is done automatically when a registered + process or port exits.</p> + </item> + <tag> + <marker id="trace_3_trace_messages_link"></marker> + <c>{trace, Pid, link, Pid2}</c> + </tag> <item> <p>When <c>Pid</c> links to a process <c>Pid2</c>.</p> </item> - <tag><c>{trace, Pid, unlink, Pid2}</c></tag> + <tag> + <marker id="trace_3_trace_messages_unlink"></marker> + <c>{trace, Pid, unlink, Pid2}</c> + </tag> <item> <p>When <c>Pid</c> removes the link from a process <c>Pid2</c>.</p> </item> - <tag><c>{trace, Pid, getting_linked, Pid2}</c></tag> + <tag> + <marker id="trace_3_trace_messages_getting_linked"></marker> + <c>{trace, PidPort, getting_linked, Pid2}</c> + </tag> <item> - <p>When <c>Pid</c> gets linked to a process <c>Pid2</c>.</p> + <p>When <c>PidPort</c> gets linked to a process <c>Pid2</c>.</p> </item> - <tag><c>{trace, Pid, getting_unlinked, Pid2}</c></tag> + <tag> + <marker id="trace_3_trace_messages_getting_unlinked"></marker> + <c>{trace, PidPort, getting_unlinked, Pid2}</c> + </tag> <item> - <p>When <c>Pid</c> gets unlinked from a process <c>Pid2</c>.</p> + <p>When <c>PidPort</c> gets unlinked from a process <c>Pid2</c>.</p> </item> - <tag><c>{trace, Pid, register, RegName}</c></tag> + <tag> + <marker id="trace_3_trace_messages_exit"></marker> + <c>{trace, Pid, exit, Reason}</c> + </tag> <item> - <p>When <c>Pid</c> gets the name <c>RegName</c> registered.</p> + <p>When <c>Pid</c> exits with reason <c>Reason</c>.</p> </item> - <tag><c>{trace, Pid, unregister, RegName}</c></tag> + <tag> + <marker id="trace_3_trace_messages_open"></marker> + <c>{trace, Port, open, Pid, Driver}</c> + </tag> <item> - <p>When <c>Pid</c> gets the name <c>RegName</c> unregistered. - Note that this is done automatically when a registered - process exits.</p> + <p>When <c>Pid</c> opens a new port <c>Port</c> with + the running the <c>Driver</c>.</p> + <p><c>Driver</c> is the name of the driver as an atom.</p> </item> - <tag><c>{trace, Pid, in, {M, F, Arity} | 0}</c></tag> + <tag> + <marker id="trace_3_trace_messages_closed"></marker> + <c>{trace, Port, closed, Reason}</c> + </tag> <item> - <p>When <c>Pid</c> is scheduled to run. The process will - run in function <c>{M, F, Arity}</c>. On some rare - occasions the current function cannot be determined, then - the last element <c>Arity</c> is 0.</p> + <p>When <c>Port</c> closed with <c>Reason</c>.</p> </item> - <tag><c>{trace, Pid, out, {M, F, Arity} | 0}</c></tag> + <tag> + <marker id="trace_3_trace_messages_in_proc"></marker> + <marker id="trace_3_trace_messages_in_exiting_proc"></marker> + <c>{trace, Pid, in | in_exiting, {M, F, Arity} | 0}</c> + </tag> + <item> + <p>When <c>Pid</c> is scheduled to run. The process + runs in function <c>{M, F, Arity}</c>. On some rare + occasions, the current function cannot be determined, + then the last element is <c>0</c>.</p> + </item> + <tag> + <marker id="trace_3_trace_messages_out_proc"></marker> + <marker id="trace_3_trace_messages_out_exiting_proc"></marker> + <marker id="trace_3_trace_messages_out_exited_proc"></marker> + <c>{trace, Pid, out | out_exiting | out_exited, {M, F, Arity} | 0}</c> + </tag> <item> <p>When <c>Pid</c> is scheduled out. The process was - running in function {M, F, Arity}. On some rare occasions + running in function {M, F, Arity}. On some rare occasions, + the current function cannot be determined, then the last + element is <c>0</c>.</p> + </item> + <tag> + <marker id="trace_3_trace_messages_in_port"></marker> + <c>{trace, Port, in, Command | 0}</c> + </tag> + <item> + <p>When <c>Port</c> is scheduled to run. <c>Command</c> is the + first thing the port will execute, it may however run several + commands before being scheduled out. On some rare + occasions, the current function cannot be determined, + then the last element is <c>0</c>.</p> + <p>The possible commands are: <c>call | close | command | connect | control | flush | info | link | open | unlink</c></p> + </item> + <tag> + <marker id="trace_3_trace_messages_out_port"></marker> + <c>{trace, Port, out, Command | 0}</c> + </tag> + <item> + <p>When <c>Port</c> is scheduled out. The last command run + was <c>Command</c>. On some rare occasions, the current function cannot be determined, then the last - element <c>Arity</c> is 0.</p> + element is <c>0</c>. <c>Command</c> can contain the same + commands as <c>in</c> + </p> </item> - <tag><marker id="gc_start"><c>{trace, Pid, gc_start, Info}</c></marker></tag> + <tag> + <marker id="trace_3_trace_messages_gc_minor_start"></marker> + <c>{trace, Pid, gc_minor_start, Info}</c> + </tag> <item> - <p>Sent when garbage collection is about to be started. + <marker id="gc_minor_start"></marker> + <p>Sent when a young garbage collection is about to be started. <c>Info</c> is a list of two-element tuples, where the first element is a key, and the second is the value. - You should not depend on the tuples have any defined - order. Currently, the following keys are defined:</p> + Do not depend on any order of the tuples. + The following keys are defined:</p> <taglist> <tag><c>heap_size</c></tag> <item>The size of the used part of the heap.</item> <tag><c>heap_block_size</c></tag> <item>The size of the memory block used for storing - the heap and the stack.</item> + the heap and the stack.</item> <tag><c>old_heap_size</c></tag> <item>The size of the used part of the old heap.</item> <tag><c>old_heap_block_size</c></tag> <item>The size of the memory block used for storing - the old heap.</item> + the old heap.</item> <tag><c>stack_size</c></tag> - <item>The actual size of the stack.</item> + <item>The size of the stack.</item> <tag><c>recent_size</c></tag> <item>The size of the data that survived the previous garbage - collection.</item> + collection.</item> <tag><c>mbuf_size</c></tag> <item>The combined size of message buffers associated with - the process.</item> - + the process.</item> <tag><c>bin_vheap_size</c></tag> - <item>The total size of unique off-heap binaries referenced from the process heap.</item> + <item>The total size of unique off-heap binaries referenced + from the process heap.</item> <tag><c>bin_vheap_block_size</c></tag> - <item>The total size of binaries, in words, allowed in the virtual - heap in the process before doing a garbage collection. </item> + <item>The total size of binaries allowed in the virtual + heap in the process before doing a garbage collection.</item> <tag><c>bin_old_vheap_size</c></tag> - <item>The total size of unique off-heap binaries referenced from the process old heap.</item> - <tag><c>bin_vheap_block_size</c></tag> - <item>The total size of binaries, in words, allowed in the virtual - old heap in the process before doing a garbage collection. </item> - - + <item>The total size of unique off-heap binaries referenced + from the process old heap.</item> + <tag><c>bin_old_vheap_block_size</c></tag> + <item>The total size of binaries allowed in the virtual + old heap in the process before doing a garbage collection.</item> </taglist> <p>All sizes are in words.</p> </item> - <tag><c>{trace, Pid, gc_end, Info}</c></tag> - <item> - <p>Sent when garbage collection is finished. <c>Info</c> - contains the same kind of list as in the <c>gc_start</c> - message, but the sizes reflect the new sizes after + <tag> + <marker id="trace_3_trace_messages_gc_max_heap_size"></marker> + <c>{trace, Pid, gc_max_heap_size, Info}</c> + </tag> + <item> + <p> + Sent when the <seealso marker="#process_flag_max_heap_size"><c>max_heap_size</c></seealso> + is reached during garbage collection. <c>Info</c> contains the + same kind of list as in message <c>gc_start</c>, + but the sizes reflect the sizes that triggered max_heap_size to + be reached. + </p> + </item> + <tag> + <marker id="trace_3_trace_messages_gc_minor_end"></marker> + <c>{trace, Pid, gc_minor_end, Info}</c> + </tag> + <item> + <p>Sent when young garbage collection is finished. <c>Info</c> + contains the same kind of list as in message <c>gc_minor_start</c>, + but the sizes reflect the new sizes after garbage collection.</p> </item> + <tag> + <marker id="trace_3_trace_messages_gc_major_start"></marker> + <c>{trace, Pid, gc_major_start, Info}</c> + </tag> + <item> + <p>Sent when fullsweep garbage collection is about to be started. <c>Info</c> + contains the same kind of list as in message <c>gc_minor_start</c>.</p> + </item> + <tag> + <marker id="trace_3_trace_messages_gc_major_end"></marker> + <c>{trace, Pid, gc_major_end, Info}</c> + </tag> + <item> + <p>Sent when fullsweep garbage collection is finished. <c>Info</c> + contains the same kind of list as in message <c>gc_minor_start</c> + but the sizes reflect the new sizes after a fullsweep garbage collection.</p> + </item> </taglist> - <p>If the tracing process dies, the flags will be silently - removed.</p> - <p>Only one process can trace a particular process. For this - reason, attempts to trace an already traced process will fail.</p> + <p>If the tracing process/port dies or the tracer module returns + <c>remove</c>, the flags are silently removed.</p> + <p>Each process can only be traced by one tracer. Therefore, + attempts to trace an already traced process fail.</p> <p>Returns: A number indicating the number of processes that - matched <c><anno>PidSpec</anno></c>. If <c><anno>PidSpec</anno></c> is a pid, - the return value will be <c>1</c>. If <c><anno>PidSpec</anno></c> is - <c>all</c> or <c>existing</c> the return value will be - the number of processes running, excluding tracer processes. - If <c><anno>PidSpec</anno></c> is <c>new</c>, the return value will be + matched <c><anno>PidPortSpec</anno></c>. + If <c><anno>PidPortSpec</anno></c> is a process + identifier, the return value is <c>1</c>. + If <c><anno>PidPortSpec</anno></c> + is <c>all</c> or <c>existing</c>, the return value is + the number of processes running. + If <c><anno>PidPortSpec</anno></c> is <c>new</c>, the return value is <c>0</c>.</p> - <p>Failure: If specified arguments are not supported. For - example <c>cpu_timestamp</c> is not supported on all - platforms.</p> + <p>Failure: <c>badarg</c> if the specified arguments are + not supported. For example, <c>cpu_timestamp</c> is not + supported on all platforms.</p> </desc> </func> + <func> <name name="trace_delivered" arity="1"/> - <fsummary>Notification when trace has been delivered</fsummary> - <desc> - <p>The delivery of trace messages is dislocated on the time-line - compared to other events in the system. If you know that the - <c><anno>Tracee</anno></c> has passed some specific point in its execution, + <fsummary>Notification when trace has been delivered.</fsummary> + <desc> + <p>The delivery of trace messages (generated by + <seealso marker="#trace/3"><c>erlang:trace/3</c></seealso>, + <seealso marker="kernel:seq_trace"><c>seq_trace</c></seealso> or + <seealso marker="#system_profile/2"><c>erlang:system_profile/2</c></seealso>) + is dislocated on the time-line + compared to other events in the system. If you know that + <c><anno>Tracee</anno></c> has passed some specific point + in its execution, and you want to know when at least all trace messages - corresponding to events up to this point have reached the tracer - you can use <c>erlang:trace_delivered(<anno>Tracee</anno>)</c>. A + corresponding to events up to this point have reached the + tracer, use <c>erlang:trace_delivered(<anno>Tracee</anno>)</c>. A <c>{trace_delivered, <anno>Tracee</anno>, <anno>Ref</anno>}</c> message is sent to the caller of <c>erlang:trace_delivered(<anno>Tracee</anno>)</c> when it - is guaranteed that all trace messages have been delivered to - the tracer up to the point that the <c><anno>Tracee</anno></c> had reached + is guaranteed that all trace messages are delivered to + the tracer up to the point that <c><anno>Tracee</anno></c> reached at the time of the call to <c>erlang:trace_delivered(<anno>Tracee</anno>)</c>.</p> - <p>Note that the <c>trace_delivered</c> message does <em>not</em> - imply that trace messages have been delivered; instead, it implies - that all trace messages that <em>should</em> be delivered have - been delivered. It is not an error if <c><anno>Tracee</anno></c> isn't, and - hasn't been traced by someone, but if this is the case, - <em>no</em> trace messages will have been delivered when the + <p>Notice that message <c>trace_delivered</c> does <em>not</em> + imply that trace messages have been delivered. + Instead it implies that all trace messages that + <em>are to be delivered</em> have been delivered. + It is not an error if <c><anno>Tracee</anno></c> is not, and + has not been traced by someone, but if this is the case, + <em>no</em> trace messages have been delivered when the <c>trace_delivered</c> message arrives.</p> - <p>Note that <c><anno>Tracee</anno></c> has to refer to a process currently, + <p>Notice that <c><anno>Tracee</anno></c> must refer + to a process currently, or previously existing on the same node as the caller of <c>erlang:trace_delivered(<anno>Tracee</anno>)</c> resides on. - The special <c><anno>Tracee</anno></c> atom <c>all</c> denotes all processes - that currently are traced in the node.</p> - <p>An example: Process <c>A</c> is <c><anno>Tracee</anno></c>, port <c>B</c> is - tracer, and process <c>C</c> is the port owner of <c>B</c>. - <c>C</c> wants to close <c>B</c> when <c>A</c> exits. <c>C</c> - can ensure that the trace isn't truncated by calling - <c>erlang:trace_delivered(A)</c> when <c>A</c> exits and wait - for the <c>{trace_delivered, A, <anno>Ref</anno>}</c> message before closing - <c>B</c>.</p> - <p>Failure: <c>badarg</c> if <c><anno>Tracee</anno></c> does not refer to a + The special <c><anno>Tracee</anno></c> atom <c>all</c> + denotes all processes that currently are traced in the node.</p> + <p>When used together with an <seealso marker="erts:erl_tracer"> + Tracer Module</seealso> any message sent in the trace callback + is guaranteed to have reached it's recipient before the + <c>trace_delivered</c> message is sent.</p> + <p>Example: Process <c>A</c> is <c><anno>Tracee</anno></c>, + port <c>B</c> is tracer, and process <c>C</c> is the port + owner of <c>B</c>. <c>C</c> wants to close <c>B</c> when + <c>A</c> exits. To ensure that the trace is not truncated, + <c>C</c> can call <c>erlang:trace_delivered(A)</c>, when + <c>A</c> exits, and wait for message <c>{trace_delivered, A, + <anno>Ref</anno>}</c> before closing <c>B</c>.</p> + <p>Failure: <c>badarg</c> if <c><anno>Tracee</anno></c> + does not refer to a process (dead or alive) on the same node as the caller of <c>erlang:trace_delivered(<anno>Tracee</anno>)</c> resides on.</p> </desc> </func> + <func> <name name="trace_info" arity="2"/> + <fsummary>Trace information about a process or function.</fsummary> <type name="trace_info_return"/> <type name="trace_info_item_result"/> <type name="trace_info_flag"/> <type name="trace_match_spec"/> - <fsummary>Trace information about a process or function</fsummary> - <desc> - <p>Returns trace information about a process or function.</p> - <p>To get information about a process, <c><anno>PidOrFunc</anno></c> should - be a pid or the atom <c>new</c>. The atom <c>new</c> means - that the default trace state for processes to be created will - be returned. <c><anno>Item</anno></c> must have one of the following - values:</p> + <desc> + <p>Returns trace information about a port, process, function or event.</p> + <p><em>To get information about a port or process</em>, + <c><anno>PidPortFuncEvent</anno></c> is to + be a process identifier (pid), port identifier or one of + the atoms <c>new</c>, <c>new_processes</c>, <c>new_ports</c>. + The atom <c>new</c> or <c>new_processes</c> means that the default trace + state for processes to be created is returned. The atom <c>new_ports</c> + means that the default trace state for ports to be created is returned. + </p> + <p>The following <c>Item</c>s are valid for ports and processes:</p> <taglist> <tag><c>flags</c></tag> <item> - <p>Return a list of atoms indicating what kind of traces is - enabled for the process. The list will be empty if no + <p>Returns a list of atoms indicating what kind of traces is + enabled for the process. The list is empty if no traces are enabled, and one or more of the followings atoms if traces are enabled: <c>send</c>, <c>'receive'</c>, <c>set_on_spawn</c>, <c>call</c>, - <c>return_to</c>, <c>procs</c>, <c>set_on_first_spawn</c>, - <c>set_on_link</c>, <c>running</c>, + <c>return_to</c>, <c>procs</c>, <c>ports</c>, <c>set_on_first_spawn</c>, + <c>set_on_link</c>, <c>running</c>, <c>running_procs</c>, + <c>running_ports</c>, <c>silent</c>, <c>exiting</c> + <c>monotonic_timestamp</c>, <c>strict_monotonic_timestamp</c>, <c>garbage_collection</c>, <c>timestamp</c>, and <c>arity</c>. The order is arbitrary.</p> </item> <tag><c>tracer</c></tag> <item> - <p>Return the identifier for process or port tracing this + <p>Returns the identifier for process, port or a tuple containing + the tracer module and tracer state tracing this process. If this process is not being traced, the return - value will be <c>[]</c>.</p> + value is <c>[]</c>.</p> </item> </taglist> - <p>To get information about a function, <c>PidOrFunc</c> should - be a three-element tuple: <c>{Module, Function, Arity}</c> or - the atom <c>on_load</c>. No wildcards are allowed. Returns - <c>undefined</c> if the function does not exist or - <c>false</c> if the function is not traced at all. <c>Item</c> - must have one of the following values:</p> + <p><em>To get information about a function</em>, <c><anno>PidPortFuncEvent</anno></c> is to + be the three-element tuple <c>{Module, Function, Arity}</c> or + the atom <c>on_load</c>. No wild cards are allowed. Returns + <c>undefined</c> if the function does not exist, or + <c>false</c> if the function is not traced. If <c><anno>PidPortFuncEvent</anno></c> + is <c>on_load</c>, the information returned refers to + the default value for code that will be loaded.</p> + + <p>The following <c>Item</c>s are valid for functions:</p> <taglist> <tag><c>traced</c></tag> <item> - <p>Return <c>global</c> if this function is traced on + <p>Returns <c>global</c> if this function is traced on global function calls, <c>local</c> if this function is - traced on local function calls (i.e local and global - function calls), and <c>false</c> if neither local nor - global function calls are traced.</p> + traced on local function calls (that is, local and global + function calls), and <c>false</c> if local or + global function calls are not traced.</p> </item> <tag><c>match_spec</c></tag> <item> - <p>Return the match specification for this function, if it + <p>Returns the match specification for this function, if it has one. If the function is locally or globally traced but has no match specification defined, the returned value is <c>[]</c>.</p> </item> <tag><c>meta</c></tag> <item> - <p>Return the meta trace tracer process or port for this - function, if it has one. If the function is not meta - traced the returned value is <c>false</c>, and if - the function is meta traced but has once detected that - the tracer proc is invalid, the returned value is [].</p> + <p>Returns the meta-trace tracer process, port or trace module + for this function, if it has one. If the function is not + meta-traced, the returned value is <c>false</c>. If + the function is meta-traced but has once detected that + the tracer process is invalid, the returned value is [].</p> </item> <tag><c>meta_match_spec</c></tag> <item> - <p>Return the meta trace match specification for this - function, if it has one. If the function is meta traced + <p>Returns the meta-trace match specification for this + function, if it has one. If the function is meta-traced but has no match specification defined, the returned value is <c>[]</c>.</p> </item> <tag><c>call_count</c></tag> <item> - <p>Return the call count value for this function or + <p>Returns the call count value for this function or <c>true</c> for the pseudo function <c>on_load</c> if call - count tracing is active. Return <c>false</c> otherwise. + count tracing is active. Otherwise <c>false</c> is returned. See also <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p> </item> <tag><c>call_time</c></tag> <item> - <p>Return the call time values for this function or + <p>Returns the call time values for this function or <c>true</c> for the pseudo function <c>on_load</c> if call - time tracing is active. Returns <c>false</c> otherwise. + time tracing is active. Otherwise <c>false</c> is returned. The call time values returned, <c>[{Pid, Count, S, Us}]</c>, - is a list of each process that has executed the function and its specific counters. - See also + is a list of each process that executed the function + and its specific counters. See also <seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p> </item> <tag><c>all</c></tag> <item> - <p>Return a list containing the <c>{<anno>Item</anno>, Value}</c> tuples - for all other items, or return <c>false</c> if no tracing + <p>Returns a list containing the + <c>{<anno>Item</anno>, Value}</c> tuples + for all other items, or returns <c>false</c> if no tracing is active for this function.</p> </item> </taglist> - <p>The actual return value will be <c>{<anno>Item</anno>, Value}</c>, where - <c>Value</c> is the requested information as described above. + <p><em>To get information about an event</em>, <c><anno>PidPortFuncEvent</anno></c> is to + be one of the atoms <c>send</c> or <c>'receive'</c>.</p> + <p>The only valid <c>Item</c> for events is:</p> + <taglist> + <tag><c>match_spec</c></tag> + <item> + <p>Returns the match specification for this event, if it + has one, or <c>true</c> if no match specification has been + set.</p> + </item> + </taglist> + <p>The return value is <c>{<anno>Item</anno>, Value}</c>, where + <c>Value</c> is the requested information as described earlier. If a pid for a dead process was given, or the name of a - non-existing function, <c>Value</c> will be <c>undefined</c>.</p> - <p>If <c><anno>PidOrFunc</anno></c> is the <c>on_load</c>, the information - returned refers to the default value for code that will be - loaded.</p> + non-existing function, <c>Value</c> is <c>undefined</c>.</p> </desc> </func> + <func> <name name="trace_pattern" arity="2" clause_i="1"/> + <fsummary>Sets trace patterns for call, send or 'receive' tracing.</fsummary> <type name="trace_pattern_mfa"/> <type name="trace_match_spec"/> - <fsummary>Set trace patterns for global call tracing</fsummary> <desc> <p>The same as - <seealso marker="#trace_pattern/3">erlang:trace_pattern(MFA, MatchSpec, [])</seealso>, + <seealso marker="#trace_pattern/3">erlang:trace_pattern(Event, MatchSpec, [])</seealso>, retained for backward compatibility.</p> </desc> </func> + <func> - <name name="trace_pattern" arity="3"/> + <name name="trace_pattern" arity="3" clause_i="1"/> + <fsummary>Sets trace pattern for message sending.</fsummary> + <type name="trace_match_spec"/> + <desc> + <p>Sets trace pattern for <em>message sending</em>. + Must be combined with + <seealso marker="#trace/3">erlang:trace/3</seealso> + to set the <c>send</c> trace flag for one or more processes. + By default all messages, sent from <c>send</c> traced processes, + are traced. Use <c>erlang:trace_pattern/3</c> to limit + traced send events based on the message content, the sender + and/or the receiver.</p> + <p>Argument <c><anno>MatchSpec</anno></c> can take the + following forms:</p> + <taglist> + <tag><c><anno>MatchSpecList</anno></c></tag> + <item> + <p>A list of match specifications. The matching is done + on the list <c>[Receiver, Msg]</c>. <c>Receiver</c> + is the process or port identity of the receiver and + <c>Msg</c> is the message term. The pid of the sending + process can be accessed with the guard function + <c>self/0</c>. An empty list is the same as <c>true</c>. + See the users guide section + <seealso marker="erts:match_spec">Match Specifications in Erlang</seealso> + for more information.</p> + </item> + <tag><c>true</c></tag> + <item> + <p>Enables tracing for all sent messages (from <c>send</c> + traced processes). Any match specification is + removed. <em>This is the default</em>.</p> + </item> + <tag><c>false</c></tag> + <item> + <p>Disables tracing for all sent messages. + Any match specification is removed.</p> + </item> + </taglist> + <p>Argument <c><anno>FlagList</anno></c> must be <c>[]</c> + for send tracing.</p> + <p>The return value is always <c>1</c>.</p> + <p>Example; only trace messages to a specific process <c>Pid</c>:</p> + <pre> +> <input>erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).</input> +1</pre> + <p>Only trace messages matching <c>{reply, _}</c>:</p> + <pre> +> <input>erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).</input> +1</pre> + <p>Only trace messages sent to the sender itself:</p> + <pre> +> <input>erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).</input> +1</pre> + <p>Only trace messages sent to other nodes:</p> + <pre> +> <input>erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).</input> +1</pre> + <note><p>A match specification for <c>send</c> trace can use + all guard and body functions except <c>caller</c>.</p></note> + </desc> + </func> + + <func> + <name name="trace_pattern" arity="3" clause_i="2"/> + <fsummary>Sets trace pattern for tracing of message receiving.</fsummary> + <type name="trace_match_spec"/> + <desc> + <p></p> + <p>Sets trace pattern for <em>message receiving</em>. + Must be combined with + <seealso marker="#trace/3">erlang:trace/3</seealso> + to set the <c>'receive'</c> trace flag for one or more processes. + By default all messages, received by <c>'receive'</c> traced processes, + are traced. Use <c>erlang:trace_pattern/3</c> to limit + traced receive events based on the message content, the sender + and/or the receiver.</p> + <p>Argument <c><anno>MatchSpec</anno></c> can take the + following forms:</p> + <taglist> + <tag><c><anno>MatchSpecList</anno></c></tag> + <item> + <p>A list of match specifications. The matching is done + on the list <c>[Node, Sender, Msg]</c>. <c>Node</c> + is the node name of the sender. <c>Sender</c> is the + process or port identity of the sender, or the atom + <c>undefined</c> if the sender is not known (which may + be the case for remote senders). <c>Msg</c> is the + message term. The pid of the receiving process can be + accessed with the guard function <c>self/0</c>. An empty + list is the same as <c>true</c>. See the users guide section + <seealso marker="erts:match_spec">Match Specifications in Erlang</seealso> + for more information.</p> + </item> + <tag><c>true</c></tag> + <item> + <p>Enables tracing for all received messages (to <c>'receive'</c> + traced processes). Any match specification is + removed. <em>This is the default</em>.</p> + </item> + <tag><c>false</c></tag> + <item> + <p>Disables tracing for all received messages. + Any match specification is removed.</p> + </item> + </taglist> + <p>Argument <c><anno>FlagList</anno></c> must be <c>[]</c> + for receive tracing.</p> + <p>The return value is always <c>1</c>.</p> + <p>Example; only trace messages from a specific process <c>Pid</c>:</p> + <pre> +> <input>erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).</input> +1</pre> + <p>Only trace messages matching <c>{reply, _}</c>:</p> + <pre> +> <input>erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).</input> +1</pre> + <p>Only trace messages from other nodes:</p> + <pre> +> <input>erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).</input> +1</pre> + <note><p>A match specification for <c>'receive'</c> trace can + use all guard and body functions except <c>caller, + is_seq_trace, get_seq_token, set_seq_token, enable_trace, + disable_trace, trace, silent</c> and <c>process_dump</c>.</p></note> + </desc> + </func> + + <func> + <name name="trace_pattern" arity="3" clause_i="3"/> + <fsummary>Sets trace patterns for tracing of function calls.</fsummary> <type name="trace_pattern_mfa"/> <type name="trace_match_spec"/> <type name="trace_pattern_flag"/> - <fsummary>Set trace patterns for tracing of function calls</fsummary> <desc> - <p>This BIF is used to enable or disable call tracing for - exported functions. It must be combined with + <p>Enables or disables <em>call tracing</em> for one or more functions. + Must be combined with <seealso marker="#trace/3">erlang:trace/3</seealso> - to set the <c>call</c> trace flag for one or more processes.</p> - <p>Conceptually, call tracing works like this: Inside - the Erlang virtual machine there is a set of processes to be - traced and a set of functions to be traced. Tracing will be - enabled on the intersection of the set. That is, if a process - included in the traced process set calls a function included - in the traced function set, the trace action will be taken. - Otherwise, nothing will happen.</p> - <p>Use - <seealso marker="#trace/3">erlang:trace/3</seealso> to - add or remove one or more processes to the set of traced - processes. Use <c>erlang:trace_pattern/2</c> to add or remove - exported functions to the set of traced functions.</p> - <p>The <c>erlang:trace_pattern/3</c> BIF can also add match - specifications to an exported function. A match specification - comprises a pattern that the arguments to the function must - match, a guard expression which must evaluate to <c>true</c> + to set the <c>call</c> trace flag + for one or more processes.</p> + <p>Conceptually, call tracing works as follows. Inside + the Erlang Virtual Machine, a set of processes and + a set of functions are to be traced. If a traced process + calls a traced function, the trace action is taken. + Otherwise, nothing happens.</p> + <p>To add or remove one or more processes to the set of traced + processes, use + <seealso marker="#trace/3">erlang:trace/3</seealso>.</p> + <p>To add or remove functions to the set of traced + functions, use <c>erlang:trace_pattern/3</c>.</p> + <p>The BIF <c>erlang:trace_pattern/3</c> can also add match + specifications to a function. A match specification + comprises a pattern that the function arguments must + match, a guard expression that must evaluate to <c>true</c>, and an action to be performed. The default action is to send a trace message. If the pattern does not match or the guard - fails, the action will not be executed.</p> - <p>The <c><anno>MFA</anno></c> argument should be a tuple like - <c>{Module, Function, Arity}</c> or the atom <c>on_load</c> - (described below). It can be the module, function, and arity - for an exported function (or a BIF in any module). - The <c>'_'</c> atom can be used to mean any of that kind. - Wildcards can be used in any of the following ways:</p> + fails, the action is not executed.</p> + <p>Argument <c><anno>MFA</anno></c> is to be a tuple, such as + <c>{Module, Function, Arity}</c>, or the atom <c>on_load</c> + (described in the following). It can be the module, function, + and arity for a function (or a BIF in any module). + The atom <c>'_'</c> can be used as a wild card in any of the + following ways:</p> <taglist> <tag><c>{Module,Function,'_'}</c></tag> <item> - <p>All exported functions of any arity named <c>Function</c> + <p>All functions of any arity named <c>Function</c> in module <c>Module</c>.</p> </item> <tag><c>{Module,'_','_'}</c></tag> <item> - <p>All exported functions in module <c>Module</c>.</p> + <p>All functions in module <c>Module</c>.</p> </item> <tag><c>{'_','_','_'}</c></tag> <item> - <p>All exported functions in all loaded modules.</p> + <p>All functions in all loaded modules.</p> </item> </taglist> <p>Other combinations, such as <c>{Module,'_',Arity}</c>, are - not allowed. Local functions will match wildcards only if - the <c>local</c> option is in the <c><anno>FlagList</anno></c>.</p> - <p>If the <c><anno>MFA</anno></c> argument is the atom <c>on_load</c>, - the match specification and flag list will be used on all + not allowed. Local functions match wild cards only if + option <c>local</c> is in <c><anno>FlagList</anno></c>.</p> + <p>If argument <c><anno>MFA</anno></c> is the atom <c>on_load</c>, + the match specification and flag list are used on all modules that are newly loaded.</p> - <p>The <c><anno>MatchSpec</anno></c> argument can take any of the following - forms:</p> + <p>Argument <c><anno>MatchSpec</anno></c> can take the + following forms:</p> <taglist> <tag><c>false</c></tag> <item> - <p>Disable tracing for the matching function(s). Any match - specification will be removed.</p> + <p>Disables tracing for the matching functions. + Any match specification is removed.</p> </item> <tag><c>true</c></tag> <item> - <p>Enable tracing for the matching function(s).</p> + <p>Enables tracing for the matching functions. + Any match specification is removed.</p> </item> <tag><c><anno>MatchSpecList</anno></c></tag> <item> <p>A list of match specifications. An empty list is - equivalent to <c>true</c>. See the ERTS User's Guide - for a description of match specifications.</p> + equivalent to <c>true</c>. For a description of match + specifications, see the User's Guide.</p> </item> <tag><c>restart</c></tag> <item> - <p>For the <c><anno>FlagList</anno></c> option <c>call_count</c> and <c>call_time</c>: - restart the existing counters. The behaviour is undefined + <p>For the <c><anno>FlagList</anno></c> options <c>call_count</c> + and <c>call_time</c>: restarts + the existing counters. The behavior is undefined for other <c><anno>FlagList</anno></c> options.</p> </item> <tag><c>pause</c></tag> <item> - <p>For the <c><anno>FlagList</anno></c> option <c>call_count</c> and <c>call_time</c>: pause - the existing counters. The behaviour is undefined for - other <c>FlagList</c> options.</p> + <p>For the <c><anno>FlagList</anno></c> options + <c>call_count</c> and <c>call_time</c>: pauses + the existing counters. The behavior is undefined for + other <c><anno>FlagList</anno></c> options.</p> </item> </taglist> - <p>The <c><anno>FlagList</anno></c> parameter is a list of options. - The following options are allowed:</p> + <p>Parameter <c><anno>FlagList</anno></c> is a list of options. + The following are the valid options:</p> <taglist> <tag><c>global</c></tag> <item> - <p>Turn on or off call tracing for global function calls + <p>Turns on or off call tracing for global function calls (that is, calls specifying the module explicitly). Only - exported functions will match and only global calls will - generate trace messages. This is the default.</p> + exported functions match and only global calls + generate trace messages. <em>This is the default</em>.</p> </item> <tag><c>local</c></tag> <item> - <p>Turn on or off call tracing for all types of function - calls. Trace messages will be sent whenever any of + <p>Turns on or off call tracing for all types of function + calls. Trace messages are sent whenever any of the specified functions are called, regardless of how they - are called. If the <c>return_to</c> flag is set for - the process, a <c>return_to</c> message will also be sent + are called. If flag <c>return_to</c> is set for + the process, a <c>return_to</c> message is also sent when this function returns to its caller.</p> </item> - <tag><c>meta | {meta, <anno>Pid</anno>}</c></tag> + <tag><c>meta | {meta, <anno>Pid</anno>} | {meta, <anno>TracerModule</anno>, <anno>TracerState</anno>}</c> + </tag> <item> - <p>Turn on or off meta tracing for all types of function - calls. Trace messages will be sent to the tracer process - or port <c><anno>Pid</anno></c> whenever any of the specified - functions are called, regardless of how they are called. - If no <c><anno>Pid</anno></c> is specified, <c>self()</c> is used as a - default tracer process.</p> - <p>Meta tracing traces all processes and does not care + <p>Turns on or off meta-tracing for all types of function + calls. Trace messages are sent to the tracer whenever any of + the specified functions are called. If no tracer is specified, + <c>self()</c> is used as a default tracer process.</p> + <p>Meta-tracing traces all processes and does not care about the process trace flags set by <c>trace/3</c>, the trace flags are instead fixed to <c>[call, timestamp]</c>.</p> - <p>The match spec function <c>{return_trace}</c> works with - meta trace and send its trace message to the same tracer - process.</p> + <p>The match specification function <c>{return_trace}</c> + works with meta-trace and sends its trace message to the + same tracer.</p> </item> <tag><c>call_count</c></tag> <item> <p>Starts (<c><anno>MatchSpec</anno> == true</c>) or stops - (<c><anno>MatchSpec</anno> == false</c>) call count tracing for all - types of function calls. For every function a counter is + (<c><anno>MatchSpec</anno> == false</c>) + call count tracing for all + types of function calls. For every function, a counter is incremented when the function is called, in any process. No process trace flags need to be activated.</p> <p>If call count tracing is started while already running, - the count is restarted from zero. Running counters can be - paused with <c><anno>MatchSpec</anno> == pause</c>. Paused and running - counters can be restarted from zero with + the count is restarted from zero. To pause running + counters, use <c><anno>MatchSpec</anno> == pause</c>. + Paused and running counters can be restarted from zero with <c><anno>MatchSpec</anno> == restart</c>.</p> - <p>The counter value can be read with + <p>To read the counter value, use <seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p> </item> <tag><c>call_time</c></tag> <item> <p>Starts (<c><anno>MatchSpec</anno> == true</c>) or stops - (<c><anno>MatchSpec</anno> == false</c>) call time tracing for all - types of function calls. For every function a counter is - incremented when the function is called. Time spent in the function - is accumulated in two other counters, seconds and micro-seconds. + (<c><anno>MatchSpec</anno> == false</c>) call time + tracing for all + types of function calls. For every function, a counter is + incremented when the function is called. + Time spent in the function is accumulated in + two other counters, seconds and microseconds. The counters are stored for each call traced process.</p> <p>If call time tracing is started while already running, - the count and time is restarted from zero. Running counters can be - paused with <c><anno>MatchSpec</anno> == pause</c>. Paused and running - counters can be restarted from zero with + the count and time is restarted from zero. To pause + running counters, use <c><anno>MatchSpec</anno> == pause</c>. + Paused and running counters can be restarted from zero with <c><anno>MatchSpec</anno> == restart</c>.</p> - <p>The counter value can be read with + <p>To read the counter value, use <seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p> </item> - </taglist> - <p>The <c>global</c> and <c>local</c> options are mutually - exclusive and <c>global</c> is the default (if no options are - specified). The <c>call_count</c> and <c>meta</c> options - perform a kind of local tracing, and can also not be combined - with <c>global</c>. A function can be either globally or + <p>The options <c>global</c> and <c>local</c> are mutually + exclusive, and <c>global</c> is the default (if no options are + specified). The options <c>call_count</c> and <c>meta</c> + perform a kind of local tracing, and cannot be combined + with <c>global</c>. A function can be globally or locally traced. If global tracing is specified for a - specified set of functions; local, meta, call time and call count - tracing for the matching set of local functions will be - disabled, and vice versa.</p> + set of functions, then local, meta, call time, and call count + tracing for the matching set of local functions is + disabled, and conversely.</p> <p>When disabling trace, the option must match the type of trace - that is set on the function, so that local tracing must be - disabled with the <c>local</c> option and global tracing with - the <c>global</c> option (or no option at all), and so forth.</p> - <p>There is no way to directly change part of a match - specification list. If a function has a match specification, - you can replace it with a completely new one. If you need to - change an existing match specification, use the + set on the function. That is, local tracing must be + disabled with option <c>local</c> and global tracing with + option <c>global</c> (or no option), and so forth.</p> + <p>Part of a match specification list cannot be changed directly. + If a function has a match specification, it can be replaced + with a new one. To change an existing match specification, + use the BIF <seealso marker="#trace_info/2">erlang:trace_info/2</seealso> - BIF to retrieve the existing match specification.</p> - <p>Returns the number of exported functions that matched - the <c><anno>MFA</anno></c> argument. This will be zero if none matched at - all.</p> + to retrieve the existing match specification.</p> + <p>Returns the number of functions matching + argument <c><anno>MFA</anno></c>. This is zero if none matched.</p> </desc> </func> + <func> <name name="trunc" arity="1"/> - <fsummary>Return an integer by the truncating a number</fsummary> + <fsummary>Returns an integer by truncating a number</fsummary> <desc> - <p>Returns an integer by the truncating <c><anno>Number</anno></c>.</p> + <p>Returns an integer by truncating <c><anno>Number</anno></c>, + for example:</p> <pre> > <input>trunc(5.5).</input> 5</pre> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="tuple_size" arity="1"/> - <fsummary>Return the size of a tuple</fsummary> + <fsummary>Returns the size of a tuple.</fsummary> <desc> - <p>Returns an integer which is the number of elements in <c><anno>Tuple</anno></c>.</p> + <p>Returns an integer that is the number of elements in + <c><anno>Tuple</anno></c>, for example:</p> <pre> > <input>tuple_size({morni, mulle, bwange}).</input> 3</pre> <p>Allowed in guard tests.</p> </desc> </func> + <func> <name name="tuple_to_list" arity="1"/> - <fsummary>Convert a tuple to a list</fsummary> + <fsummary>Converts a tuple to a list.</fsummary> <desc> - <p>Returns a list which corresponds to <c><anno>Tuple</anno></c>. - <c><anno>Tuple</anno></c> may contain any Erlang terms.</p> + <p>Returns a list corresponding to <c><anno>Tuple</anno></c>. + <c><anno>Tuple</anno></c> can contain any Erlang terms.</p> + <p>Example:</p> <pre> > <input>tuple_to_list({share, {'Ericsson_B', 163}}).</input> [share,{'Ericsson_B',163}]</pre> </desc> </func> + <func> <name name="universaltime" arity="0"/> - <fsummary>Current date and time according to Universal Time Coordinated (UTC)</fsummary> + <fsummary>Current date and time according to Universal Time Coordinated (UTC).</fsummary> <desc> <p>Returns the current date and time according to Universal - Time Coordinated (UTC), also called GMT, in the form + Time Coordinated (UTC) in the form <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c> if - supported by the underlying operating system. If not, - <c>erlang:universaltime()</c> is equivalent to + supported by the underlying OS. + Otherwise <c>erlang:universaltime()</c> is equivalent to <c>erlang:localtime()</c>.</p> + <p>Example:</p> <pre> > <input>erlang:universaltime().</input> {{1996,11,6},{14,18,43}}</pre> </desc> </func> + <func> <name name="universaltime_to_localtime" arity="1"/> - <fsummary>Convert from Universal Time Coordinated (UTC) to local date and time</fsummary> + <fsummary>Converts from Universal Time Coordinated (UTC) to local date and time.</fsummary> <desc> <p>Converts Universal Time Coordinated (UTC) date and time to - local date and time, if this is supported by the underlying - OS. Otherwise, no conversion is done, and + local date and time in the form + <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c> if + supported by the underlying OS. + Otherwise no conversion is done, and <c><anno>Universaltime</anno></c> is returned.</p> + <p>Example:</p> <pre> > <input>erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).</input> {{1996,11,7},{15,18,43}}</pre> - <p>Failure: <c>badarg</c> if <c>Universaltime</c> does not denote - a valid date and time.</p> + <p>Failure: <c>badarg</c> if <c>Universaltime</c> denotes + an invalid date and time.</p> + </desc> + </func> + + <func> + <name name="unique_integer" arity="0"/> + <fsummary>Get a unique integer value</fsummary> + <desc> + <p>Generates and returns an + <seealso marker="doc/efficiency_guide:advanced#unique_integers">integer + unique on current runtime system instance</seealso>. The same as calling + <seealso marker="#unique_integer/1"><c>erlang:unique_integer([])</c></seealso>.</p> + </desc> + </func> + <func> + <name name="unique_integer" arity="1"/> + <fsummary>Get a unique integer value</fsummary> + <desc> + <p>Generates and returns an + <seealso marker="doc/efficiency_guide:advanced#unique_integers">integer + unique on current runtime system + instance</seealso>. The integer is unique in the + sense that this BIF, using the same set of + modifiers, will not return the same integer more + than once on the current runtime system instance. + Each integer value can of course be constructed + by other means.</p> + + <p>By default, when <c>[]</c> is passed as + <c><anno>ModifierList</anno></c>, both negative and + positive integers can be returned. This in order + to utilize the range of integers that do + not need heap memory allocation as much as possible. + By default the returned integers are also only + guaranteed to be unique, that is, any returned integer + can be smaller or larger than previously + returned integers.</p> + + <p>Valid <c><anno>Modifier</anno></c>s:</p> + <taglist> + + <tag>positive</tag> + <item><p>Return only positive integers.</p> + <p>Note that by passing the <c>positive</c> modifier + you will get heap allocated integers (bignums) + quicker.</p> + </item> + + <tag>monotonic</tag> + <item><p>Return + <seealso marker="time_correction#Strictly_Monotonically_Increasing">strictly + monotonically increasing</seealso> integers + corresponding to creation time. That is, the integer + returned will always be larger than previously + returned integers on the current runtime system + instance.</p> + <p>These values can be used to determine order between events + on the runtime system instance. That is, if both + <c>X = erlang:unique_integer([monotonic])</c> and + <c>Y = erlang:unique_integer([monotonic])</c> are + executed by different processes (or the same + process) on the same runtime system instance and + <c>X < Y</c> we know that <c>X</c> was created + before <c>Y</c>.</p> + <warning><p>Strictly monotonically increasing values + are inherently quite expensive to generate and scales + poorly. This is because the values need to be + synchronized between cpu cores. That is, do not pass the <c>monotonic</c> + modifier unless you really need strictly monotonically + increasing values.</p></warning> + </item> + + </taglist> + + <p>All valid <c><anno>Modifier</anno></c>s + can be combined. Repeated (valid) + <c><anno>Modifier</anno></c>s in the <c>ModifierList</c> + are ignored.</p> + + <note><p>Note that the set of integers returned by + <c>unique_integer/1</c> using different sets of + <c><anno>Modifier</anno></c>s <em>will overlap</em>. + For example, by calling <c>unique_integer([monotonic])</c>, + and <c>unique_integer([positive, monotonic])</c> + repeatedly, you will eventually see some integers being + returned by both calls.</p></note> + + <p>Failures:</p> + <taglist> + <tag><c>badarg</c></tag> + <item>if <c><anno>ModifierList</anno></c> is not a + proper list.</item> + <tag><c>badarg</c></tag> + <item>if <c><anno>Modifier</anno></c> is not a + valid modifier.</item> + </taglist> </desc> </func> <func> <name name="unlink" arity="1"/> - <fsummary>Remove a link, if there is one, to another process or port</fsummary> + <fsummary>Removes a link to another process or port.</fsummary> <desc> <p>Removes the link, if there is one, between the calling - process and the process or port referred to by <c><anno>Id</anno></c>.</p> + process and the process or port referred to by + <c><anno>Id</anno></c>.</p> <p>Returns <c>true</c> and does not fail, even if there is no - link to <c><anno>Id</anno></c>, or if <c><anno>Id</anno></c> does not exist.</p> - <p>Once <c>unlink(<anno>Id</anno>)</c> has returned it is guaranteed that + link to <c><anno>Id</anno></c>, or if <c><anno>Id</anno></c> + does not exist.</p> + <p>Once <c>unlink(<anno>Id</anno>)</c> has returned, + it is guaranteed that the link between the caller and the entity referred to by - <c><anno>Id</anno></c> has no effect on the caller in the future (unless - the link is setup again). If caller is trapping exits, an - <c>{'EXIT', <anno>Id</anno>, _}</c> message due to the link might have - been placed in the caller's message queue prior to the call, - though. Note, the <c>{'EXIT', <anno>Id</anno>, _}</c> message can be the - result of the link, but can also be the result of <c><anno>Id</anno></c> - calling <c>exit/2</c>. Therefore, it <em>may</em> be - appropriate to cleanup the message queue when trapping exits - after the call to <c>unlink(<anno>Id</anno>)</c>, as follow:</p> + <c><anno>Id</anno></c> has no effect on the caller + in the future (unless + the link is setup again). If the caller is trapping exits, an + <c>{'EXIT', <anno>Id</anno>, _}</c> message from the link + can have been placed in the caller's message queue before + the call.</p> + <p>Notice that the <c>{'EXIT', <anno>Id</anno>, _}</c> + message can be the + result of the link, but can also be the result of <c>Id</c> + calling <c>exit/2</c>. Therefore, it <em>can</em> be + appropriate to clean up the message queue when trapping exits + after the call to <c>unlink(<anno>Id</anno>)</c>, as follows:</p> <code type="none"> - unlink(Id), receive {'EXIT', Id, _} -> @@ -7080,23 +9868,25 @@ ok true end</code> <note> - <p>Prior to OTP release R11B (erts version 5.5) <c>unlink/1</c> - behaved completely asynchronous, i.e., the link was active + <p>Prior to OTP release R11B (ERTS version 5.5) <c>unlink/1</c> + behaved completely asynchronously, i.e., the link was active until the "unlink signal" reached the linked entity. This - had one undesirable effect, though. You could never know when + had an undesirable effect, as you could never know when you were guaranteed <em>not</em> to be effected by the link.</p> - <p>Current behavior can be viewed as two combined operations: + <p>The current behavior can be viewed as two combined operations: asynchronously send an "unlink signal" to the linked entity and ignore any future results of the link.</p> </note> </desc> </func> + <func> <name name="unregister" arity="1"/> - <fsummary>Remove the registered name for a process (or port)</fsummary> + <fsummary>Removes the registered name for a process (or port).</fsummary> <desc> - <p>Removes the registered name <c><anno>RegName</anno></c>, associated with a - pid or a port identifier.</p> + <p>Removes the registered name <c><anno>RegName</anno></c> + associated with a + process identifier or a port identifier, for example:</p> <pre> > <input>unregister(db).</input> true</pre> @@ -7105,31 +9895,34 @@ true</pre> name.</p> </desc> </func> + <func> <name name="whereis" arity="1"/> - <fsummary>Get the pid (or port) with a given registered name</fsummary> + <fsummary>Gets the pid (or port) with a given registered name.</fsummary> <desc> - <p>Returns the pid or port identifier with the registered name - <c>RegName</c>. Returns <c>undefined</c> if the name is not - registered.</p> + <p>Returns the process identifier or port identifier with + the registered name <c>RegName</c>. Returns <c>undefined</c> + if the name is not registered.</p> + <p>Example:</p> <pre> > <input>whereis(db).</input> <0.43.0></pre> </desc> </func> + <func> <name name="yield" arity="0"/> - <fsummary>Let other processes get a chance to execute</fsummary> + <fsummary>Lets other processes get a chance to execute.</fsummary> <desc> - <p>Voluntarily let other processes (if any) get a chance to + <p>Voluntarily lets other processes (if any) get a chance to execute. Using <c>erlang:yield()</c> is similar to <c>receive after 1 -> ok end</c>, except that <c>yield()</c> is faster.</p> <warning><p>There is seldom or never any need to use this BIF, - especially in the SMP-emulator as other processes will have a - chance to run in another scheduler thread anyway. - Using this BIF without a thorough grasp of how the scheduler - works may cause performance degradation.</p></warning> + especially in the SMP emulator, as other processes have a + chance to run in another scheduler thread anyway. + Using this BIF without a thorough grasp of how the scheduler + works can cause performance degradation.</p></warning> </desc> </func> </funcs> diff --git a/erts/doc/src/erlc.xml b/erts/doc/src/erlc.xml index 81dffe45cf..a64927fec2 100644 --- a/erts/doc/src/erlc.xml +++ b/erts/doc/src/erlc.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1997</year><year>2012</year> + <year>1997</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -234,6 +235,16 @@ erlc +export_all file.erl</pre> from the shell.</p> <p>Supported options: -I, -o, -D, -v, -W, -b.</p> </item> + <tag>.S</tag> + <item> + <p>Erlang assembler source code. It generates a <c><![CDATA[.beam]]></c> file.</p> + <p>Supported options: same as for .erl.</p> + </item> + <tag>.core</tag> + <item> + <p>Erlang core source code. It generates a <c><![CDATA[.beam]]></c> file.</p> + <p>Supported options: same as for .erl.</p> + </item> <tag>.yrl</tag> <item> <p>Yecc source code. It generates an <c><![CDATA[.erl]]></c> file.</p> diff --git a/erts/doc/src/erlsrv.xml b/erts/doc/src/erlsrv.xml index 365ae21d39..fb00444aa4 100644 --- a/erts/doc/src/erlsrv.xml +++ b/erts/doc/src/erlsrv.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1998</year><year>2012</year> + <year>1998</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml index 2ffb55c6ab..9aef1c0b1f 100644 --- a/erts/doc/src/erts_alloc.xml +++ b/erts/doc/src/erts_alloc.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE cref SYSTEM "cref.dtd"> <cref> <header> <copyright> - <year>2002</year><year>2013</year> + <year>2002</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -51,6 +52,8 @@ <item>Allocator used for ETS data.</item> <tag><c>driver_alloc</c></tag> <item>Allocator used for driver data.</item> + <tag><c>literal_alloc</c></tag> + <item>Allocator used for constant terms in Erlang code.</item> <tag><c>sl_alloc</c></tag> <item>Allocator used for memory blocks that are expected to be short-lived.</item> @@ -60,6 +63,9 @@ <tag><c>fix_alloc</c></tag> <item>A fast allocator used for some frequently used fixed size data types.</item> + <tag><c>exec_alloc</c></tag> + <item>Allocator used by hipe for native executable code + on specific architectures (x86_64).</item> <tag><c>std_alloc</c></tag> <item>Allocator used for most memory blocks not allocated via any of the other allocators described above.</item> @@ -76,8 +82,9 @@ instead of creating new segments. This in order to reduce the number of system calls made.</item> </taglist> - <p><c>sys_alloc</c> is always enabled and - cannot be disabled. <c>mseg_alloc</c> is always enabled if it is + <p><c>sys_alloc</c> and <c>literal_alloc</c> are always enabled and + cannot be disabled. <c>exec_alloc</c> is only available if it is needed + and cannot be disabled. <c>mseg_alloc</c> is always enabled if it is available and an allocator that uses it is enabled. All other allocators can be <seealso marker="#M_e">enabled or disabled</seealso>. By default all allocators are enabled. @@ -170,6 +177,15 @@ used. The time complexity is proportional to log N, where N is the number of free blocks.</p> </item> + <tag>Address order first fit carrier best fit</tag> + <item> + <p>Strategy: Find the <em>carrier</em> with the lowest address that + can satisfy the requested block size, then find a block within + that carrier using the "best fit" strategy.</p> + <p>Implementation: Balanced binary search trees are + used. The time complexity is proportional to log N, where + N is the number of free blocks.</p> + </item> <tag>Address order first fit carrier address order best fit</tag> <item> <p>Strategy: Find the <em>carrier</em> with the lowest address that @@ -240,29 +256,102 @@ <item><c>E: ets_alloc</c></item> <item><c>F: fix_alloc</c></item> <item><c>H: eheap_alloc</c></item> + <item><c>I: literal_alloc</c></item> <item><c>L: ll_alloc</c></item> <item><c>M: mseg_alloc</c></item> <item><c>R: driver_alloc</c></item> <item><c>S: sl_alloc</c></item> <item><c>T: temp_alloc</c></item> + <item><c>X: exec_alloc</c></item> <item><c>Y: sys_alloc</c></item> </list> <p>The following flags are available for configuration of <c>mseg_alloc</c>:</p> <taglist> - <tag><marker id="MMamcbf"><c><![CDATA[+MMamcbf <size>]]></c></marker></tag> + <tag><marker id="MMamcbf"/><c><![CDATA[+MMamcbf <size>]]></c></tag> <item> Absolute max cache bad fit (in kilobytes). A segment in the memory segment cache is not reused if its size exceeds the requested size with more than the value of this parameter. Default value is 4096. </item> - <tag><marker id="MMrmcbf"><c><![CDATA[+MMrmcbf <ratio>]]></c></marker></tag> + <tag><marker id="MMrmcbf"/><c><![CDATA[+MMrmcbf <ratio>]]></c></tag> <item> Relative max cache bad fit (in percent). A segment in the memory segment cache is not reused if its size exceeds the requested size with more than relative max cache bad fit percent of the requested size. Default value is 20.</item> - <tag><marker id="MMmcs"><c><![CDATA[+MMmcs <amount>]]></c></marker></tag> + <tag><marker id="MMsco"/><c><![CDATA[+MMsco true|false]]></c></tag> + <item> + Set <seealso marker="#MMscs">super carrier</seealso> only flag. This + flag defaults to <c>true</c>. When a super carrier is used and this + flag is <c>true</c>, <c>mseg_alloc</c> will only create carriers + in the super carrier. Note that the <c>alloc_util</c> framework may + create <c>sys_alloc</c> carriers, so if you want all carriers to + be created in the super carrier, you therefore want to disable use + of <c>sys_alloc</c> carriers by also passing + <seealso marker="#Musac"><c>+Musac false</c></seealso>. When the flag + is <c>false</c>, <c>mseg_alloc</c> will try to create carriers outside + of the super carrier when the super carrier is full. + <br/><br/> + <em>NOTE</em>: Setting this flag to <c>false</c> may not be supported + on all systems. This flag will in that case be ignored. + <br/><br/> + <em>NOTE</em>: The super carrier cannot be enabled nor + disabled on halfword heap systems. This flag will be + ignored on halfword heap systems. + </item> + <tag><marker id="MMscrfsd"/><c><![CDATA[+MMscrfsd <amount>]]></c></tag> + <item> + Set <seealso marker="#MMscs">super carrier</seealso> reserved + free segment descriptors. This parameter defaults to <c>65536</c>. + This parameter determines the amount of memory to reserve for + free segment descriptors used by the super carrier. If the system + runs out of reserved memory for free segment descriptors, other + memory will be used. This may however cause fragmentation issues, + so you want to ensure that this never happens. The maximum amount + of free segment descriptors used can be retrieved from the + <c>erts_mmap</c> tuple part of the result from calling + <seealso marker="erts:erlang#system_info_allocator_tuple">erlang:system_info({allocator, mseg_alloc})</seealso>. + </item> + <tag><marker id="MMscrpm"/><c><![CDATA[+MMscrpm true|false]]></c></tag> + <item> + Set <seealso marker="#MMscs">super carrier</seealso> reserve physical + memory flag. This flag defaults to <c>true</c>. When this flag is + <c>true</c>, physical memory will be reserved for the whole super + carrier at once when it is created. The reservation will after that + be left unchanged. When this flag is set to <c>false</c> only virtual + address space will be reserved for the super carrier upon creation. + The system will attempt to reserve physical memory upon carrier + creations in the super carrier, and attempt to unreserve physical + memory upon carrier destructions in the super carrier. + <br/><br/> + <em>NOTE</em>: What reservation of physical memory actually means + highly depends on the operating system, and how it is configured. For + example, different memory overcommit settings on Linux drastically + change the behaviour. Also note, setting this flag to <c>false</c> + may not be supported on all systems. This flag will in that case + be ignored. + <br/><br/> + <em>NOTE</em>: The super carrier cannot be enabled nor + disabled on halfword heap systems. This flag will be + ignored on halfword heap systems. + </item> + <tag><marker id="MMscs"/><c><![CDATA[+MMscs <size in MB>]]></c></tag> + <item> + Set super carrier size (in MB). The super carrier size defaults to + zero; i.e, the super carrier is by default disabled. The super + carrier is a large continuous area in the virtual address space. + <c>mseg_alloc</c> will always try to create new carriers in the super + carrier if it exists. Note that the <c>alloc_util</c> framework may + create <c>sys_alloc</c> carriers. For more information on this, see the + documentation of the <seealso marker="#MMsco"><c>+MMsco</c></seealso> + flag. + <br/><br/> + <em>NOTE</em>: The super carrier cannot be enabled nor + disabled on halfword heap systems. This flag will be + ignored on halfword heap systems. + </item> + <tag><marker id="MMmcs"/><c><![CDATA[+MMmcs <amount>]]></c></tag> <item> Max cached segments. The maximum number of memory segments stored in the memory segment cache. Valid range is @@ -271,15 +360,15 @@ <p>The following flags are available for configuration of <c>sys_alloc</c>:</p> <taglist> - <tag><marker id="MYe"><c>+MYe true</c></marker></tag> + <tag><marker id="MYe"/><c>+MYe true</c></tag> <item> Enable <c>sys_alloc</c>. Note: <c>sys_alloc</c> cannot be disabled.</item> - <tag><marker id="MYm"><c>+MYm libc</c></marker></tag> + <tag><marker id="MYm"/><c>+MYm libc</c></tag> <item> <c>malloc</c> library to use. Currently only <c>libc</c> is available. <c>libc</c> enables the standard <c>libc</c> malloc implementation. By default <c>libc</c> is used.</item> - <tag><marker id="MYtt"><c><![CDATA[+MYtt <size>]]></c></marker></tag> + <tag><marker id="MYtt"/><c><![CDATA[+MYtt <size>]]></c></tag> <item> Trim threshold size (in kilobytes). This is the maximum amount of free memory at the top of the heap (allocated by @@ -291,7 +380,7 @@ trim threshold is 128. <em>Note:</em> This flag will only have any effect when the emulator has been linked with the GNU C library, and uses its <c>malloc</c> implementation.</item> - <tag><marker id="MYtp"><c><![CDATA[+MYtp <size>]]></c></marker></tag> + <tag><marker id="MYtp"/><c><![CDATA[+MYtp <size>]]></c></tag> <item> Top pad size (in kilobytes). This is the amount of extra memory that will be allocated by <c>malloc</c> when @@ -309,45 +398,47 @@ subsystem identifier, only the specific allocator identified will be effected:</p> <taglist> - <tag><marker id="M_acul"><c><![CDATA[+M<S>acul <utilization>|de]]></c></marker></tag> + <tag><marker id="M_acul"/><c><![CDATA[+M<S>acul <utilization>|de]]></c></tag> <item> Abandon carrier utilization limit. A valid <c><![CDATA[<utilization>]]></c> is an integer in the range <c>[0, 100]</c> representing utilization in percent. When a utilization value larger than zero is used, allocator instances - are allowed to abandon multiblock carriers. Currently the default - is zero. If <c>de</c> (default enabled) is passed instead of a - <c><![CDATA[<utilization>]]></c>, a recomended non zero utilization - value will be used. The actual value chosen depend on allocator - type and may be changed between ERTS versions. Carriers will be - abandoned when memory utilization in the allocator instance falls - below the utilization value used. Once a carrier has been abandoned, - no new allocations will be made in it. When an allocator instance - gets an increased multiblock carrier need, it will first try to - fetch an abandoned carrier from an allocator instances of the same + are allowed to abandon multiblock carriers. If <c>de</c> (default + enabled) is passed instead of a <c><![CDATA[<utilization>]]></c>, + a recomended non zero utilization value will be used. The actual + value chosen depend on allocator type and may be changed between + ERTS versions. Currently the default equals <c>de</c>, but this + may be changed in the future. Carriers will be abandoned when + memory utilization in the allocator instance falls below the + utilization value used. Once a carrier has been abandoned, no new + allocations will be made in it. When an allocator instance gets an + increased multiblock carrier need, it will first try to fetch an + abandoned carrier from an allocator instances of the same allocator type. If no abandoned carrier could be fetched, it will create a new empty carrier. When an abandoned carrier has been fetched it will function as an ordinary carrier. This feature has special requirements on the <seealso marker="#M_as">allocation strategy</seealso> used. Currently - only the <c>aoff</c> and the <c>aoffcaobf</c> strategies support + only the strategies <c>aoff</c>, <c>aoffcbf</c> and <c>aoffcaobf</c> support abandoned carriers. This feature also requires <seealso marker="#M_t">multiple thread specific instances</seealso> to be enabled. When enabling this feature, multiple thread specific instances will be enabled if not already enabled, and the - <c>aoffcaobf</c> strategy will be enabled if current strategy does not + <c>aoffcbf</c> strategy will be enabled if current strategy does not support abandoned carriers. This feature can be enabled on all allocators based on the <c>alloc_util</c> framework with the exception of <c>temp_alloc</c> (which would be pointless). </item> - <tag><marker id="M_as"><c><![CDATA[+M<S>as bf|aobf|aoff|aoffcaobf|gf|af]]></c></marker></tag> + <tag><marker id="M_as"/><c><![CDATA[+M<S>as bf|aobf|aoff|aoffcbf|aoffcaobf|gf|af]]></c></tag> <item> Allocation strategy. Valid strategies are <c>bf</c> (best fit), <c>aobf</c> (address order best fit), <c>aoff</c> (address order first fit), + <c>aoffcbf</c> (address order first fit carrier best fit), <c>aoffcaobf</c> (address order first fit carrier address order best fit), <c>gf</c> (good fit), and <c>af</c> (a fit). See <seealso marker="#strategy">the description of allocation strategies</seealso> in "the <c>alloc_util</c> framework" section.</item> - <tag><marker id="M_asbcst"><c><![CDATA[+M<S>asbcst <size>]]></c></marker></tag> + <tag><marker id="M_asbcst"/><c><![CDATA[+M<S>asbcst <size>]]></c></tag> <item> Absolute singleblock carrier shrink threshold (in kilobytes). When a block located in an @@ -355,23 +446,23 @@ will be left unchanged if the amount of unused memory is less than this threshold; otherwise, the carrier will be shrunk. See also <seealso marker="#M_rsbcst">rsbcst</seealso>.</item> - <tag><marker id="M_e"><c><![CDATA[+M<S>e true|false]]></c></marker></tag> + <tag><marker id="M_e"/><c><![CDATA[+M<S>e true|false]]></c></tag> <item> Enable allocator <c><![CDATA[<S>]]></c>.</item> - <tag><marker id="M_lmbcs"><c><![CDATA[+M<S>lmbcs <size>]]></c></marker></tag> + <tag><marker id="M_lmbcs"/><c><![CDATA[+M<S>lmbcs <size>]]></c></tag> <item> Largest (<c>mseg_alloc</c>) multiblock carrier size (in kilobytes). See <seealso marker="#mseg_mbc_sizes">the description on how sizes for mseg_alloc multiblock carriers are decided</seealso> in "the <c>alloc_util</c> framework" section. On 32-bit Unix style OS this limit can not be set higher than 128 megabyte.</item> - <tag><marker id="M_mbcgs"><c><![CDATA[+M<S>mbcgs <ratio>]]></c></marker></tag> + <tag><marker id="M_mbcgs"/><c><![CDATA[+M<S>mbcgs <ratio>]]></c></tag> <item> (<c>mseg_alloc</c>) multiblock carrier growth stages. See <seealso marker="#mseg_mbc_sizes">the description on how sizes for mseg_alloc multiblock carriers are decided</seealso> in "the <c>alloc_util</c> framework" section.</item> - <tag><marker id="M_mbsd"><c><![CDATA[+M<S>mbsd <depth>]]></c></marker></tag> + <tag><marker id="M_mbsd"/><c><![CDATA[+M<S>mbsd <depth>]]></c></tag> <item> Max block search depth. This flag has effect only if the good fit strategy has been selected for allocator @@ -381,40 +472,40 @@ search depth sets a limit on the maximum number of blocks to inspect in a free list during a search for suitable block satisfying the request.</item> - <tag><marker id="M_mmbcs"><c><![CDATA[+M<S>mmbcs <size>]]></c></marker></tag> + <tag><marker id="M_mmbcs"/><c><![CDATA[+M<S>mmbcs <size>]]></c></tag> <item> Main multiblock carrier size. Sets the size of the main multiblock carrier for allocator <c><![CDATA[<S>]]></c>. The main multiblock carrier is allocated via <c><![CDATA[sys_alloc]]></c> and is never deallocated.</item> - <tag><marker id="M_mmmbc"><c><![CDATA[+M<S>mmmbc <amount>]]></c></marker></tag> + <tag><marker id="M_mmmbc"/><c><![CDATA[+M<S>mmmbc <amount>]]></c></tag> <item> Max <c>mseg_alloc</c> multiblock carriers. Maximum number of multiblock carriers allocated via <c>mseg_alloc</c> by allocator <c><![CDATA[<S>]]></c>. When this limit has been reached, new multiblock carriers will be allocated via <c>sys_alloc</c>.</item> - <tag><marker id="M_mmsbc"><c><![CDATA[+M<S>mmsbc <amount>]]></c></marker></tag> + <tag><marker id="M_mmsbc"/><c><![CDATA[+M<S>mmsbc <amount>]]></c></tag> <item> Max <c>mseg_alloc</c> singleblock carriers. Maximum number of singleblock carriers allocated via <c>mseg_alloc</c> by allocator <c><![CDATA[<S>]]></c>. When this limit has been reached, new singleblock carriers will be allocated via <c>sys_alloc</c>.</item> - <tag><marker id="M_ramv"><c><![CDATA[+M<S>ramv <bool>]]></c></marker></tag> + <tag><marker id="M_ramv"/><c><![CDATA[+M<S>ramv <bool>]]></c></tag> <item> Realloc always moves. When enabled, reallocate operations will more or less be translated into an allocate, copy, free sequence. This often reduce memory fragmentation, but costs performance. </item> - <tag><marker id="M_rmbcmt"><c><![CDATA[+M<S>rmbcmt <ratio>]]></c></marker></tag> + <tag><marker id="M_rmbcmt"/><c><![CDATA[+M<S>rmbcmt <ratio>]]></c></tag> <item> Relative multiblock carrier move threshold (in percent). When a block located in a multiblock carrier is shrunk, the block will be moved if the ratio of the size of the returned memory compared to the previous size is more than this threshold; otherwise, the block will be shrunk at current location.</item> - <tag><marker id="M_rsbcmt"><c><![CDATA[+M<S>rsbcmt <ratio>]]></c></marker></tag> + <tag><marker id="M_rsbcmt"/><c><![CDATA[+M<S>rsbcmt <ratio>]]></c></tag> <item> Relative singleblock carrier move threshold (in percent). When a block located in a singleblock carrier is shrunk to @@ -423,7 +514,7 @@ the block will be left unchanged in the singleblock carrier if the ratio of unused memory is less than this threshold; otherwise, it will be moved into a multiblock carrier. </item> - <tag><marker id="M_rsbcst"><c><![CDATA[+M<S>rsbcst <ratio>]]></c></marker></tag> + <tag><marker id="M_rsbcst"/><c><![CDATA[+M<S>rsbcst <ratio>]]></c></tag> <item> Relative singleblock carrier shrink threshold (in percent). When a block located in an <c>mseg_alloc</c> @@ -431,33 +522,27 @@ unchanged if the ratio of unused memory is less than this threshold; otherwise, the carrier will be shrunk. See also <seealso marker="#M_asbcst">asbcst</seealso>.</item> - <tag><marker id="M_sbct"><c><![CDATA[+M<S>sbct <size>]]></c></marker></tag> + <tag><marker id="M_sbct"/><c><![CDATA[+M<S>sbct <size>]]></c></tag> <item> Singleblock carrier threshold. Blocks larger than this threshold will be placed in singleblock carriers. Blocks smaller than this threshold will be placed in multiblock carriers. On 32-bit Unix style OS this threshold can not be set higher than 8 megabytes.</item> - <tag><marker id="M_smbcs"><c><![CDATA[+M<S>smbcs <size>]]></c></marker></tag> + <tag><marker id="M_smbcs"/><c><![CDATA[+M<S>smbcs <size>]]></c></tag> <item> Smallest (<c>mseg_alloc</c>) multiblock carrier size (in kilobytes). See <seealso marker="#mseg_mbc_sizes">the description on how sizes for mseg_alloc multiblock carriers are decided</seealso> in "the <c>alloc_util</c> framework" section.</item> - <tag><marker id="M_t"><c><![CDATA[+M<S>t true|false]]></c></marker></tag> + <tag><marker id="M_t"/><c><![CDATA[+M<S>t true|false]]></c></tag> <item> <p>Multiple, thread specific instances of the allocator. This option will only have any effect on the runtime system with SMP support. Default behaviour on the runtime system with - SMP support:</p> - <taglist> - <tag><c>ll_alloc</c></tag> - <item><c>1</c> instance.</item> - <tag>Other allocators</tag> - <item><c>NoSchedulers+1</c> instances. Each scheduler will use - a lock-free instance of its own and other threads will use - a common instance.</item> - </taglist> + SMP support is <c>NoSchedulers+1</c> instances. Each scheduler will use + a lock-free instance of its own and other threads will use + a common instance.</p> <p>It was previously (before ERTS version 5.9) possible to configure a smaller amount of thread specific instances than schedulers. This is, however, not possible any more.</p> @@ -467,35 +552,59 @@ <c>alloc_util</c>, i.e. all allocators based on <c>alloc_util</c> will be effected:</p> <taglist> - <tag><marker id="Muycs"><c><![CDATA[+Muycs <size>]]></c></marker></tag> + <tag><marker id="Muycs"/><c><![CDATA[+Muycs <size>]]></c></tag> <item> <c>sys_alloc</c> carrier size. Carriers allocated via <c>sys_alloc</c> will be allocated in sizes which are multiples of the <c>sys_alloc</c> carrier size. This is not true for main multiblock carriers and carriers allocated during a memory shortage, though.</item> - <tag><marker id="Mummc"><c><![CDATA[+Mummc <amount>]]></c></marker></tag> + <tag><marker id="Mummc"/><c><![CDATA[+Mummc <amount>]]></c></tag> <item> Max <c>mseg_alloc</c> carriers. Maximum number of carriers placed in separate memory segments. When this limit has been reached, new carriers will be placed in memory retrieved from <c>sys_alloc</c>.</item> + <tag><marker id="Musac"/><c><![CDATA[+Musac <bool>]]></c></tag> + <item> + Allow <c>sys_alloc</c> carriers. By default <c>true</c>. If + set to <c>false</c>, <c>sys_alloc</c> carriers will never be + created by allocators using the <c>alloc_util</c> framework.</item> + </taglist> + <p>The following flag is special for <c>literal_alloc</c>:</p> + <taglist> + <tag><marker id="MIscs"/><c><![CDATA[+MIscs <size in MB>]]></c></tag> + <item> + <c>literal_alloc</c> super carrier size (in MB). The amount of + <em>virtual</em> address space reserved for literal terms in + Erlang code on 64-bit architectures. The default is 1024 (1GB) + and is usually sufficient. The flag is ignored on 32-bit + architectures.</item> + </taglist> + <p>The following flag is special for <c>exec_alloc</c>:</p> + <taglist> + <tag><marker id="MXscs"/><c><![CDATA[+MXscs <size in MB>]]></c></tag> + <item> + <c>exec_alloc</c> super carrier size (in MB). The amount of + <em>virtual</em> address space reserved for native executable code + used by hipe on specific architectures (x86_64). The default is 512 MB. + </item> </taglist> <p>Instrumentation flags:</p> <taglist> - <tag><marker id="Mim"><c>+Mim true|false</c></marker></tag> + <tag><marker id="Mim"/><c>+Mim true|false</c></tag> <item> A map over current allocations is kept by the emulator. The allocation map can be retrieved via the <c>instrument</c> module. <c>+Mim true</c> implies <c>+Mis true</c>. <c>+Mim true</c> is the same as <seealso marker="erl#instr">-instr</seealso>.</item> - <tag><marker id="Mis"><c>+Mis true|false</c></marker></tag> + <tag><marker id="Mis"/><c>+Mis true|false</c></tag> <item> Status over allocated memory is kept by the emulator. The allocation status can be retrieved via the <c>instrument</c> module.</item> - <tag><marker id="Mit"><c>+Mit X</c></marker></tag> + <tag><marker id="Mit"/><c>+Mit X</c></tag> <item> Reserved for future use. Do <em>not</em> use this flag.</item> </taglist> @@ -505,7 +614,7 @@ </note> <p>Other flags:</p> <taglist> - <tag><marker id="Mea"><c>+Mea min|max|r9c|r10b|r11b|config</c></marker></tag> + <tag><marker id="Mea"/><c>+Mea min|max|r9c|r10b|r11b|config</c></tag> <item> <taglist> <tag><c>min</c></tag> @@ -535,6 +644,16 @@ </item> </taglist> </item> + <tag><marker id="Mlpm"/><c>+Mlpm all|no</c></tag> + <item>Lock physical memory. The default value is <c>no</c>, i.e., + no physical memory will be locked. If set to <c>all</c>, all + memory mappings made by the runtime system, will be locked into + physical memory. If set to <c>all</c>, the runtime system will fail + to start if this feature is not supported, the user has not got enough + privileges, or the user is not allowed to lock enough physical memory. + The runtime system will also fail with an out of memory condition + if the user limit on the amount of locked memory is reached. + </item> </taglist> <p>Only some default values have been presented here. diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml index 9e2a87dde6..f12f76890c 100644 --- a/erts/doc/src/escript.xml +++ b/erts/doc/src/escript.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>2007</year><year>2013</year> + <year>2007</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -44,6 +45,7 @@ <p><c>escript</c> runs a script written in Erlang.</p> <p>Here follows an example.</p> <pre> +$ <input>chmod u+x factorial</input> $ <input>cat factorial</input> #!/usr/bin/env escript %% -*- erlang -*- @@ -66,12 +68,13 @@ usage() -> fac(0) -> 1; fac(N) -> N * fac(N-1). -$ <input>factorial 5</input> +$ <input>./factorial 5</input> factorial 5 = 120 -$ <input>factorial</input> +$ <input>./factorial</input> +usage: factorial integer +$ <input>./factorial five</input> usage: factorial integer -$ <input>factorial five</input> -usage: factorial integer </pre> + </pre> <p>The header of the Erlang script in the example differs from a normal Erlang module. The first line is intended to be the interpreter line, which invokes <c>escript</c>. However if you @@ -90,6 +93,18 @@ $ <input>escript factorial 5</input> </pre> marker="stdlib:epp#encoding">encoding</seealso> it can be located on the second line.</p> + <note><p> + The encoding specified by the above mentioned comment + applies to the script itself. The encoding of the + I/O-server, however, has to be set explicitly like this:</p> +<code>io:setopts([{encoding, unicode}])</code> + <p>The default encoding of the I/O-server for <c>standard_io</c> + is <c>latin1</c> + since the script runs in a non-interactive terminal + (see <seealso marker="stdlib:unicode_usage#unicode_options_summary"> + Using Unicode in Erlang</seealso>). + </p></note> + <p>On the third line (or second line depending on the presence of the Emacs directive), it is possible to give arguments to the emulator, such as </p> @@ -139,8 +154,9 @@ halt(1).</pre> -include_lib("kernel/include/file.hrl").</pre> <p>to include the record definitions for the records used by the <c>file:read_link_info/1</c> function. You can also select - encoding here, but if there is a valid encoding comment on - the second line it takes precedence.</p> + encoding by including a encoding comment here, but if there + is a valid encoding comment on the second line it takes + precedence.</p> <p>The script will be checked for syntactic and semantic correctness before being run. If there are warnings (such as @@ -161,7 +177,7 @@ halt(1).</pre> If much of the execution takes place in interpreted code it may be worthwhile to compile it, even though the compilation itself will take a little while. It is also possible to supply - <c>native</c> instead of compile, this will compile the script + <c>native</c> instead of <c>compile</c>, this will compile the script using the native flag, again depending on the characteristics of the escript this could or could not be worth while.</p> @@ -221,8 +237,13 @@ factorial 5 = 120 <v>EmuArgs = string() | 'undefined'</v> <v>Body = {source, SourceCode} | {beam, BeamCode} - | {archive, ZipArchive}</v> - <v>SourceCode = BeamCode = ZipArchive = binary()</v> + | {archive, ZipArchive} + | {archive, ZipFiles, ZipOptions}</v> + <v>SourceCode = BeamCode = file:filename() | binary()</v> + <v>ZipArchive = <seealso marker="stdlib:zip#type-filename">zip:filename()</seealso> | binary()</v> + <v>ZipFiles = [ZipFile]</v> + <v>ZipFile = file:filename() | {file:filename(), binary()} | {file:filename(), binary(), file:file_info()}</v> + <v>ZipOptions = [<seealso marker="stdlib:zip#type-create_option">zip:create_option()</seealso>]</v> </type> <desc> <p>The <marker id="create_2"></marker> <c>create/2</c> @@ -237,7 +258,7 @@ factorial 5 = 120 can either be returned as a binary or written to file.</p> <p>As an example of how the function can be used, we create an - interpreted escript which uses emu_args to set some emulator + interpreted escript which uses <c>emu_args</c> to set some emulator flag. In this case it happens to disable the smp_support. We do also extract the different sections from the newly created script:</p> diff --git a/erts/doc/src/fascicules.xml b/erts/doc/src/fascicules.xml index cae197a516..1c371bd9c8 100644 --- a/erts/doc/src/fascicules.xml +++ b/erts/doc/src/fascicules.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE fascicules SYSTEM "fascicules.dtd"> <fascicules> diff --git a/erts/doc/src/inet_cfg.xml b/erts/doc/src/inet_cfg.xml index 2a033c037c..027fe600d7 100644 --- a/erts/doc/src/inet_cfg.xml +++ b/erts/doc/src/inet_cfg.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2004</year><year>2010</year> + <year>2004</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml index d5c43f6e57..a88a815ef6 100644 --- a/erts/doc/src/init.xml +++ b/erts/doc/src/init.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -177,14 +178,8 @@ <name name="stop" arity="0"/> <fsummary>Take down an Erlang node smoothly</fsummary> <desc> - <p>All applications are taken down smoothly, all code is - unloaded, and all ports are closed before the system - terminates. If the <c>-heart</c> command line flag was given, - the <c>heart</c> program is terminated before the Erlang node - terminates. Refer to <c>heart(3)</c> for more information.</p> - <p>To limit the shutdown time, the time <c>init</c> is allowed - to spend taking down applications, the <c>-shutdown_time</c> - command line flag should be used.</p> + <p>The same as + <seealso marker="#stop/1"><c>stop(0)</c></seealso>.</p> </desc> </func> <func> @@ -240,16 +235,18 @@ marker="kernel:code">code(3)</seealso>.</p> </item> + <tag><c>-epmd_module Module</c></tag> + <item> + <p>Specifies the module to use for registration and lookup of + node names. Defaults to <c>erl_epmd</c>.</p> + </item> <tag><c>-eval Expr</c></tag> <item> <p>Scans, parses and evaluates an arbitrary expression <c>Expr</c> during system initialization. If any of these steps fail (syntax error, parse error or exception during evaluation), Erlang stops with an error message. Here is an - example that seeds the random number generator:</p> - <pre> -% <input>erl -eval '{X,Y,Z}' = now(), random:seed(X,Y,Z).'</input></pre> - <p>This example uses Erlang as a hexadecimal calculator:</p> + example that uses Erlang as a hexadecimal calculator:</p> <pre> % <input>erl -noshell -eval 'R = 16#1F+16#A0, io:format("~.16B~n", [R])' \\</input> <input>-s erlang halt</input> diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml index bdcf9c3816..7be3d15de6 100644 --- a/erts/doc/src/match_spec.xml +++ b/erts/doc/src/match_spec.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>1999</year><year>2012</year> + <year>1999</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -32,21 +33,15 @@ <file>match_spec.xml</file> </header> <p>A "match specification" (match_spec) is an Erlang term describing a - small "program" that will try to match something (either the - parameters to a function as used in the <c><![CDATA[erlang:trace_pattern/2]]></c> - BIF, or the objects in an ETS table.). + small "program" that will try to match something. It can be used + to either control tracing with + <seealso marker="erlang#trace_pattern/3">erlang:trace_pattern/3</seealso> + or to search for objects in an ETS table with for example + <seealso marker="stdlib:ets#select/2">ets:select/2</seealso>. The match_spec in many ways works like a small function in Erlang, but is interpreted/compiled by the Erlang runtime system to something much more efficient than calling an Erlang function. The match_spec is also very limited compared to the expressiveness of real Erlang functions.</p> - <p>Match specifications are given to the BIF <c><![CDATA[erlang:trace_pattern/2]]></c> to - execute matching of function arguments as well as to define some actions - to be taken when the match succeeds (the <c><![CDATA[MatchBody]]></c> part). Match - specifications can also be used in ETS, to specify objects to be - returned from an <c><![CDATA[ets:select/2]]></c> call (or other select - calls). The semantics and restrictions differ slightly when using - match specifications for tracing and in ETS, the differences are - defined in a separate paragraph below.</p> <p>The most notable difference between a match_spec and an Erlang fun is of course the syntax. Match specifications are Erlang terms, not Erlang code. A match_spec also has a somewhat strange concept of @@ -76,22 +71,26 @@ { GuardFunction, ConditionExpression, ... } </item> <item>BoolFunction ::= <c><![CDATA[is_atom]]></c> | - <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> | <c><![CDATA[is_list]]></c> | - <c><![CDATA[is_number]]></c> | <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> | - <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | <c><![CDATA[is_binary]]></c> | - <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | <c><![CDATA[is_seq_trace]]></c> | - <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> | - <c><![CDATA[andalso]]></c> | <c><![CDATA[orelse]]></c></item> + <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> | + <c><![CDATA[is_list]]></c> | <c><![CDATA[is_number]]></c> | + <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> | + <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | + <c><![CDATA[is_map]]></c> | <c><![CDATA[is_binary]]></c> | + <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | + <c><![CDATA[is_seq_trace]]></c> | <c><![CDATA['and']]></c> | + <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | + <c><![CDATA['xor']]></c> | <c><![CDATA[andalso]]></c> | + <c><![CDATA[orelse]]></c></item> <item>ConditionExpression ::= ExprMatchVariable | { GuardFunction } | { GuardFunction, ConditionExpression, ... } | TermConstruct </item> <item>ExprMatchVariable ::= MatchVariable (bound in the MatchHead) | <c><![CDATA['$_']]></c> | <c><![CDATA['$$']]></c></item> - <item>TermConstruct = {{}} | {{ ConditionExpression, ... }} | - <c><![CDATA[[]]]></c> | [ConditionExpression, ...] | NonCompositeTerm | Constant - </item> - <item>NonCompositeTerm ::= term() (not list or tuple) - </item> + <item>TermConstruct = {{}} | {{ ConditionExpression, ... }} | + <c><![CDATA[[]]]></c> | [ConditionExpression, ...] | + <c><![CDATA[#{}]]></c> | #{term() => ConditionExpression, ...} | + NonCompositeTerm | Constant</item> + <item>NonCompositeTerm ::= term() (not list or tuple or map)</item> <item>Constant ::= {<c><![CDATA[const]]></c>, term()} </item> <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> | @@ -134,22 +133,26 @@ { GuardFunction, ConditionExpression, ... } </item> <item>BoolFunction ::= <c><![CDATA[is_atom]]></c> | - <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> | <c><![CDATA[is_list]]></c> | - <c><![CDATA[is_number]]></c> | <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> | - <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | <c><![CDATA[is_binary]]></c> | - <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | <c><![CDATA[is_seq_trace]]></c> | - <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> | - <c><![CDATA[andalso]]></c> | <c><![CDATA[orelse]]></c></item> + <c><![CDATA[is_float]]></c> | <c><![CDATA[is_integer]]></c> | + <c><![CDATA[is_list]]></c> | <c><![CDATA[is_number]]></c> | + <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> | + <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> | + <c><![CDATA[is_map]]></c> | <c><![CDATA[is_binary]]></c> | + <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> | + <c><![CDATA[is_seq_trace]]></c> | <c><![CDATA['and']]></c> | + <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> | + <c><![CDATA['xor']]></c> | <c><![CDATA[andalso]]></c> | + <c><![CDATA[orelse]]></c></item> <item>ConditionExpression ::= ExprMatchVariable | { GuardFunction } | { GuardFunction, ConditionExpression, ... } | TermConstruct </item> <item>ExprMatchVariable ::= MatchVariable (bound in the MatchHead) | <c><![CDATA['$_']]></c> | <c><![CDATA['$$']]></c></item> <item>TermConstruct = {{}} | {{ ConditionExpression, ... }} | - <c><![CDATA[[]]]></c> | [ConditionExpression, ...] | NonCompositeTerm | Constant - </item> - <item>NonCompositeTerm ::= term() (not list or tuple) - </item> + <c><![CDATA[[]]]></c> | [ConditionExpression, ...] | #{} | + #{term() => ConditionExpression, ...} | NonCompositeTerm | + Constant</item> + <item>NonCompositeTerm ::= term() (not list or tuple or map)</item> <item>Constant ::= {<c><![CDATA[const]]></c>, term()} </item> <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> | @@ -172,9 +175,10 @@ <title>Functions allowed in all types of match specifications</title> <p>The different functions allowed in <c><![CDATA[match_spec]]></c> work like this: </p> - <p><em>is_atom, is_float, is_integer, is_list, is_number, is_pid, is_port, is_reference, is_tuple, is_binary, is_function: </em> Like the corresponding guard tests in - Erlang, return <c><![CDATA[true]]></c> or <c><![CDATA[false]]></c>. - </p> + <p><em>is_atom, is_float, is_integer, is_list, is_number, is_pid, is_port, + is_reference, is_tuple, is_map, is_binary, is_function:</em> Like the + corresponding guard tests in Erlang, return <c><![CDATA[true]]></c> or + <c><![CDATA[false]]></c>.</p> <p><em>is_record: </em>Takes an additional parameter, which SHALL be the result of <c><![CDATA[record_info(size, <record_type>)]]></c>, like in <c><![CDATA[{is_record, '$1', rectype, record_info(size, rectype)}]]></c>. @@ -277,7 +281,7 @@ can <em>not</em> be one of the atoms <c><![CDATA[all]]></c>, <c><![CDATA[new]]></c> or <c><![CDATA[existing]]></c> (unless, of course, they are registered names). <c><![CDATA[P2]]></c> can <em>not</em> be <c><![CDATA[cpu_timestamp]]></c> nor - <c><![CDATA[{tracer,_}]]></c>. + <c><![CDATA[tracer]]></c>. Returns <c><![CDATA[true]]></c> and may only be used in the <c><![CDATA[MatchBody]]></c> part when tracing. </p> @@ -288,7 +292,7 @@ be either a process identifier or a registered name and is given as the first argument to the match_spec function. <c><![CDATA[P2]]></c> can <em>not</em> be <c><![CDATA[cpu_timestamp]]></c> nor - <c><![CDATA[{tracer,_}]]></c>. Returns + <c><![CDATA[tracer]]></c>. Returns <c><![CDATA[true]]></c> and may only be used in the <c><![CDATA[MatchBody]]></c> part when tracing. </p> @@ -298,11 +302,14 @@ disable list is applied first, but effectively all changes are applied atomically. The trace flags are the same as for <c><![CDATA[erlang:trace/3]]></c> not including - <c><![CDATA[cpu_timestamp]]></c> but including <c><![CDATA[{tracer,_}]]></c>. If a + <c><![CDATA[cpu_timestamp]]></c> but including <c><![CDATA[tracer]]></c>. If a tracer is specified in both lists, the tracer in the enable list takes precedence. If no tracer is specified the same tracer as the process executing the match spec is - used. With three parameters to this function the first is + used. When using a <seealso marker="erl_tracer">tracer module</seealso> + the module has to be loaded before the match specification is executed. + If it is not loaded the match will fail. + With three parameters to this function the first is either a process identifier or the registered name of a process to set trace flags on, the second is the disable list, and the third is the enable list. Returns @@ -369,6 +376,51 @@ the pid() of the current process.</p> </section> + <marker id="match_target"></marker> + <section> + <title>Match target</title> + <p>Each execution of a match specification is done against + a match target term. The format and content of the target term + depends on the context in which the match is done. The match + target for ETS is always a full table tuple. The match target + for call trace is always a list of all function arguments. The + match target for event trace depends on the event type, see + table below.</p> + <table> + <row> + <cell align="left" valign="middle">Context</cell> + <cell align="left" valign="middle">Type</cell> + <cell align="left" valign="middle">Match target</cell> + <cell align="left" valign="middle">Description</cell> + </row> + <row> + <cell align="left" valign="middle">ETS</cell> + <cell align="left" valign="middle"></cell> + <cell align="left" valign="middle">{Key, Value1, Value2, ...}</cell> + <cell align="left" valign="middle">A table object</cell> + </row> + <row> + <cell align="left" valign="middle">Trace</cell> + <cell align="left" valign="middle">call</cell> + <cell align="left" valign="middle">[Arg1, Arg2, ...]</cell> + <cell align="left" valign="middle">Function arguments</cell> + </row> + <row> + <cell align="left" valign="middle">Trace</cell> + <cell align="left" valign="middle">send</cell> + <cell align="left" valign="middle">[Receiver, Message]</cell> + <cell align="left" valign="middle">Receiving process/port and message term</cell> + </row> + <row> + <cell align="left" valign="middle">Trace</cell> + <cell align="left" valign="middle">'receive'</cell> + <cell align="left" valign="middle">[Node, Sender, Message]</cell> + <cell align="left" valign="middle">Sending node, process/port and message term</cell> + </row> + <tcaption>Match target depending on context</tcaption> + </table> + </section> + <section> <title>Variables and literals</title> <p>Variables take the form <c><![CDATA['$<number>']]></c> where @@ -383,10 +435,8 @@ <c><![CDATA[MatchCondition]]></c> parts, only variables bound previously may be used. As a special case, in the <c><![CDATA[MatchCondition/MatchBody]]></c> parts, the variable <c><![CDATA['$_']]></c> - expands to the whole expression which matched the - <c><![CDATA[MatchHead]]></c> (i.e., the whole parameter list to the possibly - traced function or the whole matching object in the ets table) - and the variable <c><![CDATA['$$']]></c> expands to a list + expands to the whole <seealso marker="#match_target">match target</seealso> + term and the variable <c><![CDATA['$$']]></c> expands to a list of the values of all bound variables in order (i.e. <c><![CDATA[['$1','$2', ...]]]></c>). </p> @@ -467,8 +517,8 @@ <p>For each tuple in the <c><![CDATA[MatchExpression]]></c> list and while no match has succeeded:</p> <list type="bulleted"> - <item>Match the <c><![CDATA[MatchHead]]></c> part against the arguments to the - function, + <item>Match the <c><![CDATA[MatchHead]]></c> part against the + match target term, binding the <c><![CDATA['$<number>']]></c> variables (much like in <c><![CDATA[ets:match/2]]></c>). If the <c><![CDATA[MatchHead]]></c> cannot match the arguments, the match fails. @@ -509,13 +559,10 @@ term. The <c><![CDATA[ActionTerm]]></c>'s are executed as in an imperative language, i.e. for their side effects. Functions with side effects are also allowed when tracing.</p> - <p>In ETS the match head is a <c><![CDATA[tuple()]]></c> (or a single match - variable) while it is a list (or a single match variable) when - tracing.</p> </section> <section> - <title>Examples</title> + <title>Tracing Examples</title> <p>Match an argument list of three where the first and third arguments are equal:</p> <code type="none"><![CDATA[ @@ -572,7 +619,47 @@ parameter list with a single variable is a special case. In all other cases the <c><![CDATA[MatchHead]]></c> has to be a <em>proper</em> list. </p> - <p>Match all objects in an ets table where the first element is + <p>Only generate trace message if trace control word is set to 1:</p> + <code type="none"><![CDATA[ +[{'_', + [{'==',{get_tcw},{const, 1}}], + []}] + ]]></code> + <p>Only generate trace message if there is a seq trace token:</p> + <code type="none"><![CDATA[ +[{'_', + [{'==',{is_seq_trace},{const, 1}}], + []}] + ]]></code> + <p>Remove 'silent' trace flag when first argument is 'verbose' + and add it when it is 'silent':</p> + <code type="none"><![CDATA[ +[{'$1', + [{'==',{hd, '$1'},verbose}], + [{trace, [silent],[]}]}, + {'$1', + [{'==',{hd, '$1'},silent}], + [{trace, [],[silent]}]}] + ]]></code> + <p>Add return_trace message if function is of arity 3:</p> + <code type="none"><![CDATA[ +[{'$1', + [{'==',{length, '$1'},3}], + [{return_trace}]}, + {'_',[],[]}] + ]]></code> + <p>Only generate trace message if function is of arity 3 and first argument is 'trace':</p> + <code type="none"><![CDATA[ +[{['trace','$2','$3'], + [], + []}, + {'_',[],[]}] + ]]></code> + </section> + + <section> + <title>ETS Examples</title> + <p>Match all objects in an ets table where the first element is the atom 'strider' and the tuple arity is 3 and return the whole object.</p> <code type="none"><![CDATA[ @@ -580,7 +667,7 @@ [], ['$_']}] ]]></code> - <p>Match all objects in an ets table with arity > 1 and the first + <p>Match all objects in an ets table with arity > 1 and the first element is 'gandalf', return element 2.</p> <code type="none"><![CDATA[ [{'$1', @@ -591,7 +678,7 @@ it's much more efficient to match that key in the <c><![CDATA[MatchHead]]></c> part than in the <c><![CDATA[MatchConditions]]></c> part. The search space of the tables is restricted with regards to the <c><![CDATA[MatchHead]]></c> so - that only objects with the matching key are searched. + that only objects with the matching key are searched. </p> <p>Match tuples of 3 elements where the second element is either 'merry' or 'pippin', return the whole objects.</p> diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index f94d71ee3d..3c3129d543 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2004</year><year>2013</year> + <year>2004</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -30,6 +31,4171 @@ </header> <p>This document describes the changes made to the ERTS application.</p> + +<section><title>Erts 8.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>The handling of <c>on_load</c> functions has been + improved. The major improvement is that if a code upgrade + fails because the <c>on_load</c> function fails, the + previous version of the module will now be retained.</p> + <p> + Own Id: OTP-12593</p> + </item> + <item> + <p><c>is_builtin(erlang, apply, 3)</c> will now return + <c>true</c>.</p> + <p> + Own Id: OTP-13034</p> + </item> + <item> + <p> + Fix <c>enif_get_list_length</c> to return false if list + is improper or have length larger than <c>UINT_MAX</c> + (did return true and an incorrect length value).</p> + <p> + Own Id: OTP-13288 Aux Id: PR913 </p> + </item> + <item> + <p> + Cleanup hipe signal handling code for x86 and make it + more portable.</p> + <p> + Own Id: OTP-13341 Aux Id: PR951 </p> + </item> + <item> + <p> + Make file:datasync use fsync instead of fdatasync on Mac + OSX.</p> + <p> + Own Id: OTP-13411</p> + </item> + <item> + <p> + Make sure to create a crash dump when running out of + memory. This was accidentally removed in the erts-7.3 + release.</p> + <p> + Own Id: OTP-13419</p> + </item> + <item> + <p> + A bug has been fixed where if erlang was started +B on a + unix platform it would be killed by a SIGUSR2 signal when + creating a crash dump.</p> + <p> + Own Id: OTP-13425</p> + </item> + <item> + <p> + Fix race between <c>process_flag(trap_exit,true)</c> and + a received exit signal.</p> + <p> + A process could terminate due to exit signal even though + <c>process_flag(trap_exit,true)</c> had returned. A very + specific timing between call to <c>process_flag/2</c> and + exit signal from another scheduler was required for this + to happen.</p> + <p> + Own Id: OTP-13452</p> + </item> + <item> + <p>Don't search for non-existing Map keys twice</p> + <p>For <c>maps:get/2,3</c> and <c>maps:find/2</c>, + searching for an immediate key, e.g. an atom, in a small + map, the search was performed twice if the key did not + exist.</p> + <p> + Own Id: OTP-13459</p> + </item> + <item> + <p> + When an abnormally large distribution message is about to + be sent, the VM has been changed to create a crash dump + instead of a core dump.</p> + <p> + Own Id: OTP-13474</p> + </item> + <item> + <p> + Fix <c>erlang:process_info/2</c> type specification</p> + <p> + Own Id: OTP-13485 Aux Id: ERL-123 </p> + </item> + <item> + <p> + Fix bug in <c>open_port/2</c> with option <c>{args, + List}</c>. A vm crash could be caused by an improper + <c>List</c>.</p> + <p> + Own Id: OTP-13489 Aux Id: ERL-127 </p> + </item> + <item> + <p> + Fixed a race-condition bug where the emulator could crash + when <c>erlang:system_profile/1,2</c> was enabled and a + process had to be re-scheduled during termination.</p> + <p> + Own Id: OTP-13494 Aux Id: ERL-126 </p> + </item> + <item> + <p> + Fixed bugs where the reduction counter was not handled + correct.</p> + <p> + Own Id: OTP-13512</p> + </item> + <item> + <p> + Fixed typo in description of the <c>EPMD_DUMP_REQ</c> + response.</p> + <p> + Own Id: OTP-13517</p> + </item> + <item> + <p> + Fixed a bug where a process flagged as sensitive would + sometimes record its save_calls when it shouldn't.</p> + <p> + Own Id: OTP-13540</p> + </item> + <item> + <p> + Update configure scripts to not use hard-coded path for + /bin/pwd and /bin/rm.</p> + <p> + Own Id: OTP-13562</p> + </item> + <item> + <p> + When passing a larger binary than the outputv callback of + a linked-in driver can handle in one io vector slot, the + binary is now split into multiple slots in the io vector. + This change only effects system where the max size of an + io vector slot is smaller then the word size of the + system (e.g. Windows).</p> + <p> + This change means that it is now possible on Windows to + send binaries that are larger than 4GB to port_command, + which is what is used for file:write, gen_tcp:send etc.</p> + <p> + Own Id: OTP-13628</p> + </item> + <item> + <p> + Workaround of Maps output in crashdumps. Currently the + atom 'undefined' is generated instead of Map data if a + Map type is encountered during crash.</p> + <p> + Own Id: OTP-13657</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The tracing support has been extended to allow a <seealso + marker="erl_tracer">tracer module</seealso> to be the + trace event handler instead of a process or port. The + <seealso marker="erl_tracer">tracer module</seealso> + makes it possible for trace tools to filter or manipulate + trace event data without the trace event first having to + be copied from the traced process or port.</p> + <p> + With the introduction of this feature, + <c>erlang:trace(all|existing, _, _)</c> now also returns + the tracer process as part of the number of processes on + which tracing is enabled. The is incompatible with the + previous releases.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10267</p> + </item> + <item> + <p> + Introduce LTTng tracing of Erlang Runtime System</p> + <p> + For LTTng to be enabled OTP needs to be built with + configure option <c>--with-dynamic-trace=lttng</c>.</p> + <p> + This feature introduces tracepoints for schedulers, + drivers, memory carriers, memory and async thread pool.</p> + <p> For a list of all tracepoints, see <seealso + marker="runtime_tools:LTTng">Runtime Tools User's + Guide</seealso> .</p> + <p> + Own Id: OTP-10282</p> + </item> + <item> + <p> + Make it possible to monitor/demonitor ports using the + <seealso + marker="erlang#monitor/2">erlang:monitor/2</seealso> API. + The process and port information functions have also been + updated to include information about monitors from + processes to ports.</p> + <p> + Own Id: OTP-11384</p> + </item> + <item> + <p> + Add microstate accounting</p> + <p> + Microstate accounting is a way to track which state the + different threads within ERTS are in. The main usage area + is to pin point performance bottlenecks by checking which + states the threads are in and then from there figuring + out why and where to optimize.</p> + <p> + Since checking whether microstate accounting is on or off + is relatively expensive only a few of the states are + enabled by default and more states can be enabled through + configure.</p> + <p> + There is a convenience module called msacc that has been + added to runtime_tools that can assist in gathering and + interpreting the data from Microstate accounting.</p> + <p> + For more information see <seealso + marker="erts:erlang#statistics_microstate_accounting">erlang:statistics(microstate_accounting, + _)</seealso> and the <seealso + marker="runtime_tools:msacc">msacc</seealso> module in + runtime_tools.</p> + <p> + Own Id: OTP-12345</p> + </item> + <item> + <p> + The port of Erlang/OTP to the real-time operating system + OSE has been removed.</p> + <p> + Own Id: OTP-12573</p> + </item> + <item> + <p> + Sharing preserved copy for messages and exit signals</p> + <p> + Enable sharing preserved copy with configure option + <c>--enable-sharing-preserving</c>. This will preserve + sharing, within the process, when communication with + other processes in the Erlang node. There is a trade-off, + the copy is more costly but this cost can be reclaimed if + there is a lot of sharing in the message. In addition + literals will not be copied in a send except during a + purge phase of the module where the literals are located. + This feature is considered experimental in 19.0.</p> + <p> + Own Id: OTP-12590 Aux Id: OTP-10251 </p> + </item> + <item> + <p> + Halfword BEAM has been removed.</p> + <p> + Own Id: OTP-12883</p> + </item> + <item> + <p> + Added <seealso + marker="kernel:os#perf_counter/1">os:perf_counter/1</seealso>.</p> + <p> + The perf_counter is a very very cheap and high resolution + timer that can be used to timestamp system events. It + does not have monoticity guarantees, but should on most + OS's expose a monotonous time.</p> + <p> + Own Id: OTP-12908</p> + </item> + <item> + <p> + Support for a fragmented young heap generation. That is, + the young heap generation can consist of multiple non + continuous memory areas. The main reason for this change + is to avoid extra copying of messages that could not be + allocated directly on the receivers heap.</p> + <p> + Own Id: OTP-13047</p> + </item> + <item> + <p> + Erlang linked-in driver can now force the call to + open_port to block until a call to erl_drv_init_ack is + made inside the driver. This is useful when you want to + do some asynchronous initialization, for example getting + configuration from a pipe, and you want the initial + open_port call to fail if the configuration is incomplete + or wrong. See the erl_driver documentation for more + details on the API.</p> + <p> + Own Id: OTP-13086</p> + </item> + <item> + <p> + Erlang linked-in drivers can now set their own pids as + seen in <c>erlang:port_info/1</c> by using the + <c>erl_drv_set_pid</c> function. For more details see the + erl_driver documentation.</p> + <p> + Own Id: OTP-13087</p> + </item> + <item> + <p> + The functionality behind <c>erlang:open_port/2</c> when + called with spawn or spawn_executable has been redone so + that the forking of the new program is done in a separate + process called erl_child_setup. This allows for a much + more robust implementation that uses less memory and does + not block the entire emulator if the program to be + started is on an un-accessible NFS. Benchmarks have shown + this approach to be about 3-5 times as fast as the old + approach where the fork/vfork was done by erts. This is a + pure stability and performance fix, however some error + messages may have changed, which is why it is marked as a + backwards incompatible change.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13088</p> + </item> + <item> + <p>Improved yielding strategy in the implementation of + the following native functions:</p> <list> + <item><c>erlang:binary_to_list/1</c></item> + <item><c>erlang:binary_to_list/3</c></item> + <item><c>erlang:bitstring_to_list/1</c></item> + <item><c>erlang:list_to_binary/1</c></item> + <item><c>erlang:iolist_to_binary/1</c></item> + <item><c>erlang:list_to_bitstring/1</c></item> + <item><c>binary:list_to_bin/1</c></item> </list> <p>This + in order to improve performance of these functions.</p> + <p> + Own Id: OTP-13096</p> + </item> + <item> + <p> + All garbage collections of processes now bump reductions. + Also the amount of reductions bumped when garbage + collecting has been adjusted. It now better corresponds + to the amount of work performed. This in order to improve + the real time characteristics of the system.</p> + <p> + Own Id: OTP-13097</p> + </item> + <item> + <p>New functions that can load multiple modules at once + have been added to the '<c>code</c>' module. The + functions are <c>code:atomic_load/1</c>, + <c>code:prepare_loading/1</c>, + <c>code:finish_loading/1</c>, and + <c>code:ensure_modules_loaded/1</c>.</p> + <p> + Own Id: OTP-13111</p> + </item> + <item> + <p>The <c>-boot_var</c> option for <c>erl</c> now only + supports a single key and single value (as documented). + The option used to allow multiple key/value pairs, but + that behavior was undocumented.</p> + <p>The function <c>erl_prim_loader:start/3</c> has been + removed. Its documentation has also been removed.</p> + <p>The undocumented and unsupported function + <c>erl_prim_loader:get_files/2</c> has been removed.</p> + <p> + Own Id: OTP-13112</p> + </item> + <item> + <p> + Low level BIF <c>erlang:purge_module/1</c> is made more + robust against incorrect use. Lingering processes that + still refer the old code are now killed before the module + is purged to prevent fatal VM behavior.</p> + <p> + Own Id: OTP-13122</p> + </item> + <item> + <p>Improved dirty scheduler implementation. For more + information see the <seealso + marker="erl_nif#dirty_nifs">NIF + documentation</seealso>.</p> <note><list> <item><p>The + dirty scheduler support is still + <em>experimental</em>.</p></item> <item><p>The support + for determining whether dirty NIF support exist or not at + compile time using the C preprocessor macro + <c>ERL_NIF_DIRTY_SCHEDULER_SUPPORT</c> has been + removed.</p></item> <item><p>The + <c>enif_is_on_dirty_scheduler()</c> function has been + removed. Use <seealso + marker="erl_nif#enif_thread_type"><c>enif_thread_type()</c></seealso> + instead.</p></item> </list></note> + <p> + Own Id: OTP-13123</p> + </item> + <item> + <p> + Various optimizations done to process dictionary access.</p> + <p> + Own Id: OTP-13167</p> + </item> + <item> + <p> + Added max_heap_size process flag. max_heap_size allows + the user to limit the maximum heap used by a process. See + <seealso + marker="erlang#process_flag/2">erlang:process_flag</seealso> + for more details.</p> + <p> + Own Id: OTP-13174</p> + </item> + <item> + <p> + Allow dynamic drivers and NIF libraries to be built with + gcc option <c>-fvisibility=hidden</c> for faster loading + and more optimized code.</p> + <p> + Own Id: OTP-13227</p> + </item> + <item> + <p> + Add <c>erlang:process_info(Pid, + garbage_collection_info)</c> which returns extended + garbage_collection information. For more details see the + documentation.</p> + <p> + Own Id: OTP-13265</p> + </item> + <item> + <p> + The functions <c>erlang:list_to_integer/1</c> and + <c>string:to_integer/1</c> have been optimized for large + inputs.</p> + <p> + Own Id: OTP-13293</p> + </item> + <item> + <p> + Improved memory allocation strategy for hipe native code + on x86_64 (amd64) architectures by reserving enough low + virtual address space needed for the HiPE/AMD64 small + code model. The default virtual address area for hipe + code is set to 512Mb, but can be changed with emulator + flag <c>+MXscs</c>.</p> + <p> + Own Id: OTP-13359</p> + </item> + <item> + <p> + Introduction of configurable management of data referred + to by the message queue of a process. Each process can be + configured individually.</p> + <p> + It is now possible to configure the message queue of a + process, so that all data referred by it will be kept + outside of the heap, and by this prevent this data from + being part of garbage collections.</p> + <p> + For more information see the documentation of <seealso + marker="erlang#process_flag_message_queue_data"><c>process_flag(message_queue_data, + MQD)</c></seealso>.</p> + <p> + Own Id: OTP-13366 Aux Id: OTP-13047 </p> + </item> + <item> + <p> + Processes now yield when scanning large message queues + and not finding a matching message. This in order to + improve real time characteristics.</p> + <p> + Own Id: OTP-13401</p> + </item> + <item> + <p> + Optimized an erts internal function that is used to + traverse erlang terms. The internal function was mainly + used by term_to_binary and comparison of terms. + Benchmarks have shown up to a 10% performance increase in + those functions after the optimization.</p> + <p> + Own Id: OTP-13440</p> + </item> + <item> + <p> + Add the following NIF API functions:</p> + <p> + <list> <item><seealso + marker="erl_nif#enif_cpu_time"><c>enif_cpu_time</c></seealso></item> + <item><seealso + marker="erl_nif#enif_now_time"><c>enif_now_time</c></seealso></item> + <item><seealso + marker="erl_nif#enif_make_unique_integer"><c>enif_make_unique_integer</c></seealso></item> + <item><seealso + marker="erl_nif#enif_is_process_alive"><c>enif_is_process_alive</c></seealso></item> + <item><seealso + marker="erl_nif#enif_is_port_alive"><c>enif_is_port_alive</c></seealso></item> + <item><seealso + marker="erl_nif#enif_term_to_binary"><c>enif_term_to_binary</c></seealso></item> + <item><seealso + marker="erl_nif#enif_binary_to_term"><c>enif_binary_to_term</c></seealso></item> + <item><seealso + marker="erl_nif#enif_port_command"><c>enif_port_command</c></seealso></item> + </list></p> + <p> + for details of what each function does, see the erl_nif + documentation.</p> + <p> + Own Id: OTP-13442</p> + </item> + <item> + <p> + Optimize <c>'++'</c> operator and <c>lists:append/2</c> + by using a single pass to build a new list while checking + for properness.</p> + <p> + Own Id: OTP-13487</p> + </item> + <item> + <p> + Handle terms (pids,ports and refs) from nodes with a + 'creation' value larger than 3. This is a preparation of + the distribution protocol to allow OTP 19 nodes to + correctly communicate with future nodes (20 or higher). + The 'creation' value differentiates different + incarnations of the same node (name).</p> + <p> + Own Id: OTP-13488</p> + </item> + <item> + <p> + Don't send unasked for systemd notifications in epmd</p> + <p> + Own Id: OTP-13493 Aux Id: PR-999 </p> + </item> + <item> + <p> + The enif_send API has been extended to allow NULL to be + used as the message environment. When used this way, a + message environment is implicitly created and the given + term is copied into that environment before sending. This + can be an optimization if many small messages are being + sent by the nif.</p> + <p> + Own Id: OTP-13495</p> + </item> + <item> + <p> + The tracing support has been extended to allow tracing on + ports. Ports can be traced on using the 'ports', 'send' + and 'receive' trace flags.</p> + <p> + The first argument of <seealso + marker="erts:erlang#trace/3">erlang:trace/3</seealso> has + been extended so that <c>'all'</c>, <c>'existing'</c> and + <c>'new'</c> now include both processes and ports. New + <c>Tracee</c> variants, <c>'all_processes'</c>, + <c>'all_ports'</c>, <c>'existing_processes'</c> etc have + been added to specify only processes or ports.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13496</p> + </item> + <item> + <p> + When the <c>'procs'</c> trace flag is enabled, a + <c>'spawned'</c> trace event is now also generated by a + newly created process. The previous event <c>'spawn'</c> + remains, but as it is generated by the process that did + the spawn, it is not guaranteed that it is ordered with + other trace events from the newly spawned process. So + when tracking the lifetime of a process this new event + should be used as the creation event.</p> + <p> + This new trace event is marked as an incompatibility + because tools that expect certain trace events when + enabling 'procs' will have to updated.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13497</p> + </item> + <item> + <p> + Add the <seealso + marker="erts:erlang#match_spec_test/3">erlang:match_spec_test/3</seealso> + function. The functions allows the testing of match + specifications for both tracing and ets tables. It can be + used to test that a match specification does the expected + filtering on specific data. It also returns more verbose + error reasons for incorrectly constructed match + specifications.</p> + <p> + Own Id: OTP-13501</p> + </item> + <item> + <p> + The erts internal tracing support has been changed to + have much less overhead and be more scalable.</p> + <p> + This rewrite does not break any backwards + incompatibilities, but it does change the ordering of + some trace messages when compared to previous releases. + It should be noted that this only applies to trace + messages sent to processes or ports, it does not apply to + the new tracer module. However in future releases they + may also be effected by this.</p> + <p> + Trace messages are only guaranteed to be ordered from one + traced process or port. In previous releases this was not + visible as a <c>'send'</c> trace message would always + arrive before the corresponding <c>'receive'</c> trace + message that is no longer always the case. This also + means that timestamped trace messages may seem to arrive + out of order as the timestamp is taken when the event is + triggered and not when it is put in the queue of the + tracer.</p> + <p> + Own Id: OTP-13503</p> + </item> + <item> + <p> + Add possibility to filter <c>send</c> and <c>receive</c> + trace with match specifications.</p> + <p> + Own Id: OTP-13507</p> + </item> + <item> + <p> + Add <c>maps:update_with/3,4</c> and <c>maps:take/2</c></p> + <p> + Own Id: OTP-13522 Aux Id: PR-1025 </p> + </item> + <item> + <p> + Introduce LTTng tracing via Erlang tracing.</p> + <p> + For LTTng to be enabled OTP needs to be built with + configure option <c>--with-dynamic-trace=lttng</c>.</p> + <p>The dynamic trace module <c>dyntrace</c> is now + capable to be used as a LTTng sink for Erlang tracing. + For a list of all tracepoints, see <seealso + marker="runtime_tools:LTTng">Runtime Tools User's + Guide</seealso> .</p> + <p>This feature also introduces an incompatible change in + trace tags. The trace tags <c>gc_start</c> and + <c>gc_end</c> has been split into <c>gc_minor_start</c>, + <c>gc_minor_end</c> and <c>gc_major_start</c>, + <c>gc_major_end</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13532</p> + </item> + <item> + <p> + Print heap pointers for garbing processes during + crashdump</p> + <p> + Own Id: OTP-13541 Aux Id: PR-1026 </p> + </item> + <item> + <p> + Changed and improved low level memory statistics returned + by <c>erlang:system_info/1</c>. The info for + <c>erts_mmap</c> has been moved from <c>mseg_alloc</c> to + its own section returned by <c>{allocator, + erts_mmap}</c>.</p> + <p> + Own Id: OTP-13560</p> + </item> + <item> + <p> + Add enif_snprintf to the NIF API</p> + <p> + The function <c>enif_snprintf</c> is similar to + <c>snprintf</c> call but can handle formatting of Erlang + terms via <c>%T</c> format specifier.</p> + <p> + Own Id: OTP-13580</p> + </item> + <item> + <p>The warning in the documentation for + <c>erlang:raise/3</c> has been removed. It is now + officially perfectly fine to use raise/3 in production + code.</p> + <p> + Own Id: OTP-13599</p> + </item> + <item> + <p> + Fix bugs caused by the VM sometimes truncating object + sizes or offsets to 32 bits on 64-bit hosts. These bugs + were mainly found when working with large unicode strings + and nifs environments.</p> + <p> + Own Id: OTP-13606</p> + </item> + <item> + <p> + Add <c>-start_epmd</c> command line option, this lets you + disable automatic starting of epmd when starting a + distributed node.</p> + <p> + Add <c>-epmd_module</c> command line option, this lets + you specify a module to register and look-up node names + in. The default module is <c>erl_epmd</c>.</p> + <p> + Own Id: OTP-13627</p> + </item> + <item> + <p> + <c>erlang:halt</c> now truncates strings longer than 200 + characters instead of failing with <c>badarg</c>.</p> + <p> + Own Id: OTP-13630</p> + </item> + <item> + <p> + Fix possible race in poller wake up on windows</p> + <p> + Own Id: OTP-13634</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + <c>process_info(Pid, last_calls)</c> did not work for + <c>Pid /= self()</c>.</p> + <p> + Own Id: OTP-13418</p> + </item> + <item> + <p> + Make sure to create a crash dump when running out of + memory. This was accidentally removed in the erts-7.3 + release.</p> + <p> + Own Id: OTP-13419</p> + </item> + <item> + <p> + Schedulers could be woken by a premature timeout on + Linux. This premature wakeup was however harmless.</p> + <p> + Own Id: OTP-13420</p> + </item> + <item> + <p> + A process communicating with a port via one of the + <c>erlang:port_*</c> BIFs could potentially end up in an + inconsistent state if the port terminated during the + communication. When this occurred the process could later + block in a <c>receive</c> even though it had messages + matching in its message queue.</p> + <p> + This bug was introduced in erts version 5.10 (OTP R16A).</p> + <p> + Own Id: OTP-13424 Aux Id: OTP-10336 </p> + </item> + <item> + <p> + The reference count of a process structure could under + rare circumstances be erroneously managed. When this + happened invalid memory accesses occurred.</p> + <p> + Own Id: OTP-13446</p> + </item> + <item> + <p> + Fix race between <c>process_flag(trap_exit,true)</c> and + a received exit signal.</p> + <p> + A process could terminate due to exit signal even though + <c>process_flag(trap_exit,true)</c> had returned. A very + specific timing between call to <c>process_flag/2</c> and + exit signal from another scheduler was required for this + to happen.</p> + <p> + Own Id: OTP-13452</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The '-path' flag to 'erl' has been documented. This flag + replaces the path specified in the boot script. It has + always existed, but was earlier only documented in SASL + (script).</p> + <p> + Own Id: OTP-13060</p> + </item> + <item> + <p> + The <c>call_time</c> tracing functionality internally + used a time based on OS system time in order to measure + call time which could cause erroneous results if OS + system time was changed during tracing.</p> + <p> + This functionality now use Erlang monotonic time in order + to measure time. Besides fixing the erroneous results due + to OS system time being used, the results are often also + better since Erlang monotonic time often has better + accuracy and precision.</p> + <p> + Own Id: OTP-13216</p> + </item> + <item> + <p> + Fix behaviour of -delay_write command line switch of + epmd, which is used for debugging - in some cases epmd + was sleeping twice the requested amount of time.</p> + <p> + Own Id: OTP-13220</p> + </item> + <item> + <p> + Fix race between timeout and exit signal that could cause + a process to ignore the exit signal and continue + execution. Bug exist since OTP 18.0.</p> + <p> + Own Id: OTP-13245</p> + </item> + <item> + <p> + Fix bug in <c>erlang:halt/1,2</c> for large exit status + values, causing either <c>badarg</c> (on 32-bit) or exit + with a crash dump and/or core dump (on 64-bit). Make + <c>erlang:halt/1,2</c> tolerate any non negative integer + as exit status and truncate high order bits if the OS + does not support it.</p> + <p> + Own Id: OTP-13251 Aux Id: ERL-49 </p> + </item> + <item> + <p> + <seealso + marker="kernel:gen_tcp#accept/2"><c>gen_tcp:accept/2</c></seealso> + was not <seealso + marker="erts:time_correction#Time_Warp_Safe_Code">time + warp safe</seealso>. This since it used the same time as + returned by <seealso + marker="erts:erlang#now/0"><c>erlang:now/0</c></seealso> + when calculating timeout. This has now been fixed.</p> + <p> + Own Id: OTP-13254 Aux Id: OTP-11997, OTP-13222 </p> + </item> + <item> + <p> + Fix faulty error handling when writing to a compressed + file.</p> + <p> + Own Id: OTP-13270</p> + </item> + <item> + <p> + Fix sendfile usage for large files on FreeBSD</p> + <p> + Own Id: OTP-13271</p> + </item> + <item> + <p> + Fix bug that could cause + <c>process_info(P,current_location)</c> to crash emulator + for hipe compiled modules.</p> + <p> + Own Id: OTP-13282 Aux Id: ERL-79 </p> + </item> + <item> + <p> + Out of memory errors have been changed to cause an exit + instead of abort.</p> + <p> + Own Id: OTP-13292</p> + </item> + <item> + <p> + When calling <c>garbage_collect/[1,2]</c> or + <c>check_process_code/[2,3]</c> from a process with a + higher priority than the priority of the process operated + on, the run queues could end up in an inconsistent state. + This bug has now been fixed.</p> + <p> + Own Id: OTP-13298 Aux Id: OTP-11388 </p> + </item> + <item> + <p> + A workaround for an issue with older gcc versions (less + than 5) and inline assembly on 32-bit x86 caused an + emulator crash when it had been compiled with a newer gcc + version. An improved <c>configure</c> test, run when + building OTP, now detects whether the workaround should + be used or not.</p> + <p> + Own Id: OTP-13326 Aux Id: ERL-80 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Introduced new statistics functionality in order to + more efficiently retrieve information about run able and + active processes and ports. For more information see:</p> + <list> <item><seealso + marker="erlang#statistics_total_run_queue_lengths"><c>statistics(total_run_queue_lengths)</c></seealso></item> + <item><seealso + marker="erlang#statistics_run_queue_lengths"><c>statistics(run_queue_lengths)</c></seealso></item> + <item><seealso + marker="erlang#statistics_total_active_tasks"><c>statistics(total_active_tasks)</c></seealso></item> + <item><seealso + marker="erlang#statistics_active_tasks"><c>statistics(active_tasks)</c></seealso></item> + </list> + <p> + Own Id: OTP-13201</p> + </item> + <item> + <p> + Time warp safety improvements.</p> + <p> + Introduced the options <c>monotonic_timestamp</c>, and + <c>strict_monotonic_timestamp</c> to the trace, + sequential trace, and system profile functionality. This + since the already existing <c>timestamp</c> option is not + time warp safe.</p> + <p> + Introduced the option <c>safe_fixed_monotonic_time</c> to + <c>ets:info/2</c> and <c>dets:info/2</c>. This since the + already existing <c>safe_fixed</c> option is not time + warp safe.</p> + <p> + Own Id: OTP-13222 Aux Id: OTP-11997 </p> + </item> + <item> + <p> + Fix a register race where down nodes goes undetected in + epmd</p> + <p> + Own Id: OTP-13301</p> + </item> + <item> + <p> + Improved the gcc inline assembly implementing double word + atomic compare and exchange on x86/x86_64 so that it also + can be used when compiling with clang.</p> + <p> + Own Id: OTP-13336</p> + </item> + <item> + <p> + An optimization preventing a long wait for a scheduler + thread looking up information about a process executing + on another scheduler thread had unintentionally been lost + in erts-5.10 (OTP R16A). This optimization has now been + reintroduced.</p> + <p> + Own Id: OTP-13365 Aux Id: OTP-9892 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Revert "Fix erroneous splitting of emulator path"</p> + <p> + Own Id: OTP-13202</p> + </item> + <item> + <p> + Fix HiPE enabled emulator for FreeBSD.</p> + <p> + Own Id: OTP-13204 Aux Id: pr926 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Small documentation fixes</p> + <p> + Own Id: OTP-13017</p> + </item> + <item> + <p> + Fix memory corruption bug caused by disabling + distribution and then re-enable distribution with a node + name that has previously been used by a remote node.</p> + <p> + Own Id: OTP-13076 Aux Id: seq12959 </p> + </item> + <item> + <p> + Renamed variables with name bool as Visual Studio 2015 + now treats this is a keyword.</p> + <p> + Own Id: OTP-13079</p> + </item> + <item> + <p><c>erl_prim_loader</c> has not supported custom + loaders for several releases. In the documentation for + <c>erl_prim_loader</c>, all references to custom loaders + have now been removed.</p> + <p> + Own Id: OTP-13102</p> + </item> + <item> + <p> + Fixed compilation of erts together with libc versions + that do not define __uint32_t.</p> + <p> + Own Id: OTP-13105</p> + </item> + <item> + <p> + erl -make now returns non-zero exit codes on failure</p> + <p> + Own Id: OTP-13107</p> + </item> + <item> + <p> + Fix crash on init:restart in embedded mode caused by + on_load handler process not being relaunched leading to + load failure for modules such as crypto and asn1rt_nif + that need it to be present for correct NIF loading.</p> + <p> + Own Id: OTP-13115</p> + </item> + <item> + <p> + Fix maps decode in erlang:binary_to_term/1</p> + <p>Decoding a term with a large (HAMT) map in an small + (FLAT) map could cause a critical error if the external + format was not produced by beam.</p> + <p> + Own Id: OTP-13125</p> + </item> + <item> + <p> + Fix very rare bug in GC when big maps with a lot of hash + collisions from a remote node are waiting in inner + message queue.</p> + <p> + Own Id: OTP-13146</p> + </item> + <item> + <p> + Fixed a bug that could cause a crash dump to become + almost empty.</p> + <p> + Own Id: OTP-13150</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> Updated the xmllint target to just check the xml + files with real documentation content.<br/> Corrected + some errors and added some missing target in the DTD's. + </p> + <p> + Own Id: OTP-13026</p> + </item> + <item> + <p> + Add function enif_getenv to read OS environment variables + in a portable way from NIFs.</p> + <p> + Own Id: OTP-13147</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.1</title> + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix bug in ETS that could cause stray objects marked for + deletion to occasionally be missed by the cleanup done by + <c>safe_fixtable(_,false)</c>.</p> + <p> + Own Id: OTP-12870</p> + </item> + <item> + <p> + Fixed VM crash that could occur if a trace port was + linked to a process, and the trace port terminated + abnormally while handling a trace message. This bug has + always existed in the runtime system with SMP support.</p> + <p> + Own Id: OTP-12901</p> + </item> + <item> + <p> + Instead of aborting, the vm now creates a crash dump when + a system process is terminated.</p> + <p> + Own Id: OTP-12934</p> + </item> + <item> + <p> + Fixed a rare emulator dead lock that occurred when + erlang:process_flag(priority,...) was called by a process + that was also scheduled for an internal system activity.</p> + <p> + Own Id: OTP-12943</p> + </item> + <item> + <p> + The runtime system on various posix platforms (except for + Linux and Solaris) could crash when large amounts of + file-descriptors were in use.</p> + <p> + Own Id: OTP-12954</p> + </item> + <item> + <p> + A beam file compiled by hipe for an incompatible runtime + system was sometimes not rejected by the loader, which + could lead to vm crash. This fix will also allow the same + hipe compiler to be used by both normal and debug-built + vm.</p> + <p> + Own Id: OTP-12962</p> + </item> + <item> + <p> + Fix bug in <c>maps:merge/2</c> when called by hipe + compiled code that could cause vm crash. Bug exists since + erts-7.0 (OTP 18.0).</p> + <p> + Own Id: OTP-12965</p> + </item> + <item> + <p> + When tracing with <c>process_dump</c> option, the VM + could abort if there was an ongoing binary match + somewhere in the call stack of the traced process.</p> + <p> + Own Id: OTP-12968</p> + </item> + <item> + <p> + Fixed possible output deadlock in tty driver when hitting + "CTRL-C" in a non-smp emulator shell on unix.</p> + <p> + Own Id: OTP-12987 Aux Id: Seq12947 </p> + </item> + <item> + <p> + Fix <c>binary_to_integer</c> to throw badarg for "+" and + "-" similar to <c>list_to_integer</c>.</p> + <p> + Own Id: OTP-12988</p> + </item> + <item> + <p> + Suppress warning of unused argument when using macro + enif_make_pid.</p> + <p> + Own Id: OTP-12989</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Changed default clock source used for OS system time on + MacOS X to <c>gettimeofday()</c> in order to improve + performance. The system can be configured during build to + use the previously used higher resolution clock source by + passing the switch <seealso + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP_Configuring"><c>--with-clock-resolution=high</c></seealso> + when configuring the build.</p> + <p> + Own Id: OTP-12945 Aux Id: OTP-12892 </p> + </item> + <item> + <p> + Added the <c>configure</c> option <seealso + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP_Configuring"><c>--disable-saved-compile-time</c></seealso> + which disables saving of compile date and time in the + emulator binary.</p> + <p> + Own Id: OTP-12971</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.0.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed a binary memory leak when printing to shell using + the tty driver (i.e. not -oldshell).</p> + <p> + Own Id: OTP-12941</p> + </item> + <item> + <p> + Fix a bug where the standard error port sometimes crashes + with eagain as the reason.</p> + <p> + Own Id: OTP-12942</p> + </item> + <item> + <p> + When tracing with <c>process_dump</c> option, the VM + could abort if there was an ongoing binary match + somewhere in the call stack of the traced process./</p> + <p> + Own Id: OTP-12968</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.0.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A process could end up in an inconsistent half exited + state in the runtime system without SMP support. This + could occur if the processes was traced by a port that it + also was linked to, and the port terminated abnormally + while handling a trace message for the process.</p> + <p> + This bug has always existed in the runtime system without + SMP support, but never in the runtime system with SMP + support.</p> + <p> + Own Id: OTP-12889 Aux Id: seq12885 </p> + </item> + <item> + <p> + Removed unnecessary copying of data when retrieving + corrected Erlang monotonic time.</p> + <p> + Own Id: OTP-12894</p> + </item> + <item> + <p> + Changed default OS monotonic clock source chosen at build + time. This in order to improve performance. The behavior + will now on most systems be that (both OS and Erlang) + monotonic time stops when the system is suspended.</p> + <p> + If you prefer that monotonic time elapse during suspend + of the machine, you can pass the command line argument + <c>--enable-prefer-elapsed-monotonic-time-during-suspend</c> + to <c>configure</c> when building Erlang/OTP. The + configuration stage will try to find such a clock source, + but might not be able to find it. Note that there might + be a performance penalty associated with such a clock + source.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12895</p> + </item> + <item> + <p> + <c>erlang:system_info(end_time)</c> returned a faulty + value on 32-bit architectures.</p> + <p> + Own Id: OTP-12896</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The <c>configure</c> command line argument + <c>--enable-gettimeofday-as-os-system-time</c> has been + added which force usage of <c>gettimeofday()</c> for OS + system time. This will improve performance of + <c>os:system_time()</c> and <c>os:timestamp()</c> on + MacOS X, at the expense of worse accuracy, resolution and + precision of Erlang monotonic time, Erlang system time, + and OS system time.</p> + <p> + Own Id: OTP-12892</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.0.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix a rare hanging of the VM seen to happen just after + emulator start. Bug exists since R14.</p> + <p> + Own Id: OTP-12859 Aux Id: seq12882 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 7.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix issuing with spaces and quoting in the arguments when + using erlang:open_port spawn_executable on windows. The + behavior now mimics how unix works. This change implies a + backwards incompatibility for how spawn_executable works + on windows.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11905</p> + </item> + <item> + <p> + Fix global call trace when hipe compiled code call beam + compiled functions. Tracing of beam functions should now + alway work regardless who the caller is.</p> + <p> + Own Id: OTP-11939</p> + </item> + <item> + <p> + Correct cache alignment for ETS <c>write_concurrency</c> + locks to improve performance by reduced false sharing. + May increase memory footprint for tables with + <c>write_concurrency</c>.</p> + <p> + Own Id: OTP-11974</p> + </item> + <item> + <p> + All possibly blocking operations in the fd/spawn and + terminal driver have been converted to non-blocking + operations. Before this fix it was possible for the VM to + be blocked for a long time if the entity consuming + stdout/stderr did not consume it fast enough.</p> + <p> + Own Id: OTP-12239</p> + </item> + <item> + <p> + Add missing overhead for offheap binaries created from + external format. This fix can improve the garbage + collection of large binaries originating from + <c>binary_to_term</c> or messages from remote nodes.</p> + <p> + Own Id: OTP-12554</p> + </item> + <item> + <p> + Ensure hashing of zero is consistent</p> + <p> Erlang treats positive and negative zero as + equal:</p> + <p> + <c>true = 0.0 =:= 0.0/-1</c></p> + <p>However, Erlangs hash functions: hash, phash and + phash2 did not reflect this behaviour. The hash values + produced by the different hash functions would not be + identical for positive and negative zero.</p> <p>This + change ensures that hash value of positive zero is always + produced regardless of the signedness of the zero float, + i.e.,</p> + <p> + <c>true = erlang:phash2(0.0) =:= + erlang:phash2(0.0/-1)</c></p> + <p> + Own Id: OTP-12641</p> + </item> + <item> + <p> + Ensure NIF term creation disallows illegal floating point + values and too long atoms. Such values will cause a NIF + to throw badarg exception when it returns.</p> + <p> + Own Id: OTP-12655</p> + </item> + <item> + <p> + Fixed building of Map results from match_specs</p> + <p> + A faulty "box-value" entered into the heap which could + cause a segmentation fault in the garbage collector if it + was written on a heap fragment.</p> + <p> + Own Id: OTP-12656</p> + </item> + <item> + <p> + Fix hipe bug when matching a "writable" binary. The bug + has been seen to sometimes cause a failed binary matching + of a correct utf8 character, but other symptoms are also + possible.</p> + <p> + Own Id: OTP-12667</p> + </item> + <item> + <p> + Keep dirty schedulers from waking other schedulers.</p> + <p> + Own Id: OTP-12685</p> + </item> + <item> + <p> + Disable floating point exceptions if the VM is compiled + by clang/llvm. This is a known long-standing problem in + clang/llvm.</p> + <p> + Own Id: OTP-12717</p> + </item> + <item> + <p> + Fix bug in <c>file:sendfile</c> for FreeBSD causing not + the entire file to be sent.</p> + <p> + Own Id: OTP-12720</p> + </item> + <item> + <p> + Fix the broken Android support in erl_child_setup.c</p> + <p> + Own Id: OTP-12751</p> + </item> + <item> + <p> + Faulty statistics reported by the <c>fix_alloc</c> + allocator.</p> + <p> + Own Id: OTP-12766</p> + </item> + <item> + <p> + Fix two erts_snprintf() calls to correct sizes.</p> + <p> + - run_erl.c (ose): Use the size of the signal type, not + its pointer. - erl_node_tables.c: Use the size of the + _BUFFER in erts_snprintf() to make sure we can use the + full space.</p> + <p> + Own Id: OTP-12771</p> + </item> + <item> + <p> + Delayed memory allocations could be delayed an + unnecessarily long time.</p> + <p> + Own Id: OTP-12812</p> + </item> + <item> + <p> + Make sure that timeouts on a pool of acceptors are + released in the correct order.</p> + <p> + Own Id: OTP-12817</p> + </item> + <item> + <p> + Fix segmentation fault in module_info for deleted modules</p> + <p> + Own Id: OTP-12820</p> + </item> + <item> + <p>Fix garbage collection of literals in code purge</p> + <p>During code purging and check_process_code, the + checking of the binary reference embedded in the match + binary state was omitted for the tracing tests. This + would cause the binary match state to reference + deallocated memory.</p> + <p> + Own Id: OTP-12821</p> + </item> + <item> + <p> + A bug has been corrected for gen_tcp:close so when + {linger,{true,0}} is in effect it does not wait for data + in the driver queue to transfer out before closing the + port. Bug fix by Rory Byrne.</p> + <p> + Own Id: OTP-12840</p> + </item> + <item> + <p> + The documentation of the driver callback <seealso + marker="driver_entry#start"><c>start()</c></seealso> + erroneously stated that a return value of + <c>ERL_DRV_ERROR_ERRNO</c> caused the error value to be + passed via <c>erl_errno</c> when it should have been + <c>errno</c>.</p> + <p> + Own Id: OTP-12855</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add <c>md5</c> and <c>module</c> entries to + <c>?MODULE:module_info/0/1</c> and remove obsolete entry + 'import'.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11940</p> + </item> + <item> + <p> + Debug function <c>erlang:display/1</c> shows content of + binaries and bitstrings, not only the length.</p> + <p> + Own Id: OTP-11941</p> + </item> + <item> + <p>The time functionality of Erlang has been extended. + This both includes a <seealso + marker="time_correction#The_New_Time_API">new + API</seealso> for time, as well as <seealso + marker="time_correction#Time_Warp_Modes">time warp + modes</seealso> which alters the behavior of the system + when system time changes. <em>You are strongly encouraged + to use the new API</em> instead of the old API based on + <seealso + marker="erlang#now/0"><c>erlang:now/0</c></seealso>. + <c>erlang:now/0</c> has been deprecated since it is and + forever will be a scalability bottleneck. For more + information see the <seealso + marker="time_correction">Time and Time + Correction</seealso> chapter of the ERTS User's + Guide.</p> + <p>Besides the API changes and time warp modes a lot of + scalability and performance improvements regarding time + management has been made internally in the runtime + system. Examples of such improvements are scheduler + specific timer wheels, scheduler specific BIF timer + management, parallel retrieval of monotonic time and + system time on systems with primitives that are not + buggy.</p> + <p> + Own Id: OTP-11997</p> + </item> + <item> + <p><c>erlang:function_exported(M, F, A)</c> will now + return <c>true</c> if <c>M:F/A</c> refers to a BIF.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12099</p> + </item> + <item> + <p> + New BIF: <c>erlang:get_keys/0</c>, lists all keys + associated with the process dictionary. Note: + <c>erlang:get_keys/0</c> is auto-imported.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12151 Aux Id: seq12521 </p> + </item> + <item> + <p> + Make distributed send of large messages yield to improve + real-time characteristics.</p> + <p> + Own Id: OTP-12232</p> + </item> + <item> + <p> + Use high accuracy poll timeouts</p> + <p> + Where available, use poll/select API's that can handle + time resolutions less than 1ms. In the cases where such + API's are not available the timeout is rounded up to the + nearest ms.</p> + <p> + Own Id: OTP-12236</p> + </item> + <item> + <p> + The internal group to user_drv protocol has been changed + to be synchronous in order to guarantee that output sent + to a process implementing the user_drv protocol is + printed before replying. This protocol is used by the + standard_output device and the ssh application when + acting as a client. </p> + <p> + This change changes the previous unlimited buffer when + printing to standard_io and other devices that end up in + user_drv to 1KB.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12240</p> + </item> + <item> + <p>The previously introduced "eager check I/O" feature is + now enabled by default.</p> + <p>Eager check I/O can be disabled using the <c>erl</c> + command line argument: <seealso + marker="erl#+secio"><c>+secio false</c></seealso></p> + <p>Characteristics impact compared to previous + default:</p> <list> <item>Lower latency and smoother + management of externally triggered I/O operations.</item> + <item>A slightly reduced priority of externally triggered + I/O operations.</item> </list> + <p> + Own Id: OTP-12254 Aux Id: OTP-12117 </p> + </item> + <item> + <p> + Properly support maps in match_specs</p> + <p> + Own Id: OTP-12270</p> + </item> + <item> + <p> + The notice that a crashdump has been written has been + moved to be printed before the crashdump is generated + instead of afterwords. The wording of the notice has also + been changed.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12292</p> + </item> + <item> + <p> + New function <c>ets:take/2</c>. Works the same as + <c>ets:delete/2</c> but also returns the deleted + object(s).</p> + <p> + Own Id: OTP-12309</p> + </item> + <item> + <p> + Tracing with cpu_timestamp option has been enabled on + Linux.</p> + <p> + Own Id: OTP-12366</p> + </item> + <item> + <p> + ets:info/1,2 now contains information about whether + write_concurrency or read_concurrency is enabled.</p> + <p> + Own Id: OTP-12376</p> + </item> + <item> + <p> + Improved usage of <c>gcc</c>'s builtins for atomic memory + access. These are used when no other implementation of + atomic memory operations is available. For example, when + compiling for ARM when <c>libatomic_ops</c> is not + available.</p> + <p> + The largest improvement will be seen when compiling with + a <c>gcc</c> with support for the <c>__atomic_*</c> + builtins (using a <c>gcc</c> of at least version 4.7), + but also when only the legacy <c>__sync_*</c> builtins + are available (using a <c>gcc</c> of at least version + 4.1) an improvement can be seen.</p> + <p> + For more information see the "<seealso + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP_Configuring_Atomic-Memory-Operations-and-the-VM">Atomic + Memory Operations and the VM</seealso>" section of + <c>$ERL_TOP/HOWTO/INSTALL.md</c>.</p> + <p> + Own Id: OTP-12383</p> + </item> + <item> + <p> + Introduce <c>math:log2/1</c> function to math module.</p> + <p> + Own Id: OTP-12411</p> + </item> + <item> + <p>The documentation of the Abstract Format (in the ERTS + User's Guide) has been updated with types and + specification. (Thanks to Anthony Ramine.) </p> <p> The + explicit representation of parentheses used in types of + the abstract format has been removed. Instead the new + functions <c>erl_parse:type_inop_prec()</c> and + <c>erl_parse:type_preop_prec()</c> can be used for + inserting parentheses where needed. </p> + <p> + Own Id: OTP-12492</p> + </item> + <item> + <p> + Remove perfctr support</p> + <p> + Development of perfctr in the linux kernel ceased in + 2010. The perfctr support code in the Erlang VM is thus + effectively dead code and therefor removed.</p> + <p> + Own Id: OTP-12508</p> + </item> + <item> + <p><c>zlib:inflateChunk/2</c> has been added. It works + like <c>zlib:inflate/2</c>, but decompresses no more data + than will fit in the buffer configured by + <c>zlib:setBufSize/2</c>.</p> + <p> + Own Id: OTP-12548</p> + </item> + <item> + <p> + Use linear search for small select_val arrays</p> + <p> + Own Id: OTP-12555</p> + </item> + <item> + <p> + New BIF ets:update_counter/4 with a default object as + argument, which will be inserted in the table if the key + was not found.</p> + <p> + Own Id: OTP-12563</p> + </item> + <item> + <p> + Export missing types from zlib module</p> + <p> + Own Id: OTP-12584</p> + </item> + <item> + <p> + Use persistent hashmaps for large Maps</p> + <p>Maps will use a + persistent hashmap implementation when the number of + pairs in a Map becomes sufficiently large. The change + will occur when a Map reaches 33 pairs in size but this + limit might change in the future.</p> + <p>The most significant impact for the user by this + change is speed, and to a lesser degree memory + consumption and introspection of Maps. Memory consumption + size is probalistic but lesser than <c>gb_trees</c> or + <c>dict</c> for instance. Any other impacts will be + transparent for the user except for the following + changes.</p> + <p>Semantics of Maps have changed in two incompatible + ways compared to the experimental implementation in OTP + 17:</p> <list> <item>Hashing of maps is done different by + <c>erlang:phash2/1,2</c>, <c>erlang:phash/1</c> and + <c>erlang:hash/2</c>.</item> <item>Comparing two maps + with ==, /=, =<, <, >= and >, is done + different if the keys contain floating point + numbers.</item> </list> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12585</p> + </item> + <item> + <p> + Scalability improvement for <seealso + marker="erlang#make_ref/0">erlang:make_ref/0</seealso>, + and other functionality that create references. Each + scheduler now manage its own set of references. By this + no communication at all is needed when creating + references.</p> + <p> + Previous implementation generated a strictly + monotonically increasing sequence of references + corresponding to creation time on the runtime system + instance. This is <em>not</em> the case with current + implementation. You can only expect reference to be + unique. The Erlang/OTP documentation has never mentioned + anything else but the uniqueness property, so this change + <em>is</em> fully compatible. The only reason we've + marked this as a potential incompatibility is since an + early draft for an Erlang specification mentions strict + monotonicity as a property.</p> + <p> + If you need to create data with a strict monotonicity + property use <seealso + marker="erlang#unique_integer/1">erlang:unique_integer([monotonic])</seealso>. + Do <em>not</em> use the deprecated <seealso + marker="erlang#now/0">erlang:now()</seealso>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12610</p> + </item> + <item> + <p> + Enable different abort signal from heart</p> + <p>By using environment variable HEART_KILL_SIGNAL, heart + can now use a different signal to kill the old running + Erlang.</p> + <p>By default the signal is SIGKILL but SIGABRT may also + be used by setting environment variable: + HEART_KILL_SIGNAL=SIGABRT</p> + <p> + Own Id: OTP-12613 Aux Id: seq12826 </p> + </item> + <item> + <p> + Update autconf to latest version 2015-03-04</p> + <p> + Own Id: OTP-12646</p> + </item> + <item> + <p> + Optimization of timers internally in the VM. This include + process timers (<c>receive ... after</c>), port timers + (<c>driver_set_timer()</c>) as well as BIF timers + (<c>erlang:send_after()</c>/<c>erlang:start_timer()</c>).</p> + <p> + Each scheduler thread now has its own lock-free timer + service instead of one locked central service. This + dramatically improves performance of timer management on + systems with a large amount of schedulers and timers.</p> + <p> + The timer service internal data structure has also been + optimized to be able to handle more timers than before. + That is, each timer service is by its self able to handle + more timers without dramatic performance loss than the + old centralized timer service.</p> + <p> + The API of BIF timers has also been extended. Timeout + values are for example no longer limited to 32-bit + integers. For more information see the documentation of + <seealso + marker="erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso>, + <seealso + marker="erlang#send_after/4"><c>erlang:send_after/4</c></seealso>, + <seealso + marker="erlang#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>, + and <seealso + marker="erlang#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p> + <p> + Characteristics impact: Calls to the synchronous versions + of <c>erlang:cancel_timer()</c>, and + <c>erlang:read_timer()</c> may take substantially longer + time to complete than before. This occur when the timer + that is accessed is managed by a remote scheduler. You + typically want to use the new asynchronous option in + order to avoid blocking the calling process.</p> + <p> + Own Id: OTP-12650 Aux Id: OTP-11997 </p> + </item> + <item> + <p> + Specialize instructions from common assembler patterns</p> + <p>Specialize common instructions of <c>rem</c>, + <c>band</c>, <c>minus</c> and <c>plus</c> in the beam + loader. This will reduce the number of fetches and thus + lessen the instruction dispatch pressure during runtime + and speed up those operations in some common cases.</p> + <p>Specialize move patterns from x-registers to the stack + with a new <c>move_window</c> instruction. This change + will reduce instruction dispatch pressure.</p> + <p> + Own Id: OTP-12690</p> + </item> + <item> + <p> + Fix cross compilation for Android.</p> + <p> + Own Id: OTP-12693</p> + </item> + <item> + <p> + Fix incorrect use of autoconf macro AC_EGREP_CPP, which + could cause faulty configuration if run from a path + containing the string 'yes'.</p> + <p> + Own Id: OTP-12706</p> + </item> + <item> + <p> + Minimal Java version is now 1.6</p> + <p> + Own Id: OTP-12715</p> + </item> + <item> + <p> + Send format and args on process exit to error_logger</p> + <p> + Previously, the emulator would generate a whole string + with values and call the error_logger passing + <c>"~s~n"</c>. This changes it to a format string + containing <c>~p</c> with the respective values as + arguments.</p> + <p> + Own Id: OTP-12735</p> + </item> + <item> + <p> + Map error logger warnings to warning messages by default.</p> + <p> + Own Id: OTP-12755</p> + </item> + <item> + <p> + Configure architecture ppc64le architecture as a ppc64</p> + <p> + Own Id: OTP-12761</p> + </item> + <item> + <p> + Add function <c>enif_raise_exception</c> to allow a NIF + to raise an error exception with any type of reason.</p> + <p> + Own Id: OTP-12770</p> + </item> + <item> + <p> + Optimized node table statistics retrieval.</p> + <p> + Own Id: OTP-12777</p> + </item> + <item> + <p> + Map beam error logger warnings to warning messages by + default. Previously these messages were mapped to the + error channel by default.</p> + <p> + Own Id: OTP-12781</p> + </item> + <item> + <p> + gen_tcp:shutdown/2 is now asynchronous</p> + <p> + This solves the following problems with the old + implementation:</p> + <p> + It doesn't block when the TCP peer is idle or slow. This + is the expected behaviour when shutdown() is called: the + caller needs to be able to continue reading from the + socket, not be prevented from doing so.</p> + <p> + It doesn't truncate the output. The current version of + gen_tcp:shutdown/2 will truncate any outbound data in the + driver queue after about 10 seconds if the TCP peer is + idle of slow. Worse yet, it doesn't even inform anyone + that the data has been truncated: 'ok' is returned to the + caller; and a FIN rather than an RST is sent to the TCP + peer.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12797</p> + </item> + <item> + <p> + Introduced delayed node table GC. This in order to avoid + oscillation of entries in and out of the tables. The + oscillation caused unnecessary lock contention on the + table locks. The delay length can be set by passing the + <seealso marker="erl#+zdntgc"><c>+zdntgc</c></seealso> + command line argument.</p> + <p> + Characteristics impact: The tables can grow to very large + sizes with unused entries if the node is get huge amounts + of short lived connections from other nodes. This problem + can be alleviated by shortening the length of the delay + using the <c>+zdntgc</c> command line argument.</p> + <p> + Own Id: OTP-12802</p> + </item> + <item> + <p>Improved implementation of <seealso + marker="erlang#statistics/1"><c>erlang:statistics</c></seealso><c>(io)</c> + in order to reduce contention between schedulers.</p> + <p>Characteristics impact: The actual call to + <c>erlang:statistics(io)</c> takes longer time to + complete, but the overall impact on the system is + improved.</p> + <p> + Own Id: OTP-12842</p> + </item> + <item> + <p> + There are many cases where user code needs to be able to + distinguish between a socket that was closed normally and + one that was aborted. Setting the option + {show_econnreset, true} enables the user to receive + ECONNRESET errors on both active and passive sockets.</p> + <p> + Own Id: OTP-12843</p> + </item> + <item> + <p> + Do not preallocate too large event pool</p> + <p> + A default pool size of 4000 is too excessive for the + common case. This corresponds directly to the number of + threads in the system. Change + ERTS_TS_EV_ALLOC_DEFAULT_POOL_SIZE to 2048. Change + ERTS_TS_EV_ALLOC_POOL_SIZE to 32.</p> + <p> + Own Id: OTP-12849</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4.1.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed a bug that could cause a crash dump to become + almost empty.</p> + <p> + Own Id: OTP-13150</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4.1.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The 'raw' socket option could not be used multiple times + in one call to any e.g gen_tcp function because only one + of the occurrences were used. This bug has been fixed, + and also a small bug concerning propagating error codes + from within inet:setopts/2.</p> + <p> + Own Id: OTP-11482 Aux Id: seq12872 </p> + </item> + </list> + </section> + +</section> + + +<section><title>Erts 6.4.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The VTS mode in Common Test has been modified to use a + private version of the Webtool application (ct_webtool).</p> + <p> + Own Id: OTP-12704 Aux Id: OTP-10922 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix missing quotation in the <c>LM_FIND_EMU_CC</c> + <c>autoconf</c> macro which could cause build failures.</p> + <p> + Own Id: OTP-12388</p> + </item> + <item> + <p> + Fix erroneous printout of monitors in crashdump file.</p> + <p> + Own Id: OTP-12537</p> + </item> + <item> + <p> + The runtime system without SMP support could crash in the + BIF <c>port_control/3</c> if the port that was being + accessed died during the call to the BIF.</p> + <p> + Own Id: OTP-12544 Aux Id: Seq12777 </p> + </item> + <item> + <p> + Avoid corrupt oversized integer to be created from binary + matching. Instead throw system_limit exception which is + the correct behavior. A peculiar symptom of this bug was + that bitwise operations (band, bor, bxor) on such + oversized integers could return the empty list []. + Credit: Mikael Pettersson, Nico Kruber</p> + <p> + Own Id: OTP-12556</p> + </item> + <item> + <p> + A race condition when calling <c>port_info/1</c> could + cause a memory fault has been fixed.</p> + <p> + Own Id: OTP-12587</p> + </item> + <item> + <p> + Fix comparison of exact terms. An overflow that could + cause faulty comparisons has been fixed. Comparison of + exact terms is exclusively used within Maps.</p> + <p> + Own Id: OTP-12623</p> + </item> + <item> + <p> + Fix bug in <c>list_to_integer/1</c> for very long lists + that could cause VM crash.</p> + <p> + Own Id: OTP-12624</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Introduced a runtime system internal 64-bit API for + atomic memory operations.</p> + <p> + Own Id: OTP-12351</p> + </item> + <item> + <p> + Add command line argument option for the initial size of + process dictionaries.</p> + <p> + Use '+hpds <size>' to set initial process + dictionary size for spawned processes.</p> + <p> + Own Id: OTP-12535 Aux Id: seq12809 </p> + </item> + <item> + <p> + Fix documentation on $char for Unicode</p> + <p> + Own Id: OTP-12545</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix getifaddrs realloc pointer error</p> + <p> + When a buffer was exhausted and subsequently reallocated, + we could get an unsafe pointer pointing to faulty memory.</p> + <p> + For this to occur we would need to have a large number of + interfaces and a reallocation of memory to a lower + addresses.</p> + <p> + The symptom would be garbage returned from + erlang:port_control(Port, 25, []) + (prim_inet:getifaddrs(Port) resulting in a badarg) or a + segmentation fault.</p> + <p> + Own Id: OTP-12445</p> + </item> + <item> + <p> + Don't close all file descriptors twice in child_setup</p> + <p> + The commit c2b4eab25c907f453a394d382c04cd04e6c06b49 + introduced an error in which child_setup erroneously + tried to close all file descriptors twice.</p> + <p> + Use closefrom() if available when closing all file + descriptors.</p> + <p> + The function closefrom() was only used in the vfork() + case before but is now also used in the fork() case if + available.</p> + <p> + Own Id: OTP-12446</p> + </item> + <item> + <p> + During a crashdump all file descriptors are closed to + ensure the closing of the epmd port and to reserve a file + descriptor for the crashdump file.</p> + <p> + If a driver (third party library) cannot handle closing + of sockets this could result in a segmentation fault in + which case a crashdump would not be produced. This is now + fixed by only closing inets sockets via an emergency + close callback to the driver and thus closing the epmd + socket.</p> + <p> + Own Id: OTP-12447</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix HiPE debug lock checking on OS X 64bit</p> + <p> + Position-independent code is mandatory on OS X. We use + r11 as an intermediate register to fill + BIF_P->hipe.bif_callee. This fixes the following error + when doing `make debug FLAVOR=smp`:</p> + <p> + clang -cc1as: fatal error: error in backend: 32-bit + absolute addressing is not supported in 64-bit mode</p> + <p> + Own Id: OTP-12188</p> + </item> + <item> + <p> + Fix race bug that could cause VM crash in + <c>erlang:port_get_data/1</c> if the port was closed by a + concurrent process. Also fix fatal bug if + <c>port_set_data/2</c> is called with a non-immediate + data term. Both bugs exist since R16B01.</p> + <p> + Own Id: OTP-12208</p> + </item> + <item> + <p> + Correct make variable SSL_DED_LD_RUNTIME_LIBRARY_PATH + when erl_xcomp_sysroot ends with a slash.</p> + <p> + Own Id: OTP-12216 Aux Id: seq12700 </p> + </item> + <item> + <p> + Fix two cases of unreachable code caused by false use of + assigment operators.</p> + <p> + Own Id: OTP-12222</p> + </item> + <item> + <p> + Fix bug when hipe compiled code makes tail call to a BIF + that disables GC while trapping (sush as binary_to_list, + list_to_binary, binary_to_term, term_to_binary).</p> + <p> + Own Id: OTP-12231</p> + </item> + <item> + <p> + Fix bug when a migrated empty memory carrier is reused + just before it should be destroyed by the thread that + created it.</p> + <p> + Own Id: OTP-12249</p> + </item> + <item> + <p> + Prevents compile-time errors in NIFs, when the compiler + is instructed to treat missing field initializers as + errors, by adding an initializer for the new options + field which was added to ErlNifEntry for 17.3.</p> + <p> + Own Id: OTP-12266</p> + </item> + <item> + <p> + Fixed CPU topology detection on FreeBSD systems where + Erlang/OTP is compiled by new C compilers (including, but + possibly not limited to, gcc 4.9 and clang).</p> + <p> + Own Id: OTP-12267</p> + </item> + <item> + <p> + Use C99 function isfinite() instead of finite() when + available on non GCC compilers.</p> + <p> + Own Id: OTP-12268</p> + </item> + <item> + <p> + Fix bug on windows where an incorrect number of links + could be returned when doing file:read_file_info on a + directory.</p> + <p> + Own Id: OTP-12269</p> + </item> + <item> + <p> + Fix rare bug when purging module on VM started with + +Meamin.</p> + <p> + Own Id: OTP-12273</p> + </item> + <item> + <p> + Repair run_erl terminal window size adjustment sent from + to_erl. This was broken in OTP 17.0 which could lead to + strange cursor behaviour in the to_erl shell.</p> + <p> + Own Id: OTP-12275 Aux Id: seq12739 </p> + </item> + <item> + <p> + Fixed bug on windows causing gen_tcp/udp to return an + error when given an fd to work with.</p> + <p> + Own Id: OTP-12289</p> + </item> + <item> + <p> + Fix various internal erts issues where negating a signed + integer in C would trigger undefined behavior. This fixes + issues when dividing with bignums and list_to_integer.</p> + <p> + Own Id: OTP-12290</p> + </item> + <item> + <p> + When flushing output to stdout on windows, the emulator + could sometimes hang indefinitely waiting for the flush + to complete. This has been fixed.</p> + <p> + Own Id: OTP-12291</p> + </item> + <item> + <p> + Fix so that non-smp emulators with dirty scheduler + support shows the correct number of dirty schedulers when + calling erlang:system_info(system_version).</p> + <p> + Own Id: OTP-12295</p> + </item> + <item> + <p> + Add <c>nif_version</c> to <c>erlang:system_info/1</c> in + order to get the NIF API version of the runtime system in + a way similar to <c>driver_version</c>.</p> + <p> + Own Id: OTP-12298</p> + </item> + <item> + <p> + Fix bug that could cause the return value from dirty NIF + with zero arity to be treated as garbage, leading to VM + crash.</p> + <p> + Own Id: OTP-12300</p> + </item> + <item> + <p> + Improve allocation carrier migration search logic. This + will reduce the risk of failed migrations that could lead + to excess memory consumption. It will also improve smp + performance due to reduced memory contention on the + migration pool.</p> + <p> + Own Id: OTP-12323</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Introduced support for eager check I/O.</p> + <p>By default eager check I/O will be disabled, but this + will most likely be changed in OTP 18. When eager check + I/O is enabled, schedulers will more frequently check for + I/O work. Outstanding I/O operations will however not be + prioritized to the same extent as when eager check I/O is + disabled.</p> + <p>Eager check I/O can be enabled using the <c>erl</c> + command line argument: <seealso + marker="erl#+secio"><c>+secio true</c></seealso></p> + <p>Characteristics impact when enabled:</p> <list> + <item>Lower latency and smoother management of externally + triggered I/O operations.</item> <item>A slightly reduced + priority of externally triggered I/O operations.</item> + </list> + <p> + Own Id: OTP-12117</p> + </item> + <item> + <p> + Fix erts .app-file</p> + <p> + Own Id: OTP-12189</p> + </item> + <item> + <p> + Add configure option --with-ssl-incl=PATH to support + OpenSSL installations with headers and libraries at + different places.</p> + <p> + Own Id: OTP-12215 Aux Id: seq12700 </p> + </item> + <item> + <p> + Optimization of atomic memory operations with release + barrier semantics on 32-bit PowerPC when using the + implementation included in OTP.</p> + <p> + Own Id: OTP-12250</p> + </item> + <item> + <p> + Minor adjustment of scheduler activation code making sure + that an activation of a scheduler is not prevented by its + run-queue being non-empty. (Thanks to Songlu Cai)</p> + <p> + Own Id: OTP-12287</p> + </item> + <item> + <p> + Improved support for atomic memory operations provided by + the <url + href="https://github.com/ivmai/libatomic_ops/">libatomic_ops</url> + library. Most importantly support for use of native + double word atomics when implemented by + <c>libatomic_ops</c> (for example, implemented for ARM).</p> + <p> + The <seealso + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP_Configuring_Atomic-Memory-Operations-and-the-VM"><c>$ERL_TOP/HOWTO/INSTALL.md</c></seealso> + document now also more clearly describes when you want to + build together with a <c>libatomic_ops</c> installation.</p> + <p> + Own Id: OTP-12302</p> + </item> + <item> + <p> + Add configure option --with-ssl-rpath to control which + runtime library path to use for dynamic linkage toward + OpenSSL.</p> + <p> + Own Id: OTP-12316 Aux Id: seq12753 </p> + </item> + <item> + <p> + Added systemd notify support to epmd</p> + <p> + Own Id: OTP-12321</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix bug when an migrated empty memory carrier is reused + just before it should be destroyed by the thread that + created it.</p> + <p> + Own Id: OTP-12249</p> + </item> + <item> + <p> + Repair run_erl terminal window size adjustment sent from + to_erl. This was broken in OTP 17.0 which could lead to + strange cursor behaviour in the to_erl shell.</p> + <p> + Own Id: OTP-12275 Aux Id: seq12739 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + General documentation updates.</p> + <p> + Own Id: OTP-12052</p> + </item> + <item> + <p>A bug in the VM code implementing sending of signals + to ports could cause the receiving port queue to remain + in a busy state forever. When this state had been + reached, processes sending command signals to the port + either got suspended forever, or, if the <c>nosuspend</c> + feature was used, always failed to send to the port. This + bug was introduced in ERTS version 5.10.</p> + <p>In order for this bug to be triggered on a port, one + had to at least once utilize the <c>nosuspend</c> + functionality when passing a signal to the port. This by + either calling</p> <list> <item> <seealso + marker="erlang#port_command/3"><c>port_command(Port, + Data, [nosuspend | Options])</c></seealso>, </item> + <item> <seealso + marker="erlang#send/3"><c>erlang:send(Port, {PortOwner, + {command, Data}}, [nosuspend | Options])</c></seealso>, + </item> <item> <seealso + marker="erlang#send_nosuspend/2"><c>erlang:send_nosuspend(Port, + {PortOwner, {command, Data}})</c></seealso>, or </item> + <item> <seealso + marker="erlang#send_nosuspend/3"><c>erlang:send_nosuspend(Port, + {PortOwner, {command, Data}}, Options)</c></seealso>. + </item> </list> + <p>Thanks Vasily Demidenok for reporting the issue, and + Sergey Kudryashov for providing a testcase.</p> + <p> + Own Id: OTP-12082 Aux Id: OTP-10336 </p> + </item> + <item> + <p> + Fix size overflow bug at memory allocation. A memory + allocation call, with an insane size close to the entire + address space, could return successfully as if it had + allocated just a few bytes. (Thanks to Don A. Bailey for + reporting)</p> + <p> + Own Id: OTP-12091</p> + </item> + <item> + <p> + Fix various issues where negating a signed integer would + trigger undefined behaviour. This fixes issues in the + enif_make_int64 interface and some edge cases inside the + erlang runtime system.</p> + <p> + Own Id: OTP-12097</p> + </item> + <item> + <p> + The documentation erroneously listed the <seealso + marker="erl#+swct"><c>+swct</c></seealso> command line + argument under <c>+sws</c>.</p> + <p> + Own Id: OTP-12102 Aux Id: OTP-10994 </p> + </item> + <item> + <p> + Profiling messages could be delivered out of order when + profiling on <c>runnable_procs</c> and/or + <c>runnable_ports</c> using <seealso + marker="erlang#system_profile/2"><c>erlang:system_profile/2</c></seealso>. + This bug was introduced in ERTS version 5.10.</p> + <p> + Own Id: OTP-12105 Aux Id: OTP-10336 </p> + </item> + <item> + <p> + Various logging fixes, including: Add run queue index to + the process dump in crash dumps.<br/> Add thread index to + enomem slogan when crashing.<br/> Remove error logger + message for sending messages to old instances of the same + node.</p> + <p> + Own Id: OTP-12115</p> + </item> + <item> + <p> + Fix compiler warnings reported by LLVM</p> + <p> + Own Id: OTP-12138</p> + </item> + <item> + <p> + Correct conversion of <c>MIN_SMALL</c> by + <c>list_to_integer/1</c> and <c>binary_to_integer/1</c>. + The bug produced an unnormalized bignum which can cause + strange behavior such as comparing different to a correct + <c>MIN_SMALL</c> integer. The value <c>MIN_SMALL</c> is + <c>-(1 bsl 27) = -134217728</c> on a 32-bit VM and <c>-(1 + bsl 59) = -576460752303423488</c> on a 64-bit VM. (Thanks + to Jesper Louis Andersen, Mikael Pettersson and Anthony + Ramine for report, patch and optimization suggestion)</p> + <p> + Own Id: OTP-12140</p> + </item> + <item> + <p> + Fix bug in <c>term_to_binary</c> that reallocates binary + with inconsistent size information. Bug has never been + confirmed to be the cause of any faulty behavior.</p> + <p> + Own Id: OTP-12141</p> + </item> + <item> + <p> + Real_path method used while prim loading archive files + was not taking into account the fact that windows + directory symlinks can be across different drives.</p> + <p> + Own Id: OTP-12155</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add log2 histogram to lcnt for lock wait time</p> + <p> + Own Id: OTP-12059</p> + </item> + <item> + <p> + Introduced <seealso + marker="erl_nif#enif_schedule_nif"><c>enif_schedule_nif()</c></seealso> + to the NIF API.</p> + <p> + The <c>enif_schedule_nif()</c> function allows a + long-running NIF to be broken into separate NIF + invocations without the help of a wrapper function + written in Erlang. The NIF first executes part of the + long-running task, then calls <c>enif_schedule_nif()</c> + to schedule a NIF for later execution to continue the + task. Any number of NIFs can be scheduled in this manner, + one after another. Since the emulator regains control + between invocations, this helps avoid problems caused by + native code tying up scheduler threads for too long.</p> + <p> + The <c>enif_schedule_nif()</c> function also replaces the + <c>enif_schedule_dirty_nif()</c> in the experimental + dirty NIF API. Note that the only incompatible changes + made are in the experimental dirty NIF API.</p> + <p> + See the <seealso marker="erl_nif">NIF + documentation</seealso> for more information.</p> + <p> + Thanks to Steve Vinoski.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-12128</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + OTP-11850 fixed filelib:wildcard/1 to work with broken + symlinks. This correction, however, introduced problems + since symlinks were no longer followed for functions like + filelib:ensure_dir/1, filelib:is_dir/1, + filelib:file_size/1, etc. This is now corrected.</p> + <p> + Own Id: OTP-12054 Aux Id: seq12660 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed ETHR_FORCE_INLINE which caused the build to break + on some platforms without adequate thread support + (VxWorks).</p> + <p> + Own Id: OTP-12010</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>The documentation for <c>spawn_opt/5</c> now has a + note mentioning that the <c>monitor</c> option is not + supported.</p> + <p> + Own Id: OTP-11849</p> + </item> + <item> + <p> + Fix broken system monitoring of <c>large_heap</c> for + non-smp VM. No message for <c>large_heap</c> was ever + sent on non-smp VM. Bug exist since R16B.</p> + <p> + Own Id: OTP-11852</p> + </item> + <item> + <p> + The emulator without SMP support crashed when passing a + message to a process without enough heap space for the + message. This bug was introduced in <c>erts-6.0</c>.</p> + <p> + Own Id: OTP-11887 Aux Id: OTP-11388 </p> + </item> + <item> + <p> + Fix race between ETS table deletion and unfixation that + could cause VM crash. The race could happen between a + terminating process that does not own the table but has a + fixation on it and another process that deletes the table + (maybe the owner terminating) at the same time. Bug + existed since R15B02.</p> + <p> + Own Id: OTP-11892</p> + </item> + <item> + <p>The string following the <c>-eval</c> option when + invoking <c>erl</c> would not be properly translated from + UTF-8 to a list of Unicode characters (as would the + arguments for <c>-run</c>).</p> + <p>That bug would cause the build of Erlang/OTP to fail + when building in a directory whose pathname contained + non-US ASCII characters encoded in UTF-8. (Thanks to Eric + Pailleau for reporting this bug.)</p> + <p> + Own Id: OTP-11916</p> + </item> + <item> + <p> + Fix erts_debug:size/1 to handle Map sizes</p> + <p> + Own Id: OTP-11923</p> + </item> + <item> + <p> + Removed <c>erlang:bitstr_to_list/1</c> and + <c>erlang:list_to_bitstr/1</c>. They were added by + mistake, and have always raised an <c>undefined</c> + exception when called.</p> + <p> + Own Id: OTP-11942</p> + </item> + <item> + <p> + Fixed compilation using mingw-w64 on Windows.</p> + <p> + Thanks to Jani Hakala.</p> + <p> + Own Id: OTP-11945</p> + </item> + <item> + <p> + The git sha is no longer printed in the shell start + header when erlang is built from a tagged git release.</p> + <p> + Own Id: OTP-11961</p> + </item> + <item> + <p> + Fixed a bug where <c>send</c> trace events were + erroneously dropped when the send was done to a + registered process. This bug was introduced in R16B.</p> + <p> + Own Id: OTP-11968</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>The following native functions now bump an appropriate + amount of reductions and yield when out of + reductions:</p> <list> + <item><c>erlang:binary_to_list/1</c></item> + <item><c>erlang:binary_to_list/3</c></item> + <item><c>erlang:bitstring_to_list/1</c></item> + <item><c>erlang:list_to_binary/1</c></item> + <item><c>erlang:iolist_to_binary/1</c></item> + <item><c>erlang:list_to_bitstring/1</c></item> + <item><c>binary:list_to_bin/1</c></item> </list> + <p>Characteristics impact:</p> <taglist> + <tag>Performance</tag> <item>The functions converting + from lists got a performance loss for very small lists, + and a performance gain for very large lists.</item> + <tag>Priority</tag> <item>Previously a process executing + one of these functions effectively got an unfair priority + boost. This priority boost depended on the input size. + The larger the input was, the larger the priority boost + got. This unfair priority boost is now lost. </item> + </taglist> + <p> + Own Id: OTP-11888</p> + </item> + <item> + <p> + The systemd features of epmd have been removed from epmd + by default. To enable them you have to build erlang with + the configure option --enable-systemd.</p> + <p> + Own Id: OTP-11921</p> + </item> + <item> + <p> + Removed Erlang wrapper code used when calling + <c>binary_to_term/1</c>, and <c>binary_to_term/2</c>. + This improves the performance of these BIFs especially + when they are called with small binaries as input.</p> + <p> + Own Id: OTP-11931</p> + </item> + <item> + <p> + Add erlang:system_info(tolerant_timeofday), an API to + check whether compensation for sudden changes of system + time is enabled or not.</p> + <p> + Own Id: OTP-11970</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.0.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix broken system monitoring of <c>large_heap</c> for + non-smp VM. No message for <c>large_heap</c> was ever + sent on non-smp VM. Bug exist since R16B.</p> + <p> + Own Id: OTP-11852</p> + </item> + <item> + <p> + Fixed type spec of <c>erlang:system_info/1</c>.</p> + <p> + Own Id: OTP-11859 Aux Id: OTP-11615 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The option dupnames did not work as intended in re. When + looking for names with {capture, [Name, ...]}, re:run + returned a random instance of the match for that name, + instead of the leftmost matching instance, which was what + the documentation stated. This is now corrected to adhere + to the documentation. The option {capture,all_names} + along with a re:inspect/2 function is also added to + further help in using named subpatterns.</p> + <p> + Own Id: OTP-11205</p> + </item> + <item> + <p> + Allow loading of NIF library with unicode path name</p> + <p> + Own Id: OTP-11408</p> + </item> + <item> + <p> + Allow loading of driver with unicode path name</p> + <p> + Own Id: OTP-11549</p> + </item> + <item> + <p> + Fixed a bug where starting Erlang without having an open + stdin on fd 0 would sometimes deadlock the emulator when + terminating.</p> + <p> + Own Id: OTP-11558</p> + </item> + <item> + <p> + The option '-names' in epmd now works on Windows (Thanks + to Johannes Weißl)</p> + <p> + Own Id: OTP-11565</p> + </item> + <item> + <p> + Correction of the examples in escript documentation. + (Thanks to Pierre Fenoll).</p> + <p> + Own Id: OTP-11577</p> + </item> + <item> + <p> + Fix bs_get_integer instruction</p> + <p> + The instruction bs_get_integer could unnecessarily + trigger a garbage collection in failure cases which is + unwanted or outright dangerous.</p> + <p> + Ex:</p> + <p> + <<X:Sz,_/bits>> = <<"some + binary">></p> + <p> + Previously, if Sz induced X to a bignum it would reserved + memory size this on the heap via a garbage collection + before checking if the size could actually match.</p> + <p> + It will now check the binary size before triggering a + collection.</p> + <p> + Own Id: OTP-11581</p> + </item> + <item> + <p> + Remove heap space overestimation in <c>binary_to_term</c> + (and remote message reception) for integers in the + intervals [-2147483648,-1] and [256,2147483647] on 64-bit + emulators.</p> + <p> + Own Id: OTP-11585</p> + </item> + <item> + <p> + Add support for detecting the separate tinfo library from + ncurses (Thanks to Dirkjan Ochtman)</p> + <p> + Own Id: OTP-11590</p> + </item> + <item> + <p> + Deprecation warning for system_flag(cpu_topology) has + been extended for removal in OTP 18 (Thanks to Steve + Vinoski for the update)</p> + <p> + Own Id: OTP-11602</p> + </item> + <item> + <p> + Documentation improvement regarding some awkward wording + around the +spp flag. (Thanks to Brian L. Troutwine )</p> + <p> + Own Id: OTP-11607</p> + </item> + <item> + <p> + Fixed bug where sendfile would return the wrong error + code for a remotely closed socket if the socket was in + passive mode. (Thanks to Vincent Siliakus for reporting + the bug.)</p> + <p> + Own Id: OTP-11614</p> + </item> + <item> + <p> + Increase garbage collection tenure rate</p> + <p>The garbage collector tries to maintain the previous + heap block size during a minor gc, i.e. 'need' is not + utilized in determining the size of the new heap, instead + it relies on tenure and garbage to be sufficiently + large.</p> + <p>In instances during intense growing with exclusively + live data on the heap coupled with delayed tenure, + fullsweeps would be triggered directly after a minor gc + to make room for 'need' since the new heap would be + full.</p> + <p>To remedy this, the tenure of terms on the minor heap + will always happen (if it is below the high watermark) + instead of every other minor gc.</p> + <p>Characteristics Impact: Reduced CPU-time spent in + garbage collection but may infer delays in collecting + garbage from the heap. Tweak 'fullsweep_after' options to + increase gc pressure if needed.</p> + <p> + Own Id: OTP-11617</p> + </item> + <item> + <p> + Fix bug when comparing integers with floats larger than + 2^992. The bug could potentially cause memory corruption + on 32-bit emulators.</p> + <p> + Own Id: OTP-11618</p> + </item> + <item> + <p> + Cross-compilation fixes for TileraMDE-3.0.1.125620</p> + <p> + Own Id: OTP-11635</p> + </item> + <item> + <p> + sendfile no longer uses async threads by default</p> + <p> + This has been done because a slow client attack is + possible if the async thread pool is used. The scenario + is:</p> + <p> + Client does a request for a file and then slowly receives + the file one byte at a time. This will eventually fill + the async thread pool with blocking sendfile operations + and thus starving the vm of all file operations.</p> + <p> + If you still want to use the async threads pool for + sendfile an option to enable it has been introduced.</p> + <p> + Thanks to Christopher Faulet for identifying this + vulnerability.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11639</p> + </item> + <item> + <p> + Do proper rollback of calls to + <c>enif_open_resource_type</c> when load/upgrade + callbacks of NIF library return failure.</p> + <p> + Own Id: OTP-11722</p> + </item> + <item> + <p> + Changed the default configuration when configuring with + <c>$ERL_TOP/configure</c> to be the same as when + configuring with <c>$ERL_TOP/otp_build configure</c>.</p> + <p> + Previously floating point exceptions got enabled by + default on Linux when HiPE was enabled when configuring + with <c>$ERL_TOP/configure</c>, but not when configuring + with <c>$ERL_TOP/otp_build configure</c>. The default is + now in both cases not to use floating point exceptions + since there still exist unresolved issues with floating + point exceptions on Linux.</p> + <p> + For more information see <seealso + marker="doc/installation_guide:INSTALL"><c>$ERL_TOP/HOWTO/INSTALL.md</c></seealso>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11723</p> + </item> + <item> + <p> + A comment in erl_db_tree.c no longer differ from the + code. (Thanks to Cobus Carstens)</p> + <p> + Own Id: OTP-11793</p> + </item> + <item> + <p> + Fix epmd debug functionality for VxWorks (Thanks to Jay + True)</p> + <p> + Own Id: OTP-11808</p> + </item> + <item> + <p> + Use closefrom/2 when available in child_setup (Thanks to + Rick Reed and Anthony Ramine)</p> + <p> + Own Id: OTP-11809</p> + </item> + <item> + <p> + Fix dtrace/systemtap bug where the probe arguments would + be concatenated due to faulty length calculation. </p> + <p> + Thanks to Michal Ptaszek and Scott Lystig Fritchie</p> + <p> + Own Id: OTP-11816</p> + </item> + <item> + <p> + It is now better documented that the <c>+fn*</c> flags to + <c>erl</c> also affect how command line parameters and + environment variables are read. (Thanks to Vlad + Dumitrescu)</p> + <p> + Own Id: OTP-11818</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Options to set match_limit and match_limit_recursion are + added to re:run. The option report_errors is also added + to get more information when re:run fails due to limits + or compilation errors.</p> + <p> + Own Id: OTP-10285</p> + </item> + <item> + <p> Dialyzer's <c>unmatched_return</c> warnings have been + corrected. </p> + <p> + Own Id: OTP-10908</p> + </item> + <item> + <p> + A common case is to wrap an argument to + <c>list_to_binary/1</c> in a list to ensure conversion + can happen even though the argument may already be a + binary. Take special care of this case and do not copy + binary.</p> + <p> + Impact: May cause incompatibility since a single binary + is no longer copied. Use <c>binary:copy/1,2</c> instead.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11082</p> + </item> + <item> + <p> + Make erlang:open_port/2 spawn and spawn_executable handle + unicode.</p> + <p> + Own Id: OTP-11105</p> + </item> + <item> + <p> + Handle unicode (widestring) in erl, erlc, heart, etc on + windows.</p> + <p> + Own Id: OTP-11135</p> + </item> + <item> + <p> + The version of the PCRE library Used by Erlang's re + module is raised to 8.33 from 7.6. This means, among + other things, better Unicode and Unicode Character + Properties support. New options connected to PCRE 8.33 + are also added to the re module (ucd, notempty_atstart, + no_start_optimize). PCRE has extended the regular + expression syntax between 7.6 and 8.33, why this imposes + a potential incompatibility. Only very complicated + regular expressions may be affected, but if you know you + are using obscure features, please test run your regular + expressions and verify that their behavior has not + changed.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11204</p> + </item> + <item> + <p>Filenames containing UTF-8 encoded characters can now + be handled by erlc.</p> + <p>If you have set the <c>ERLC_EMULATOR</c> environment + variable, note that <c>erlc</c> in OTP 17 will only work + with <c>erl</c> in OTP 17 since the protocol between the + <c>erlc</c> program and the <c>erl_compile</c> module has + changed.</p> + <p> + Own Id: OTP-11248</p> + </item> + <item> + <p> + By giving --enable-static-{nifs,drivers} to configure it + is now possible to statically linking of nifs and drivers + to the main Erlang VM binary. At the moment only the asn1 + and crypto nifs of the Erlang/OTP nifs and drivers have + been prepared to be statically linked. For more details + see the Installation Guide in the System documentation.</p> + <p> + Own Id: OTP-11258</p> + </item> + <item> + <p> + Erlang/OTP has been ported to the realtime operating + system OSE. The port supports both smp and non-smp + emulator. For details around the port and how to started + see the User's Guide in the <seealso + marker="ose:ose_intro">ose</seealso> application. </p> + <p> + Note that not all parts of Erlang/OTP has been ported. </p> + <p> + Notable things that work are: non-smp and smp emulators, + OSE signal interaction, crypto, asn1, run_erl/to_erl, + tcp, epmd, distribution and most if not all non-os + specific functionality of Erlang.</p> + <p> + Notable things that does not work are: udp/sctp, os_mon, + erl_interface, binding of schedulers.</p> + <p> + Own Id: OTP-11334</p> + </item> + <item> + <p> + Add the {active,N} socket option for TCP, UDP, and SCTP, + where N is an integer in the range -32768..32767, to + allow a caller to specify the number of data messages to + be delivered to the controlling process. Once the + socket's delivered message count either reaches 0 or is + explicitly set to 0 with inet:setopts/2 or by including + {active,0} as an option when the socket is created, the + socket transitions to passive ({active, false}) mode and + the socket's controlling process receives a message to + inform it of the transition. TCP sockets receive + {tcp_passive,Socket}, UDP sockets receive + {udp_passive,Socket} and SCTP sockets receive + {sctp_passive,Socket}. </p> + <p> + The socket's delivered message counter defaults to 0, but + it can be set using {active,N} via any gen_tcp, gen_udp, + or gen_sctp function that takes socket options as + arguments, or via inet:setopts/2. New N values are added + to the socket's current counter value, and negative + numbers can be used to reduce the counter value. + Specifying a number that would cause the socket's counter + value to go above 32767 causes an einval error. If a + negative number is specified such that the counter value + would become negative, the socket's counter value is set + to 0 and the socket transitions to passive mode. If the + counter value is already 0 and inet:setopts(Socket, + [{active,0}]) is specified, the counter value remains at + 0 but the appropriate passive mode transition message is + generated for the socket.</p> + <p> + Thanks to Steve Vinoski</p> + <p> + Own Id: OTP-11368</p> + </item> + <item> + <p> + A new optional scheduler utilization balancing mechanism + has been introduced. For more information see the + <seealso marker="erl#+sub"><c>+sub</c></seealso> command + line argument.</p> + <p> + Characteristics impact: None, when not enabled. When + enabled, changed timing in the system, normally a small + overhead due to measuring of utilization and calculating + balancing information. On some systems, such as old + Windows systems, the overhead can be quite substantial. + This time measurement overhead highly depend on the + underlying primitives provided by the OS.</p> + <p> + Own Id: OTP-11385</p> + </item> + <item> + <p> + A call to either the <c>garbage_collect/1</c> BIF or the + <c>check_process_code/2</c> BIF may trigger garbage + collection of another processes than the process calling + the BIF. The previous implementations performed these + kinds of garbage collections without considering the + internal state of the process being garbage collected. In + order to be able to more easily and more efficiently + implement yielding native code, these types of garbage + collections have been rewritten. A garbage collection + like this is now triggered by an asynchronous request + signal, the actual garbage collection is performed by the + process being garbage collected itself, and finalized by + a reply signal to the process issuing the request. Using + this approach processes can disable garbage collection + and yield without having to set up the heap in a state + that can be garbage collected.</p> + <p> + The <seealso + marker="erts:erlang#garbage_collect/2"><c>garbage_collect/2</c></seealso>, + and <seealso + marker="erts:erlang#check_process_code/3"><c>check_process_code/3</c></seealso> + BIFs have been introduced. Both taking an option list as + last argument. Using these, one can issue asynchronous + requests.</p> + <p> + <c>code:purge/1</c> and <c>code:soft_purge/1</c> have + been rewritten to utilize asynchronous + <c>check_process_code</c> requests in order to + parallelize work.</p> + <p> + Characteristics impact: A call to the + <c>garbage_collect/1</c> BIF or the + <c>check_process_code/2</c> BIF will normally take longer + time to complete while the system as a whole wont be as + much negatively effected by the operation as before. A + call to <c>code:purge/1</c> and <c>code:soft_purge/1</c> + may complete faster or slower depending on the state of + the system while the system as a whole wont be as much + negatively effected by the operation as before.</p> + <p> + Own Id: OTP-11388 Aux Id: OTP-11535, OTP-11648 </p> + </item> + <item> + <p> + Cleanup 'Buckets' and 'Time left' fields in crashdump to + ease parsing.</p> + <p> + Own Id: OTP-11419</p> + </item> + <item> + <p> + Add sync option to file:open/2.</p> + <p> + The sync option adds the POSIX O_SYNC flag to the open + system call on platforms that support the flag or its + equivalent, e.g., FILE_FLAG_WRITE_THROUGH on Windows. For + platforms that don't support it, file:open/2 returns + {error, enotsup} if the sync option is passed in. Thank + to Steve Vinoski and Joseph Blomstedt</p> + <p> + Own Id: OTP-11498</p> + </item> + <item> + <p> + erlang:binary_to_term will now cost an appropriate amount + of reductions and will interrupt (yield) for reschedule + if the term is big. This avoids too long schedules when + binary_to_term is used. (Thanks to Svante Karlsson for + the original patch)</p> + <p> + Impact: Programs running binary_to_term on large binaries + will run more smoothly, but rescheduling will impact the + single process performance of the BIF. Single threaded + benchmarks might show degraded performance of the BIF, + while general system behaviour will be improved.</p> + <p> + Own Id: OTP-11535 Aux Id: OTP-11388 </p> + </item> + <item> + <p> + Added high resolution icon for windows. (Thanks to Daniel + Goertz for the inspiration.)</p> + <p> + Own Id: OTP-11560</p> + </item> + <item> + <p> + Migration of memory carriers has been enabled by default + on all ERTS internal memory allocators based on the + <seealso + marker="erts_alloc#alloc_util"><c>alloc_util</c></seealso> + framework except for <c>temp_alloc</c>. That is, <seealso + marker="erts_alloc#M_acul"><c>+M<S>acul + de</c></seealso> is default for these allocators. Note + that this also implies changed allocation strategies for + all of these allocators. They will all now use the + "address order first fit carrier best fit" strategy.</p> + <p> + By passing <c>+Muacul 0</c> on the command line, all + configuration changes made by this change will be + reverted.</p> + <p> + Characteristics impact: Improved memory characteristics + with a smaller memory footprint at the expense of a quite + small performance cost.</p> + <p> + Own Id: OTP-11604 Aux Id: OTP-10279 </p> + </item> + <item> + <p>A clarification has been added to the documentation of + <c>-on_load()</c> in the Reference Manual that it is only + recommended for loading NIF libraries.</p> + <p> + Own Id: OTP-11611</p> + </item> + <item> + <p><c>+fnaw</c> is now default when starting the + emulator; it used to be <c>+fnl</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11612</p> + </item> + <item> + <p> + EEP43: New data type - Maps</p> + <p> + With Maps you may for instance:</p> + <taglist> + <tag/> <item><c>M0 = #{ a => 1, b => 2}, % create + associations</c></item> + <tag/><item><c>M1 = M0#{ a := 10 }, % update values</c></item> + <tag/><item><c>M2 = M1#{ "hi" => + "hello"}, % add new associations</c></item> + <tag/><item><c>#{ "hi" := V1, a := V2, b := V3} = M2. + % match keys with values</c></item> + </taglist> + <p> + For information on how to use Maps please see Map Expressions in the + <seealso marker="doc/reference_manual:expressions#map_expressions"> + Reference Manual</seealso>.</p> + <p> + The current implementation is without the following + features:</p> + <taglist> + <tag/><item>No variable keys</item> + <tag/><item>No single value access</item> + <tag/><item>No map comprehensions</item> + </taglist> + <p> + Note that Maps is <em>experimental</em> during OTP 17.0.</p> + <p> + Own Id: OTP-11616</p> + </item> + <item> + <p> + The previously deprecated driver API function + <c>driver_async_cancel()</c> has been removed. Due to + this, the driver API version has been bumped to 3.0.</p> + <p> + Thanks to Steve Vinoski.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11628</p> + </item> + <item> + <p> + Experimental "dirty scheduler" functionality has been + introduced. In order to try the functionality out, you + need to pass the command line argument + <c>--enable-dirty-schedulers</c> to <c>configure</c> when + building the system.</p> + <p> + Dirty schedulers can currently only be used by NIFs on a + system with SMP support. More information can be found in + the <seealso + marker="erl_nif#dirty_nifs"><c>erl_nif(3)</c></seealso> + documentation, the <seealso + marker="erl"><c>erl(1)</c></seealso> documentation, and + in the git commit comment of commit + 'c1c03ae4ee50e58b7669ea88ec4d29c6b2b67c7b'.</p> + <p> + Note that the functionality is <em>experimental</em>, and + <em>not supported</em>. This functionality <em>will</em> + be subject to backward incompatible changes. You should + <em>not</em> enable the dirty scheduler functionality on + production systems. It is only provided for testing.</p> + <p> + Thanks to Steve Vinoski.</p> + <p> + Own Id: OTP-11629</p> + </item> + <item> + <p> + Improve reduction cost and yielding of + <c>term_to_binary</c>. The reduction cost is increased + and garbage collection is disabled during yield.</p> + <p> + Impact: Improves system responsiveness when + <c>term_to_binary</c> is called with large terms without + significant degradation of single threaded performance.</p> + <p> + Own Id: OTP-11648 Aux Id: OTP-11388 </p> + </item> + <item> + <p> + By default, the system's version of zlib will be used, + provided its version is 1.2.4 or higher; otherwise the + built-in zlib will be used. The built-in version of zlib + has been bumped to 1.2.8. (Use the + <c>--enable-builtin-zlib</c> option to <c>configure</c> + to force the use of the built-in zlib.)</p> + <p> + Own Id: OTP-11669</p> + </item> + <item> + <p> + The default float encoding in binary_to_term and + external_size has been changed to use minor_mode 1 + instead of 0.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11738</p> + </item> + <item> + <p> + Introduced the <c>configure</c> option + <c>--with-assumed-cache-line-size=SIZE</c>. For more + information see <seealso + marker="doc/installation_guide:INSTALL"><c>$ERL_TOP/HOWTO/INSTALL.md</c></seealso>.</p> + <p> + Own Id: OTP-11742</p> + </item> + <item> + <p> + Halfword emulator is marked as deprecated. It still works + as before but is planned to be removed in a future major + release.</p> + <p> + Own Id: OTP-11777</p> + </item> + <item> + <p> + The external format for Maps has changed in a way that is + not compatible with the format used in OTP 17.0-rc1 and + OTP 17.0-rc2.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11782</p> + </item> + <item> + <p> + Fixed faulty make dependency that would make some make + versions fail while building gen_git_version.mk.</p> + <p> + Own Id: OTP-11784</p> + </item> + <item> + <p> + Introduced functionality for allowing old drivers and NIF + libraries to be loaded during a transition period. For + more information see <seealso + marker="erts:erl_driver#version_management">the version + management section in the <c>erl_driver(3)</c> + documentation</seealso> and <seealso + marker="erts:erl_nif#version_management">the version + management section in the <c>erl_nif(3)</c> + documentation</seealso>.</p> + <p> + Own Id: OTP-11799</p> + </item> + <item> + <p> + Support file paths longer than 259 characters on Windows. + Long absolute paths are automatically converted to UNC + format with a <c>\\?\</c> prefix which is the only way to + represent long paths. The 259 character limit still + applies for individual file names, relative paths and the + current working directory.</p> + <p> + Own Id: OTP-11813</p> + </item> + <item> + <p> + Document that escript:create/2 also accepts a 3-elements + tuple containing files and zip:create/3 options to build + a zip file.</p> + <p> + Thanks to Pierre Fenoll</p> + <p> + Own Id: OTP-11827</p> + </item> + <item> + <p> + Add systemd socket activation for epmd.</p> + <p> + Thanks to Matwey V. Kornilov</p> + <p> + Own Id: OTP-11829</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.4.1</title> + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p> + When using gen_tcp:connect and the <c>fd</c> option with + <c>port</c> and/or <c>ip</c>, the <c>port</c> and + <c>ip</c> options were ignored. This has been fixed so + that if <c>port</c> and/or <c>ip</c> is specified + together with <c>fd</c> a bind is requested for that + <c>fd</c>. If <c>port</c> and/or <c>ip</c> is not + specified bind will not be called.</p> + <p> + Own Id: OTP-12061</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + When normalizing paths, erl_prim_loader would always + convert backslash to forward slash. This is correct on + Windows, but not on other operating systems. + erl_prim_loader now checks which OS is running before + performing this conversion.</p> + <p> + Own Id: OTP-11170</p> + </item> + <item> + <p> + Fixed syslog defines and defined LOG_ERR for systems + without syslog.h. Thanks to Matt Lewandowsky.</p> + <p> + Own Id: OTP-11349</p> + </item> + <item> + <p> + Check all pattern arguments passed to binary:matches/2. + Thanks to Mike Sassak.</p> + <p> + Own Id: OTP-11350</p> + </item> + <item> + <p> + Fix two small silent rules omissions. Thanks to Anthony + Ramine.</p> + <p> + Own Id: OTP-11351</p> + </item> + <item> + <p> + Teach configure to detect if posix_memalign cannot align + to more than the system page size. </p> + <p> + For cross-compiled systems a new environment variable + called erl_xcomp_posix_memalign has been introduced to + indicate whether posix_memalign should be used.</p> + <p> + Own Id: OTP-11371</p> + </item> + <item> + <p> + Fix bsr bug occurring when shifting a huge number a huge + number of bits to the right. Thanks to Lars Hesel + Christensen.</p> + <p> + Own Id: OTP-11381</p> + </item> + <item> + <p> + Fix memory leak for distributed monitors</p> + <p> + Own Id: OTP-11410</p> + </item> + <item> + <p> + Fix various typos in erts, kernel and ssh. Thanks to + Martin Hässler.</p> + <p> + Own Id: OTP-11414</p> + </item> + <item> + <p> + Crashdumps initiated by out-of-memory on process spawn + could cause the beam to segfault during crashdump writing + due to invalid pointers.</p> + <p> + The pointers are invalid since the process creation never + finished. This fix removes these processes from the + printouts. Reported by Richard Carlsson.</p> + <p> + Own Id: OTP-11420</p> + </item> + <item> + <p> + Crash dumps from 64-bit Erlang machines would have all + memory addresses truncated to 32 bits, which could cause + trouble inspecting processes message queues and stacks in + the crashdump viewer.</p> + <p> + Own Id: OTP-11450</p> + </item> + <item> + <p> + Threads other than schedulers threads could make thread + unsafe accesses when support for migration of memory + carriers had been enabled, i.e., when the <seealso + marker="erts_alloc#M_acul"><c>+M<S>acul</c></seealso> + command line flag had been passed to <seealso + marker="erl"><c>erl</c></seealso>. This could cause + corruption of the VMs internal state.</p> + <p> + This bug was introduced in erts-5.10.2 when the support + for migration of memory carriers was introduced.</p> + <p> + Own Id: OTP-11456 Aux Id: OTP-10279 </p> + </item> + <item> + <p> + Fix bug in <c>binary_to_term</c> for invalid bitstrings + and very large binaries (>2Gb).</p> + <p> + Own Id: OTP-11479</p> + </item> + <item> + <p> + Under rare circumstances a process calling <seealso + marker="kernel:inet#close/1"><c>inet:close/1</c></seealso>, + <seealso + marker="kernel:gen_tcp#close/1"><c>gen_tcp:close/1</c></seealso>, + <seealso + marker="kernel:gen_udp#close/1"><c>gen_udp:close/1</c></seealso>, + or <seealso + marker="kernel:gen_sctp#close/1"><c>gen_sctp:close/1</c></seealso> + could hang in the call indefinitely.</p> + <p> + Own Id: OTP-11491</p> + </item> + <item> + <p> + Fix bug that could cause a 32-bit emulator to always + crash at start (since R16B01) depending on the alignment + of static data in the beam executable.</p> + <p> + Own Id: OTP-11496</p> + </item> + <item> + <p> + Fix benign bugs regarding bitstring compare. Only a + nuisance for debug and valgrind VM.</p> + <p> + Own Id: OTP-11501</p> + </item> + <item> + <p> + Silence warnings (Thanks to Anthony Ramine)</p> + <p> + Own Id: OTP-11517</p> + </item> + <item> + <p> + The default wordsize of the emulator (beam) is now + determined by compiler default on Mac OSX (Darwin). This + was previously forced to 32bits by the configure script + unless otherwise specified.</p> + <p> + Own Id: OTP-11521</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A new memory allocation feature called "super carrier" + has been introduced. The super carrier feature can be + used in different ways. It can for example be used for + pre-allocation of all memory that the runtime system + should be able to use.</p> + <p> + By default the super carrier is disabled. It is enabled + by passing the <seealso + marker="erts:erts_alloc#MMscs"><c>+MMscs <size in + MB></c></seealso> command line argument. For more + information see the documentation of the <seealso + marker="erts:erts_alloc#MMsco"><c>+MMsco</c></seealso>, + <seealso + marker="erts:erts_alloc#MMscrfsd"><c>+MMscrfsd</c></seealso>, + <seealso + marker="erts:erts_alloc#MMscrpm"><c>+MMscrpm</c></seealso>, + <seealso + marker="erts:erts_alloc#MMscs"><c>+MMscs</c></seealso>, + <seealso + marker="erts:erts_alloc#Musac"><c>+MMusac</c></seealso>, + and, <seealso + marker="erts:erts_alloc#Mlpm"><c>+Mlpm</c></seealso> + command line arguments in the <seealso + marker="erts:erts_alloc"><c>erts_alloc(3)</c></seealso> + documentation.</p> + <p> + Since it is disabled by default there should be no impact + on system characteristics if not used.</p> + <p> + This change has been marked as a potential + incompatibility since the returned list when calling + <seealso + marker="erts:erlang#system_info_allocator_tuple"><c>erlang:system_info({allocator, + mseg_alloc})</c></seealso> now also include an + <c>{erts_mmap, _}</c> tuple as one element in the list.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11149</p> + </item> + <item> + <p> + Added erlang:system_info(ets_limit) to provide a way to + retrieve the runtime's maximum number of ETS tables. + Thanks to Steve Vinoski</p> + <p> + Own Id: OTP-11362</p> + </item> + <item> + <p> + Add new BIF os:unsetenv/1 which deletes an environment + variable. Thanks to Martin Hässler.</p> + <p> + Own Id: OTP-11446</p> + </item> + <item> + <p> Introduced a new guarantee regarding exit signals + from ports: </p><p> If the process calling one of the + synchronous port BIFs listed below is linked to the port + identified by the first argument, and the port exits + before sending the result of the port operation, the exit + signal issued due to this link will be received by the + processes before the BIF returns, or fail with an + exception due to the port not being open. </p><p> The + synchronous port BIFs are: </p> <list> <item><seealso + marker="erlang#port_close/1"><c>port_close/1</c></seealso></item> + <item><seealso + marker="erlang#port_command/2"><c>port_command/2</c></seealso></item> + <item><seealso + marker="erlang#port_command/3"><c>port_command/3</c></seealso></item> + <item><seealso + marker="erlang#port_connect/2"><c>port_connect/2</c></seealso></item> + <item><seealso + marker="erlang#port_control/3"><c>port_control/3</c></seealso></item> + <item><seealso + marker="erlang#port_call/3"><c>erlang:port_call/3</c></seealso></item> + <item><seealso + marker="erlang#port_info/1"><c>erlang:port_info/1</c></seealso></item> + <item><seealso + marker="erlang#port_info/2"><c>erlang:port_info/2</c></seealso></item> + </list> <p> Note that some ports under certain + circumstances unlink themselves from the calling process + before exiting, i.e. even though the process linked + itself to the port there might be no link triggering an + exit signal. </p> <p>Characteristics impact: The return + or exception from the synchronous port BIF will be + delayed if the port simultaneously exit due to some issue + unrelated to the outstanding synchronous port BIF call. + In all other cases characteristics are unchanged. </p> + <p> + Own Id: OTP-11489</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.3.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Memory allocators will be able to create <c>sys_alloc</c> + carriers as fallback, if <c>mseg_alloc</c> cannot create + more carriers, on systems with <c>posix_memalign()</c> + support. This is similar to how it worked in pre-R16 + releases.</p> + <p> + Windows systems will create carriers using + <c>_aligned_malloc()</c> and can by this use the new + optimized allocator header scheme introduced in R16 on + other platforms.</p> + <p> + Own Id: OTP-11318</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 5.10.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> The documentation of predefined types and built-in + types has been corrected. </p> + <p> + Own Id: OTP-11090</p> + </item> + <item> + <p> + Fix changing terminal parameters in to_erl</p> + <p> + Change the behaviour of to_erl to use TCSADRAIN instead + of TCSANOW when changing terminal parameters. This makes + the serial driver wait for the output queues to be empty + before applying the terminal parameter change. Thanks to + Stefan Zegenhagen.</p> + <p> + Own Id: OTP-11206</p> + </item> + <item> + <p> + The default value of {flush, boolean()} in erlang:halt/2 + is documented to be 'true' if the status is an integer. + The implementation behaviour was reversed. The + Implementation is now corrected to adhere to the + documentation. Thanks to Jose Valim for reporting the + error.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11218</p> + </item> + <item> + <p> + Fix serious race bug in R16B01 that could cause PID + mix-ups when a lot of processes were spawned and + terminated in a very rapid pace on an SMP emulator with + at least two scheduler threads.</p> + <p> + Own Id: OTP-11225</p> + </item> + <item> + <p> + Validating a trace pattern with the option silent no + longer incorrectly enables/disables the silent option of + the calling process.</p> + <p> + Own Id: OTP-11232</p> + </item> + <item> + <p> + Fixed a bug where GCC 4.8 and later use a more aggressive + loop optimization algorithm that broke some previously + working code in the efile driver. Thanks to Tomas + Abrahamsson for reporting this issue.</p> + <p> + Own Id: OTP-11246</p> + </item> + <item> + <p> + Fixed bug when printing memory allocator acul option in + crash dump.</p> + <p> + Own Id: OTP-11264</p> + </item> + <item> + <p> + Opening a new compressed file on Windows could in rare + (random) cases result in {error,eisdir} or other error + codes although it should have succeeded. This is now + corrected.</p> + <p> + Own Id: OTP-11265</p> + </item> + <item> + <p> + Fixed a race condition when closing a trace port that + would cause the emulator to crash.</p> + <p> + Own Id: OTP-11290</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + There is a new somewhat experimental socket option + 'netns' that can set the network namespace for a socket + on Linux:es where it is supported. See the documentation.</p> + <p> + Own Id: OTP-11157</p> + </item> + <item> + <p> + New allocator strategy <c>aoffcbf</c> (address order + first fit carrier best fit). Supports carrier migration + but with better CPU performance than <c>aoffcaobf</c>.</p> + <p> + Own Id: OTP-11174</p> + </item> + <item> + <p> + Introduced functionality for inspection of system and + build configuration.</p> + <p> + Own Id: OTP-11196</p> + </item> + <item> + <p> + Fix matching of floating point middle-endian machines. + Thanks to Johannes Weissl.</p> + <p> + Own Id: OTP-11201</p> + </item> + <item> + <p> + Fix compile error on ARM and GCC versions greater than + 4.1.0. Thanks to Johannes Weissl.</p> + <p> + Own Id: OTP-11214</p> + </item> + <item> + <p> + run_erl: Redirect standard streams to /dev/null. Thanks + to Johannes Weissl.</p> + <p> + Own Id: OTP-11215</p> + </item> + <item> + <p> + Misc. corrections in documentation for erl_driver. Thanks + to Giacomo Olgeni.</p> + <p> + Own Id: OTP-11227</p> + </item> + <item> + <p> + Fix documentation regarding binary_part.</p> + <p> + Own Id: OTP-11239</p> + </item> + <item> + <p> + Make edlin understand a few important control keys. + Thanks to Stefan Zegenhagen.</p> + <p> + Own Id: OTP-11251</p> + </item> + <item> + <p> + Export type zlib:zstream/0. Thanks to Loic Hoguin.</p> + <p> + Own Id: OTP-11278</p> + </item> + <item> + <p> + Add erl option to set schedulers by percentages. </p> + <p> + For applications where measurements show enhanced + performance from the use of a non-default number of + emulator scheduler threads, having to accurately set the + right number of scheduler threads across multiple hosts + each with different numbers of logical processors is + difficult because the erl +S option requires absolute + numbers of scheduler threads and scheduler threads online + to be specified.</p> + <p> + To address this issue, add a +SP option to erl, similar + to the existing +S option but allowing the number of + scheduler threads and scheduler threads online to be set + as percentages of logical processors configured and + logical processors available, respectively. For example, + "+SP 50:25" sets the number of scheduler threads to 50% + of the logical processors configured, and the number of + scheduler threads online to 25% of the logical processors + available. The +SP option also interacts with any + settings specified with the +S option, such that the + combination of options "+S 4:4 +SP 50:50" (in either + order) results in 2 scheduler threads and 2 scheduler + threads online.</p> + <p> + Thanks to Steve Vinoski</p> + <p> + Own Id: OTP-11282</p> + </item> + <item> + <p> + Extend erl_driver interface with lock names</p> + <p> + Lock and thread names are already a feature in the driver + interface. This extension will let developers read these + names which eases debugging.</p> + <p> + Own Id: OTP-11303</p> + </item> + <item> + <p> + Fix incorrect values returned by integer_to_binary/2. + Thanks to Juan Jose Comellas.</p> + <p> + Own Id: OTP-11311</p> + </item> + <item> + <p> + Fix system_flag scheduling_statistics - disable . Thanks + to Steve Vinoski.</p> + <p> + Own Id: OTP-11317</p> + </item> + <item> + <p> The documentation of predefined types has been + corrected Thanks to Kostis Sagonas. </p> + <p> + Own Id: OTP-11321</p> + </item> + </list> + </section> + +</section> + <section><title>Erts 5.10.2</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -321,7 +4487,7 @@ <item> <p> Support wide characters in the shell through wcwidth(). - Thanks to Anthony Ramine. Reported by Lo�c Hoguin.</p> + Thanks to Anthony Ramine. Reported by Loïc Hoguin.</p> <p> Own Id: OTP-11088</p> </item> @@ -342,7 +4508,7 @@ <item> <p> Remove 'query' from the list of reserved words in docs. - Thanks to Matthias Endler and Lo�c Hoguin.</p> + Thanks to Matthias Endler and Loïc Hoguin.</p> <p> Own Id: OTP-11158</p> </item> @@ -1500,8 +5666,7 @@ <p> Fix erl_prim_loader errors in handling of primary archive. The following errors have been corrected:</p> - <p> - <list> <item> If primary archive was named "xxx", then a + <list> <item> If primary archive was named "xxx", then a file in the same directory named "xxxyyy" would be interpreted as a file named "yyy" inside the archive. </item> <item> erl_prim_loader did not correctly create @@ -1516,7 +5681,8 @@ erl_prim_loader:list_dir/1 would sometimes return an empty string inside the file list. This was a virtual element representing the top directory of the archive. - This has been removed. </item> </list></p> + This has been removed. </item> + </list> <p> Thanks to Tuncer Ayaz and Shunichi Shinohara for reporting and co-authoring corrections.</p> @@ -1961,7 +6127,7 @@ <item> <p> Fix typo in supervisor behaviour doc (Thanks to Ricardo - Catalinas Jim�nez)</p> + Catalinas Jiménez)</p> <p> Own Id: OTP-9924</p> </item> @@ -2225,7 +6391,7 @@ <item> <p> Fixes module erlang doc style: option description (Thanks - to Ricardo Catalinas Jim�nez)</p> + to Ricardo Catalinas Jiménez)</p> <p> Own Id: OTP-9697</p> </item> @@ -2674,7 +6840,7 @@ <item> <p> Fix typos in the epmd documentation (Thanks to Holger - Wei� )</p> + Weiß )</p> <p> Own Id: OTP-9387</p> </item> @@ -2779,7 +6945,7 @@ <item> <p> Fix non-existing function (erlang:disconnect/1) in - distributed reference manual (Thanks to Fabian Kr�l)</p> + distributed reference manual (Thanks to Fabian Król)</p> <p> Own Id: OTP-9504</p> </item> @@ -2807,7 +6973,7 @@ only separator characters (comma and space).</p> <p> The same applies to epmd's -address option.(Thanks to - Holger Wei�)</p> + Holger Weiß)</p> <p> Own Id: OTP-9525</p> </item> @@ -2951,7 +7117,7 @@ <p> Add support for querying the number of configured and online processors on SGI systems running IRIX.(Thanks to - Holger Wei�)</p> + Holger Weiß)</p> <p> Own Id: OTP-9531</p> </item> @@ -3061,7 +7227,7 @@ using a comma-separated list. If the loopback address is not in this list, it will be added implicitly, so that the daemon can be queried by an interactive epmd - process.(Thanks to Holger Wei�)</p> + process.(Thanks to Holger Weiß)</p> <p> Own Id: OTP-9213</p> </item> @@ -3096,7 +7262,7 @@ value over to dbg_gen_printf(). This fixes the problem that errno had been reset to zero by the time it was used (to print the corresponding error message) in the - dbg_gen_printf() function. (Thanks to Holger Wei�)</p> + dbg_gen_printf() function. (Thanks to Holger Weiß)</p> <p> Own Id: OTP-9223</p> </item> @@ -3482,7 +7648,7 @@ Mention that "-detached" implies "-noinput"</p> <p> Clarify that specifying "-noinput" is unnecessary if the - "-detached" flag is given. (thanks to Holger Wei�)</p> + "-detached" flag is given. (thanks to Holger Weiß)</p> <p> Own Id: OTP-9086</p> </item> @@ -3613,7 +7779,7 @@ <item> <p> The <c>configure</c> command line argument <seealso - marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso> + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--enable-ethread-pre-pentium4-compatibility</seealso> had no effect. This option is now also automatically enabled if required on the build machine.</p> <p> @@ -3959,12 +8125,12 @@ Own Id: OTP-8726 Aux Id: seq11617 </p> </item> <item> - <p>Fix libm linking with --as-needed flag + <p>Fix libm linking with --as-needed flag</p> <p> When building with "--as-needed" linker flags on Linux the build will fail. This has now been fixed.</p> <p> - (Thanks to Christian Faulhammer)</p></p> + (Thanks to Christian Faulhammer)</p> <p> Own Id: OTP-8728</p> </item> @@ -4192,7 +8358,7 @@ platforms than before. If <c>configure</c> warns about no atomic implementation available, try using the <c>libatomic_ops</c> library. Use the <seealso - marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--with-libatomic_ops=PATH</seealso> + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--with-libatomic_ops=PATH</seealso> <c>configure</c> command line argument when specifying where the <c>libatomic_ops</c> installation is located. The <c>libatomic_ops</c> library can be downloaded from: @@ -4210,7 +8376,7 @@ the pentium 4 processor. If you want the runtime system to be compatible with older processors (back to 486) you need to pass the <seealso - marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso> + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--enable-ethread-pre-pentium4-compatibility</seealso> <c>configure</c> command line argument when configuring the system.</p> <p> @@ -4988,7 +9154,7 @@ failed to detect gcc C compilers with other command line names than gcc. `configure' now substitute GCC into the makefiles. If CC is a gcc C compiler, GCC will have the - value yes. (Thanks to Jean-S�bastien P�dron)</p> + value yes. (Thanks to Jean-Sébastien Pédron)</p> <p> Own Id: OTP-8373</p> </item> @@ -7358,7 +11524,7 @@ <p> IPv6 name resolving has now been fixed to use getaddrinfo() patch (thoroughly reworked) courtesy of Love - H�rnquist-�strand submitted by Fredrik Thulin. It also + Hörnquist-Ã…strand submitted by Fredrik Thulin. It also can use gethostname2() patch (also reworked) courtesy of Mikael Magnusson for debian submitted by Sergei Golovan.</p> <p> diff --git a/erts/doc/src/notes_history.xml b/erts/doc/src/notes_history.xml index cc3b938c86..0bc2ab1383 100644 --- a/erts/doc/src/notes_history.xml +++ b/erts/doc/src/notes_history.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2006</year><year>2009</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml index fa50329cad..b2abfc62ca 100644 --- a/erts/doc/src/part.xml +++ b/erts/doc/src/part.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -32,6 +33,7 @@ <p>The Erlang Runtime System Application <em>ERTS</em>.</p> </description> <xi:include href="communication.xml"/> + <xi:include href="time_correction.xml"/> <xi:include href="match_spec.xml"/> <xi:include href="crash_dump.xml"/> <xi:include href="alt_dist.xml"/> diff --git a/erts/doc/src/part_notes.xml b/erts/doc/src/part_notes.xml index 4f183999e6..e579b7635d 100644 --- a/erts/doc/src/part_notes.xml +++ b/erts/doc/src/part_notes.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2004</year><year>2009</year> + <year>2004</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/part_notes_history.xml b/erts/doc/src/part_notes_history.xml index 1b9bcca773..277683a2b5 100644 --- a/erts/doc/src/part_notes_history.xml +++ b/erts/doc/src/part_notes_history.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2006</year><year>2009</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml index e55923c344..e45402a397 100644 --- a/erts/doc/src/ref_man.xml +++ b/erts/doc/src/ref_man.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE application SYSTEM "application.dtd"> <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -55,5 +56,6 @@ <xi:include href="driver_entry.xml"/> <xi:include href="erts_alloc.xml"/> <xi:include href="erl_nif.xml"/> + <xi:include href="erl_tracer.xml"/> </application> diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl.xml index c9784299b3..6b0fef7c0a 100644 --- a/erts/doc/src/run_erl.xml +++ b/erts/doc/src/run_erl.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1999</year><year>2011</year> + <year>1999</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml index e5c2f4783f..ed6be650e5 100644 --- a/erts/doc/src/specs.xml +++ b/erts/doc/src/specs.xml @@ -1,7 +1,8 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <specs xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="../specs/specs_erl_prim_loader.xml"/> <xi:include href="../specs/specs_erlang.xml"/> + <xi:include href="../specs/specs_erl_tracer.xml"/> <xi:include href="../specs/specs_init.xml"/> <xi:include href="../specs/specs_zlib.xml"/> </specs> diff --git a/erts/doc/src/start.xml b/erts/doc/src/start.xml index 5dc33deb2a..adacf5b98d 100644 --- a/erts/doc/src/start.xml +++ b/erts/doc/src/start.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1999</year><year>2009</year> + <year>1999</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/start_erl.xml b/erts/doc/src/start_erl.xml index 92d87b095a..243aeaa717 100644 --- a/erts/doc/src/start_erl.xml +++ b/erts/doc/src/start_erl.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1998</year><year>2011</year> + <year>1998</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/time_correction.xml b/erts/doc/src/time_correction.xml new file mode 100644 index 0000000000..236fe679cb --- /dev/null +++ b/erts/doc/src/time_correction.xml @@ -0,0 +1,902 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2015</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>Time and Time Correction in Erlang</title> + <prepared></prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>2013-08-28</date> + <rev>PA1</rev> + <file>time_correction.xml</file> + </header> + + <section> + <title>New Extended Time Functionality</title> + <note><p>As of OTP 18 (<c>ERTS</c> version 7.0) the time functionality of + Erlang has been extended. This includes a + <seealso marker="#The_New_Time_API">new API</seealso> + for time and + <seealso marker="#Time_Warp_Modes">time warp + modes</seealso> that alter the system behavior when + system time changes.</p> + + <p>The <seealso marker="#No_Time_Warp_Mode">default + time warp mode</seealso> has the same behavior as before, and the + old API still works. Thus, you are not required to change + anything unless you want to. However, <em>you are strongly + encouraged to use the new API</em> instead of the old API based + on <seealso marker="erlang#now/0"><c>erlang:now/0</c></seealso>. + <c>erlang:now/0</c> is deprecated, as it is and + will be a scalability bottleneck.</p> + + <p>By using the new API, you + automatically get scalability and performance improvements. This + also enables you to use the + <seealso marker="#Multi_Time_Warp_Mode">multi-time warp mode</seealso> + that improves accuracy and precision of time measurements.</p> + </note> + </section> + + <section> + <title>Terminology</title> + <p>To make it easier to understand this section, some terms + are defined. This is a mix of our own terminology + (Erlang/OS system time, Erlang/OS monotonic time, time warp) + and globally accepted terminology.</p> + + <marker id="Monotonically_Increasing"/> + <section> + <title>Monotonically Increasing</title> + <p>In a monotonically increasing sequence of values, all values + that have a predecessor are either larger than or equal to its + predecessor.</p> + </section> + + <marker id="Strictly_Monotonically_Increasing"/> + <section> + <title>Strictly Monotonically Increasing</title> + <p>In a strictly monotonically increasing sequence of values, + all values that have a predecessor are larger than its + predecessor.</p> + </section> + + <marker id="UT1"/> + <section> + <title>UT1</title> + <p>Universal Time. UT1 is based on the rotation of the earth + and conceptually means solar time at 0° longitude.</p> + </section> + + <marker id="UTC"/> + <section> + <title>UTC</title> + <p>Coordinated Universal Time. UTC almost aligns with + <seealso marker="#UT1">UT1</seealso>. However, UTC uses the + SI definition of a second, which has not exactly the same length + as the second used by UT1. This means that UTC slowly drifts from + UT1. To keep UTC relatively in sync with UT1, leap seconds + are inserted, and potentially also deleted. That is, an UTC day can + be 86400, 86401, or 86399 seconds long.</p> + </section> + + <marker id="POSIX_Time"/> + <section> + <title>POSIX Time</title> + <p>Time since + <url href="http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap03.html#tag_21_03_00_17">Epoch</url>. + Epoch is defined to be 00:00:00 <seealso marker="#UTC">UTC</seealso>, + 1970-01-01. + <url href="http://pubs.opengroup.org/onlinepubs/009604499/basedefs/xbd_chap04.html#tag_04_14">A day in POSIX time</url> + is defined to be exactly 86400 seconds long. Strangely enough + Epoch is defined to be a time in UTC, and UTC has another + definition of how long a day is. Quoting the Open Group + <url href="http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_15">"POSIX time is therefore not necessarily UTC, despite its appearance"</url>. + The effect of this is that when an UTC leap second is + inserted, POSIX time either stops for a second, or repeats the + last second. If an UTC leap second would be deleted (which has not + happened yet), POSIX time would make a one second leap forward.</p> + </section> + + <marker id="Time_Resolution"/> + <section> + <title>Time Resolution</title> + <p>The shortest time interval that can be distinguished when + reading time values.</p> + </section> + + <marker id="Time_Precision"/> + <section> + <title>Time Precision</title> + <p>The shortest time interval that can be distinguished + repeatedly and reliably when reading time values. Precision + is limited by the + <seealso marker="#Time_Resolution">resolution</seealso>, but + resolution and precision can differ significantly.</p> + </section> + + <marker id="Time_Accuracy"/> + <section> + <title>Time Accuracy</title> + <p>The correctness of time values.</p> + </section> + + <marker id="Time_Warp"/> + <section> + <title>Time Warp</title> + <p>A time warp is a leap forwards or backwards in time. That + is, the difference of time values taken before and after the + time warp does not correspond to the actual elapsed time.</p> + </section> + + <marker id="OS_System_Time"/> + <section> + <title>OS System Time</title> + <p>The operating systems view of + <seealso marker="#POSIX_Time">POSIX time</seealso>. To + retrieve it, call + <seealso marker="kernel:os#system_time/0"><c>os:system_time()</c></seealso>. + This may or may not be an accurate view of POSIX time. This time + may typically be adjusted both backwards and forwards without + limitation. That is, <seealso marker="#Time_Warp">time warps</seealso> + may be observed.</p> + + <p>To get information about the Erlang runtime + system's source of OS system time, call + <seealso marker="erlang#system_info_os_system_time_source"><c>erlang:system_info(os_system_time_source)</c></seealso>.</p> + </section> + + <marker id="OS_Monotonic_Time"/> + <section> + <title>OS Monotonic Time</title> + <p>A monotonically increasing time provided by the operating + system. This time does not leap and has a relatively steady + frequency although not completely correct. However, it is not + uncommon that OS monotonic time stops if the system is + suspended. This time typically increases since some + unspecified point in time that is not connected to + <seealso marker="#OS_System_Time">OS system time</seealso>. + This type of time is not necessarily provided by all + operating systems.</p> + + <p>To get information about the Erlang + runtime system's source of OS monotonic time, call + <seealso marker="erlang#system_info_os_monotonic_time_source"><c>erlang:system_info(os_monotonic_time_source)</c></seealso>.</p> + </section> + + <marker id="Erlang_System_Time"/> + <section> + <title>Erlang System Time</title> + <p>The Erlang runtime systems view of + <seealso marker="#POSIX_Time">POSIX time</seealso>. To + retrieve it, call + <seealso marker="erlang#system_time/0"><c>erlang:system_time()</c></seealso>.</p> + + <p>This time may or may not be an accurate view of POSIX time, + and may + or may not align with <seealso marker="#OS_System_Time">OS system + time</seealso>. The runtime system works towards aligning the two + system times. Depending on the + <seealso marker="#Time_Warp_Modes">time warp mode</seealso> used, + this can be achieved by letting Erlang + system time perform a <seealso marker="#Time_Warp">time + warp</seealso>.</p> + </section> + + <marker id="Erlang_Monotonic_Time"/> + <section> + <title>Erlang Monotonic Time</title> + <p>A monotonically increasing time provided by the + Erlang runtime system. Erlang monotonic time increases since + some unspecified point in time. To retrieve it, call + <seealso marker="erlang#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso>. + </p> + + <p>The <seealso marker="#Time_Accuracy">accuracy</seealso> and + <seealso marker="#Time_Precision">precision</seealso> of Erlang + monotonic time heavily depends on the following:</p> + + <list type="bulleted"> + <item>Accuracy and precision of + <seealso marker="#OS_Monotonic_Time">OS monotonic time</seealso> + </item> + <item>Accuracy and precision of + <seealso marker="#OS_System_Time">OS system time</seealso> + </item> + <item><seealso marker="#Time_Warp_Modes">time warp mode</seealso> used + </item> + </list> + + <p>On a system without OS monotonic time, Erlang monotonic + time guarantees monotonicity, but cannot give + other guarantees. The frequency adjustments made to + Erlang monotonic time depend on the time warp mode used.</p> + + <p>Internally in the runtime system, Erlang monotonic + time is the "time engine" that is used for more or less + everything that has anything to do with time. All timers, + regardless of it is a <c>receive ... after</c> timer, BIF timer, + or a timer in the <c>timer</c> module, are triggered + relative Erlang monotonic time. Even + <seealso marker="#Erlang_System_Time">Erlang system + time</seealso> is based on Erlang monotonic time. + By adding current Erlang monotonic time with current time + offset, you get current Erlang system time.</p> + + <p>To retrieve current time offset, call + <seealso marker="erlang#time_offset/0"><c>erlang:time_offset/0</c></seealso>. + </p> + </section> + + </section> + + <section> + <title>Introduction</title> + <p>Time is vital to an Erlang program and, more importantly, <em>correct</em> + time is vital to an Erlang program. As Erlang is a language with + soft real-time properties and we can express + time in our programs, the Virtual Machine and the language must be + careful about what is considered a correct time and in + how time functions behave.</p> + + <p>When Erlang was designed, it was assumed that the wall + clock time in the system showed a monotonic time moving forward at + exactly the same pace as the definition of time. This more or less meant + that an atomic clock (or better time source) was expected to be attached + to your hardware and that the hardware was then expected to be + locked away from any human tinkering forever. While this can be a + compelling thought, it is simply never the case.</p> + + <p>A "normal" modern computer cannot keep time, not on itself and + not unless you have a chip-level atomic clock wired to it. Time, + as perceived by your computer, must normally be corrected. Hence + the Network Time Protocol (NTP) protocol, together with the <c>ntpd</c> + process, does its best to keep your computer time in sync with + the correct time. Between NTP corrections, usually a + less potent time-keeper than an atomic clock is used.</p> + + <p>However, NTP is not fail-safe. The NTP server can be unavailable, + <c>ntp.conf</c> can be wrongly configured, or your computer may + sometimes be disconnected from Internet. Furthermore, you can have a + user (or even system administrator) who thinks the correct + way to handle Daylight Saving Time is to adjust the clock one + hour two times a year (which is the incorrect way to do it). + To complicate things further, this user fetched your + software from Internet and has not considered what + the correct time is as perceived by a computer. The user does + not care about keeping the wall clock in sync with the correct + time. The user expects your program to have unlimited knowledge + about the time.</p> + + <p>Most programmers also expect time to be reliable, at least until + they realize that the wall clock time on their workstation is off by + a minute. Then they set it to the correct time, but most probably + not in a smooth way.</p> + + <p>The number of problems that arise when you always expect the wall clock + time on the system to be correct can be immense. Erlang therefore + introduced the "corrected estimate of time", or the "time + correction", many years ago. The time correction relies on the fact + that most operating systems have some kind of monotonic clock, + either a real-time extension or some built-in "tick counter" that is + independent of the wall clock settings. This counter can have + microsecond resolution or much less, but it has a drift that cannot + be ignored.</p> + </section> + + <section> + <marker id="Time_Correction"/> + <title>Time Correction</title> + <p>If time correction is enabled, the Erlang runtime system + makes use of both + <seealso marker="#OS_System_Time">OS system time</seealso> + and <seealso marker="#OS_Monotonic_Time">OS monotonic time</seealso>, + to adjust the frequency of the Erlang + monotonic clock. Time correction ensures that + <seealso marker="#Erlang_Monotonic_Time">Erlang monotonic time</seealso> + does not warp and that the frequency is relatively accurate. + The type of frequency adjustments depends on the time warp mode used. + Section <seealso marker="#Time_Warp_Modes">Time Warp Modes</seealso> + provides more details.</p> + + <p>By default time correction is enabled if support for + it exists on the specific platform. Support for it includes + both OS monotonic time, provided by the OS, and an + implementation in the Erlang runtime system using + OS monotonic time. To check if your system has support + for OS monotonic time, call + <seealso marker="erlang#system_info_os_monotonic_time_source"><c>erlang:system_info(os_monotonic_time_source)</c></seealso>. + To check if time correction is enabled on your system, call + <seealso marker="erlang#system_info_time_correction"><c>erlang:system_info(time_correction)</c></seealso>.</p> + + <p>To enable or disable time correction, pass command-line argument + <seealso marker="erl#+c"><c>+c [true|false]</c></seealso> + to <c>erl</c>.</p> + + <p>If time correction is disabled, Erlang monotonic time + may warp forwards or stop, or even freeze for extended + periods of time. There are then no guarantees that the frequency + of the Erlang monotonic clock is accurate or stable.</p> + + <p><em>You typically never want to disable time correction</em>. + Previously a performance penalty was associated with time + correction, but nowadays it is usually the other way around. + If time correction is disabled, you probably get bad scalability, + bad performance, and bad time measurements.</p> + </section> + + <section> + <marker id="Time_Warp_Safe_Code"/> + <title>Time Warp Safe Code</title> + <p>Time warp safe code can handle + a <seealso marker="#Time_Warp">time warp</seealso> of + <seealso marker="#Erlang_System_Time">Erlang system time</seealso>.</p> + + <p><seealso marker="erlang#now/0"><c>erlang:now/0</c></seealso> + behaves bad when Erlang system time warps. When Erlang + system time does a time warp backwards, the values returned + from <c>erlang:now/0</c> freeze (if you disregard the + microsecond increments made because of the actual call) until + OS system time reaches the point of the last value returned by + <c>erlang:now/0</c>. This freeze can continue for a long time. It + can take years, decades, and even longer until the freeze stops.</p> + + <p>All uses of <c>erlang:now/0</c> are not necessarily + time warp unsafe. If you do not use it to get time, it + is time warp safe. However, <em>all uses of + <c>erlang:now/0</c> are suboptimal</em> from a performance + and scalability perspective. So you really want to replace + the use of it with other functionality. For examples + of how to replace the use of <c>erlang:now/0</c>, see Section + <seealso marker="#Dos_and_Donts">How to Work with the New + API</seealso>.</p> + </section> + + <section> + <title>Time Warp Modes</title> + <marker id="Time_Warp_Modes"/> + <p>Current <seealso marker="#Erlang_System_Time">Erlang system + time</seealso> is determined by adding current + <seealso marker="erlang#monotonic_time/0">Erlang monotonic time</seealso> + with current + <seealso marker="erlang#time_offset/0">time offset</seealso>. The + time offset is managed differently depending on which time + warp mode you use.</p> + + <p>To set the time warp mode, pass command-line argument + <seealso marker="erl#+C_"><c>+C + [no_time_warp|single_time_warp|multi_time_warp]</c></seealso> + to <c>erl</c>.</p> + + <marker id="No_Time_Warp_Mode"/> + <section> + <title>No Time Warp Mode</title> + <p>The time offset is determined at runtime system start + and does not change later. This is the default behavior, but + not because it is the best mode (which it is not). It is + default <em>only</em> because this is how the runtime system + behaved until <c>ERTS</c> 7.0. + Ensure that your Erlang code that may execute during a time + warp is <seealso marker="#Time_Warp_Safe_Code">time warp + safe</seealso> before enabling other modes.</p> + + <p>As the time offset is not allowed to change, time + correction must adjust the frequency of the Erlang + monotonic clock to align Erlang system time with OS + system time smoothly. A significant downside of this approach + is that we on purpose will use a faulty frequency on the + Erlang monotonic clock if adjustments are needed. This + error can be as large as 1%. This error will show up in all + time measurements in the runtime system.</p> + + <p>If time correction is not enabled, Erlang monotonic + time freezes when OS system time leaps backwards. + The freeze of monotonic time continues until + OS system time catches up. The freeze can continue for + a long time. When OS system time leaps forwards, + Erlang monotonic time also leaps forward.</p> + </section> + + <marker id="Single_Time_Warp_Mode"/> + <section> + <title>Single Time Warp Mode</title> + <p>This mode is more or less a backwards compatibility mode + as of its introduction.</p> + + <p>On an embedded system it is not uncommon that the system + has no power supply, not even a battery, when it is + shut off. The system clock on such a system is typically + way off when the system boots. If + <seealso marker="#No_Time_Warp_Mode">no time warp mode</seealso> + is used, and the Erlang runtime system is started before + OS system time has been corrected, Erlang system time + can be wrong for a long time, centuries or even longer.</p> + + <p>If you need to use Erlang code that is not + <seealso marker="#Time_Warp_Safe_Code">time warp safe</seealso>, + and you need to start the Erlang runtime system before OS + system time has been corrected, you may want to use the single + time warp mode.</p> + + <note><p>There are limitations to when you can + execute time warp unsafe code using this mode. If it is possible + to use time warp safe code only, it is <em>much</em> better + to use the <seealso marker="#Multi_Time_Warp_Mode">multi-time + warp mode</seealso> instead.</p></note> + + <p>Using the single time warp mode, the time offset is + handled in two phases:</p> + + <taglist> + <tag>Preliminary Phase</tag> + <item> + <p>This phase starts when the runtime + system starts. A preliminary time offset based on + current OS system time is determined. This offset is from + now on to be fixed during the whole preliminary phase.</p> + + <p>If time correction is enabled, adjustments to the + Erlang monotonic clock are made to keep its + frequency as correct as possible. However, <em>no</em> + adjustments are made trying to align Erlang system + time and OS system time. That is, during the preliminary phase + Erlang system time and OS system time can diverge + from each other, and no attempt is made to prevent this.</p> + + <p>If time correction is disabled, changes in OS system + time affects the monotonic clock the same way as + when the <seealso marker="#No_Time_Warp_Mode">no time warp + mode</seealso> is used.</p> + </item> + + <tag>Final Phase</tag> + <item> + <p>This phase begins when the user finalizes the time + offset by calling + <seealso marker="erlang#system_flag_time_offset"><c>erlang:system_flag(time_offset, finalize)</c></seealso>. + The finalization can only be performed once.</p> + + <p>During finalization, the time offset is adjusted and + fixated so that current Erlang system time aligns with + current OS system time. As the time offset can + change during the finalization, Erlang system time + can do a time warp at this point. The time offset is + from now on fixed until the runtime system terminates. + If time correction has been enabled, the time + correction from now on also makes adjustments + to align Erlang system time with OS system + time. When the system is in the final phase, it behaves + exactly as in the <seealso marker="#No_Time_Warp_Mode">no + time warp mode</seealso>.</p> + </item> + </taglist> + + <p>In order for this to work properly, the user must ensure + that the following two requirements are satisfied:</p> + + <taglist> + <tag>Forward Time Warp</tag> + <item><p>The time warp made when finalizing the time offset + can only be done forwards without encountering problems. + This implies that the user must ensure that OS + system time is set to a time earlier or equal to actual + POSIX time before starting the Erlang runtime system.</p> + + <p>If you are not sure that OS system time is correct, + set it to a time that is guaranteed to be earlier than + actual POSIX time before starting the Erlang runtime + system, just to be safe.</p> + </item> + + <tag>Finalize Correct OS System Time</tag> + <item><p>OS system time must be correct when + the user finalizes the time offset.</p> + </item> + </taglist> + + <p>If these requirements are not fulfilled, the system + may behave very bad.</p> + + <p>Assuming that these requirements are fulfilled, + time correction is enabled, and that OS system time + is adjusted using a time adjustment protocol such as NTP, + only small adjustments of Erlang monotonic + time are needed to keep system times + aligned after finalization. As long as the system is not + suspended, the largest adjustments needed are for + inserted (or deleted) leap seconds.</p> + + <warning><p>To use this mode, ensure that + all Erlang code that will execute in both phases are + <seealso marker="#Time_Warp_Safe_Code">time warp + safe</seealso>.</p> + <p>Code executing only in the final phase does not have + to be able to cope with the time warp.</p></warning> + </section> + + <marker id="Multi_Time_Warp_Mode"/> + <section> + <title>Multi-Time Warp Mode</title> + <p><em>Multi-time warp mode in combination with time + correction is the preferred configuration</em>. This as + the Erlang runtime system have better performance, scale + better, and behave better on almost all platforms. In + addition, the accuracy and precision of time measurements + are better. Only Erlang runtime systems executing on + ancient platforms benefit from another configuration.</p> + + <p>The time offset may change at any time without limitations. + That is, Erlang system time may perform time warps both + forwards and backwards at <em>any</em> time. As we align + Erlang system time with OS system time by changing + the time offset, we can enable a time correction that tries + to adjust the frequency of the Erlang monotonic clock to be as + correct as possible. This makes time measurements using + Erlang monotonic time more accurate and precise.</p> + + <p>If time correction is disabled, Erlang monotonic time + leaps forward if OS system time leaps forward. If + OS system time leaps backwards, Erlang monotonic time + stops briefly, but it does not freeze for extended periods + of time. This as the time offset is changed to + align Erlang system time with OS system time.</p> + + <warning><p>To use this mode, ensure that all + Erlang code that will execute on the runtime system is + <seealso marker="#Time_Warp_Safe_Code">time warp + safe</seealso>.</p></warning> + </section> + </section> + + <section> + <title>New Time API</title> + <marker id="The_New_Time_API"/> + <p>The old time API is based on + <seealso marker="erlang#now/0"><c>erlang:now/0</c></seealso>. + <c>erlang:now/0</c> was intended to be used for many unrelated + things. This tied these unrelated operations together and + caused issues with performance, scalability, accuracy, and + precision for operations that did not need to have + such issues. To improve this, the new API spreads different + functionality over multiple functions.</p> + + <p>To be backwards compatible, <c>erlang:now/0</c> + remains as is, but <em>you are strongly discouraged from using + it</em>. Many use cases of <c>erlang:now/0</c> + prevents you from using the new + <seealso marker="#Multi_Time_Warp_Mode">multi-time warp + mode</seealso>, which is an important part of this + new time functionality improvement.</p> + + <p>Some of the new BIFs on some systems, perhaps surprisingly, + return negative integer values on a newly started runtime + system. This is not a bug, but a memory use optimization.</p> + + <p>The new API consists of the following new BIFs:</p> + + <list> + <item><p><seealso marker="erlang#convert_time_unit/3"><c>erlang:convert_time_unit/3</c></seealso></p></item> + <item><p><seealso marker="erlang#monotonic_time/0"><c>erlang:monotonic_time/0</c></seealso></p></item> + <item><p><seealso marker="erlang#monotonic_time/1"><c>erlang:monotonic_time/1</c></seealso></p></item> + <item><p><seealso marker="erlang#system_time/0"><c>erlang:system_time/0</c></seealso></p></item> + <item><p><seealso marker="erlang#system_time/1"><c>erlang:system_time/1</c></seealso></p></item> + <item><p><seealso marker="erlang#time_offset/0"><c>erlang:time_offset/0</c></seealso></p></item> + <item><p><seealso marker="erlang#time_offset/1"><c>erlang:time_offset/1</c></seealso></p></item> + <item><p><seealso marker="erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso></p></item> + <item><p><seealso marker="erlang#unique_integer/0"><c>erlang:unique_integer/0</c></seealso></p></item> + <item><p><seealso marker="erlang#unique_integer/1"><c>erlang:unique_integer/1</c></seealso></p></item> + <item><p><seealso marker="kernel:os#system_time/0"><c>os:system_time/0</c></seealso></p></item> + <item><p><seealso marker="kernel:os#system_time/1"><c>os:system_time/1</c></seealso></p></item> + </list> + + <p>The new API also consists of extensions of the following existing BIFs:</p> + + <list> + <item><p><seealso marker="erlang#monitor/2"><c>erlang:monitor(time_offset, clock_service)</c></seealso></p></item> + <item><p><seealso marker="erlang#system_flag_time_offset"><c>erlang:system_flag(time_offset, finalize)</c></seealso></p></item> + <item><p><seealso marker="erlang#system_info_os_monotonic_time_source"><c>erlang:system_info(os_monotonic_time_source)</c></seealso></p></item> + <item><p><seealso marker="erlang#system_info_os_system_time_source"><c>erlang:system_info(os_system_time_source)</c></seealso></p></item> + <item><p><seealso marker="erlang#system_info_time_offset"><c>erlang:system_info(time_offset)</c></seealso></p></item> + <item><p><seealso marker="erlang#system_info_time_warp_mode"><c>erlang:system_info(time_warp_mode)</c></seealso></p></item> + <item><p><seealso marker="erlang#system_info_time_correction"><c>erlang:system_info(time_correction)</c></seealso></p></item> + <item><p><seealso marker="erlang#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso></p></item> + <item><p><seealso marker="erlang#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso></p></item> + </list> + + <marker id="The_New_Erlang_Monotonic_Time"/> + <section> + <title>New Erlang Monotonic Time</title> + <p>Erlang monotonic time as such is new as of <c>ERTS</c> 7.0. + It is introduced to detach time measurements, such as elapsed + time from calendar time. In many use cases there is a need to + measure elapsed time or specify a time relative to another point + in time without the need to know the involved times in UTC or + any other globally defined time scale. By introducing a time + scale with a local definition of where it starts, time that do + not concern calendar time can be managed on that time + scale. Erlang monotonic time uses such a time scale with a + locally defined start.</p> + + <p>The introduction of Erlang monotonic time allows + us to adjust the two Erlang times (Erlang + monotonic time and Erlang system time) separately. By + doing this, the accuracy of elapsed time does not have to + suffer just because the system time happened to be + wrong at some point in time. Separate adjustments + of the two times are only performed in the time warp + modes, and only fully separated in the + <seealso marker="#Multi_Time_Warp_Mode">multi-time + warp mode</seealso>. All other modes than the + multi-time warp mode are for backwards + compatibility reasons. When using these modes, the + accuracy of Erlang monotonic time suffer, as + the adjustments of Erlang monotonic time in these + modes are more or less tied to Erlang system time.</p> + + <p>The adjustment of system time could have been made + smother than using a time warp approach, but we think + that would be a bad choice. As we can + express and measure time that is not connected to + calendar time by the use of Erlang monotonic time, it + is better to expose the change in Erlang system time + immediately. This as the Erlang applications + executing on the system can react on the change in + system time as soon as possible. This is also more or + less exactly how most operating systems handle this + (OS monotonic time and OS system time). By adjusting + system time smoothly, we would just hide the fact that + system time changed and make it harder for the Erlang + applications to react to the change in a sensible way.</p> + + <p>To be able to react to a change in Erlang + system time, you must be able to detect that it + happened. The change in Erlang system time occurs when + current time offset is changed. We have therefore + introduced the possibility to monitor the time offset using + <seealso marker="erlang#monitor/2"><c>erlang:monitor(time_offset, clock_service)</c></seealso>. + A process monitoring the time + offset is sent a message on the following format + when the time offset is changed:</p> + + <code type="none">{'CHANGE', MonitorReference, time_offset, clock_service, NewTimeOffset}</code> + </section> + + <marker id="Unique_Values"/> + <section> + <title>Unique Values</title> + <p>Besides reporting time, <c>erlang:now/0</c> also + produces unique and strictly monotonically increasing + values. To detach this functionality from + time measurements, we have introduced + <seealso marker="erlang#unique_integer/1"><c>erlang:unique_integer()</c></seealso>. + </p> + </section> + + <marker id="Dos_and_Donts"/> + <section> + <title>How to Work with the New API</title> + <p>Previously <c>erlang:now/0</c> was the only option for doing + many things. This section deals with some things that + <c>erlang:now/0</c> can be used for, and how you are to + these using the new API.</p> + + <marker id="Dos_and_Donts_Retrieve_Erlang_System_Time"/> + <section> + <title>Retrieve Erlang System Time</title> + <dont> + <p> + Use <c>erlang:now/0</c> to retrieve current Erlang system time. + </p> + </dont> + <do> + <p> + Use + <seealso marker="erlang#system_time/1"><c>erlang:system_time/1</c></seealso> + to retrieve current Erlang system time on the + <seealso marker="erlang#type_time_unit">time unit</seealso> + of your choice.</p> + <p>If you want the same format as returned by <c>erlang:now/0</c>, use + <seealso marker="erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>. + </p> + </do> + </section> + + <marker id="Dos_and_Donts_Measure_Elapsed_Time"/> + <section> + <title>Measure Elapsed Time</title> + <dont> + <p> + Take timestamps with <c>erlang:now/0</c> and calculate + the difference in time with + <seealso marker="stdlib:timer#now_diff/2"><c>timer:now_diff/2</c></seealso>. + </p> + </dont> + <do> + <p> + Take timestamps with + <seealso marker="erlang#monotonic_time/0"><c>erlang:monotonic_time/0</c></seealso> + and calculate the time difference using ordinary subtraction. + The result will be in <c>native</c> + <seealso marker="erlang#type_time_unit">time unit</seealso>. + If you want to convert the + result to another time unit, you can use + <seealso marker="erlang#convert_time_unit/3"><c>erlang:convert_time_unit/3</c></seealso>. + </p> + + <p>An easier way to do this is to use + <seealso marker="erlang#monotonic_time/1"><c>erlang:monotonic_time/1</c></seealso> + with the desired time unit. However, you can then lose accuracy + and precision. + </p> + </do> + </section> + + <marker id="Dos_and_Donts_Determine_Order_of_Events"/> + <section> + <title>Determine Order of Events</title> + <dont> + <p> + Determine the order of events by saving a timestamp + with <c>erlang:now/0</c> when the event occurs. + </p> + </dont> + <do> + <p> + Determine the order of events by saving the integer + returned by + <seealso marker="erlang#unique_integer/1"><c>erlang:unique_integer([monotonic])</c></seealso> + when the event occurs. These integers will be strictly + monotonically ordered on current runtime system instance + corresponding to creation time. + </p> + </do> + </section> + + <marker id="Dos_and_Donts_Determine_Order_of_Events_With_Time_of_the_Event"/> + <section> + <title>Determine Order of Events with Time of the Event</title> + <dont> + <p> + Determine the order of events by saving a timestamp + with <c>erlang:now/0</c> when the event occurs. + </p> + </dont> + <do> + <p> + Determine the order of events by saving a tuple containing + <seealso marker="erlang#monotonic_time/0">monotonic time</seealso> + and a <seealso marker="erlang#unique_integer/1">strictly + monotonically increasing integer</seealso> as follows:</p> + + <code type="none"> +Time = erlang:monotonic_time(), +UMI = erlang:unique_integer([monotonic]), +EventTag = {Time, UMI}</code> + + <p>These tuples will be strictly monotonically ordered + on current runtime system instance according to + creation time. It is important that the + monotonic time is in the first element (the most + significant element when comparing 2-tuples). Using + the monotonic time in the tuples, you can calculate time + between events.</p> + + <p>If you are interested in Erlang system time at the + time when the event occurred, you can also save the time + offset before or after saving the events using + <seealso marker="erlang#time_offset/0"><c>erlang:time_offset/0</c></seealso>. + Erlang monotonic time added with the time + offset corresponds to Erlang system time.</p> + + <p>If you are executing in a mode where time offset + can change, and you want to get the actual + Erlang system time when the event occurred, you can + save the time offset as a third element in the tuple + (the least significant element when comparing 3-tuples).</p> + </do> + </section> + + <marker id="Dos_and_Donts_Create_a_Unique_Name"/> + <section> + <title>Create a Unique Name</title> + <dont> + <p> + Use the values returned from <c>erlang:now/0</c> + to create a name unique on the current runtime system instance. + </p> + </dont> + <do> + <p> + Use the value returned from + <seealso marker="erlang#unique_integer/0"><c>erlang:unique_integer/0</c></seealso> + to create a name unique on the current runtime system + instance. If you only want positive integers, you can use + <seealso marker="erlang#unique_integer/1"><c>erlang:unique_integer([positive])</c></seealso>. + </p> + </do> + </section> + + <marker id="Dos_and_Donts_Seed_Random_Number_Generation_With_a_Unique_Value"/> + <section> + <title>Seed Random Number Generation with a Unique Value</title> + <dont> + <p> + Seed random number generation using <c>erlang:now()</c>. + </p> + </dont> + <do> + <p> + Seed random number generation using a combination of + <seealso marker="erlang#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso>, + <seealso marker="erlang#time_offset/0"><c>erlang:time_offset()</c></seealso>, + <seealso marker="erlang#unique_integer/0"><c>erlang:unique_integer()</c></seealso>, + and other functionality. + </p> + </do> + </section> + + <p>To sum up this section: <em>Do not use <c>erlang:now/0</c>.</em></p> + </section> + </section> + + <section> + <marker id="Supporting_Both_New_and_Old_OTP_Releases"/> + <title>Support of Both New and Old OTP Releases</title> + <p>It can be required that your code must run on a variety + of OTP installations of different OTP releases. If so, you + cannot use the new API out of the box, as it will + not be available on old pre OTP 18 releases. The solution + is <em>not</em> to avoid using the new API, as your + code then would not benefit from the scalability + and accuracy improvements made. Instead, use the + new API when available, and fall back on <c>erlang:now/0</c> + when the new API is unavailable.</p> + + <p>Fortunately most of the new API can easily be + implemented using existing primitives, except for:</p> + + <list type="bulleted"> + <item> + <seealso marker="erlang#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso> + </item> + <item> + <seealso marker="erlang#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso> + </item> + <item> + <seealso marker="erlang#system_info_os_monotonic_time_source"><c>erlang:system_info(os_monotonic_time_source)</c></seealso> + </item> + <item> + <seealso marker="erlang#system_info_os_system_time_source"><c>erlang:system_info(os_system_time_source)</c></seealso>) + </item> + </list> + + <p>By wrapping the API with functions that fall back on + <c>erlang:now/0</c> when the new API is unavailable, + and using these wrappers instead of using the API directly, + the problem is solved. These wrappers can, for example, + be implemented as in + <url href="time_compat.erl">$ERL_TOP/erts/example/time_compat.erl</url>.</p> + </section> +</chapter> diff --git a/erts/doc/src/tty.xml b/erts/doc/src/tty.xml index 7d662a2849..b2866c82cf 100644 --- a/erts/doc/src/tty.xml +++ b/erts/doc/src/tty.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>1996</year><year>2010</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -47,7 +48,7 @@ <section> <title>Normal Mode</title> <p>In normal mode keystrokes from the user are collected and interpreted by <c><![CDATA[tty]]></c>. Most of the <em>emacs</em> line editing commands are supported. The following is a complete list of the supported line editing commands.<br></br></p> - <p><em>Note:</em> The notation <c><![CDATA[C-a]]></c> means pressing the control key and the letter <c><![CDATA[a]]></c> simultaneously. <c><![CDATA[M-f]]></c> means pressing the <c><![CDATA[ESC]]></c> key followed by the letter <c><![CDATA[f]]></c>. + <p><em>Note:</em> The notation <c><![CDATA[C-a]]></c> means pressing the control key and the letter <c><![CDATA[a]]></c> simultaneously. <c><![CDATA[M-f]]></c> means pressing the <c><![CDATA[ESC]]></c> key followed by the letter <c><![CDATA[f]]></c>. <c><![CDATA[Home]]></c> and <c><![CDATA[End]]></c> represent the keys with the same name on the keyboard, whereas <c><![CDATA[Left]]></c> and <c><![CDATA[Right]]></c> represent the corresponding arrow keys. </p> <table> <row> @@ -55,6 +56,10 @@ <cell align="left" valign="middle"><em>Function</em></cell> </row> <row> + <cell align="left" valign="middle">Home</cell> + <cell align="left" valign="middle">Beginning of line</cell> + </row> + <row> <cell align="left" valign="middle">C-a</cell> <cell align="left" valign="middle">Beginning of line</cell> </row> @@ -63,6 +68,10 @@ <cell align="left" valign="middle">Backward character</cell> </row> <row> + <cell align="left" valign="middle">C-Left</cell> + <cell align="left" valign="middle">Backward word</cell> + </row> + <row> <cell align="left" valign="middle">M-b</cell> <cell align="left" valign="middle">Backward word</cell> </row> @@ -75,6 +84,10 @@ <cell align="left" valign="middle">Delete word</cell> </row> <row> + <cell align="left" valign="middle">End</cell> + <cell align="left" valign="middle">End of line</cell> + </row> + <row> <cell align="left" valign="middle">C-e</cell> <cell align="left" valign="middle">End of line</cell> </row> @@ -83,6 +96,10 @@ <cell align="left" valign="middle">Forward character</cell> </row> <row> + <cell align="left" valign="middle">C-Right</cell> + <cell align="left" valign="middle">Forward word</cell> + </row> + <row> <cell align="left" valign="middle">M-f</cell> <cell align="left" valign="middle">Forward word</cell> </row> @@ -95,6 +112,10 @@ <cell align="left" valign="middle">Kill line</cell> </row> <row> + <cell align="left" valign="middle">C-u</cell> + <cell align="left" valign="middle">Backward kill line</cell> + </row> + <row> <cell align="left" valign="middle">C-l</cell> <cell align="left" valign="middle">Redraw line</cell> </row> @@ -111,6 +132,10 @@ <cell align="left" valign="middle">Transpose characters</cell> </row> <row> + <cell align="left" valign="middle">C-w</cell> + <cell align="left" valign="middle">Backward kill word</cell> + </row> + <row> <cell align="left" valign="middle">C-y</cell> <cell align="left" valign="middle">Insert previously killed text</cell> </row> diff --git a/erts/doc/src/werl.xml b/erts/doc/src/werl.xml index 1494d91da8..1a3cb6f502 100644 --- a/erts/doc/src/werl.xml +++ b/erts/doc/src/werl.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd"> <comref> <header> <copyright> - <year>1998</year><year>2009</year> + <year>1998</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml index 8917ab5c3a..861661043f 100644 --- a/erts/doc/src/zlib.xml +++ b/erts/doc/src/zlib.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2005</year><year>2011</year> + <year>2005</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - 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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -99,7 +100,7 @@ list_to_binary([Compressed|Last])</pre> <datatype> <name name="zwindowbits"/> <desc> - <p>Normally in the range <c>-15..-9 | 9..15</c>.</p> + <p>Normally in the range <c>-15..-8 | 8..15</c>.</p> </desc> </datatype> </datatypes> @@ -149,7 +150,7 @@ list_to_binary([Compressed|Last])</pre> currently the only supported method is <c>deflated</c>.</p> <p>The <c><anno>WindowBits</anno></c> parameter is the base two logarithm of the window size (the size of the history buffer). It - should be in the range 9 through 15. Larger values + should be in the range 8 through 15. Larger values of this parameter result in better compression at the expense of memory usage. The default value is 15 if <c>deflateInit/2</c>. A negative <c><anno>WindowBits</anno></c> @@ -161,20 +162,22 @@ list_to_binary([Compressed|Last])</pre> state. <c><anno>MemLevel</anno></c>=1 uses minimum memory but is slow and reduces compression ratio; <c><anno>MemLevel</anno></c>=9 uses maximum memory for optimal speed. The default value is 8.</p> - <p>The <c><anno>Strategy</anno></c> parameter is used to tune the - compression algorithm. Use the value <c>default</c> for - normal data, <c>filtered</c> for data produced by a filter - (or predictor), or <c>huffman_only</c> to force Huffman - encoding only (no string match). Filtered data consists - mostly of small values with a somewhat random - distribution. In this case, the compression algorithm is - tuned to compress them better. The effect of - <c>filtered</c>is to force more Huffman coding and less - string matching; it is somewhat intermediate between - <c>default</c> and <c>huffman_only</c>. The <c><anno>Strategy</anno></c> - parameter only affects the compression ratio but not the - correctness of the compressed output even if it is not set - appropriately.</p> + <p>The <c><anno>Strategy</anno></c> parameter is used to tune + the compression algorithm. Use the value <c>default</c> for + normal data, <c>filtered</c> for data produced by a filter (or + predictor), <c>huffman_only</c> to force Huffman encoding + only (no string match), or <c>rle</c> to limit match + distances to one (run-length encoding). Filtered data + consists mostly of small values with a somewhat random + distribution. In this case, the compression algorithm is tuned + to compress them better. The effect of <c>filtered</c>is to + force more Huffman coding and less string matching; it is + somewhat intermediate between <c>default</c> and + <c>huffman_only</c>. <c>rle</c> is designed to be almost as + fast as <c>huffman_only</c>, but give better compression for PNG + image data. The <c><anno>Strategy</anno></c> parameter only + affects the compression ratio but not the correctness of the + compressed output even if it is not set appropriately.</p> </desc> </func> <func> @@ -286,7 +289,7 @@ list_to_binary([B1,B2])</pre> <p>Initialize decompression session on zlib stream.</p> <p>The <c><anno>WindowBits</anno></c> parameter is the base two logarithm of the maximum window size (the size of the history buffer). - It should be in the range 9 through 15. + It should be in the range 8 through 15. The default value is 15 if <c>inflateInit/1</c> is used. If a compressed stream with a larger window size is given as input, inflate() will throw the <c>data_error</c> @@ -300,7 +303,7 @@ list_to_binary([B1,B2])</pre> <fsummary>Decompress data</fsummary> <desc> <p><c>inflate/2</c> decompresses as much data as possible. - It may some introduce some output latency (reading + It may introduce some output latency (reading input without producing any output).</p> <p>If a preset dictionary is needed at this point (see <c>inflateSetDictionary</c> below), <c>inflate/2</c> throws a @@ -310,6 +313,53 @@ list_to_binary([B1,B2])</pre> </desc> </func> <func> + <name name="inflateChunk" arity="2"/> + <fsummary>Decompress data with limited output size</fsummary> + <desc> + <p>Like <c>inflate/2</c>, but decompress no more data than + will fit in the buffer configured via <c>setBufSize/2</c>. + Is is useful when decompressing a stream with a high compression + ratio such that a small amount of compressed input may expand up to + 1000 times. + It returns <c>{more, Decompressed}</c>, when there is more output + available, and <c>inflateChunk/1</c> should be used to read it. + It may introduce some output latency (reading + input without producing any output).</p> + <p>If a preset dictionary is needed at this point (see + <c>inflateSetDictionary</c> below), <c>inflateChunk/2</c> throws a + <c>{need_dictionary,Adler}</c> exception where <c>Adler</c> is + the adler32 checksum of the dictionary chosen by the + compressor.</p> + + <pre> +walk(Compressed, Handler) -> + Z = zlib:open(), + zlib:inflateInit(Z), + % Limit single uncompressed chunk size to 512kb + zlib:setBufSize(Z, 512 * 1024), + loop(Z, Handler, zlib:inflateChunk(Z, Compressed)), + zlib:inflateEnd(Z), + zlib:close(Z). + +loop(Z, Handler, {more, Uncompressed}) -> + Handler(Uncompressed), + loop(Z, Handler, zlib:inflateChunk(Z)); +loop(Z, Handler, Uncompressed) -> + Handler(Uncompressed). + </pre> + </desc> + </func> + <func> + <name name="inflateChunk" arity="1"/> + <fsummary>Read next uncompressed chunk</fsummary> + <desc> + <p>Read next chunk of uncompressed data, initialized by + <c>inflateChunk/2</c>.</p> + <p>This function should be repeatedly called, while it returns + <c>{more, Decompressed}</c>.</p> + </desc> + </func> + <func> <name name="inflateSetDictionary" arity="2"/> <fsummary>Initialize the decompression dictionary</fsummary> <desc> |